GNU Automake Notes – 时光志

英文原文: http://www.gnu.org/software/automake/manual/automake.html((version 1.11.1 )

中文原文: http://www.linuxforum.net/books/automake.html#IDX79(version 1.3 )

1 Introduction

Automake is a tool for automatically generating Makefile.ins from files called Makefile.am. Each Makefile.am is basically a series of make variable definitions1, with rules being thrown in occasionally. The generated Makefile.ins are compliant with the GNU Makefile standards.

The typical Automake input file is simply a series of variable definitions. Each such file is processed to create a Makefile.in. There should generally be one Makefile.am per directory of a project.

Automake does constrain a project in certain ways; for instance, it assumes that the project uses Autoconf (see Introduction), and enforces certain restrictions on the configure.ac contents2.

2 An Introduction to the Autotools

If you need some teaching material, more illustrations, or a less automake-centered continuation, some slides for this introduction are available in Alexandre Duret-Lutz’s Autotools Tutorial. This chapter is the written version of the first part of his tutorial.

2.2 Use Cases for the GNU Build System

In this section we explore several use cases for the GNU Build System. You can replay all these examples on the amhello-1.0.tar.gz package distributed with Automake. If Automake is installed on your system, you should find a copy of this file in prefix/share/doc/automake/amhello-1.0.tar.gz, where prefix is the installation prefix specified during configuration. Download from: http://ftp.gnu.org/gnu/automake/

2.2.2 Standard Makefile Targets

Here is a list of the most useful targets that the GNU Coding Standards specify.

make all: Build programs, libraries, documentation, etc. (same as make).
make install: Install what needs to be installed, copying the files from the package’s tree to system-wide directories.
make install-strip: Same as make install, then strip debugging symbols. Some users like to trade space for useful bug reports…
make uninstall: The opposite of make install: erase the installed files. (This needs to be run from the same build tree that was installed.)
make clean: Erase from the build tree the files built by make all.
make distclean: Additionally erase anything ./configure created.
make check: Run the test suite, if any.
make installcheck: Check the installed programs or libraries, if supported.
make dist: Recreate package-version.tar.gz from all the source files.

2.2.3 Standard Directory Variables

prefix /usr/local

exec_prefix ${prefix}

bindir ${exec_prefix}/bin

libdir ${exec_prefix}/lib

…

includedir ${prefix}/include

datarootdir ${prefix}/share

datadir ${datarootdir}

mandir ${datarootdir}/man

infodir ${datarootdir}/info

docdir ${datarootdir}/doc/${PACKAGE}

…

2.2.4 Standard Configuration Variables

The GNU Coding Standards also define a set of standard configuration variables used during the build. Here are some:

CC: C compiler command
CFLAGS: C compiler flags
CXX: C++ compiler command
CXXFLAGS: C++ compiler flags
LDFLAGS: linker flags
CPPFLAGS: C/C++ preprocessor flags
…

Here is how one would call configure to force it to use gcc-3 as C compiler, use header files from ~/usr/include when compiling, and libraries from ~/usr/lib when linking.

     ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
     CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib

Again, a full list of these variables appears in the output of ./configure –help.

2.2.5 Overriding Default Configuration Setting with config.site

When installing several packages using the same setup, it can be convenient to create a file to capture common settings. If a file named prefix/share/config.site exists, configure will source it at the beginning of its execution.

Now, any time a configure script is using the ~/usr prefix, it will execute the above config.site and define these three variables.

     ~/amhello-1.0 % ./configure --prefix ~/usr
     configure: loading site script /home/adl/usr/share/config.site
     ...

2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)

A common request from users is that they want to confine all derived files to a single directory, to keep their source directories uncluttered. Here is how we could run configure to build everything in a subdirectory called build/.

     ~ % tar zxf ~/amhello-1.0.tar.gz
     ~ % cd amhello-1.0
     ~/amhello-1.0 % mkdir build && cd build
     ~/amhello-1.0/build % ../configure
     ...
     ~/amhello-1.0/build % make
     ...

These setups, where source and build trees are different, are often called parallel builds or VPATH builds.

VPATH builds have other interesting uses. One is to build the same sources with multiple configurations. For instance:

     ~ % tar zxf ~/amhello-1.0.tar.gz
     ~ % cd amhello-1.0
     ~/amhello-1.0 % mkdir debug optim && cd debug
     ~/amhello-1.0/debug % ../configure CFLAGS='-g -O0'
     ...
     ~/amhello-1.0/debug % make
     ...
     ~/amhello-1.0/debug % cd ../optim
     ~/amhello-1.0/optim % ../configure CFLAGS='-O3 -fomit-frame-pointer'
     ...
     ~/amhello-1.0/optim % make

2.2.7 Two-Part Installation

These targets are install-exec for architecture-dependent files and install-data for architecture-independent files. The command we used up to now, make install, can be thought of as a shorthand for make install-exec install-data.

In the list of directory variables we provided earlier (see Standard Directory Variables), all the variables based on exec-prefix designate architecture-dependent directories whose files will be installed by make install-exec. The others designate architecture-independent directories and will serve files installed by make install-data. See The Two Parts of Install, for more details.

2.2.8 Cross-Compilation

When speaking of cross-compilation, it is important to distinguish between the build platform on which the compilation is performed, and the host platform on which the resulting executable is expected to run. The following configure options are used to specify each of them:

–build=BUILD: The system on which the package is built.
–host=HOST: The system where built programs and libraries will run.

When the –host is used, configure will search for the cross-compiling suite for this platform. Cross-compilation tools commonly have their target architecture as prefix of their name. For instance my cross-compiler for MinGW32 has its binaries called i586-mingw32msvc-gcc, i586-mingw32msvc-ld, i586-mingw32msvc-as, etc.

Here is how we could build amhello-1.0 for i586-mingw32msvc on a GNU/Linux PC.

     ~/amhello-1.0 % ./configure --build i686-pc-linux-gnu --host i586-mingw32msvc
     checking for a BSD-compatible install... /usr/bin/install -c
     checking whether build environment is sane... yes
     checking for gawk... gawk
     checking whether make sets $(MAKE)... yes
     checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
     checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
     checking for C compiler default output file name... a.exe
     checking whether the C compiler works... yes
     checking whether we are cross compiling... yes
     checking for suffix of executables... .exe
     checking for suffix of object files... o
     checking whether we are using the GNU C compiler... yes
     checking whether i586-mingw32msvc-gcc accepts -g... yes
     checking for i586-mingw32msvc-gcc option to accept ANSI C...
     ...
     ~/amhello-1.0 % make
     ...
     ~/amhello-1.0 % cd src; file hello.exe
     hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable

The –host and –build options are usually all we need for cross-compiling. The only exception is if the package being built is itself a cross-compiler: we need a third option to specify its target architecture.

–target=TARGET: When building compiler tools: the system for which the tools will create output.

2.2.9 Renaming Programs at Install Time

–program-prefix=PREFIX: Prepend PREFIX to installed program names.
–program-suffix=SUFFIX: Append SUFFIX to installed program names.
–program-transform-name=PROGRAM: Run sed PROGRAM on installed program names.

The following commands would install hello as /usr/local/bin/test-hello, for instance.

     ~/amhello-1.0 % ./configure --program-prefix test-
     ...
     ~/amhello-1.0 % make
     ...
     ~/amhello-1.0 % sudo make install

2.2.10 Building Binary Packages Using DESTDIR

For instance here is how we could create a binary package containing a snapshot of all the files to be installed.

     ~/amhello-1.0 % ./configure --prefix /usr
     ...
     ~/amhello-1.0 % make
     ...
     ~/amhello-1.0 % make DESTDIR=$HOME/inst install
     ...
     ~/amhello-1.0 % cd ~/inst
     ~/inst % find . -type f -print > ../files.lst
     ~/inst % tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`
     ./usr/bin/hello
     ./usr/share/doc/amhello/README

After this example, amhello-1.0-i686.tar.gz is ready to be uncompressed in / on many hosts. (Using `cat ../files.lst` instead of ‘.’ as argument for tar avoids entries for each subdirectory in the archive: we would not like tar to restore the modification time of /, /usr/, etc.)

2.2.11 Preparing Distributions

Another, more useful command is make distcheck. The distcheck target constructs package-version.tar.gz just as well as dist, but it additionally ensures most of the use cases presented so far work:

It attempts a full compilation of the package (see Basic Installation), unpacking the newly constructed tarball, running make, make check, make install, as well as make installcheck, and even make dist,
it tests VPATH builds with read-only source tree (see VPATH Builds),
it makes sure make clean, make distclean, and make uninstall do not omit any file (see Standard Targets),
and it checks that DESTDIR installations work (see DESTDIR).

2.2.12 Automatic Dependency Tracking

–disable-dependency-tracking: Speed up one-time builds.
–enable-dependency-tracking: Do not reject slow dependency extractors.

2.2.13 Nested Packages

The command configure –help=recursive can be used to display the options supported by all the included packages.

2.4.1 Creating amhello-1.0.tar.gz

Do this using the autoreconf command as follows:

     ~/amhello % autoreconf --install
     configure.ac: installing `./install-sh'
     configure.ac: installing `./missing'
     src/Makefile.am: installing `./depcomp'

autoreconf is a script that calls autoconf, automake, and a bunch of other commands in the right order.

2.4.2 amhello-1.0 Explained

Let us begin with the contents of configure.ac.

     AC_INIT([amhello], [1.0], [bug-automake@gnu.org])
     AM_INIT_AUTOMAKE([-Wall -Werror foreign])
     AC_PROG_CC
     AC_CONFIG_HEADERS([config.h])
     AC_CONFIG_FILES([
      Makefile
      src/Makefile
     ])
     AC_OUTPUT

The macros prefixed with AC_ are Autoconf macros, documented in the Autoconf manual (see Autoconf Macro Index). The macros that start with AM_ are Automake macros, documented later in this manual (see Macro Index).

The argument to AM_INIT_AUTOMAKE is a list of options for automake (see Options). -Wall and -Werror ask automake to turn on all warnings and report them as errors.

The AC_CONFIG_HEADERS([config.h]) invocation causes the configure script to create a config.h file gathering ‘#define’s defined by other macros in configure.ac.

As you probably noticed, src/main.c includes config.h so it can use PACKAGE_STRING. In a real-world project, config.h can grow really big, with one ‘#define’ per feature probed on the system.

We now turn to src/Makefile.am. This file contains Automake instructions to build and install hello.

     bin_PROGRAMS = hello
     hello_SOURCES = main.c

Variables that end with _PROGRAMS are special variables that list programs that the resulting Makefile should build. In Automake speak, this _PROGRAMS suffix is called a primary; Automake recognizes other primaries such as _SCRIPTS, _DATA, _LIBRARIES, etc. corresponding to different types of files.

The ‘bin’ part of the bin_PROGRAMS tells automake that the resulting programs should be installed in bindir.

Finally here are some explanations regarding the top-level Makefile.am.

     SUBDIRS = src
     dist_doc_DATA = README

SUBDIRS is a special variable listing all directories that make should recurse into before processing the current directory.

The line dist_doc_DATA = README causes README to be distributed and installed in docdir. Files listed with the _DATA primary are not automatically part of the tarball built with make dist, so we add the dist_ prefix so they get distributed.

3.1 General Operation

Automake also allows a form of comment that is not copied into the output; all lines beginning with ‘##’ (leading spaces allowed) are completely ignored by Automake.

3.2 Strictness

To this end, Automake supports three levels of strictness

foreign gnu gnits

3.3 The Uniform Naming Scheme

Automake extends this list with pkgdatadir, pkgincludedir, pkglibdir, and pkglibexecdir; these are the same as the non-‘pkg’ versions, but with ‘$(PACKAGE)’ appended. For instance, pkglibdiris defined as ‘$(libdir)/$(PACKAGE)’.

For each primary, there is one additional variable named by prepending ‘EXTRA_’ to the primary name. This variable is used to list objects that may or may not be built, depending on whatconfiguredecides.

For instance,cpiodecides at configure time which programs should be built. Some of the programs are installed in bindir, and some are installed in sbindir:

     EXTRA_PROGRAMS = mt rmt
     bin_PROGRAMS = cpio pax
     sbin_PROGRAMS = $(MORE_PROGRAMS)

Defining a primary without a prefix as a variable, e.g., ‘PROGRAMS’, is an error.

Note that the common ‘dir’ suffix is left off when constructing the variable names; thus one writes ‘bin_PROGRAMS’ and not ‘bindir_PROGRAMS’.

For instance, the following snippet will installfile.xmlinto ‘$(datadir)/xml’.

     xmldir = $(datadir)/xml
     xml_DATA = file.xml

The special prefix ‘noinst_’ indicates that the objects in question should be built but not installed at all. This is usually used for objects required to build the rest of your package, for instance static libraries (see A Library), or helper scripts.

The special prefix ‘check_’ indicates that the objects in question should not be built until the ‘make check’ command is run. Those objects are not installed either.

The current primary names are ‘PROGRAMS’, ‘LIBRARIES’, ‘LISP’, ‘PYTHON’, ‘JAVA’, ‘SCRIPTS’, ‘DATA’, ‘HEADERS’, ‘MANS’, and ‘TEXINFOS’. Some primaries also allow additional prefixes that control other aspects ofautomake‘s behavior. The currently defined prefixes are ‘dist_’, ‘nodist_’, ‘nobase_’, and ‘notrans_’. These prefixes are explained later (see Program and Library Variables) (see Man Pages).

3.5 How derived variables are named

For example, if your program is namedsniff-glue, the derived variable name would be ‘sniff_glue_SOURCES’, not ‘sniff-glue_SOURCES’. Similarly the sources for a library namedlibmumble++.ashould be listed in the ‘libmumble___a_SOURCES’ variable.

3.6 Variables reserved for the user

To get around this problem, Automake introduces an automake-specific shadow variable for each user flag variable. (Shadow variables are not introduced for variables like CC, where they would make no sense.) The shadow variable is named by prepending ‘AM_’ to the user variable’s name. For instance, the shadow variable for YFLAGS is AM_YFLAGS. The package maintainer—that is, the author(s) of theMakefile.amandconfigure.acfiles—may adjust these shadow variables however necessary.

3.7 Programs automake might require

Although all of these files are distributed and installed with Automake, a couple of them are maintained separately. The Automake copies are updated before each release, but we mention the original source in case you need more recent versions.

ansi2knr.c
ansi2knr.1: These two files are used for de-ANSI-fication support (obsolete see ANSI).
compile: This is a wrapper for compilers that do not accept options-cand-oat the same time. It is only used when absolutely required. Such compilers are rare.
config.guess
config.sub: These two programs compute the canonical triplets for the given build, host, or target architecture. These programs are updated regularly to support new architectures and fix probes broken by changes in new kernel versions. Each new release of Automake comes with up-to-date copies of these programs. If your copy of Automake is getting old, you are encouraged to fetch the latest versions of these files from http://savannah.gnu.org/git/?group=config before making a release.
config-ml.in: This file is not a program, it is aconfigurefragment used for multilib support (see Multilibs). This file is maintained in the GCC tree at http://gcc.gnu.org/svn.html.
depcomp: This program understands how to run a compiler so that it will generate not only the desired output but also dependency information that is then used by the automatic dependency tracking feature (see Dependencies).
elisp-comp: This program is used to byte-compile Emacs Lisp code.
install-sh: This is a replacement for theinstallprogram that works on platforms whereinstallis unavailable or unusable.
mdate-sh: This script is used to generate aversion.texifile. It examines a file and prints some date information about it.
missing: This wraps a number of programs that are typically only required by maintainers. If the program in question doesn’t exist,missingprints an informative warning and attempts to fix things so that the build can continue.
mkinstalldirs: This script used to be a wrapper around ‘mkdir -p’, which is not portable. Now we prefer to use ‘install-sh -d’ whenconfigurefinds that ‘mkdir -p’ does not work, this makes one less script to distribute.; For backward compatibilitymkinstalldirsis still used and distributed whenautomakefinds it in a package. But it is no longer installed automatically, and it should be safe to remove it.
py-compile: This is used to byte-compile Python scripts.
symlink-tree: This program duplicates a tree of directories, using symbolic links instead of copying files. Such an operation is performed when building multilibs (see Multilibs). This file is maintained in the GCC tree at http://gcc.gnu.org/svn.html.
texinfo.tex: Not a program, this file is required for ‘make dvi’, ‘make ps’ and ‘make pdf’ to work when Texinfo sources are in the package. The latest version can be downloaded from http://www.gnu.org/software/texinfo/.
ylwrap: This program wrapslexandyaccto rename their output files. It also ensures that, for instance, multipleyaccinstances can be invoked in a single directory in parallel

5 Creating a`Makefile.in`

Automake will runautoconfto scanconfigure.acand its dependencies (i.e.,aclocal.m4and any included file), thereforeautoconfmust be in yourPATH. If there is anAUTOCONFvariable in your environment it will be used instead ofautoconf, this allows you to select a particular version of Autoconf.

automakeaccepts the following options:

-a
--add-missing

Automake requires certain common files to exist in certain situations; for instance,config.guessis required ifconfigure.acinvokes AC_CANONICAL_HOST.

Many of the potentially-missing files are common scripts whose location may be specified via the AC_CONFIG_AUX_DIR macro. Therefore, AC_CONFIG_AUX_DIR‘s setting affects whether a file is considered missing, and where the missing file is added (see Optional).

--libdir=dir: Look for Automake data files in directory dir instead of in the installation directory. T
-c
--copy: When used with–add-missing, causes installed files to be copied.
--cygnus: Causes the generatedMakefile.ins to follow Cygnus rules, instead of GNU or Gnits rules
-f
--force-missing: When used with–add-missing, causes standard files to be reinstalled even if they already exist in the source tree.
--foreign: Set the global strictness toforeign.
--gnits: Set the global strictness tognits.
--gnu: Set the global strictness tognu.
-i
--ignore-deps: This disables the dependency tracking feature in generatedMakefiles;
--include-deps: This enables the dependency tracking feature.
--no-force: Ordinarilyautomakecreates allMakefile.ins mentioned inconfigure.ac
-v
--verbose: Cause Automake to print information about which files are being read or created.
-W CATEGORY
--warnings=category: Output warnings falling in category. category can be one of:
gnu: warnings related to the GNU Coding Standards (see Top).
obsolete: obsolete features or constructions
override: user redefinitions of Automake rules or variables
portability: portability issues (e.g., use ofmakefeatures that are known to be not portable)
syntax: weird syntax, unused variables, typos
unsupported: unsupported or incomplete features
all: all the warnings
none: turn off all the warnings
error: treat warnings as errors

A category can be turned off by prefixing its name with ‘no-’. For instance,-Wno-syntaxwill hide the warnings about unused variables.

The categories output by default are ‘syntax’ and ‘unsupported’.

this way -Wnone will also ignore any warning category enabled by WARNINGS.

If the environment variable AUTOMAKE_JOBS contains a positive number, it is taken as the maximum number of Perl threads to use in automake for generating multiple Makefile.in files concurrently.

6.1 Configuration requirements

The one real requirement of Automake is that yourconfigure.accall AM_INIT_AUTOMAKE. This macro does several things that are required for proper Automake operation (see Macros).

Here are the other macros that Automake requires but which are not run by AM_INIT_AUTOMAKE:

AC_CONFIG_FILES
AC_OUTPUT: These two macros are usually invoked as follows near the end ofconfigure.ac.

          ...
          AC_CONFIG_FILES([
            Makefile
            doc/Makefile
            src/Makefile
            src/lib/Makefile
            ...
          ])
          AC_OUTPUT

Automake uses these to determine which files to create (see Creating Output Files). A listed file is considered to be an Automake generatedMakefileif there exists a file with the same name and the.amextension appended.

To summarize:

Use literals forMakefiles, and for other files whenever possible.
Use ‘$file’ (or ‘${file}’ without ‘AC_SUBST([file])’) for files thatautomakeshould ignore.
Use ‘${file}’ and ‘AC_SUBST([file])’ for files thatautomakeshould not ignore.

6.2 Other things Automake recognizes

. Currently recognized macros and their effects are:

AC_CANONICAL_BUILD
AC_CANONICAL_HOST
AC_CANONICAL_TARGET: Automake will ensure thatconfig.guessandconfig.subexist. Also, theMakefilevariables build_triplet, host_triplet and target_triplet are introduced.
AC_CONFIG_AUX_DIR: Automake will look for various helper scripts, such asinstall-sh, in the directory named in this macro invocation. (The full list of scripts is:config.guess,config.sub,depcomp,elisp-comp,compile,install-sh,ltmain.sh,mdate-sh,missing,mkinstalldirs,py-compile,texinfo.tex, andylwrap.) Not all scripts are always searched for; some scripts will only be sought if the generatedMakefile.inrequires them.
AC_CONFIG_LIBOBJ_DIR: Automake will require the sources file declared with AC_LIBSOURCE (see below) in the directory specified by this macro.
AC_CONFIG_HEADERS: Automake will generate rules to rebuild these headers.; AC_CONFIG_LINKS; Automake will generate rules to removeconfiguregenerated links on ‘make distclean’ and to distribute named source files as part of ‘make dist’.
AC_LIBOBJ
AC_LIBSOURCE
AC_LIBSOURCES: Automake will automatically distribute any file listed in AC_LIBSOURCE or AC_LIBSOURCES.

Note that the AC_LIBOBJ macro calls AC_LIBSOURCE. So if an Autoconf macro is documented to call ‘AC_LIBOBJ([file])’, thenfile.cwill be distributed automatically by Automake. This encompasses many macros like AC_FUNC_ALLOCA, AC_FUNC_MEMCMP, AC_REPLACE_FUNCS, and others.

By the way, direct assignments to LIBOBJS are no longer supported. You should always use AC_LIBOBJ for this purpose. See AC_LIBOBJ vs. LIBOBJS.

AC_PROG_RANLIB: This is required if any libraries are built in the package.
AC_PROG_CXX: This is required if any C++ source is included.
AC_PROG_OBJC: This is required if any Objective C source is included.
AC_PROG_F77: This is required if any Fortran 77 source is included.
AC_F77_LIBRARY_LDFLAGS: This is required for programs and shared libraries that are a mixture of languages that include Fortran 77
AC_FC_SRCEXT: Automake will add the flags computed by AC_FC_SRCEXT to compilation of files with the respective source extension
AC_PROG_FC: This is required if any Fortran 90/95 source is included.
AC_PROG_LIBTOOL: Automake will turn on processing forlibtool
AC_PROG_YACC: If a Yacc source file is seen, then you must either use this macro or define the variable YACCinconfigure.ac.
AC_PROG_LEX: If a Lex source file is seen, then this macro must be used.
AC_REQUIRE_AUX_FILE: For each AC_REQUIRE_AUX_FILE([file]),automakewill ensure that file exists in the aux directory, and will complain otherwise.
AC_SUBST: The first argument is automatically defined as a variable in each generatedMakefile.in, unless AM_SUBST_NOTMAKE is also used for this variable.
AM_C_PROTOTYPES: This is required when using the obsolete de-ANSI-fication feature;
AM_CONDITIONAL: This introduces an Automake conditional (see Conditionals).
AM_COND_IF: This macro allows automaketo detect subsequent access withinconfigure.acto a conditional previously introduced with AM_CONDITIONAL, thus enabling conditional AC_CONFIG_FILES (see Usage of Conditionals).
AM_GNU_GETTEXT: This macro is required for packages that use GNU gettext
AM_GNU_GETTEXT_INTL_SUBDIR: This macro specifies that theintl/subdirectory is to be built, even if the AM_GNU_GETTEXTmacro was invoked with a first argument of ‘external’.
AM_MAINTAINER_MODE([default-mode]): This macro adds an–enable-maintainer-modeoption toconfigure. If this is used,automakewill cause “maintainer-only” rules to be turned off by default in the generatedMakefile.ins, unless default-modeis ‘enable’.See maintainer-mode.; AM_SUBST_NOTMAKE(var)
m4_include: Files included byconfigure.acusing this macro will be detected by Automake and automatically distributed.

`6.3 Auto-generating aclocal.m4`

Automake includes a number of Autoconf macros that can be used in your package (see Macros); some of them are actually required by Automake in certain situations. These macros must be defined in your

aclocal.m4;

At startup, aclocal scans all the .m4 files it can find, looking for macro definitions (see Macro Search Path). Then it scans configure.ac

. Any mention of one of the macros found in the first step causes that macro, and any macros it in turn requires, to be put into

aclocal.m4.

Putting the file that contains the macro definition into aclocal.m4 is usually done by copying the entire text of this file, including unused macro definitions as well as both ‘#’ and ‘dnl’ comments. If you want to make a comment that will be completely ignored by aclocal, use ‘##’ as the comment leader.

While computing aclocal.m4, aclocal runs autom4te (see Using Autom4te) in order to trace the macros that are really used, and omit from aclocal.m4 all macros that are mentioned but otherwise unexpanded

`6.3.1 aclocal Options`

aclocal accepts the following options:

--acdir=dir: Look for the macro files in dir instead of the installation directory. This is typically used for debugging.
--diff[=command]: Run commandon M4 file that would be installed or overwritten by–install. The default commandis ‘diff -u’. This option implies–installand–dry-run.
--dry-run: Do not actually overwrite (or create)aclocal.m4and M4 files installed by–install.
-I dir: Add the directory dirto the list of directories searched for.m4files.
--install: Install system-wide third-party macros into the first directory specified with ‘-Idir’ instead of copying them in the output file.; When this option is used, and only when this option is used,aclocalwill also honor ‘#serialNUMBER’ lines that appear in macros: an M4 file is ignored if there exists another M4 file with the same basename and a greater serial number in the search path (see Serials).
--force: Always overwrite the output file. The default is to overwrite the output file only when really needed, i.e., when its contents changes or if one of its dependencies is younger.; This option forces the update ofaclocal.m4(or the file specified with–outputbelow) and only this file, it has absolutely no influence on files that may need to be installed by–install.
--output=file: Cause the output to be put into fileinstead ofaclocal.m4.
--print-ac-dir: Prints the name of the directory thataclocalwill search to find third-party.m4files. When this option is given, normal processing is suppressed. This option can be used by a package to determine where to install a macro file.
--verbose: Print the names of the files it examines.
-W CATEGORY
--warnings=category: Output warnings falling in category. category can be one of:

syntax: dubious syntactic constructs, underquoted macros, unused macros, etc.
unsupported: unknown macros
all: all the warnings, this is the default
none: turn off all the warnings
error: treat warnings as errors

All warnings are output by default.

`6.3.2 Macro Search Path`

By default, aclocal searches for .m4 files in the following directories, in this order:

acdir-APIVERSION: This is where the.m4macros distributed with Automake itself are stored. APIVERSION depends on the Automake release used; for Automake 1.6.x, APIVERSION = 1.6.
acdir: This directory is intended for third party.m4files, and is configured whenautomakeitself is built. This is@datadir@/aclocal/, which typically expands to${prefix}/share/aclocal/. To find the compiled-in value of acdir, use the–print-ac-diroption (see aclocal Options).

As an example, suppose thatautomake-1.6.2was configured with–prefix=/usr/local. Then, the search path would be:

/usr/local/share/aclocal-1.6/
/usr/local/share/aclocal/

`Modifying the Macro Search Path:` `–acdir`

The most erroneous option to modify the search path is–acdir=dir, which changes default directory and drops the APIVERSIONdirectory. For example, if one specifies ‘–acdir=/opt/private/’, then the search path becomes:

/opt/private/

This option,–acdir, is intended for use by the internal Automake test suite only; it is not ordinarily needed by end-users.

Modifying the Macro Search Path: ‘`-Idir`’

Any extra directories specified using-Ioptions (see aclocal Options) are prependedto this search list. Thus, ‘aclocal -I /foo -I /bar’ results in the following search path:

/foo
/bar
acdir–APIVERSION
acdir

`Modifying the Macro Search Path:` `dirlist`

There is a third mechanism for customizing the search path. If adirlistfile exists in acdir, then that file is assumed to contain a list of directory patterns, one per line.aclocalexpands these patterns to directory names, and adds them to the search list afterall other directories.dirlistentries may use shell wildcards such as ‘*’, ‘?’, or [...].

For example, suppose acdir/dirlistcontains the following:

     /test1
     /test2
     /test3*

`6.3.3 Writing your own aclocal macros`

A macro file's name should end in .m4. Such files should be installed in $(datadir)/aclocal. This is as simple as writing:

     aclocaldir = $(datadir)/aclocal
     aclocal_DATA = mymacro.m4 myothermacro.m4

Please do use$(datadir)/aclocal, and not something based on the result of ‘aclocal –print-ac-dir’. See Hard-Coded Install Paths, for arguments.

A file of macros should be a series of properly quoted AC_DEFUN‘s (see Macro Definitions). Theaclocalprograms also understands AC_REQUIRE (see Prerequisite Macros), so it is safe to put each macro in a separate file.

`6.3.4 Handling Local Macros`

There are two ways to organize custom macros in a package.

The first possibility (the historical practice) is to list all your macros in acinclude.m4. This file will be included in aclocal.m4 when you run aclocal, and its macro(s) will henceforth be visible to autoconf.

The second possibility, which we do recommend, is to write each macro in its own file and gather all these files in a directory. This directory is usually called m4/. To build aclocal.m4, one should therefore instruct aclocal to scan m4/. From the command line, this is done with ‘aclocal -I m4’. The top-level Makefile.am should also be updated to define

     ACLOCAL_AMFLAGS = -I m4

ACLOCAL_AMFLAGScontains options to pass toaclocalwhenaclocal.m4is to be rebuilt bymake.

Since Automake 1.10, aclocal offers an option to copy these system-wide third-party macros in your local macro directory, solving the above problem. Simply use:

     ACLOCAL_AMFLAGS = -I m4 --install

With this setup, system-wide macros will be copied tom4/the first time you runautoreconf. Then the locally installed macros will have precedence over the system-wide installed macros each timeaclocalis run again.

`6.4.1 Public Macros`

AM_ENABLE_MULTILIB: This is used when a “multilib” library is being built. The first optional argument is the name of theMakefilebeing generated; it defaults to ‘Makefile’. The second optional argument is used to find the top source directory; it defaults to the empty string (generally this should not be used unless you are familiar with the internals). See Multilibs.
AM_INIT_AUTOMAKE([OPTIONS])
AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE]): Runs many macros required for proper operation of the generated Makefiles.; This macro has two forms, the first of which is preferred. In this form, AM_INIT_AUTOMAKEis called with a single argument: a space-separated list of Automake options that should be applied to everyMakefile.amin the tree. The effect is as if each option were listed in AUTOMAKE_OPTIONS (see Options).; The second, deprecated, form of AM_INIT_AUTOMAKE has two required arguments: the package and the version number. This form is obsolete because the package and version can be obtained from Autoconf’s AC_INIT macro (which itself has an old and a new form).; If yourconfigure.achas:

          AC_INIT([src/foo.c])
          AM_INIT_AUTOMAKE([mumble], [1.5])

you can modernize it as follows:

          AC_INIT([mumble], [1.5])
          AC_CONFIG_SRCDIR([src/foo.c])
          AM_INIT_AUTOMAKE

Note that if you’re upgrading yourconfigure.acfrom an earlier version of Automake, it is not always correct to simply move the package and version arguments from AM_INIT_AUTOMAKE directly to AC_INIT, as in the example above. The first argument to AC_INITshould be the name of your package (e.g., ‘GNU Automake’), not the tarball name (e.g., ‘automake’) that you used to pass to AM_INIT_AUTOMAKE. Autoconf tries to derive a tarball name from the package name, which should work for most but not all package names. (If it doesn’t work for yours, you can use the four-argument form of AC_INIT to provide the tarball name explicitly).

By default this macro AC_DEFINE‘s PACKAGE and VERSION. This can be avoided by passing theno-defineoption, as in:

          AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])

or by passing a third non-empty argument to the obsolete form.
AM_PATH_LISPDIR: Searches for the programemacs, and, if found, sets the output variable lispdir to the full path to Emacs’ site-lisp directory.
AM_PROG_AS: Use this macro when you have assembly code in your project. This will choose the assembler for you (by default the C compiler) and set CCAS, and will also set CCASFLAGS if required.
AM_PROG_CC_C_O: This is like AC_PROG_CC_C_O, but it generates its results in the manner required by Automake. You must use this instead of AC_PROG_CC_C_O when you need this functionality, that is, when using per-target flags or subdir-objects with C sources.
AM_PROG_LEX: Like AC_PROG_LEX (see Particular Program Checks), but uses themissingscript on systems that do not havelex. HP-UX 10 is one such system.
AM_PROG_GCJ: This macro finds thegcjprogram or causes an error. It sets GCJ and GCJFLAGS.gcjis the Java front-end to the GNU Compiler Collection.
AM_PROG_UPC([compiler-search-list]): Find a compiler for Unified Parallel C and define the UPC variable. The default compiler-search-listis ‘upcc upc’. This macro will abortconfigureif no Unified Parallel C compiler is found.
AM_SILENT_RULES: Enable the machinery for less verbose build output (see Options).
AM_WITH_DMALLOC: Add support for the Dmalloc package. If the user runsconfigurewith–with-dmalloc, then define WITH_DMALLOCand add-ldmallocto LIBS.
AM_WITH_REGEX: Adds–with-regexto theconfigurecommand line. If specified (the default), then the ‘regex’ regular expression library is used,regex.ois put into LIBOBJS, and WITH_REGEXis defined. If–without-regexis given, then the rxregular expression library is used, andrx.ois put into LIBOBJS.

`7.1 Recursing subdirectories`

This is done via the SUBDIRS variable. The SUBDIRS variable holds a list of subdirectories in which building of various sorts can occur.

When Automake invokes make in a subdirectory, it uses the value of the MAKE variable. It passes the value of the variable AM_MAKEFLAGS to the make invocation; this can be set in Makefile.am if there are flags you must always pass to make. The directories mentioned in SUBDIRS are usually direct children of the current directory, each subdirectory containing its own Makefile.am with a SUBDIRS pointing to deeper subdirectories. Automake can be used to construct packages of arbitrary depth this way.

`7.2 Conditional Subdirectories`

There are two ways to setup a project like this. You can use Automake conditionals (see Conditionals) or use Autoconf AC_SUBST variables (see Setting Output Variables). Using Automake conditionals is the preferred solution.

`7.2.1 SUBDIRS vs. DIST_SUBDIRS`

Automake considers two sets of directories, defined by the variables SUBDIRS and DIST_SUBDIRS.

SUBDIRS contains the subdirectories of the current directory that must be built (see Subdirectories). It must be defined manually; Automake will never guess a directory is to be built.

DIST_SUBDIRS is used in rules that need to recurse in all directories, even those that have been conditionally left out of the build.

Precisely, DIST_SUBDIRS is used by ‘make maintainer-clean’, ‘make distclean’ and ‘make dist’. All other recursive rules use SUBDIRS.

`7.2.2 Subdirectories with AM_CONDITIONAL`

configure should output the Makefile for each directory and define a condition into which opt/ should be built.

     ...
     AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
     AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
     ...

Then SUBDIRScan be defined in the top-levelMakefile.amas follows.

     if COND_OPT
       MAYBE_OPT = opt
     endif
     SUBDIRS = src $(MAYBE_OPT)

As you can see, runningmakewill rightly recurse intosrc/and maybeopt/.

As you can’t see, running ‘make dist’ will recurse into bothsrc/andopt/directories because ‘make dist’, unlike ‘make all’, doesn’t use the SUBDIRS variable. It uses the DIST_SUBDIRS variable.

In this case Automake will define ‘DIST_SUBDIRS = src opt’ automatically because it knows that MAYBE_OPTcan contain ‘opt’ in some condition.

`7.2.3 Subdirectories with AC_SUBST`

Another possibility is to define MAYBE_OPT from ./configure using AC_SUBST:

     ...
     if test "$want_opt" = yes; then
       MAYBE_OPT=opt
     else
       MAYBE_OPT=
     fi
     AC_SUBST([MAYBE_OPT])
     AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
     ...

In this case the top-levelMakefile.amshould look as follows.

     SUBDIRS = src $(MAYBE_OPT)
     DIST_SUBDIRS = src opt

The drawback is that since Automake cannot guess what the possible values of MAYBE_OPT are, it is necessary to define DIST_SUBDIRS.

`7.3 An Alternative Approach to Subdirectories`

If you've ever read Peter Miller's excellent paper, Recursive Make Considered Harmful, the preceding sections on the use of subdirectories will probably come as unwelcome advice.

`7.4 Nesting Packages`

These other packages should just appear as subdirectories of their parent package. They must be listed in SUBDIRS like other ordinary directories. However the subpackage's Makefiles should be output by its own configure script, not by the parent's configure. This is achieved using the AC_CONFIG_SUBDIRS Autoconf macro (see AC_CONFIG_SUBDIRS).

The purpose of the ‘AC_CONFIG_AUX_DIR([.])’ instruction is to force Automake and Autoconf to search for auxiliary scripts in the current directory.

`8.1.1 Defining program sources`

For instance:

     bin_PROGRAMS = hello

In this simple case, the resultingMakefile.inwill contain code to generate a program named hello.

The variable hello_SOURCES is used to specify which source files get built into an executable:

     hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h

`8.1.2 Linking the program`

If you need to link against libraries that are not found by configure, you can use LDADD to do so. This variable is used to specify additional objects or libraries to link with; it is inappropriate for specifying specific linker flags, you should use AM_LDFLAGS for this purpose. Sometimes, multiple programs are built in one directory but do not share the same link-time requirements. In this case, you can use the prog_LDADD variable

prog_LDADD is inappropriate for passing program-specific linker flags (except for -l, -L, -dlopen and -dlpreopen). So, use the prog_LDFLAGS variable for this purpose.

It is also occasionally useful to have a program depend on some other target that is not actually part of that program. This can be done using the prog_DEPENDENCIES variable.

`8.1.3 Conditional compilation of sources`

`nditional Compilation using _LDADD Substitutions`

Automake must know all the source files that could possibly go into a program, even if not all the files are built in every circumstance. Any files that are only conditionally built should be listed in the appropriate EXTRA_variable. For instance, ifhello-linux.corhello-generic.cwere conditionally included in hello, theMakefile.amwould contain:

     bin_PROGRAMS = hello
     hello_SOURCES = hello-common.c
     EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
     hello_LDADD = $(HELLO_SYSTEM)
     hello_DEPENDENCIES = $(HELLO_SYSTEM)

You can then setup the ‘$(HELLO_SYSTEM)’ substitution fromconfigure.ac:

     ...
     case $host in
       *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
       *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
     esac
     AC_SUBST([HELLO_SYSTEM])
     ...

In this case, the variable HELLO_SYSTEMshould be replaced by eitherhello-linux.oorhello-generic.o, and added to both hello_DEPENDENCIES and hello_LDADD in order to be built and linked in.

`Conditional Compilation using Automake Conditionals`

An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use thisMakefile.amconstruct to build the samehelloexample:

     bin_PROGRAMS = hello
     if LINUX
     hello_SOURCES = hello-linux.c hello-common.c
     else
     hello_SOURCES = hello-generic.c hello-common.c
     endif

In this case,configure.acshould setup the LINUX conditional using AM_CONDITIONAL (see Conditionals).

`8.2 Building a library`

In this case, the name of the primary is LIBRARIES. Libraries can be installed in libdir or pkglibdir.

Each _LIBRARIES variable is a list of the libraries to be built. For instance, to create a library named libcpio.a, but not install it, you would write:

     noinst_LIBRARIES = libcpio.a
     libcpio_a_SOURCES = ...

Building a static library is done by compiling all object files, then by invoking ‘$(AR) $(ARFLAGS)’ followed by the name of the library and the list of objects, and finally by calling ‘$(RANLIB)’ on that library. You should call AC_PROG_RANLIB from your configure.ac to define RANLIB (Automake will complain otherwise). AR and ARFLAGS default to ar and cru respectively; you can override these two variables my setting them in your Makefile.am, by AC_SUBSTing them from your configure.ac, or by defining a per-library maude_AR variable

`8.3 Building a Shared Library`

Building shared libraries portably is a relatively complex matter. For this reason, GNU Libtool (see Introduction) was created to help build shared libraries in a platform-independent way.

`8.3.1 The Libtool Concept`

Libtool abstracts shared and static libraries into a unified concept henceforth called libtool libraries. Libtool libraries are files using the .la suffix, and can designate a static library, a shared library, or maybe both. (However the package's maintainers can tune the default, see The AC_PROG_LIBTOOL macro.)

`8.3.2 Building Libtool Libraries`

Automake uses libtool to build libraries declared with the LTLIBRARIES primary. Each _LTLIBRARIES variable is a list of libtool libraries to build. For instance, to create a libtool library named libgettext.la, and install it in libdir, write:

     lib_LTLIBRARIES = libgettext.la
     libgettext_la_SOURCES = gettext.c gettext.h ...

`8.3.3 Building Libtool Libraries Conditionally`

Like conditional programs (see Conditional Programs), there are two main ways to build conditional libraries: using Automake conditionals or using Autoconf AC_SUBSTitutions.

The important implementation detail you have to be aware of is that the place where a library will be installed matters to libtool: it needs to be indicated at link-time using the -rpath option.

The examples below illustrate the differences between these two methods.

Here is an example where WANTEDLIBS is an AC_SUBSTed variable set at./configure-time to eitherlibfoo.la,libbar.la, both, or none. Although ‘$(WANTEDLIBS)’ appears in the lib_LTLIBRARIES, Automake cannot guess it relates tolibfoo.laorlibbar.laat the time it creates the link rule for these two libraries. Therefore the-rpathargument must be explicitly supplied.

     EXTRA_LTLIBRARIES = libfoo.la libbar.la
     lib_LTLIBRARIES = $(WANTEDLIBS)
     libfoo_la_SOURCES = foo.c ...
     libfoo_la_LDFLAGS = -rpath '$(libdir)'
     libbar_la_SOURCES = bar.c ...
     libbar_la_LDFLAGS = -rpath '$(libdir)'

Here is how the sameMakefile.amwould look using Automake conditionals named WANT_LIBFOO and WANT_LIBBAR. Now Automake is able to compute the-rpathsetting itself, because it’s clear that both libraries will end up in ‘$(libdir)’ if they are installed.

     lib_LTLIBRARIES =
     if WANT_LIBFOO
     lib_LTLIBRARIES += libfoo.la
     endif
     if WANT_LIBBAR
     lib_LTLIBRARIES += libbar.la
     endif
     libfoo_la_SOURCES = foo.c ...
     libbar_la_SOURCES = bar.c …

`8.3.5 Libtool Convenience Libraries`

nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
‘EXTRA_*_SOURCES’ variables are used to keep track of source files that might be compiled (this is mostly useful when doing conditional compilation using AC_SUBST, see Conditional Libtool Sources), and the nodist_ prefix means the listed sources are not to be distributed

`8.3.7 _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS`

As shown in previous sections, the ‘library_LIBADD’ variable should be used to list extra libtool objects (.lo files) or libtool libraries (.la) to add to library. 
The ‘library_LDFLAGS’ variable is the place to list additional libtool linking flags, such as -version-info, -static, and a lot more. See Link mode.

Generic options include –tag=TAG and –silent (see Invoking libtool for more options) should appear before the mode selection on the command line; in Makefile.ams they should be listed in the ‘library_LIBTOOLFLAGS’ variable.

If ‘library_LIBTOOLFLAGS’ is not defined, then the variable AM_LIBTOOLFLAGS is used instead.

`8.4 Program and Library Variables`

maude_SOURCES: This variable, if it exists, lists all the source files that are compiled to build the program.
EXTRA_maude_SOURCES: Automake needs to know the list of files you intend to compile statically.
maude_AR: A static library is created by default by invoking ‘$(AR) $(ARFLAGS)’ followed by the name of the library and then the objects being put into the library.
maude_LIBADD: Extra objects can be added to a library using the _LIBADD variable.
maude_LDADD: Extra objects (*.$(OBJEXT)) and libraries (*.a,*.la) can be added to a program by listing them in the _LDADD variable.
maude_LDFLAGS: This variable is used to pass extra flags to the link step of a program or a shared library. It overrides the AM_LDFLAGS variable.
maude_LIBTOOLFLAGS: This variable is used to pass extra options tolibtool. It overrides the AM_LIBTOOLFLAGS variable.
maude_DEPENDENCIES: It is also occasionally useful to have a target (program or library) depend on some other file that is not actually part of that target.; Since these dependencies are associated to the link rule used to create the programs they should normally list files used by the link command. That is *.$(OBJEXT), *.a, or *.la files for programs; *.lo and *.la files for Libtool libraries; and *.$(OBJEXT) files for static libraries. In rare cases you may need to add other kinds of files such as linker scripts, but listing a source file in _DEPENDENCIES is wrong. If some source file needs to be built before all the components of a program are built, consider using the BUILT_SOURCES variable (see Sources).
maude_LINK: You can override the linker on a per-program basis.
maude_CCASFLAGS
maude_CFLAGS
maude_CPPFLAGS
maude_CXXFLAGS
maude_FFLAGS
maude_GCJFLAGS
maude_LFLAGS
maude_OBJCFLAGS
maude_RFLAGS
maude_UPCFLAGS
maude_YFLAGS: Automake allows you to set compilation flags on a per-program (or per-library) basis.
maude_SHORTNAME: On some platforms the allowable file names are very short.

`8.5 Default _SOURCES`

Default sources are mainly useful in test suites, when building many test programs each from a single source. For instance, in

     check_PROGRAMS = test1 test2 test3
     AM_DEFAULT_SOURCE_EXT = .cpp

test1,test2, andtest3will be built fromtest1.cpp,test2.cpp, andtest3.cpp. Without the last line, they will be built fromtest1.c,test2.c, andtest3.c.

`8.6 Special handling for LIBOBJS and ALLOCA`

The ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables list object files that should be compiled into the project to provide an implementation for functions that are missing or broken on the host system. They are substituted byconfigure.

These variables are defined by Autoconf macros such as AC_LIBOBJ, AC_REPLACE_FUNCS (see Generic Function Checks), or AC_FUNC_ALLOCA (see Particular Function Checks). Many other Autoconf macros call AC_LIBOBJ or AC_REPLACE_FUNCSto populate ‘$(LIBOBJS)’.

 # configure.ac
     ...
     AC_CONFIG_LIBOBJ_DIR([lib])
     ...
     AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
     AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
     AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
     AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA

8.7 Variables used when building a program

Some variables are inherited from Autoconf; these are CC, CFLAGS, CPPFLAGS, DEFS, LDFLAGS, and LIBS. There are some additional variables that Automake defines on its own:

AM_CPPFLAGS: The contents of this variable are passed to every compilation that invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance,-Iand-Doptions should be listed here.
INCLUDES: This does the same job as AM_CPPFLAGS
M_CFLAGS: This is the variable theMakefile.amauthor can use to pass in additional C compiler flags. \
COMPILE: This is the command used to actually compile a C source file.
AM_LDFLAGS: This is the variable theMakefile.amauthor can use to pass in additional linker flags.
LINK: This is the command used to actually link a C program.

`8.8 Yacc and Lex support`

When yacc is invoked, it is passed YFLAGS and AM_YFLAGS. The former is a user variable and the latter is intended for the

Makefile.am author.

`8.9 C++ Support`

ny package including C++ code must define the output variable CXX in configure.ac; the simplest way to do this is to use the AC_PROG_CXX macro (see Particular Program Checks).

A few additional variables are defined when a C++ source file is seen:

CXX: The name of the C++ compiler.
CXXFLAGS: Any flags to pass to the C++ compiler.
AM_CXXFLAGS: The maintainer’s variant of CXXFLAGS.
CXXCOMPILE: The command used to actually compile a C++ source file. The file name is appended to form the complete command line.
CXXLINK: The command used to actually link a C++ program.

`8.10 Objective C Support`

Any package including Objective C code must define the output variable OBJC in configure.ac; the simplest way to do this is to use the AC_PROG_OBJC macro (see Particular Program Checks).

A few additional variables are defined when an Objective C source file is seen:

OBJC: The name of the Objective C compiler.
OBJCFLAGS: Any flags to pass to the Objective C compiler.
AM_OBJCFLAGS: The maintainer’s variant of OBJCFLAGS.
OBJCCOMPILE: The command used to actually compile an Objective C source file. The file name is appended to form the complete command line.
OBJCLINK: The command used to actually link an Objective C program.

`8.12 Assembly Support`

Automake includes some support for assembly code. There are two forms of assembler files: normal (*.s) and preprocessed by CPP(*.Sor*.sx).

The variable CCASholds the name of the compiler used to build assembly code. This compiler must work a bit like a C compiler; in particular it must accept-cand-o. The values of CCASFLAGS and AM_CCASFLAGS (or its per-target definition) is passed to the compilation. For preprocessed files, DEFS, DEFAULT_INCLUDES, INCLUDES, CPPFLAGS and AM_CPPFLAGS are also used.

The autoconf macro AM_PROG_AS will define CCAS and CCASFLAGS for you (unless they are already set, it simply sets CCAS to the C compiler and CCASFLAGS to the C compiler flags), but you are free to define these variables by other means.

8.13 Fortran 77 Support

Any package including Fortran 77 code must define the output variable F77inconfigure.ac; the simplest way to do this is to use the AC_PROG_F77 macro (see Particular Program Checks).
F77: The name of the Fortran 77 compiler.
FFLAGS: Any flags to pass to the Fortran 77 compiler.
AM_FFLAGS: The maintainer’s variant of FFLAGS.
RFLAGS: Any flags to pass to the Ratfor compiler.
AM_RFLAGS: The maintainer’s variant of RFLAGS.
F77COMPILE: The command used to actually compile a Fortran 77 source file. The file name is appended to form the complete command line.
FLINK: The command used to actually link a pure Fortran 77 program or shared library.

8.13.2 Compiling Fortran 77 Files

N.ois made automatically fromN.f,N.ForN.rby running the Fortran 77 compiler. The precise command used is as follows:

.f: $(F77) -c $(AM_FFLAGS) $(FFLAGS)
.F: $(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)
.r: $(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)

8.13.3 Mixing Fortran 77 With C and C++

For example, consider the followingMakefile.am:

     bin_PROGRAMS = foo
     foo_SOURCES = main.cc foo.f
     foo_LDADD = libfoo.la $(FLIBS)

     pkglib_LTLIBRARIES = libfoo.la
     libfoo_la_SOURCES = bar.f baz.c zardoz.cc
     libfoo_la_LIBADD = $(FLIBS)

In this case, Automake will insist that AC_F77_LIBRARY_LDFLAGSis mentioned inconfigure.ac. Also, if ‘$(FLIBS)’ hadn’t been mentioned in foo_LDADD and libfoo_la_LIBADD, then Automake would have issued a warning.

.13.3.1 How the Linker is Chosen

When a program or library mixes several languages, Automake choose the linker according to the following priorities. (The names in parentheses are the variables containing the link command.)

Native Java (GCJLINK)
C++ (CXXLINK)
Fortran 77 (F77LINK)
Fortran (FCLINK)
Objective C (OBJCLINK)
Unified Parallel C (UPCLINK)
C (LINK)

8.14 Fortran 9x Support

A few additional variables are defined when a Fortran 9x source file is seen:

FC: The name of the Fortran 9x compiler.
FCFLAGS: Any flags to pass to the Fortran 9x compiler.
AM_FCFLAGS: The maintainer’s variant of FCFLAGS.
FCCOMPILE: The command used to actually compile a Fortran 9x source file. The file name is appended to form the complete command line.
FCLINK: The command used to actually link a pure Fortran 9x program or shared library.

8.15 Java Support

Automake includes support for compiled Java, usinggcj, the Java front end to the GNU Compiler Collection.

Any package including Java code to be compiled must define the output variable GCJinconfigure.ac; the variable GCJFLAGSmust also be defined somehow (either inconfigure.acorMakefile.am). The simplest way to do this is to use the AM_PROG_GCJ macro.

9.1 Executable Scripts

Script are not distributed by default; as we have just seen, those that should be distributed can be specified using a dist_ prefix as with other primaries.

9.4.1 Built Sources Example

Using `BUILT_SOURCES`

A solution is to requirebindir.hto be built before anything else. This is what BUILT_SOURCES is meant for (see Sources).

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     nodist_foo_SOURCES = bindir.h
     BUILT_SOURCES = bindir.h
     CLEANFILES = bindir.h
     bindir.h: Makefile
             echo '#define bindir "$(bindir)"' >$@

However, as said earlier, BUILT_SOURCES applies only to the all, check, and installtargets. It still fails if you try to run ‘make foo’ explicitly:

Recording Dependencies manually

Usually people are happy enough with BUILT_SOURCESbecause they never build targets such as ‘make foo’ before ‘make all’, as in the previous example. However if this matters to you, you can avoid BUILT_SOURCESand record such dependencies explicitly in theMakefile.am.

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     nodist_foo_SOURCES = bindir.h
     foo.$(OBJEXT): bindir.h
     CLEANFILES = bindir.h
     bindir.h: Makefile
             echo '#define bindir "$(bindir)"' >$@

You don’t have to list allthe dependencies offoo.oexplicitly, only those that might need to be built.

Which is best?

You cannot use BUILT_SOURCESif the ability to run ‘make foo’ on a clean tree is important to you.

You won’t add explicit dependencies if you are leery of overriding an Automake rule by mistake.

Building files from./configureis not always possible, neither is converting.hfiles into.cfiles.

12.2 The Two Parts of Install

Variables using the standard directory prefixes ‘data’, ‘info’, ‘man’, ‘include’, ‘oldinclude’, ‘pkgdata’, or ‘pkginclude’ are installed by install-data.

Variables using the standard directory prefixes ‘bin’, ‘sbin’, ‘libexec’, ‘sysconf’, ‘localstate’, ‘lib’, or ‘pkglib’ are installed by install-exec.

For instance, data_DATA files are installed by install-data, while bin_PROGRAMS files are installed by install-exec.

Any variable using a user-defined directory prefix with ‘exec’ in the name (e.g., myexecbin_PROGRAMS) is installed by install-exec. All other user-defined prefixes are installed by install-data.

14.5 The Types of Distributions

Automake generates rules to provide archives of the project for distributions in various formats. Their targets are:

dist-bzip2: Generate a bzip2 tar archive of the distribution. bzip2 archives are frequently smaller than gzipped archives.
dist-gzip: Generate a gzip tar archive of the distribution.
dist-lzma: Generate an ‘lzma’ tar archive of the distribution.lzmaarchives are frequently smaller thanbzip2-compressed archives.
dist-shar: Generate a shar archive of the distribution.
dist-xz: Generate an ‘xz’ tar archive of the distribution.xzarchives are frequently smaller thanbzip2-compressed archives. The ‘xz’ format will soon (early 2009) displace the ‘lzma’ format.
dist-zip: Generate a zip archive of the distribution.
dist-tarZ: Generate a compressed tar archive of the distribution.

The rule dist (and its historical synonym dist-all) will create archives in all the enabled formats, Options. By default, only the dist-gzip target is hooked to dist.

20.1 Usage of Conditionals

Before using a conditional, you must define it by using AM_CONDITIONALin theconfigure.acfile (see Macros).

— Macro: AM_CONDITIONAL (conditional, condition)

The conditional name, conditional, should be a simple string starting with a letter and containing only letters, digits, and underscores. It must be different from ‘TRUE’ and ‘FALSE’ that are reserved by Automake.

The shell condition (suitable for use in a shell ifstatement) is evaluated whenconfigureis run. Note that you must arrange for every AM_CONDITIONALto be invoked every timeconfigureis run. If AM_CONDITIONAL is run conditionally (e.g., in a shell ifstatement), then the result will confuseautomake.

Conditionals typically depend upon options that the user provides to theconfigurescript. Here is an example of how to write a conditional that is true if the user uses the–enable-debugoption.

     AC_ARG_ENABLE([debug],
     [ --enable-debug Turn on debugging],
     [case "${enableval}" in
       yes) debug=true ;;
       no) debug=false ;;
       *) AC_MSG_ERROR([bad value ${enableval} for --enable-debug]) ;;
     esac],[debug=false])
     AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])

Here is an example of how to use that conditional inMakefile.am:

     if DEBUG
     DBG = debug
     else
     DBG =
     endif
     noinst_PROGRAMS = $(DBG)

This trivial example could also be handled using EXTRA_PROGRAMS (see Conditional Programs).

You may only test a single variable in an ifstatement, possibly negated using ‘!’. The else statement may be omitted. Conditionals may be nested to any depth. You may specify an argument to else in which case it must be the negation of the condition used for the current if. Similarly you may specify the condition that is closed on the endif line:

     if DEBUG
     DBG = debug
     else !DEBUG
     DBG =
     endif !DEBUG

Unbalanced conditions are errors. The if, else, and endif statements should not be indented, i.e., start on column one.

The else branch of the above two examples could be omitted, since assigning the empty string to an otherwise undefined variable makes no difference.

In order to allow access to the condition registered by AM_CONDITIONALinsideconfigure.ac, and to allow conditional AC_CONFIG_FILES, AM_COND_IF may be used:

— Macro: AM_COND_IF (conditional, [if-true], [if-false])

If conditional is fulfilled, execute if-true, otherwise execute if-false. If either branch contains AC_CONFIG_FILES, it will causeautomaketo output the rules for the respective files only for the given condition.

AM_COND_IF macros may be nested when m4 quotation is used properly (see M4 Quotation).

Here is an example of how to define a conditional config file:

     AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
     AM_COND_IF([SHELL_WRAPPER],
                [AC_CONFIG_FILES([wrapper:wrapper.in])])

23.2 Third-Party`Makefile`s

When a user runs one of these targets, that target is run recursively in all subdirectories. This is why it is important that even third-partyMakefiles support them.

all: Compile the entire package. This is the default target in Automake-generatedMakefiles, but it does not need to be the default in third-partyMakefiles.
distdir: Copy files to distribute into ‘$(distdir)’, before a tarball is constructed. Of course this target is not required if theno-distoption (see Options) is used.; The variables ‘$(top_distdir)’ and ‘$(distdir)’ (see The dist Hook) will be passed from the outer package to the subpackage when the distdir target is invoked. These two variables have been adjusted for the directory that is being recursed into, so they are ready to use.
install
install-data
install-exec
uninstall: Install or uninstall files (see Install).
install-dvi
install-html
install-info
install-ps
install-pdf: Install only some specific documentation format (see Texinfo).
installdirs: Create install directories, but do not install any files.
check
installcheck: Check the package (see Tests).
mostlyclean
clean
distclean
maintainer-clean: Cleaning rules (see Clean).
dvi
pdf
ps
info
html: Build the documentation in various formats (see Texinfo).
tags
ctags: BuildTAGSandCTAGS(see Tags).

26 Upgrading a Package to a Newer Automake Version

Automake maintains three kind of files in a package.

aclocal.m4
Makefile.ins
auxiliary tools likeinstall-shorpy-compile

aclocal.m4is generated byaclocaland contains some Automake-supplied M4 macros. Auxiliary tools are installed by ‘automake –add-missing’ when needed.Makefile.ins are built fromMakefile.ambyautomake, and rely on the definitions of the M4 macros put inaclocal.m4as well as the behavior of the auxiliary tools installed.

1 Introduction

2.2.2 Standard Makefile Targets

2.2.3 Standard Directory Variables

2.2.4 Standard Configuration Variables

2.2.5 Overriding Default Configuration Setting with config.site

2.2.6 Parallel Build Trees (a.k.a. VPATH Builds)

2.2.7 Two-Part Installation

2.2.8 Cross-Compilation

2.2.9 Renaming Programs at Install Time

2.2.10 Building Binary Packages Using DESTDIR

2.2.11 Preparing Distributions

2.2.12 Automatic Dependency Tracking

2.2.13 Nested Packages

2.4.1 Creating amhello-1.0.tar.gz

2.4.2 amhello-1.0 Explained

3.1 General Operation

3.2 Strictness

3.3 The Uniform Naming Scheme

3.5 How derived variables are named

3.6 Variables reserved for the user

3.7 Programs automake might require

5 Creating aMakefile.in

6.1 Configuration requirements

6.2 Other things Automake recognizes

6.3 Auto-generating aclocal.m4

6.3.1 aclocal Options

6.3.2 Macro Search Path

Modifying the Macro Search Path: –acdir

Modifying the Macro Search Path: ‘-Idir’

Modifying the Macro Search Path: dirlist

6.3.3 Writing your own aclocal macros

6.3.4 Handling Local Macros

6.4.1 Public Macros

7.1 Recursing subdirectories

7.2 Conditional Subdirectories

7.2.1 SUBDIRS vs. DIST_SUBDIRS

7.2.2 Subdirectories with AM_CONDITIONAL

7.2.3 Subdirectories with AC_SUBST

7.3 An Alternative Approach to Subdirectories

7.4 Nesting Packages

8.1.1 Defining program sources

8.1.2 Linking the program

8.1.3 Conditional compilation of sources

nditional Compilation using _LDADD Substitutions

Conditional Compilation using Automake Conditionals

8.2 Building a library

8.3 Building a Shared Library

8.3.1 The Libtool Concept

8.3.2 Building Libtool Libraries

8.3.3 Building Libtool Libraries Conditionally

8.3.5 Libtool Convenience Libraries

8.3.7 _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS

8.4 Program and Library Variables

8.5 Default _SOURCES

8.6 Special handling for LIBOBJS and ALLOCA