英文原文: 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, pkglibdir
is 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 aMakefile.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
andtarget_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
orAC_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
YACC
inconfigure.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
automake
to detect subsequent access withinconfigure.acto a conditional previously introduced withAM_CONDITIONAL
, thus enabling conditionalAC_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_GETTEXT
macro 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,
aclocalscans all the
.m4files 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.m4is 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,
aclocalruns
autom4te(see Using
Autom4te) in order to trace the macros that are really used, and omit from
aclocal.m4all 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,
aclocalsearches for
.m4files in the following directories, in this order:
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.m4when 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_AMFLAGS
contains 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_AUTOMAKE
is 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 inAUTOMAKE_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’sAC_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 toAC_INIT
, as in the example above. The first argument toAC_INIT
should be the name of your package (e.g., ‘GNU Automake’), not the tarball name (e.g., ‘automake’) that you used to pass toAM_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 ofAC_INIT
to provide the tarball name explicitly). - By default this macro
AC_DEFINE
‘sPACKAGE
andVERSION
. 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 setCCASFLAGS
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 ofAC_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
andGCJFLAGS
.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_DMALLOC
and add-ldmalloctoLIBS
. 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
, andWITH_REGEX
is defined. If–without-regexis given, then therx
regular expression library is used, andrx.ois put intoLIBOBJS
.
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 SUBDIRS
can 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_OPT
can 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_SYSTEM
should 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_SUBST
ed 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 (
.lofiles) 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
*.lafiles for programs;
*.loand
*.lafiles 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_FUNCS
to 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.amauthor.
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
CCAS
holds 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 ofCCASFLAGS
andAM_CCASFLAGS
(or its per-target definition) is passed to the compilation. For preprocessed files,DEFS
,DEFAULT_INCLUDES
,INCLUDES
,CPPFLAGS
andAM_CPPFLAGS
are also used. - The autoconf macro
AM_PROG_AS
will defineCCAS
andCCASFLAGS
for you (unless they are already set, it simply setsCCAS
to the C compiler andCCASFLAGS
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
F77
inconfigure.ac; the simplest way to do this is to use theAC_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_LDFLAGS
is 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 GCJ
inconfigure.ac; the variable GCJFLAGS
must 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 install
targets. It still fails if you try to run ‘make foo’ explicitly:
Recording Dependencies manually
Usually people are happy enough with BUILT_SOURCES
because 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_SOURCES
and 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_SOURCES
if 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_CONDITIONAL
in 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
if
statement) is evaluated whenconfigureis run. Note that you must arrange for everyAM_CONDITIONAL
to be invoked every timeconfigureis run. IfAM_CONDITIONAL
is run conditionally (e.g., in a shellif
statement), 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 if
statement, 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_CONDITIONAL
insideconfigure.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-PartyMakefiles
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.