This manual is for GNU Automake (version 1.11, 17 May 2009), a program that creates GNU standards-compliant Makefiles from template files.
Copyright © 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”
--- The Detailed Node Listing ---
An Introduction to the Autotools
Use Cases for the GNU Build System
A Small Hello World
General ideas
Some example packages
Scanning configure.ac
Auto-generating aclocal.m4
Autoconf macros supplied with Automake
Directories
Conditional Subdirectories
Building Programs and Libraries
Building a program
Building a Shared Library
Fortran 77 Support
Mixing Fortran 77 With C and C++
Fortran 9x Support
Other Derived Objects
Built Sources
Other GNU Tools
Building documentation
Installation
Distribution
Support for Test Suites
Miscellaneous Rules
Conditionals
When Automake Isn't Enough
Frequently Asked Questions about Automake
History of Automake
Dependency Tracking Evolution
Copying This Manual
Indices
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 GNU Makefile Standards Document (see Makefile Conventions) is long, complicated, and subject to change. The goal of Automake is to remove the burden of Makefile maintenance from the back of the individual GNU maintainer (and put it on the back of the Automake maintainers).
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.
Automake requires perl in order to generate the Makefile.ins. However, the distributions created by Automake are fully GNU standards-compliant, and do not require perl in order to be built.
Mail suggestions and bug reports for Automake to bug-automake@gnu.org.
If you are new to Automake, maybe you know that it is part of a set of tools called The Autotools. Maybe you've already delved into a package full of files named configure, configure.ac, Makefile.in, Makefile.am, aclocal.m4, ..., some of them claiming to be generated by Autoconf or Automake. But the exact purpose of these files and their relations is probably fuzzy. The goal of this chapter is to introduce you to this machinery, to show you how it works and how powerful it is. If you've never installed or seen such a package, do not worry: this chapter will walk you through it.
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.
It is a truth universally acknowledged, that a developer in possession of a new package, must be in want of a build system.
In the Unix world, such a build system is traditionally achieved using the command make (see Overview). The developer expresses the recipe to build his package in a Makefile. This file is a set of rules to build the files in the package. For instance the program prog may be built by running the linker on the files main.o, foo.o, and bar.o; the file main.o may be built by running the compiler on main.c; etc. Each time make is run, it reads Makefile, checks the existence and modification time of the files mentioned, decides what files need to be built (or rebuilt), and runs the associated commands.
When a package needs to be built on a different platform than the one
it was developed on, its Makefile usually needs to be adjusted.
For instance the compiler may have another name or require more
options. In 1991, David J. MacKenzie got tired of customizing
Makefile for the 20 platforms he had to deal with. Instead, he
handcrafted a little shell script called configure to
automatically adjust the Makefile (see Genesis). Compiling his package was now
as simple as running ./configure && make.
Today this process has been standardized in the GNU project. The GNU
Coding Standards (see The Release Process) explains how each package of the
GNU project should have a configure script, and the minimal
interface it should have. The Makefile too should follow some
established conventions. The result? A unified build system that
makes all packages almost indistinguishable by the installer. In its
simplest scenario, all the installer has to do is to unpack the
package, run ./configure && make && make install, and repeat
with the next package to install.
We call this build system the GNU Build System, since it was grown out of the GNU project. However it is used by a vast number of other packages: following any existing convention has its advantages.
The Autotools are tools that will create a GNU Build System for your package. Autoconf mostly focuses on configure and Automake on Makefiles. It is entirely possible to create a GNU Build System without the help of these tools. However it is rather burdensome and error-prone. We will discuss this again after some illustration of the GNU Build System in action.
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 (prefix defaults to /usr/local, however if Automake was installed by some GNU/Linux distribution it most likely has been set to /usr). If you do not have a copy of Automake installed, you can find a copy of this file inside the doc/ directory of the Automake package.
Some of the following use cases present features that are in fact extensions to the GNU Build System. Read: they are not specified by the GNU Coding Standards, but they are nonetheless part of the build system created by the Autotools. To keep things simple, we do not point out the difference. Our objective is to show you many of the features that the build system created by the Autotools will offer to you.
The most common installation procedure looks as follows.
~ % tar zxf amhello-1.0.tar.gz
~ % cd amhello-1.0
~/amhello-1.0 % ./configure
...
config.status: creating Makefile
config.status: creating src/Makefile
...
~/amhello-1.0 % make
...
~/amhello-1.0 % make check
...
~/amhello-1.0 % su
Password:
/home/adl/amhello-1.0 # make install
...
/home/adl/amhello-1.0 # exit
~/amhello-1.0 % make installcheck
...
The user first unpacks the package. Here, and in the following
examples, we will use the non-portable tar zxf command for
simplicity. On a system without GNU tar installed, this
command should read gunzip -c amhello-1.0.tar.gz | tar xf -.
The user then enters the newly created directory to run the configure script. This script probes the system for various features, and finally creates the Makefiles. In this toy example there are only two Makefiles, but in real-world projects, there may be many more, usually one Makefile per directory.
It is now possible to run make. This will construct all the
programs, libraries, and scripts that need to be constructed for the
package. In our example, this compiles the hello program.
All files are constructed in place, in the source tree; we will see
later how this can be changed.
make check causes the package's tests to be run. This step is
not mandatory, but it is often good to make sure the programs that
have been built behave as they should, before you decide to install
them. Our example does not contain any tests, so running make
check is a no-op.
After everything has been built, and maybe tested, it is time to
install it on the system. That means copying the programs,
libraries, header files, scripts, and other data files from the
source directory to their final destination on the system. The
command make install will do that. However, by default
everything will be installed in subdirectories of /usr/local:
binaries will go into /usr/local/bin, libraries will end up in
/usr/local/lib, etc. This destination is usually not writable
by any user, so we assume that we have to become root before we can
run make install. In our example, running make install
will copy the program hello into /usr/local/bin
and README into /usr/local/share/doc/amhello.
A last and optional step is to run make installcheck. This
command may run tests on the installed files. make check tests
the files in the source tree, while make installcheck tests
their installed copies. The tests run by the latter can be different
from those run by the former. For instance, there are tests that
cannot be run in the source tree. Conversely, some packages are set
up so that make installcheck will run the very same tests as
make check, only on different files (non-installed
vs. installed). It can make a difference, for instance when the
source tree's layout is different from that of the installation.
Furthermore it may help to diagnose an incomplete installation.
Presently most packages do not have any installcheck tests
because the existence of installcheck is little known, and its
usefulness is neglected. Our little toy package is no better: make
installcheck does nothing.
So far we have come across four ways to run make in the GNU
Build System: make, make check, make install, and
make installcheck. The words check, install, and
installcheck, passed as arguments to make, are called
targets. make is a shorthand for make all,
all being the default target in the GNU Build System.
Here is a list of the most useful targets that the GNU Coding Standards specify.
make allmake).
make installmake install-stripmake install, then strip debugging symbols. Some
users like to trade space for useful bug reports...
make uninstallmake install: erase the installed files.
(This needs to be run from the same build tree that was installed.)
make cleanmake all.
make distclean./configure created.
make checkmake installcheckmake distThe GNU Coding Standards also specify a hierarchy of variables to denote installation directories. Some of these are:
| Directory variable | Default value
|
|---|---|
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}
|
| ...
|
Each of these directories has a role which is often obvious from its
name. In a package, any installable file will be installed in one of
these directories. For instance in amhello-1.0, the program
hello is to be installed in bindir, the directory for
binaries. The default value for this directory is
/usr/local/bin, but the user can supply a different value when
calling configure. Also the file README will be
installed into docdir, which defaults to
/usr/local/share/doc/amhello.
A user who wishes to install a package on his own account could proceed as follows:
~/amhello-1.0 % ./configure --prefix ~/usr
...
~/amhello-1.0 % make
...
~/amhello-1.0 % make install
...
This would install ~/usr/bin/hello and ~/usr/share/doc/amhello/README.
The list of all such directory options is shown by
./configure --help.
The GNU Coding Standards also define a set of standard configuration variables used during the build. Here are some:
CCCFLAGSCXXCXXFLAGSLDFLAGSCPPFLAGSconfigure usually does a good job at setting appropriate values for these variables, but there are cases where you may want to override them. For instance you may have several versions of a compiler installed and would like to use another one, you may have header files installed outside the default search path of the compiler, or even libraries out of the way of the linker.
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.
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.
Recall the command from the previous section:
~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \
CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib
Assuming we are installing many package in ~/usr, and will
always want to use these definitions of CC, CPPFLAGS, and
LDFLAGS, we can automate this by creating the following
~/usr/share/config.site file:
test -z "$CC" && CC=gcc-3
test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
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
...
See Setting Site Defaults, for more information about this feature.
The GNU Build System distinguishes two trees: the source tree, and the build tree.
The source tree is rooted in the directory containing configure. It contains all the sources files (those that are distributed), and may be arranged using several subdirectories.
The build tree is rooted in the directory in which configure was run, and is populated with all object files, programs, libraries, and other derived files built from the sources (and hence not distributed). The build tree usually has the same subdirectory layout as the source tree; its subdirectories are created automatically by the build system.
If configure is executed in its own directory, the source and build trees are combined: derived files are constructed in the same directories as their sources. This was the case in our first installation example (see Basic Installation).
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. The expression
parallel build is misleading: the word parallel is a
reference to the way the build tree shadows the source tree, it is not
about some concurrency in the way build commands are run. For this
reason we refer to such setups using the name VPATH builds in
the following. VPATH is the name of the make feature
used by the Makefiles to allow these builds (see VPATH: Search Path for All Prerequisites).
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
...
With network file systems, a similar approach can be used to build the
same sources on different machines. For instance, suppose that the
sources are installed on a directory shared by two hosts: HOST1
and HOST2, which may be different platforms.
~ % cd /nfs/src
/nfs/src % tar zxf ~/amhello-1.0.tar.gz
On the first host, you could create a local build directory:
[HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
[HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure
...
[HOST1] /tmp/amh % make && sudo make install
...
(Here we assume that the installer has configured sudo so it
can execute make install with root privileges; it is more convenient
than using su like in Basic Installation).
On the second host, you would do exactly the same, possibly at the same time:
[HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh
[HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure
...
[HOST2] /tmp/amh % make && sudo make install
...
In this scenario, nothing forbids the /nfs/src/amhello-1.0 directory from being read-only. In fact VPATH builds are also a means of building packages from a read-only medium such as a CD-ROM. (The FSF used to sell CD-ROM with unpacked source code, before the GNU project grew so big.)
In our last example (see VPATH Builds), a source tree was shared by two hosts, but compilation and installation were done separately on each host.
The GNU Build System also supports networked setups where part of the installed files should be shared amongst multiple hosts. It does so by distinguishing architecture-dependent files from architecture-independent files, and providing two Makefile targets to install each of these classes of files.
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.
From the GNU Build System point of view, the distinction between
architecture-dependent files and architecture-independent files is
based exclusively on the directory variable used to specify their
installation destination. 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.
Here is how we could revisit our two-host installation example, assuming that (1) we want to install the package directly in /usr, and (2) the directory /usr/share is shared by the two hosts.
On the first host we would run
[HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
[HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr
...
[HOST1] /tmp/amh % make && sudo make install
...
On the second host, however, we need only install the architecture-specific files.
[HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh
[HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr
...
[HOST2] /tmp/amh % make && sudo make install-exec
...
In packages that have installation checks, it would make sense to run
make installcheck (see Basic Installation) to verify that
the package works correctly despite the apparent partial installation.
To cross-compile is to build on one platform a binary that will run on another platform. 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:
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.
For instance when installing GCC, the GNU Compiler Collection, we can use --target=TARGET to specify that we want to build GCC as a cross-compiler for TARGET. Mixing --build and --target, we can actually cross-compile a cross-compiler; such a three-way cross-compilation is known as a Canadian cross.
See Specifying the System Type, for more information about these configure options.
The GNU Build System provides means to automatically rename executables and manpages before they are installed (see Man Pages). This is especially convenient when installing a GNU package on a system that already has a proprietary implementation you do not want to overwrite. For instance, you may want to install GNU tar as gtar so you can distinguish it from your vendor's tar.
This can be done using one of these three configure options.
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
...
The GNU Build System's make install and make uninstall
interface does not exactly fit the needs of a system administrator
who has to deploy and upgrade packages on lots of hosts. In other
words, the GNU Build System does not replace a package manager.
Such package managers usually need to know which files have been
installed by a package, so a mere make install is
inappropriate.
The DESTDIR variable can be used to perform a staged
installation. The package should be configured as if it was going to
be installed in its final location (e.g., --prefix /usr), but
when running make install, the DESTDIR should be set to
the absolute name of a directory into which the installation will be
diverted. From this directory it is easy to review which files are
being installed where, and finally copy them to their final location
by some means.
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.)
Note that when building packages for several architectures, it might
be convenient to use make install-data and make
install-exec (see Two-Part Install) to gather
architecture-independent files in a single package.
See Install, for more information.
We have already mentioned make dist. This target collects all
your source files and the necessary parts of the build system to
create a tarball named package-version.tar.gz.
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:
make, make check, make install, as well as
make installcheck, and even make dist,
make clean, make distclean, and make
uninstall do not omit any file (see Standard Targets),
DESTDIR installations work (see DESTDIR).
All of these actions are performed in a temporary subdirectory, so that no root privileges are required.
Releasing a package that fails make distcheck means that one of
the scenarios we presented will not work and some users will be
disappointed. Therefore it is a good practice to release a package
only after a successful make distcheck. This of course does
not imply that the package will be flawless, but at least it will
prevent some of the embarrassing errors you may find in packages
released by people who have never heard about distcheck (like
DESTDIR not working because of a typo, or a distributed file
being erased by make clean, or even VPATH builds not
working).
See Creating amhello, to recreate amhello-1.0.tar.gz using
make distcheck. See Checking the Distribution, for more
information about distcheck.
Dependency tracking is performed as a side-effect of compilation. Each time the build system compiles a source file, it computes its list of dependencies (in C these are the header files included by the source being compiled). Later, any time make is run and a dependency appears to have changed, the dependent files will be rebuilt.
When configure is executed, you can see it probing each compiler for the dependency mechanism it supports (several mechanisms can be used):
~/amhello-1.0 % ./configure --prefix /usr
...
checking dependency style of gcc... gcc3
...
Because dependencies are only computed as a side-effect of the
compilation, no dependency information exists the first time a package
is built. This is OK because all the files need to be built anyway:
make does not have to decide which files need to be rebuilt.
In fact, dependency tracking is completely useless for one-time builds
and there is a configure option to disable this:
Some compilers do not offer any practical way to derive the list of dependencies as a side-effect of the compilation, requiring a separate run (maybe of another tool) to compute these dependencies. The performance penalty implied by these methods is important enough to disable them by default. The option --enable-dependency-tracking must be passed to configure to activate them.
See Dependency Tracking Evolution, for some discussion about the different dependency tracking schemes used by Automake over the years.
Although nesting packages isn't something we would recommend to someone who is discovering the Autotools, it is a nice feature worthy of mention in this small advertising tour.
Autoconfiscated packages (that means packages whose build system have been created by Autoconf and friends) can be nested to arbitrary depth.
A typical setup is that package A will distribute one of the libraries it needs in a subdirectory. This library B is a complete package with its own GNU Build System. The configure script of A will run the configure script of B as part of its execution, building and installing A will also build and install B. Generating a distribution for A will also include B.
It is possible to gather several package like this. GCC is a heavy user of this feature. This gives installers a single package to configure, build and install, while it allows developers to work on subpackages independently.
When configuring nested packages, the configure options given to the top-level configure are passed recursively to nested configures. A package that does not understand an option will ignore it, assuming it is meaningful to some other package.
The command configure --help=recursive can be used to display
the options supported by all the included packages.
See Subpackages, for an example setup.
There are several reasons why you may not want to implement the GNU Build System yourself (read: write a configure script and Makefiles yourself).
The GNU Autotools take all this burden off your back and provide:
Yet there also exist reasons why you may want NOT to use the Autotools... For instance you may be already using (or used to) another incompatible build system. Autotools will only be useful if you do accept the concepts of the GNU Build System. People who have their own idea of how a build system should work will feel frustrated by the Autotools.
In this section we recreate the amhello-1.0 package from scratch. The first subsection shows how to call the Autotools to instantiate the GNU Build System, while the second explains the meaning of the configure.ac and Makefile.am files read by the Autotools.
Here is how we can recreate amhello-1.0.tar.gz from scratch. The package is simple enough so that we will only need to write 5 files. (You may copy them from the final amhello-1.0.tar.gz that is distributed with Automake if you do not want to write them.)
Create the following files in an empty directory.
~/amhello % cat src/main.c
#include <config.h>
#include <stdio.h>
int
main (void)
{
puts ("Hello World!");
puts ("This is " PACKAGE_STRING ".");
return 0;
}
~/amhello % cat README
This is a demonstration package for GNU Automake.
Type `info Automake' to read the Automake manual.
~/amhello % cat src/Makefile.am
bin_PROGRAMS = hello
hello_SOURCES = main.c
~/amhello % cat Makefile.am
SUBDIRS = src
dist_doc_DATA = README
~/amhello % cat 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
Once you have these five files, it is time to run the Autotools to instantiate the build system. 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'
At this point the build system is complete.
In addition to the three scripts mentioned in its output, you can see that autoreconf created four other files: configure, config.h.in, Makefile.in, and src/Makefile.in. The latter three files are templates that will be adapted to the system by configure under the names config.h, Makefile, and src/Makefile. Let's do this:
~/amhello % ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking for gcc... gcc
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables...
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking for style of include used by make... GNU
checking dependency style of gcc... gcc3
configure: creating ./config.status
config.status: creating Makefile
config.status: creating src/Makefile
config.status: creating config.h
config.status: executing depfiles commands
You can see Makefile, src/Makefile, and config.h being created at the end after configure has probed the system. It is now possible to run all the targets we wish (see Standard Targets). For instance:
~/amhello % make
...
~/amhello % src/hello
Hello World!
This is amhello 1.0.
~/amhello % make distcheck
...
=============================================
amhello-1.0 archives ready for distribution:
amhello-1.0.tar.gz
=============================================
Note that running autoreconf is only needed initially when the GNU Build System does not exist. When you later change some instructions in a Makefile.am or configure.ac, the relevant part of the build system will be regenerated automatically when you execute make.
autoreconf is a script that calls autoconf, automake, and a bunch of other commands in the right order. If you are beginning with these tools, it is not important to figure out in which order all these tools should be invoked and why. However, because Autoconf and Automake have separate manuals, the important point to understand is that autoconf is in charge of creating configure from configure.ac, while automake is in charge of creating Makefile.ins from Makefile.ams and configure.ac. This should at least direct you to the right manual when seeking answers.
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
This file is read by both autoconf (to create configure) and automake (to create the various Makefile.ins). It contains a series of M4 macros that will be expanded as shell code to finally form the configure script. We will not elaborate on the syntax of this file, because the Autoconf manual has a whole section about it (see Writing configure.ac).
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 first two lines of configure.ac initialize Autoconf and
Automake. AC_INIT takes in as parameters the name of the package,
its version number, and a contact address for bug-reports about the
package (this address is output at the end of ./configure
--help, for instance). When adapting this setup to your own package,
by all means please do not blindly copy Automake's address: use the
mailing list of your package, or your own mail address.
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. We are speaking of Automake warnings
here, such as dubious instructions in Makefile.am. This has
absolutely nothing to do with how the compiler will be called, even
though it may support options with similar names. Using -Wall
-Werror is a safe setting when starting to work on a package: you do
not want to miss any issues. Later you may decide to relax things a
bit. The foreign option tells Automake that this package
will not follow the GNU Standards. GNU packages should always
distribute additional files such as ChangeLog, AUTHORS,
etc. We do not want automake to complain about these
missing files in our small example.
The AC_PROG_CC line causes the configure script to
search for a C compiler and define the variable CC with its
name. The src/Makefile.in file generated by Automake uses the
variable CC to build hello, so when configure
creates src/Makefile from src/Makefile.in, it will define
CC with the value it has found. If Automake is asked to create
a Makefile.in that uses CC but configure.ac does
not define it, it will suggest you add a call to AC_PROG_CC.
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. In our
case, the AC_INIT macro already defined a few of them. Here
is an excerpt of config.h after configure has run:
...
/* Define to the address where bug reports for this package should be sent. */
#define PACKAGE_BUGREPORT "bug-automake@gnu.org"
/* Define to the full name and version of this package. */
#define PACKAGE_STRING "amhello 1.0"
...
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.
The AC_CONFIG_FILES macro declares the list of files that
configure should create from their *.in templates.
Automake also scans this list to find the Makefile.am files it must
process. (This is important to remember: when adding a new directory
to your project, you should add its Makefile to this list,
otherwise Automake will never process the new Makefile.am you
wrote in that directory.)
Finally, the AC_OUTPUT line is a closing command that actually
produces the part of the script in charge of creating the files
registered with AC_CONFIG_HEADERS and AC_CONFIG_FILES.
When starting a new project, we suggest you start with such a simple configure.ac, and gradually add the other tests it requires. The command autoscan can also suggest a few of the tests your package may need (see Using autoscan to Create configure.ac).
We now turn to src/Makefile.am. This file contains Automake instructions to build and install hello.
bin_PROGRAMS = hello
hello_SOURCES = main.c
A Makefile.am has the same syntax as an ordinary Makefile. When automake processes a Makefile.am it copies the entire file into the output Makefile.in (that will be later turned into Makefile by configure) but will react to certain variable definitions by generating some build rules and other variables. Often Makefile.ams contain only a list of variable definitions as above, but they can also contain other variable and rule definitions that automake will pass along without interpretation.
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. Recall that the GNU Build System uses a set of variables
to denote destination directories and allow users to customize these
locations (see Standard Directory Variables). Any such directory
variable can be put in front of a primary (omitting the dir
suffix) to tell automake where to install the listed files.
Programs need to be built from source files, so for each program
prog listed in a _PROGRAMS variable,
automake will look for another variable named
prog_SOURCES listing its source files. There may be more
than one source file: they will all be compiled and linked together.
Automake also knows that source files need to be distributed when
creating a tarball (unlike built programs). So a side-effect of this
hello_SOURCES declaration is that main.c will be
part of the tarball created by make dist.
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. So this line is responsible for make building
src/hello even though we run it from the top-level. This line
also causes make install to install src/hello before
installing README (not that this order matters).
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. However, for README it would not have been
necessary: automake automatically distributes any
README file it encounters (the list of other files
automatically distributed is presented by automake --help).
The only important effect of this second line is therefore to install
README during make install.
The following sections cover a few basic ideas that will help you understand how Automake works.
Automake works by reading a Makefile.am and generating a
Makefile.in. Certain variables and rules defined in the
Makefile.am instruct Automake to generate more specialized code;
for instance, a bin_PROGRAMS variable definition will cause rules
for compiling and linking programs to be generated.
The variable definitions and rules in the Makefile.am are
copied verbatim into the generated file. This allows you to add
arbitrary code into the generated Makefile.in. For instance,
the Automake distribution includes a non-standard rule for the
git-dist target, which the Automake maintainer uses to make
distributions from his source control system.
Note that most GNU make extensions are not recognized by Automake. Using such extensions in a Makefile.am will lead to errors or confusing behavior.
A special exception is that the GNU make append operator, ‘+=’, is supported. This operator appends its right hand argument to the variable specified on the left. Automake will translate the operator into an ordinary ‘=’ operator; ‘+=’ will thus work with any make program.
Further note that variable assignments should not be indented with <TAB> characters, use spaces if necessary. On the other hand, rule commands should be indented with a leading <TAB> character.
Automake tries to keep comments grouped with any adjoining rules or variable definitions.
A rule defined in Makefile.am generally overrides any such rule of a similar name that would be automatically generated by automake. Although this is a supported feature, it is generally best to avoid making use of it, as sometimes the generated rules are very particular.
Similarly, a variable defined in Makefile.am or
AC_SUBSTed from configure.ac will override any
definition of the variable that automake would ordinarily
create. This feature is more often useful than the ability to
override a rule. Be warned that many of the variables generated by
automake are considered to be for internal use only, and their
names might change in future releases.
When examining a variable definition, Automake will recursively examine
variables referenced in the definition. For example, if Automake is
looking at the content of foo_SOURCES in this snippet
xs = a.c b.c
foo_SOURCES = c.c $(xs)
it would use the files a.c, b.c, and c.c as the
contents of foo_SOURCES.
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.
It is customary to make the first line of Makefile.am read:
## Process this file with automake to produce Makefile.in
While Automake is intended to be used by maintainers of GNU packages, it does make some effort to accommodate those who wish to use it, but do not want to use all the GNU conventions.
To this end, Automake supports three levels of strictness—the strictness indicating how stringently Automake should check standards conformance.
The valid strictness levels are:
See Gnits, for more information on the precise implications of the strictness level.
Automake also has a special “cygnus” mode that is similar to strictness but handled differently. This mode is useful for packages that are put into a “Cygnus” style tree (e.g., the GCC tree). See Cygnus, for more information on this mode.
Automake variables generally follow a uniform naming scheme that makes it easy to decide how programs (and other derived objects) are built, and how they are installed. This scheme also supports configure time determination of what should be built.
At make time, certain variables are used to determine which objects are to be built. The variable names are made of several pieces that are concatenated together.
The piece that tells automake what is being built is commonly called
the primary. For instance, the primary PROGRAMS holds a
list of programs that are to be compiled and linked.
A different set of names is used to decide where the built objects
should be installed. These names are prefixes to the primary, and they
indicate which standard directory should be used as the installation
directory. The standard directory names are given in the GNU standards
(see Directory Variables).
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 what configure decides. This variable is required because Automake must statically know the entire list of objects that may be built in order to generate a Makefile.in that will work in all cases.
For instance, cpio decides 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’.
Not every sort of object can be installed in every directory. Automake will flag those attempts it finds in error. Automake will also diagnose obvious misspellings in directory names.
Sometimes the standard directories—even as augmented by Automake—are not enough. In particular it is sometimes useful, for clarity, to install objects in a subdirectory of some predefined directory. To this end, Automake allows you to extend the list of possible installation directories. A given prefix (e.g., ‘zar’) is valid if a variable of the same name with ‘dir’ appended is defined (e.g., ‘zardir’).
For instance, the following snippet will install file.xml into ‘$(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 of automake'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).
Traditionally, most unix-like systems have a length limitation for the command line arguments and environment contents when creating new processes (see for example http://www.in-ulm.de/~mascheck/various/argmax/ for an overview on this issue), which of course also applies to commands spawned by make. POSIX requires this limit to be at least 4096 bytes, and most modern systems have quite high limits (or are unlimited).
In order to create portable Makefiles that do not trip over these limits, it is necessary to keep the length of file lists bounded. Unfortunately, it is not possible to do so fully transparently within Automake, so your help may be needed. Typically, you can split long file lists manually and use different installation directory names for each list. For example,
data_DATA = file1 ... fileN fileN+1 ... file2N
may also be written as
data_DATA = file1 ... fileN
data2dir = $(datadir)
data2_DATA = fileN+1 ... file2N
and will cause Automake to treat the two lists separately during
make install. See The Two Parts of Install for choosing
directory names that will keep the ordering of the two parts of
installation Note that make dist may still only work on a host
with a higher length limit in this example.
Automake itself employs a couple of strategies to avoid long command
lines. For example, when ‘${srcdir}/’ is prepended to file
names, as can happen with above $(data_DATA) lists, it limits
the amount of arguments passed to external commands.
Unfortunately, some system's make commands may prepend
VPATH prefixes like ‘${srcdir}/’ to file names from the
source tree automatically (see Automatic Rule Rewriting). In this case, the user
may have to switch to use GNU Make, or refrain from using VPATH builds,
in order to stay below the length limit.
For libraries and programs built from many sources, convenience archives may be used as intermediates in order to limit the object list length (see Libtool Convenience Libraries).
Sometimes a Makefile variable name is derived from some text the maintainer supplies. For instance, a program name listed in ‘_PROGRAMS’ is rewritten into the name of a ‘_SOURCES’ variable. In cases like this, Automake canonicalizes the text, so that program names and the like do not have to follow Makefile variable naming rules. All characters in the name except for letters, numbers, the strudel (@), and the underscore are turned into underscores when making variable references.
For example, if your program is named sniff-glue, the derived variable name would be ‘sniff_glue_SOURCES’, not ‘sniff-glue_SOURCES’. Similarly the sources for a library named libmumble++.a should be listed in the ‘libmumble___a_SOURCES’ variable.
The strudel is an addition, to make the use of Autoconf substitutions in variable names less obfuscating.
Some Makefile variables are reserved by the GNU Coding Standards
for the use of the “user”—the person building the package. For
instance, CFLAGS is one such variable.
Sometimes package developers are tempted to set user variables such as
CFLAGS because it appears to make their job easier. However,
the package itself should never set a user variable, particularly not
to include switches that are required for proper compilation of the
package. Since these variables are documented as being for the
package builder, that person rightfully expects to be able to override
any of these variables at build time.
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 the Makefile.am and configure.ac
files—may adjust these shadow variables however necessary.
See Flag Variables Ordering, for more discussion about these variables and how they interact with per-target variables.
Automake sometimes requires helper programs so that the generated Makefile can do its work properly. There are a fairly large number of them, and we list them here.
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.cansi2knr.1compileconfig.guessconfig.subconfig-ml.indepcompelisp-compinstall-shmdate-shmissingmkinstalldirsFor backward compatibility mkinstalldirs is still used and
distributed when automake finds it in a package. But it is no
longer installed automatically, and it should be safe to remove it.
py-compilesymlink-treetexinfo.texylwrapThis section contains two small examples.
The first example (see Complete) assumes you have an existing project already using Autoconf, with handcrafted Makefiles, and that you want to convert it to using Automake. If you are discovering both tools, it is probably better that you look at the Hello World example presented earlier (see Hello World).
The second example (see true) shows how two programs can be built from the same file, using different compilation parameters. It contains some technical digressions that are probably best skipped on first read.
Let's suppose you just finished writing zardoz, a program to make
your head float from vortex to vortex. You've been using Autoconf to
provide a portability framework, but your Makefile.ins have been
ad-hoc. You want to make them bulletproof, so you turn to Automake.
The first step is to update your configure.ac to include the
commands that automake needs. The way to do this is to add an
AM_INIT_AUTOMAKE call just after AC_INIT:
AC_INIT([zardoz], [1.0])
AM_INIT_AUTOMAKE
...
Since your program doesn't have any complicating factors (e.g., it
doesn't use gettext, it doesn't want to build a shared library),
you're done with this part. That was easy!
Now you must regenerate configure. But to do that, you'll need to tell autoconf how to find the new macro you've used. The easiest way to do this is to use the aclocal program to generate your aclocal.m4 for you. But wait... maybe you already have an aclocal.m4, because you had to write some hairy macros for your program. The aclocal program lets you put your own macros into acinclude.m4, so simply rename and then run:
mv aclocal.m4 acinclude.m4
aclocal
autoconf
Now it is time to write your Makefile.am for zardoz.
Since zardoz is a user program, you want to install it where the
rest of the user programs go: bindir. Additionally,
zardoz has some Texinfo documentation. Your configure.ac
script uses AC_REPLACE_FUNCS, so you need to link against
‘$(LIBOBJS)’. So here's what you'd write:
bin_PROGRAMS = zardoz
zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
zardoz_LDADD = $(LIBOBJS)
info_TEXINFOS = zardoz.texi
Now you can run ‘automake --add-missing’ to generate your Makefile.in and grab any auxiliary files you might need, and you're done!
Here is another, trickier example. It shows how to generate two
programs (true and false) from the same source file
(true.c). The difficult part is that each compilation of
true.c requires different cpp flags.
bin_PROGRAMS = true false
false_SOURCES =
false_LDADD = false.o
true.o: true.c
$(COMPILE) -DEXIT_CODE=0 -c true.c
false.o: true.c
$(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
Note that there is no true_SOURCES definition. Automake will
implicitly assume that there is a source file named true.c
(see Default _SOURCES), and
define rules to compile true.o and link true. The
‘true.o: true.c’ rule supplied by the above Makefile.am,
will override the Automake generated rule to build true.o.
false_SOURCES is defined to be empty—that way no implicit value
is substituted. Because we have not listed the source of
false, we have to tell Automake how to link the program. This is
the purpose of the false_LDADD line. A false_DEPENDENCIES
variable, holding the dependencies of the false target will be
automatically generated by Automake from the content of
false_LDADD.
The above rules won't work if your compiler doesn't accept both -c and -o. The simplest fix for this is to introduce a bogus dependency (to avoid problems with a parallel make):
true.o: true.c false.o
$(COMPILE) -DEXIT_CODE=0 -c true.c
false.o: true.c
$(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
Also, these explicit rules do not work if the obsolete de-ANSI-fication feature is used (see ANSI). Supporting de-ANSI-fication requires a little more work:
true_.o: true_.c false_.o
$(COMPILE) -DEXIT_CODE=0 -c true_.c
false_.o: true_.c
$(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o
As it turns out, there is also a much easier way to do this same task.
Some of the above techniques are useful enough that we've kept the
example in the manual. However if you were to build true and
false in real life, you would probably use per-program
compilation flags, like so:
bin_PROGRAMS = false true
false_SOURCES = true.c
false_CPPFLAGS = -DEXIT_CODE=1
true_SOURCES = true.c
true_CPPFLAGS = -DEXIT_CODE=0
In this case Automake will cause true.c to be compiled twice, with different flags. De-ANSI-fication will work automatically. In this instance, the names of the object files would be chosen by automake; they would be false-true.o and true-true.o. (The name of the object files rarely matters.)
To create all the Makefile.ins for a package, run the automake program in the top level directory, with no arguments. automake will automatically find each appropriate Makefile.am (by scanning configure.ac; see configure) and generate the corresponding Makefile.in. Note that automake has a rather simplistic view of what constitutes a package; it assumes that a package has only one configure.ac, at the top. If your package has multiple configure.acs, then you must run automake in each directory holding a configure.ac. (Alternatively, you may rely on Autoconf's autoreconf, which is able to recurse your package tree and run automake where appropriate.)
You can optionally give automake an argument; .am is appended to the argument and the result is used as the name of the input file. This feature is generally only used to automatically rebuild an out-of-date Makefile.in. Note that automake must always be run from the topmost directory of a project, even if being used to regenerate the Makefile.in in some subdirectory. This is necessary because automake must scan configure.ac, and because automake uses the knowledge that a Makefile.in is in a subdirectory to change its behavior in some cases.
Automake will run autoconf to scan configure.ac and its dependencies (i.e., aclocal.m4 and any included file), therefore autoconf must be in your PATH. If there is an AUTOCONF variable in your environment it will be used instead of autoconf, this allows you to select a particular version of Autoconf. By the way, don't misunderstand this paragraph: automake runs autoconf to scan your configure.ac, this won't build configure and you still have to run autoconf yourself for this purpose.
automake accepts the following options:
-a--add-missingAC_CANONICAL_HOST. Automake is distributed with several of these
files (see Auxiliary Programs); this option will cause the missing
ones to be automatically added to the package, whenever possible. In
general if Automake tells you a file is missing, try using this option.
By default Automake tries to make a symbolic link pointing to its own
copy of the missing file; this can be changed with --copy.
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).
In some strictness modes, additional files are installed, see Gnits
for more information.
--libdir=dir-c--copy--cygnus-f--force-missing--foreign--gnits--gnu--help-i--ignore-deps--include-deps--no-force-o dir--output-dir=dir-v--verbose--version-W CATEGORY--warnings=categorygnuobsoleteoverrideportabilitysyntaxunsupportedallnoneerrorA category can be turned off by prefixing its name with ‘no-’. For instance, -Wno-syntax will hide the warnings about unused variables.
The categories output by default are ‘syntax’ and ‘unsupported’. Additionally, ‘gnu’ and ‘portability’ are enabled in --gnu and --gnits strictness. On the other hand, the silent-rules options (see Options) turns off portability warnings about recursive variable expansions.
The environment variable WARNINGS can contain a comma separated list of categories to enable. It will be taken into account before the command-line switches, this way -Wnone will also ignore any warning category enabled by WARNINGS. This variable is also used by other tools like autoconf; unknown categories are ignored for this reason.
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. This is an experimental feature.
Automake scans the package's configure.ac to determine certain information about the package. Some autoconf macros are required and some variables must be defined in configure.ac. Automake will also use information from configure.ac to further tailor its output.
Automake also supplies some Autoconf macros to make the maintenance easier. These macros can automatically be put into your aclocal.m4 using the aclocal program.
The one real requirement of Automake is that your configure.ac
call 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_FILESAC_OUTPUT ...
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 generated Makefile if there exists a file with the same name and the .am extension appended. Typically, ‘AC_CONFIG_FILES([foo/Makefile])’ will cause Automake to generate foo/Makefile.in if foo/Makefile.am exists.
When using AC_CONFIG_FILES with multiple input files, as in
AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
automake will generate the first .in input file for which a .am file exists. If no such file exists the output file is not considered to be generated by Automake.
Files created by AC_CONFIG_FILES, be they Automake
Makefiles or not, are all removed by ‘make distclean’.
Their inputs are automatically distributed, unless they
are the output of prior AC_CONFIG_FILES commands.
Finally, rebuild rules are generated in the Automake Makefile
existing in the subdirectory of the output file, if there is one, or
in the top-level Makefile otherwise.
The above machinery (cleaning, distributing, and rebuilding) works
fine if the AC_CONFIG_FILES specifications contain only
literals. If part of the specification uses shell variables,
automake will not be able to fulfill this setup, and you will
have to complete the missing bits by hand. For instance, on
file=input
...
AC_CONFIG_FILES([output:$file],, [file=$file])
automake will output rules to clean output, and rebuild it. However the rebuild rule will not depend on input, and this file will not be distributed either. (You must add ‘EXTRA_DIST = input’ to your Makefile.am if input is a source file.)
Similarly
file=output
file2=out:in
...
AC_CONFIG_FILES([$file:input],, [file=$file])
AC_CONFIG_FILES([$file2],, [file2=$file2])
will only cause input to be distributed. No file will be cleaned automatically (add ‘DISTCLEANFILES = output out’ yourself), and no rebuild rule will be output.
Obviously automake cannot guess what value ‘$file’ is
going to hold later when configure is run, and it cannot use
the shell variable ‘$file’ in a Makefile. However, if you
make reference to ‘$file’ as ‘${file}’ (i.e., in a way
that is compatible with make's syntax) and furthermore use
AC_SUBST to ensure that ‘${file}’ is meaningful in a
Makefile, then automake will be able to use
‘${file}’ to generate all these rules. For instance, here is
how the Automake package itself generates versioned scripts for its
test suite:
AC_SUBST([APIVERSION], ...)
...
AC_CONFIG_FILES(
[tests/aclocal-${APIVERSION}:tests/aclocal.in],
[chmod +x tests/aclocal-${APIVERSION}],
[APIVERSION=$APIVERSION])
AC_CONFIG_FILES(
[tests/automake-${APIVERSION}:tests/automake.in],
[chmod +x tests/automake-${APIVERSION}])
Here cleaning, distributing, and rebuilding are done automatically, because ‘${APIVERSION}’ is known at make-time.
Note that you should not use shell variables to declare
Makefile files for which automake must create
Makefile.in. Even AC_SUBST does not help here, because
automake needs to know the file name when it runs in order
to check whether Makefile.am exists. (In the very hairy case
that your setup requires such use of variables, you will have to tell
Automake which Makefile.ins to generate on the command-line.)
It is possible to let automake emit conditional rules for
AC_CONFIG_FILES with the help of AM_COND_IF
(see Optional).
To summarize:
Every time Automake is run it calls Autoconf to trace configure.ac. This way it can recognize the use of certain macros and tailor the generated Makefile.in appropriately. Currently recognized macros and their effects are:
AC_CANONICAL_BUILDAC_CANONICAL_HOSTAC_CANONICAL_TARGETbuild_triplet,
host_triplet and target_triplet are introduced. See
Getting the Canonical System Type.
AC_CONFIG_AUX_DIRIf AC_CONFIG_AUX_DIR is not given, the scripts are looked for in
their standard locations. For mdate-sh,
texinfo.tex, and ylwrap, the standard location is the
source directory corresponding to the current Makefile.am. For
the rest, the standard location is the first one of ., ..,
or ../.. (relative to the top source directory) that provides any
one of the helper scripts. See Finding `configure' Input.
Required files from AC_CONFIG_AUX_DIR are automatically
distributed, even if there is no Makefile.am in this directory.
AC_CONFIG_LIBOBJ_DIRAC_LIBSOURCE (see below) in the directory specified by this
macro.
AC_CONFIG_HEADERSAM_CONFIG_HEADER
(see Macros); this is no longer the case.
As for AC_CONFIG_FILES (see Requirements), parts of the
specification using shell variables will be ignored as far as
cleaning, distributing, and rebuilding is concerned.
AC_CONFIG_LINKSAs for AC_CONFIG_FILES (see Requirements), parts of the
specification using shell variables will be ignored as far as cleaning
and distributing is concerned. (There are no rebuild rules for links.)
AC_LIBOBJAC_LIBSOURCEAC_LIBSOURCESAC_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])’, then
file.c will 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_RANLIBAC_PROG_CXXAC_PROG_OBJCAC_PROG_F77AC_F77_LIBRARY_LDFLAGSAC_FC_SRCEXTAC_FC_SRCEXT to compilation
of files with the respective source extension (see Fortran Compiler Characteristics).
AC_PROG_FCAC_PROG_LIBTOOLAC_PROG_YACCYACC in configure.ac. The former is
preferred (see Particular Program Checks).
AC_PROG_LEXAC_REQUIRE_AUX_FILEAC_REQUIRE_AUX_FILE([file]),
automake will ensure that file exists in the
aux directory, and will complain otherwise. It
will also automatically distribute the file. This macro should be
used by third-party Autoconf macros that require some supporting
files in the aux directory specified with AC_CONFIG_AUX_DIR
above. See Finding configure Input.
AC_SUBSTAM_SUBST_NOTMAKE is also
used for this variable. See Setting Output Variables.
For every substituted variable var, automake will add
a line var = value to each Makefile.in file.
Many Autoconf macros invoke AC_SUBST to set output variables
this way, e.g., AC_PATH_XTRA defines X_CFLAGS and
X_LIBS. Thus, you can access these variables as
$(X_CFLAGS) and $(X_LIBS) in any Makefile.am
if AC_PATH_XTRA is called.
AM_C_PROTOTYPESAM_CONDITIONALAM_COND_IFautomake to detect subsequent access within
configure.ac to a conditional previously introduced with
AM_CONDITIONAL, thus enabling conditional AC_CONFIG_FILES
(see Usage of Conditionals).
AM_GNU_GETTEXTAM_GNU_GETTEXT_INTL_SUBDIRAM_GNU_GETTEXT macro was invoked with a first argument
of ‘external’.
AM_MAINTAINER_MODE([default-mode])MAINTAINER_MODE
conditional, which you can use in your own Makefile.am.
See maintainer-mode.
AM_SUBST_NOTMAKE(var)AC_SUBST([var]). This macro prevents that
definition from Automake. If AC_SUBST has not been called
for this variable, then AM_SUBST_NOTMAKE has no effects.
Preventing variable definitions may be useful for substitution of
multi-line values, where var = @value@ might yield
unintended results.
m4_includem4_include is seldom used by configure.ac authors, but
can appear in aclocal.m4 when aclocal detects that
some required macros come from files local to your package (as opposed
to macros installed in a system-wide directory, see Invoking aclocal).
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; otherwise they will not be seen by autoconf.
The aclocal program will automatically generate aclocal.m4 files based on the contents of configure.ac. This provides a convenient way to get Automake-provided macros, without having to search around. The aclocal mechanism allows other packages to supply their own macros (see Extending aclocal). You can also use it to maintain your own set of custom macros (see Local Macros).
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.
When a file selected by aclocal is located in a subdirectory
specified as a relative search path with aclocal's -I
argument, aclocal assumes the file belongs to the package
and uses m4_include instead of copying it into
aclocal.m4. This makes the package smaller, eases dependency
tracking, and cause the file to be distributed automatically.
(See Local Macros, for an example.) Any macro that is found in a
system-wide directory, or via an absolute search path will be copied.
So use ‘-I `pwd`/reldir’ instead of ‘-I reldir’ whenever
some relative directory need to be considered outside the package.
The contents of acinclude.m4, if this file exists, are also automatically included in aclocal.m4. We recommend against using acinclude.m4 in new packages (see Local Macros).
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 (this can happen when a macro is called conditionally). autom4te is expected to be in the PATH, just as autoconf. Its location can be overridden using the AUTOM4TE environment variable.
aclocal accepts the following options:
--acdir=dir--diff[=command]--dry-run--help-I dir--installWhen this option is used, and only when this option is used,
aclocal will also honor ‘#serial NUMBER’ 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).
--forceThis option forces the update of aclocal.m4 (or the file
specified with --output below) and only this file, it has
absolutely no influence on files that may need to be installed by
--install.
--output=file--print-ac-dir--verbose--version-W CATEGORY--warnings=categorysyntaxunsupportedallnoneerrorAll warnings are output by default.
The environment variable WARNINGS is honored in the same way as it is for automake (see Invoking Automake).
By default, aclocal searches for .m4 files in the following directories, in this order:
1.6.
As an example, suppose that automake-1.6.2 was configured with --prefix=/usr/local. Then, the search path would be:
As explained in (see aclocal Options), there are several options that can be used to change or extend this search path.
The most erroneous option to modify the search path is --acdir=dir, which changes default directory and drops the APIVERSION directory. For example, if one specifies ‘--acdir=/opt/private/’, then the search path becomes:
This option, --acdir, is intended for use by the internal Automake test suite only; it is not ordinarily needed by end-users.
Any extra directories specified using -I options (see aclocal Options) are prepended to this search list. Thus, ‘aclocal -I /foo -I /bar’ results in the following search path:
There is a third mechanism for customizing the search path. If a
dirlist file exists in acdir, then that file is assumed to
contain a list of directory patterns, one per line. aclocal
expands these patterns to directory names, and adds them to the search
list after all other directories. dirlist entries may
use shell wildcards such as ‘*’, ‘?’, or [...].
For example, suppose acdir/dirlist contains the following:
/test1
/test2
/test3*
and that aclocal was called with the ‘-I /foo -I /bar’ options. Then, the search path would be
/foo
/bar
/test1
/test2
and all directories with path names starting with /test3.
If the --acdir=dir option is used, then aclocal will search for the dirlist file in dir. In the ‘--acdir=/opt/private/’ example above, aclocal would look for /opt/private/dirlist. Again, however, the --acdir option is intended for use by the internal Automake test suite only; --acdir is not ordinarily needed by end-users.
dirlist is useful in the following situation: suppose that
automake version 1.6.2 is installed with
‘--prefix=/usr’ by the system vendor. Thus, the default search
directories are
/usr/share/aclocal-1.6/
/usr/share/aclocal/
However, suppose further that many packages have been manually installed on the system, with $prefix=/usr/local, as is typical. In that case, many of these “extra” .m4 files are in /usr/local/share/aclocal. The only way to force /usr/bin/aclocal to find these “extra” .m4 files is to always call ‘aclocal -I /usr/local/share/aclocal’. This is inconvenient. With dirlist, one may create a file /usr/share/aclocal/dirlist containing only the single line
/usr/local/share/aclocal
Now, the “default” search path on the affected system is
/usr/share/aclocal-1.6/
/usr/share/aclocal/
/usr/local/share/aclocal/
without the need for -I options; -I options can be reserved for project-specific needs (my-source-dir/m4/), rather than using it to work around local system-dependent tool installation directories.
Similarly, dirlist can be handy if you have installed a local copy of Automake in your account and want aclocal to look for macros installed at other places on the system.
The aclocal program doesn't have any built-in knowledge of any macros, so it is easy to extend it with your own macros.
This can be used by libraries that want to supply their own Autoconf
macros for use by other programs. For instance, the gettext
library supplies a macro AM_GNU_GETTEXT that should be used by
any package using gettext. When the library is installed, it
installs this macro so that aclocal will find it.
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). The aclocal programs also understands
AC_REQUIRE (see Prerequisite Macros), so it is safe to put each macro in a separate file.
Each file should have no side effects but macro definitions.
Especially, any call to AC_PREREQ should be done inside the
defined macro, not at the beginning of the file.
Starting with Automake 1.8, aclocal will warn about all
underquoted calls to AC_DEFUN. We realize this will annoy a
lot of people, because aclocal was not so strict in the past
and many third party macros are underquoted; and we have to apologize
for this temporary inconvenience. The reason we have to be stricter
is that a future implementation of aclocal (see Future of aclocal) will have to temporarily include all these third party
.m4 files, maybe several times, including even files that are
not actually needed. Doing so should alleviate many problems of the
current implementation, however it requires a stricter style from the
macro authors. Hopefully it is easy to revise the existing macros.
For instance,
# bad style
AC_PREREQ(2.57)
AC_DEFUN(AX_FOOBAR,
[AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
])
should be rewritten as
AC_DEFUN([AX_FOOBAR],
[AC_PREREQ([2.57])dnl
AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
])
Wrapping the AC_PREREQ call inside the macro ensures that
Autoconf 2.57 will not be required if AX_FOOBAR is not actually
used. Most importantly, quoting the first argument of AC_DEFUN
allows the macro to be redefined or included twice (otherwise this
first argument would be expanded during the second definition). For
consistency we like to quote even arguments such as 2.57 that
do not require it.
If you have been directed here by the aclocal diagnostic but are not the maintainer of the implicated macro, you will want to contact the maintainer of that macro. Please make sure you have the latest version of the macro and that the problem hasn't already been reported before doing so: people tend to work faster when they aren't flooded by mails.
Another situation where aclocal is commonly used is to manage macros that are used locally by the package, Local Macros.
Feature tests offered by Autoconf do not cover all needs. People often have to supplement existing tests with their own macros, or with third-party 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. However if it contains numerous macros, it will rapidly become difficult to maintain, and it will be almost impossible to share macros between packages.
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 to aclocal
when aclocal.m4 is to be rebuilt by make. This line is
also used by autoreconf (see Using autoreconf to Update configure Scripts) to run aclocal with suitable
options, or by autopoint (see Invoking the autopoint Program)
and gettextize (see Invoking the gettextize Program) to locate
the place where Gettext's macros should be installed. So even if you
do not really care about the rebuild rules, you should define
ACLOCAL_AMFLAGS.
When ‘aclocal -I m4’ is run, it will build an aclocal.m4
that m4_includes any file from m4/ that defines a
required macro. Macros not found locally will still be searched in
system-wide directories, as explained in Macro Search Path.
Custom macros should be distributed for the same reason that
configure.ac is: so that other people have all the sources of
your package if they want to work on it. Actually, this distribution
happens automatically because all m4_included files are
distributed.
However there is no consensus on the distribution of third-party
macros that your package may use. Many libraries install their own
macro in the system-wide aclocal directory (see Extending aclocal). For instance, Guile ships with a file called
guile.m4 that contains the macro GUILE_FLAGS that can
be used to define setup compiler and linker flags appropriate for
using Guile. Using GUILE_FLAGS in configure.ac will
cause aclocal to copy guile.m4 into
aclocal.m4, but as guile.m4 is not part of the project,
it will not be distributed. Technically, that means a user who
needs to rebuild aclocal.m4 will have to install Guile first.
This is probably OK, if Guile already is a requirement to build the
package. However, if Guile is only an optional feature, or if your
package might run on architectures where Guile cannot be installed,
this requirement will hinder development. An easy solution is to copy
such third-party macros in your local m4/ directory so they get
distributed.
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 to m4/ the first time you run autoreconf. Then the locally installed macros will have precedence over the system-wide installed macros each time aclocal is run again.
One reason why you should keep --install in the flags even after the first run is that when you later edit configure.ac and depend on a new macro, this macro will be installed in your m4/ automatically. Another one is that serial numbers (see Serials) can be used to update the macros in your source tree automatically when new system-wide versions are installed. A serial number should be a single line of the form
#serial NNN
where NNN contains only digits and dots. It should appear in the M4 file before any macro definition. It is a good practice to maintain a serial number for each macro you distribute, even if you do not use the --install option of aclocal: this allows other people to use it.
Because third-party macros defined in *.m4 files are naturally shared between multiple projects, some people like to version them. This makes it easier to tell which of two M4 files is newer. Since at least 1996, the tradition is to use a ‘#serial’ line for this.
A serial number should be a single line of the form
# serial version
where version is a version number containing only digits and dots. Usually people use a single integer, and they increment it each time they change the macro (hence the name of “serial”). Such a line should appear in the M4 file before any macro definition.
The ‘#’ must be the first character on the line, and it is OK to have extra words after the version, as in
#serial version garbage
Normally these serial numbers are completely ignored by aclocal and autoconf, like any genuine comment. However when using aclocal's --install feature, these serial numbers will modify the way aclocal selects the macros to install in the package: if two files with the same basename exist in your search path, and if at least one of them uses a ‘#serial’ line, aclocal will ignore the file that has the older ‘#serial’ line (or the file that has none).
Note that a serial number applies to a whole M4 file, not to any macro it contains. A file can contains multiple macros, but only one serial.
Here is a use case that illustrates the use of --install and
its interaction with serial numbers. Let's assume we maintain a
package called MyPackage, the configure.ac of which requires a
third-party macro AX_THIRD_PARTY defined in
/usr/share/aclocal/thirdparty.m4 as follows:
# serial 1
AC_DEFUN([AX_THIRD_PARTY], [...])
MyPackage uses an m4/ directory to store local macros as explained in Local Macros, and has
ACLOCAL_AMFLAGS = -I m4 --install
in its top-level Makefile.am.
Initially the m4/ directory is empty. The first time we run autoreconf, it will fetch the options to pass to aclocal in Makefile.am, and run ‘aclocal -I m4 --install’. aclocal will notice that
AX_THIRD_PARTY
AX_THIRD_PARTY
AX_THIRD_PARTY
with serial 1.
Because /usr/share/aclocal/thirdparty.m4 is a system-wide macro and aclocal was given the --install option, it will copy this file in m4/thirdparty.m4, and output an aclocal.m4 that contains ‘m4_include([m4/thirdparty.m4])’.
The next time ‘aclocal -I m4 --install’ is run (either via autoreconf, by hand, or from the Makefile rebuild rules) something different happens. aclocal notices that
AX_THIRD_PARTY
AX_THIRD_PARTY
with serial 1.
AX_THIRD_PARTY
with serial 1.
Because both files have the same serial number, aclocal uses the first it found in its search path order (see Macro Search Path). aclocal therefore ignores /usr/share/aclocal/thirdparty.m4 and outputs an aclocal.m4 that contains ‘m4_include([m4/thirdparty.m4])’.
Local directories specified with -I are always searched before system-wide directories, so a local file will always be preferred to the system-wide file in case of equal serial numbers.
Now suppose the system-wide third-party macro is changed. This can happen if the package installing this macro is updated. Let's suppose the new macro has serial number 2. The next time ‘aclocal -I m4 --install’ is run the situation is the following:
AX_THIRD_PARTY
AX_THIRD_PARTY
with serial 1.
AX_THIRD_PARTY
with serial 2.
When aclocal sees a greater serial number, it immediately forgets anything it knows from files that have the same basename and a smaller serial number. So after it has found /usr/share/aclocal/thirdparty.m4 with serial 2, aclocal will proceed as if it had never seen m4/thirdparty.m4. This brings us back to a situation similar to that at the beginning of our example, where no local file defined the macro. aclocal will install the new version of the macro in m4/thirdparty.m4, in this case overriding the old version. MyPackage just had its macro updated as a side effect of running aclocal.
If you are leery of letting aclocal update your local macro, you can run ‘aclocal -I m4 --diff’ to review the changes ‘aclocal -I m4 --install’ would perform on these macros.
Finally, note that the --force option of aclocal has absolutely no effect on the files installed by --install. For instance, if you have modified your local macros, do not expect --install --force to replace the local macros by their system-wide versions. If you want to do so, simply erase the local macros you want to revert, and run ‘aclocal -I m4 --install’.
aclocal is expected to disappear. This feature really should not be offered by Automake. Automake should focus on generating Makefiles; dealing with M4 macros really is Autoconf's job. The fact that some people install Automake just to use aclocal, but do not use automake otherwise is an indication of how that feature is misplaced.
The new implementation will probably be done slightly differently. For instance, it could enforce the m4/-style layout discussed in Local Macros.
We have no idea when and how this will happen. This has been discussed several times in the past, but someone still has to commit to that non-trivial task.
From the user point of view, aclocal's removal might turn out to be painful. There is a simple precaution that you may take to make that switch more seamless: never call aclocal yourself. Keep this guy under the exclusive control of autoreconf and Automake's rebuild rules. Hopefully you won't need to worry about things breaking, when aclocal disappears, because everything will have been taken care of. If otherwise you used to call aclocal directly yourself or from some script, you will quickly notice the change.
Many packages come with a script called bootstrap.sh or autogen.sh, that will just call aclocal, libtoolize, gettextize or autopoint, autoconf, autoheader, and automake in the right order. Actually this is precisely what autoreconf can do for you. If your package has such a bootstrap.sh or autogen.sh script, consider using autoreconf. That should simplify its logic a lot (less things to maintain, yum!), it's even likely you will not need the script anymore, and more to the point you will not call aclocal directly anymore.
For the time being, third-party packages should continue to install public macros into /usr/share/aclocal/. If aclocal is replaced by another tool it might make sense to rename the directory, but supporting /usr/share/aclocal/ for backward compatibility should be really easy provided all macros are properly written (see Extending aclocal).
Automake ships with several Autoconf macros that you can use from your configure.ac. When you use one of them it will be included by aclocal in aclocal.m4.
AM_ENABLE_MULTILIBAM_INIT_AUTOMAKE([OPTIONS])AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])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 every Makefile.am in 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 your configure.ac has:
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 your configure.ac from 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_INIT should 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 the no-define
option, 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_LISPDIRlispdir to the full path to Emacs' site-lisp
directory.
Note that this test assumes the emacs found to be a version
that supports Emacs Lisp (such as gnu Emacs or XEmacs). Other
emacsen can cause this test to hang (some, like old versions of
MicroEmacs, start up in interactive mode, requiring C-x C-c to
exit, which is hardly obvious for a non-emacs user). In most cases,
however, you should be able to use C-c to kill the test. In
order to avoid problems, you can set EMACS to “no” in the
environment, or use the --with-lispdir option to
configure to explicitly set the correct path (if you're sure
you have an emacs that supports Emacs Lisp).
AM_PROG_ASCCAS, and will also set CCASFLAGS if required.
AM_PROG_CC_C_OAC_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_LEXAC_PROG_LEX (see Particular Program Checks), but uses the
missing script on systems that do not have lex.
HP-UX 10 is one such system.
AM_PROG_GCJGCJ and GCJFLAGS. gcj is the Java front-end to the
GNU Compiler Collection.
AM_PROG_UPC([compiler-search-list])UPC
variable. The default compiler-search-list is ‘upcc upc’.
This macro will abort configure if no Unified Parallel C
compiler is found.
AM_SILENT_RULESAM_WITH_DMALLOCWITH_DMALLOC and add -ldmalloc to LIBS.
AM_WITH_REGEXLIBOBJS, and
WITH_REGEX is defined. If --without-regex is given, then
the rx regular expression library is used, and rx.o is put
into LIBOBJS.
Although using some of the following macros was required in past releases, you should not use any of them in new code. Running autoupdate should adjust your configure.ac automatically (see Using autoupdate to Modernize configure.ac).
AM_C_PROTOTYPESU and
ANSI2KNR to the empty string. Otherwise, set U to
‘_’ and ANSI2KNR to ‘./ansi2knr’. Automake uses these
values to implement the obsolete de-ANSI-fication feature.
AM_CONFIG_HEADERAC_CONFIG_HEADERS
today (see Optional).
AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTLTIOCGWINSZ requires <sys/ioctl.h>, then
define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be
found in <termios.h>. This macro is obsolete, you should
use Autoconf's AC_HEADER_TIOCGWINSZ instead.
AM_PROG_MKDIR_Pmkdir_p to one of mkdir -p, install-sh
-d, or mkinstalldirs.
Nowadays Autoconf provides a similar functionality with
AC_PROG_MKDIR_P (see Particular Program Checks), however this defines
the output variable MKDIR_P instead. Therefore
AM_PROG_MKDIR_P has been rewritten as a thin wrapper around
AC_PROG_MKDIR_P to define mkdir_p to the same value as
MKDIR_P for backward compatibility.
If you are using Automake, there is normally no reason to call this
macro, because AM_INIT_AUTOMAKE already does so. However, make
sure that the custom rules in your Makefiles use
$(MKDIR_P) and not $(mkdir_p). Even if both variables
still work, the latter should be considered obsolete.
If you are not using Automake, please call AC_PROG_MKDIR_P
instead of AM_PROG_MKDIR_P.
AM_SYS_POSIX_TERMIOSam_cv_sys_posix_termios to
‘yes’. If not, set the variable to ‘no’. This macro is obsolete,
you should use Autoconf's AC_SYS_POSIX_TERMIOS instead.
The following macros are private macros you should not call directly. They are called by the other public macros when appropriate. Do not rely on them, as they might be changed in a future version. Consider them as implementation details; or better, do not consider them at all: skip this section!
_AM_DEPENDENCIESAM_SET_DEPDIRAM_DEP_TRACKAM_OUTPUT_DEPENDENCY_COMMANDSAM_MAKE_INCLUDEinclude statements. This macro is automatically invoked when
needed; there should be no need to invoke it manually.
AM_PROG_INSTALL_STRIPinstall that can be used to
strip a program at installation time. This macro is automatically
included when required.
AM_SANITY_CHECKAM_INIT_AUTOMAKE.
For simple projects that distribute all files in the same directory it is enough to have a single Makefile.am that builds everything in place.
In larger projects it is common to organize files in different directories, in a tree. For instance one directory per program, per library or per module. The traditional approach is to build these subdirectories recursively: each directory contains its Makefile (generated from Makefile.am), and when make is run from the top level directory it enters each subdirectory in turn to build its contents.
In packages with subdirectories, the top level Makefile.am must
tell Automake which subdirectories are to be built. This is done via
the SUBDIRS variable.
The SUBDIRS variable holds a list of subdirectories in which
building of various sorts can occur. The rules for many targets
(e.g., all) in the generated Makefile will run commands
both locally and in all specified subdirectories. Note that the
directories listed in SUBDIRS are not required to contain
Makefile.ams; only Makefiles (after configuration).
This allows inclusion of libraries from packages that do not use
Automake (such as gettext; see also Third-Party Makefiles).
In packages that use subdirectories, the top-level Makefile.am is often very short. For instance, here is the Makefile.am from the GNU Hello distribution:
EXTRA_DIST = BUGS ChangeLog.O README-alpha
SUBDIRS = doc intl po src tests
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.
By default, Automake generates Makefiles that work depth-first
in postfix order: the subdirectories are built before the current
directory. However, it is possible to change this ordering. You can
do this by putting ‘.’ into SUBDIRS. For instance,
putting ‘.’ first will cause a prefix ordering of
directories.
Using
SUBDIRS = lib src . test
will cause lib/ to be built before src/, then the current directory will be built, finally the test/ directory will be built. It is customary to arrange test directories to be built after everything else since they are meant to test what has been constructed.
All clean rules are run in reverse order of build rules.
It is possible to define the SUBDIRS variable conditionally if,
like in the case of GNU Inetutils, you want to only build a subset of
the entire package.
To illustrate how this works, let's assume we have two directories src/ and opt/. src/ should always be built, but we want to decide in configure whether opt/ will be built or not. (For this example we will assume that opt/ should be built when the variable ‘$want_opt’ was set to ‘yes’.)
Running make should thus recurse into src/ always, and then maybe in opt/.
However ‘make dist’ should always recurse into both src/ and opt/. Because opt/ should be distributed even if it is not needed in the current configuration. This means opt/Makefile should be created unconditionally.
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. Before we illustrate these
two possibilities, let's introduce DIST_SUBDIRS.
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. As we
will see in the next two sections, it is possible to define it
conditionally so that some directory will be omitted from the build.
DIST_SUBDIRS is used in rules that need to recurse in all
directories, even those that have been conditionally left out of the
build. Recall our example where we may not want to build subdirectory
opt/, but yet we want to distribute it? This is where
DIST_SUBDIRS comes into play: ‘opt’ may not appear in
SUBDIRS, but it must appear in DIST_SUBDIRS.
Precisely, DIST_SUBDIRS is used by ‘make
maintainer-clean’, ‘make distclean’ and ‘make dist’. All
other recursive rules use SUBDIRS.
If SUBDIRS is defined conditionally using Automake
conditionals, Automake will define DIST_SUBDIRS automatically
from the possible values of SUBDIRS in all conditions.
If SUBDIRS contains AC_SUBST variables,
DIST_SUBDIRS will not be defined correctly because Automake
does not know the possible values of these variables. In this case
DIST_SUBDIRS needs to be defined manually.
AM_CONDITIONALconfigure 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-level Makefile.am
as follows.
if COND_OPT
MAYBE_OPT = opt
endif
SUBDIRS = src $(MAYBE_OPT)
As you can see, running make will rightly recurse into src/ and maybe opt/.
As you can't see, running ‘make dist’ will recurse into both
src/ and opt/ 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.
AC_SUBSTAnother 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-level Makefile.am should 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.
The semantics of DIST_SUBDIRS are often misunderstood by some
users that try to configure and build subdirectories
conditionally. Here by configuring we mean creating the
Makefile (it might also involve running a nested
configure script: this is a costly operation that explains
why people want to do it conditionally, but only the Makefile
is relevant to the discussion).
The above examples all assume that every Makefile is created,
even in directories that are not going to be built. The simple reason
is that we want ‘make dist’ to distribute even the directories
that are not being built (e.g., platform-dependent code), hence
make dist must recurse into the subdirectory, hence this
directory must be configured and appear in DIST_SUBDIRS.
Building packages that do not configure every subdirectory is a tricky business, and we do not recommend it to the novice as it is easy to produce an incomplete tarball by mistake. We will not discuss this topic in depth here, yet for the adventurous here are a few rules to remember.
|
In order to prevent recursion in some unconfigured directory you
must therefore ensure that this directory does not appear in
DIST_SUBDIRS (and SUBDIRS). For instance, if you define
SUBDIRS conditionally using AC_SUBST and do not define
DIST_SUBDIRS explicitly, it will be default to
‘$(SUBDIRS)’; another possibility is to force DIST_SUBDIRS
= $(SUBDIRS).
Of course, directories that are omitted from DIST_SUBDIRS will
not be distributed unless you make other arrangements for this to
happen (for instance, always running ‘make dist’ in a
configuration where all directories are known to appear in
DIST_SUBDIRS; or writing a dist-hook target to
distribute these directories).
In few packages, unconfigured directories are not even expected to
be distributed. Although these packages do not require the
aforementioned extra arrangements, there is another pitfall. If the
name of a directory appears in SUBDIRS or DIST_SUBDIRS,
automake will make sure the directory exists. Consequently
automake cannot be run on such a distribution when one
directory has been omitted. One way to avoid this check is to use the
AC_SUBST method to declare conditional directories; since
automake does not know the values of AC_SUBST
variables it cannot ensure the corresponding directory exists.
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. For those who haven't read the paper, Miller's main thesis is that recursive make invocations are both slow and error-prone.
Automake provides sufficient cross-directory support 3 to enable you to write a single Makefile.am for a complex multi-directory package.
By default an installable file specified in a subdirectory will have its directory name stripped before installation. For instance, in this example, the header file will be installed as $(includedir)/stdio.h:
include_HEADERS = inc/stdio.h
However, the ‘nobase_’ prefix can be used to circumvent this path stripping. In this example, the header file will be installed as $(includedir)/sys/types.h:
nobase_include_HEADERS = sys/types.h
‘nobase_’ should be specified first when used in conjunction with either ‘dist_’ or ‘nodist_’ (see Fine-grained Distribution Control). For instance:
nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
Finally, note that a variable using the ‘nobase_’ prefix can often be replaced by several variables, one for each destination directory (see Uniform). For instance, the last example could be rewritten as follows:
imagesdir = $(pkgdatadir)/images
soundsdir = $(pkgdatadir)/sounds
dist_images_DATA = images/vortex.pgm
dist_sounds_DATA = sounds/whirl.ogg
This latter syntax makes it possible to change one destination directory without changing the layout of the source tree.
Currently, ‘nobase_*_LTLIBRARIES’ are the only exception to this rule, in that there is no particular installation order guarantee for an otherwise equivalent set of variables without ‘nobase_’ prefix.
In the GNU Build System, packages can be nested to arbitrary depth. This means that a package can embed other packages with their own configure, Makefiles, etc.
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).
Here is an example package for an arm program that links with
a hand library that is a nested package in subdirectory
hand/.
arm's configure.ac:
AC_INIT([arm], [1.0])
AC_CONFIG_AUX_DIR([.])
AM_INIT_AUTOMAKE
AC_PROG_CC
AC_CONFIG_FILES([Makefile])
# Call hand's ./configure script recursively.
AC_CONFIG_SUBDIRS([hand])
AC_OUTPUT
arm's Makefile.am:
# Build the library in the hand subdirectory first.
SUBDIRS = hand
# Include hand's header when compiling this directory.
AM_CPPFLAGS = -I$(srcdir)/hand
bin_PROGRAMS = arm
arm_SOURCES = arm.c
# link with the hand library.
arm_LDADD = hand/libhand.a
Now here is hand's hand/configure.ac:
AC_INIT([hand], [1.2])
AC_CONFIG_AUX_DIR([.])
AM_INIT_AUTOMAKE
AC_PROG_CC
AC_PROG_RANLIB
AC_CONFIG_FILES([Makefile])
AC_OUTPUT
and its hand/Makefile.am:
lib_LIBRARIES = libhand.a
libhand_a_SOURCES = hand.c
When ‘make dist’ is run from the top-level directory it will
create an archive arm-1.0.tar.gz that contains the arm
code as well as the hand subdirectory. This package can be
built and installed like any ordinary package, with the usual
‘./configure && make && make install’ sequence (the hand
subpackage will be built and installed by the process).
When ‘make dist’ is run from the hand directory, it will create a self-contained hand-1.2.tar.gz archive. So although it appears to be embedded in another package, it can still be used separately.
The purpose of the ‘AC_CONFIG_AUX_DIR([.])’ instruction is to
force Automake and Autoconf to search for auxiliary scripts in the
current directory. For instance, this means that there will be two
copies of install-sh: one in the top-level of the arm
package, and another one in the hand/ subdirectory for the
hand package.
The historical default is to search for these auxiliary scripts in
the parent directory and the grandparent directory. So if the
‘AC_CONFIG_AUX_DIR([.])’ line was removed from
hand/configure.ac, that subpackage would share the auxiliary
script of the arm package. This may looks like a gain in size
(a few kilobytes), but it is actually a loss of modularity as the
hand subpackage is no longer self-contained (‘make dist’
in the subdirectory will not work anymore).
Packages that do not use Automake need more work to be integrated this way. See Third-Party Makefiles.
A large part of Automake's functionality is dedicated to making it easy to build programs and libraries.
In order to build a program, you need to tell Automake which sources are part of it, and which libraries it should be linked with.
This section also covers conditional compilation of sources or programs. Most of the comments about these also apply to libraries (see A Library) and libtool libraries (see A Shared Library).
In a directory containing source that gets built into a program (as
opposed to a library or a script), the PROGRAMS primary is used.
Programs can be installed in bindir, sbindir,
libexecdir, pkglibdir, pkglibexecdir, or not at all
(noinst_). They can also be built only for ‘make check’, in
which case the prefix is ‘check_’.
For instance:
bin_PROGRAMS = hello
In this simple case, the resulting Makefile.in will contain code
to generate a program named hello.
Associated with each program are several assisting variables that are named after the program. These variables are all optional, and have reasonable defaults. Each variable, its use, and default is spelled out below; we use the “hello” example throughout.
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
This causes each mentioned .c file to be compiled into the corresponding .o. Then all are linked to produce hello.
If hello_SOURCES is not specified, then it defaults to the single
file hello.c (see Default _SOURCES).
Multiple programs can be built in a single directory. Multiple programs
can share a single source file, which must be listed in each
_SOURCES definition.
Header files listed in a _SOURCES definition will be included in
the distribution but otherwise ignored. In case it isn't obvious, you
should not include the header file generated by configure in a
_SOURCES variable; this file should not be distributed. Lex
(.l) and Yacc (.y) files can also be listed; see Yacc and Lex.
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 (where prog is the name of the
program as it appears in some _PROGRAMS variable, and usually
written in lowercase) to override LDADD. If this variable exists
for a given program, then that program is not linked using LDADD.
For instance, in GNU cpio, pax, cpio and mt are
linked against the library libcpio.a. However, rmt is
built in the same directory, and has no such link requirement. Also,
mt and rmt are only built on certain architectures. Here
is what cpio's src/Makefile.am looks like (abridged):
bin_PROGRAMS = cpio pax $(MT)
libexec_PROGRAMS = $(RMT)
EXTRA_PROGRAMS = mt rmt
LDADD = ../lib/libcpio.a $(INTLLIBS)
rmt_LDADD =
cpio_SOURCES = ...
pax_SOURCES = ...
mt_SOURCES = ...
rmt_SOURCES = ...
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. Each program
depends on the contents of such a variable, but no further
interpretation is done.
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. 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 instead (see Sources).
If prog_DEPENDENCIES is not supplied, it is computed by
Automake. The automatically-assigned value is the contents of
prog_LDADD, with most configure substitutions, -l,
-L, -dlopen and -dlpreopen options removed. The
configure substitutions that are left in are only ‘$(LIBOBJS)’ and
‘$(ALLOCA)’; these are left because it is known that they will not
cause an invalid value for prog_DEPENDENCIES to be
generated.
Conditional Sources shows a situation where _DEPENDENCIES
may be used.
We recommend that you avoid using -l options in LDADD
or prog_LDADD when referring to libraries built by your
package. Instead, write the file name of the library explicitly as in
the above cpio example. Use -l only to list
third-party libraries. If you follow this rule, the default value of
prog_DEPENDENCIES will list all your local libraries and
omit the other ones.
You can't put a configure substitution (e.g., ‘@FOO@’ or
‘$(FOO)’ where FOO is defined via AC_SUBST) into a
_SOURCES variable. The reason for this is a bit hard to
explain, but suffice to say that it simply won't work. Automake will
give an error if you try to do this.
Fortunately there are two other ways to achieve the same result. One is
to use configure substitutions in _LDADD variables, the other is
to use an Automake conditional.
_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, if
hello-linux.c or hello-generic.c were conditionally included
in hello, the Makefile.am would 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 from configure.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
either hello-linux.o or hello-generic.o, and added to
both hello_DEPENDENCIES and hello_LDADD in order to be
built and linked in.
An often simpler way to compile source files conditionally is to use Automake conditionals. For instance, you could use this Makefile.am construct to build the same hello example:
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.ac should setup the LINUX
conditional using AM_CONDITIONAL (see Conditionals).
When using conditionals like this you don't need to use the
EXTRA_ variable, because Automake will examine the contents of
each variable to construct the complete list of source files.
If your program uses a lot of files, you will probably prefer a conditional ‘+=’.
bin_PROGRAMS = hello
hello_SOURCES = hello-common.c
if LINUX
hello_SOURCES += hello-linux.c
else
hello_SOURCES += hello-generic.c
endif
Sometimes it is useful to determine the programs that are to be built
at configure time. For instance, GNU cpio only builds
mt and rmt under special circumstances. The means to
achieve conditional compilation of programs are the same you can use
to compile source files conditionally: substitutions or conditionals.
In this case, you must notify Automake of all the programs that can
possibly be built, but at the same time cause the generated
Makefile.in to use the programs specified by configure.
This is done by having configure substitute values into each
_PROGRAMS definition, while listing all optionally built programs
in EXTRA_PROGRAMS.
bin_PROGRAMS = cpio pax $(MT)
libexec_PROGRAMS = $(RMT)
EXTRA_PROGRAMS = mt rmt
As explained in EXEEXT, Automake will rewrite
bin_PROGRAMS, libexec_PROGRAMS, and
EXTRA_PROGRAMS, appending ‘$(EXEEXT)’ to each binary.
Obviously it cannot rewrite values obtained at run-time through
configure substitutions, therefore you should take care of
appending ‘$(EXEEXT)’ yourself, as in ‘AC_SUBST([MT],
['mt${EXEEXT}'])’.
You can also use Automake conditionals (see Conditionals) to
select programs to be built. In this case you don't have to worry
about ‘$(EXEEXT)’ or EXTRA_PROGRAMS.
bin_PROGRAMS = cpio pax
if WANT_MT
bin_PROGRAMS += mt
endif
if WANT_RMT
libexec_PROGRAMS = rmt
endif
Building a library is much like building a program. In this case, the
name of the primary is LIBRARIES. Libraries can be installed in
libdir or pkglibdir.
See A Shared Library, for information on how to build shared
libraries using libtool and the LTLIBRARIES primary.
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 = ...
The sources that go into a library are determined exactly as they are
for programs, via the _SOURCES variables. Note that the library
name is canonicalized (see Canonicalization), so the _SOURCES
variable corresponding to libcpio.a is ‘libcpio_a_SOURCES’,
not ‘libcpio.a_SOURCES’.
Extra objects can be added to a library using the
library_LIBADD variable. This should be used for objects
determined by configure. Again from cpio:
libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
In addition, sources for extra objects that will not exist until
configure-time must be added to the BUILT_SOURCES variable
(see 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 (see Program and Library Variables).
Be careful when selecting library components conditionally. Because building an empty library is not portable, you should ensure that any library always contains at least one object.
To use a static library when building a program, add it to
LDADD for this program. In the following example, the program
cpio is statically linked with the library libcpio.a.
noinst_LIBRARIES = libcpio.a
libcpio_a_SOURCES = ...
bin_PROGRAMS = cpio
cpio_SOURCES = cpio.c ...
cpio_LDADD = libcpio.a
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.
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. Their exact nature cannot be
determined until ./configure is run: not all platforms support
all kinds of libraries, and users can explicitly select which
libraries should be built. (However the package's maintainers can
tune the default, see The AC_PROG_LIBTOOL macro.)
Because object files for shared and static libraries must be compiled differently, libtool is also used during compilation. Object files built by libtool are called libtool objects: these are files using the .lo suffix. Libtool libraries are built from these libtool objects.
You should not assume anything about the structure of .la or .lo files and how libtool constructs them: this is libtool's concern, and the last thing one wants is to learn about libtool's guts. However the existence of these files matters, because they are used as targets and dependencies in Makefiles rules when building libtool libraries. There are situations where you may have to refer to these, for instance when expressing dependencies for building source files conditionally (see Conditional Libtool Sources).
People considering writing a plug-in system, with dynamically loaded modules, should look into libltdl: libtool's dlopening library (see Using libltdl). This offers a portable dlopening facility to load libtool libraries dynamically, and can also achieve static linking where unavoidable.
Before we discuss how to use libtool with Automake in details, it should be noted that the libtool manual also has a section about how to use Automake with libtool (see Using Automake with Libtool).
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 ...
Automake predefines the variable pkglibdir, so you can use
pkglib_LTLIBRARIES to install libraries in
‘$(libdir)/@PACKAGE@/’.
If gettext.h is a public header file that needs to be installed
in order for people to use the library, it should be declared using a
_HEADERS variable, not in libgettext_la_SOURCES.
Headers listed in the latter should be internal headers that are not
part of the public interface.
lib_LTLIBRARIES = libgettext.la
libgettext_la_SOURCES = gettext.c ...
include_HEADERS = gettext.h ...
A package can build and install such a library along with other
programs that use it. This dependency should be specified using
LDADD. The following example builds a program named
hello that is linked with libgettext.la.
lib_LTLIBRARIES = libgettext.la
libgettext_la_SOURCES = gettext.c ...
bin_PROGRAMS = hello
hello_SOURCES = hello.c ...
hello_LDADD = libgettext.la
Whether hello is statically or dynamically linked with libgettext.la is not yet known: this will depend on the configuration of libtool and the capabilities of the host.
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.
For libraries whose destination directory is known when Automake runs,
Automake will automatically supply the appropriate -rpath
option to libtool. This is the case for libraries listed explicitly in
some installable _LTLIBRARIES variables such as
lib_LTLIBRARIES.
However, for libraries determined at configure time (and thus
mentioned in EXTRA_LTLIBRARIES), Automake does not know the
final installation directory. For such libraries you must add the
-rpath option to the appropriate _LDFLAGS variable by
hand.
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 either libfoo.la,
libbar.la, both, or none. Although ‘$(WANTEDLIBS)’
appears in the lib_LTLIBRARIES, Automake cannot guess it
relates to libfoo.la or libbar.la at the time it creates
the link rule for these two libraries. Therefore the -rpath
argument 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 same Makefile.am would look using Automake
conditionals named WANT_LIBFOO and WANT_LIBBAR. Now
Automake is able to compute the -rpath setting 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 ...
Conditional compilation of sources in a library can be achieved in the
same way as conditional compilation of sources in a program
(see Conditional Sources). The only difference is that
_LIBADD should be used instead of _LDADD and that it
should mention libtool objects (.lo files).
So, to mimic the hello example from Conditional Sources, we could build a libhello.la library using either hello-linux.c or hello-generic.c with the following Makefile.am.
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
libhello_la_LIBADD = $(HELLO_SYSTEM)
libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
And make sure configure defines HELLO_SYSTEM as
either hello-linux.lo or hello-generic.lo.
Or we could simply use an Automake conditional as follows.
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
if LINUX
libhello_la_SOURCES += hello-linux.c
else
libhello_la_SOURCES += hello-generic.c
endif
Sometimes you want to build libtool libraries that should not be installed. These are called libtool convenience libraries and are typically used to encapsulate many sublibraries, later gathered into one big installed library.
Libtool convenience libraries are declared by directory-less variables
such as noinst_LTLIBRARIES, check_LTLIBRARIES, or even
EXTRA_LTLIBRARIES. Unlike installed libtool libraries they do
not need an -rpath flag at link time (actually this is the only
difference).
Convenience libraries listed in noinst_LTLIBRARIES are always
built. Those listed in check_LTLIBRARIES are built only upon
‘make check’. Finally, libraries listed in
EXTRA_LTLIBRARIES are never built explicitly: Automake outputs
rules to build them, but if the library does not appear as a Makefile
dependency anywhere it won't be built (this is why
EXTRA_LTLIBRARIES is used for conditional compilation).
Here is a sample setup merging libtool convenience libraries from subdirectories into one main libtop.la library.
# -- Top-level Makefile.am --
SUBDIRS = sub1 sub2 ...
lib_LTLIBRARIES = libtop.la
libtop_la_SOURCES =
libtop_la_LIBADD = \
sub1/libsub1.la \
sub2/libsub2.la \
...
# -- sub1/Makefile.am --
noinst_LTLIBRARIES = libsub1.la
libsub1_la_SOURCES = ...
# -- sub2/Makefile.am --
# showing nested convenience libraries
SUBDIRS = sub2.1 sub2.2 ...
noinst_LTLIBRARIES = libsub2.la
libsub2_la_SOURCES =
libsub2_la_LIBADD = \
sub21/libsub21.la \
sub22/libsub22.la \
...
When using such setup, beware that automake will assume
libtop.la is to be linked with the C linker. This is because
libtop_la_SOURCES is empty, so automake picks C as
default language. If libtop_la_SOURCES was not empty,
automake would select the linker as explained in How the Linker is Chosen.
If one of the sublibraries contains non-C source, it is important that the appropriate linker be chosen. One way to achieve this is to pretend that there is such a non-C file among the sources of the library, thus forcing automake to select the appropriate linker. Here is the top-level Makefile of our example updated to force C++ linking.
SUBDIRS = sub1 sub2 ...
lib_LTLIBRARIES = libtop.la
libtop_la_SOURCES =
# Dummy C++ source to cause C++ linking.
nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
libtop_la_LIBADD = \
sub1/libsub1.la \
sub2/libsub2.la \
...
‘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 (see Program and Library Variables). In effect the file dummy.cxx does not need to
exist in the source tree. Of course if you have some real source file
to list in libtop_la_SOURCES there is no point in cheating with
nodist_EXTRA_libtop_la_SOURCES.
These are libtool libraries meant to be dlopened. They are indicated to libtool by passing -module at link-time.
pkglib_LTLIBRARIES = mymodule.la
mymodule_la_SOURCES = doit.c
mymodule_la_LDFLAGS = -module
Ordinarily, Automake requires that a library's name start with
lib. However, when building a dynamically loadable module you
might wish to use a "nonstandard" name. Automake will not complain
about such nonstandard names if it knows the library being built is a
libtool module, i.e., if -module explicitly appears in the
library's _LDFLAGS variable (or in the common AM_LDFLAGS
variable when no per-library _LDFLAGS variable is defined).
As always, AC_SUBST variables are black boxes to Automake since
their values are not yet known when automake is run.
Therefore if -module is set via such a variable, Automake
cannot notice it and will proceed as if the library was an ordinary
libtool library, with strict naming.
If mymodule_la_SOURCES is not specified, then it defaults to
the single file mymodule.c (see Default _SOURCES).
_LIBADD, _LDFLAGS, and _LIBTOOLFLAGSAs 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.
The libtool command has two kinds of options: mode-specific options and generic options. Mode-specific options such as the aforementioned linking flags should be lumped with the other flags passed to the tool invoked by libtool (hence the use of ‘library_LDFLAGS’ for libtool linking flags). 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.
These flags are passed to libtool after the --tag=TAG
option computed by Automake (if any), so
‘library_LIBTOOLFLAGS’ (or AM_LIBTOOLFLAGS) is a
good place to override or supplement the --tag=TAG
setting.
The libtool rules also use a LIBTOOLFLAGS variable that should
not be set in Makefile.am: this is a user variable (see Flag Variables Ordering. It allows users to run ‘make
LIBTOOLFLAGS=--silent’, for instance. Note that the verbosity of
libtool can also be influenced with the Automake
silent-rules option (see Options).
LTLIBOBJS and LTALLOCAWhere an ordinary library might include ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ (see LIBOBJS), a libtool library must use ‘$(LTLIBOBJS)’ or ‘$(LTALLOCA)’. This is required because the object files that libtool operates on do not necessarily end in .o.
Nowadays, the computation of LTLIBOBJS from LIBOBJS is
performed automatically by Autoconf (see AC_LIBOBJ vs. LIBOBJS).
Libtool comes with a tool called libtoolize that will install libtool's supporting files into a package. Running this command will install ltmain.sh. You should execute it before aclocal and automake.
People upgrading old packages to newer autotools are likely to face this issue because older Automake versions used to call libtoolize. Therefore old build scripts do not call libtoolize.
Since Automake 1.6, it has been decided that running libtoolize was none of Automake's business. Instead, that functionality has been moved into the autoreconf command (see Using autoreconf). If you do not want to remember what to run and when, just learn the autoreconf command. Hopefully, replacing existing bootstrap.sh or autogen.sh scripts by a call to autoreconf should also free you from any similar incompatible change in the future.
Sometimes, the same source file is used both to build a libtool library and to build another non-libtool target (be it a program or another library).
Let's consider the following Makefile.am.
bin_PROGRAMS = prog
prog_SOURCES = prog.c foo.c ...
lib_LTLIBRARIES = libfoo.la
libfoo_la_SOURCES = foo.c ...
(In this trivial case the issue could be avoided by linking
libfoo.la with prog instead of listing foo.c in
prog_SOURCES. But let's assume we really want to keep
prog and libfoo.la separate.)
Technically, it means that we should build foo.$(OBJEXT) for prog, and foo.lo for libfoo.la. The problem is that in the course of creating foo.lo, libtool may erase (or replace) foo.$(OBJEXT), and this cannot be avoided.
Therefore, when Automake detects this situation it will complain with a message such as
object `foo.$(OBJEXT)' created both with libtool and without
A workaround for this issue is to ensure that these two objects get different basenames. As explained in Renamed Objects, this happens automatically when per-targets flags are used.
bin_PROGRAMS = prog
prog_SOURCES = prog.c foo.c ...
prog_CFLAGS = $(AM_CFLAGS)
lib_LTLIBRARIES = libfoo.la
libfoo_la_SOURCES = foo.c ...
Adding ‘prog_CFLAGS = $(AM_CFLAGS)’ is almost a no-op, because
when the prog_CFLAGS is defined, it is used instead of
AM_CFLAGS. However as a side effect it will cause
prog.c and foo.c to be compiled as
prog-prog.$(OBJEXT) and prog-foo.$(OBJEXT), which solves
the issue.
Associated with each program is a collection of variables that can be used to modify how that program is built. There is a similar list of such variables for each library. The canonical name of the program (or library) is used as a base for naming these variables.
In the list below, we use the name “maude” to refer to the program or library. In your Makefile.am you would replace this with the canonical name of your program. This list also refers to “maude” as a program, but in general the same rules apply for both static and dynamic libraries; the documentation below notes situations where programs and libraries differ.
maude_SOURCES_SOURCES variable has an unrecognized extension, Automake
will do one of two things with it. If a suffix rule exists for turning
files with the unrecognized extension into .o files, then
automake will treat this file as it will any other source file
(see Support for Other Languages). Otherwise, the file will be
ignored as though it were a header file.
The prefixes dist_ and nodist_ can be used to control
whether files listed in a _SOURCES variable are distributed.
dist_ is redundant, as sources are distributed by default, but it
can be specified for clarity if desired.
It is possible to have both dist_ and nodist_ variants of
a given _SOURCES variable at once; this lets you easily
distribute some files and not others, for instance:
nodist_maude_SOURCES = nodist.c
dist_maude_SOURCES = dist-me.c
By default the output file (on Unix systems, the .o file) will
be put into the current build directory. However, if the option
subdir-objects is in effect in the current directory then the
.o file will be put into the subdirectory named after the
source file. For instance, with subdir-objects enabled,
sub/dir/file.c will be compiled to sub/dir/file.o. Some
people prefer this mode of operation. You can specify
subdir-objects in AUTOMAKE_OPTIONS (see Options).
EXTRA_maude_SOURCES_LDADD (see below), then you should list the corresponding source
files in the EXTRA_ variable.
This variable also supports dist_ and nodist_ prefixes.
For instance, nodist_EXTRA_maude_SOURCES would list extra
sources that may need to be built, but should not be distributed.
maude_AR_AR variable. This is usually used with C++; some C++
compilers require a special invocation in order to instantiate all the
templates that should go into a library. For instance, the SGI C++
compiler likes this variable set like so:
libmaude_a_AR = $(CXX) -ar -o
maude_LIBADD_LIBADD
variable. For instance, this should be used for objects determined by
configure (see A Library).
In the case of libtool libraries, maude_LIBADD can also refer
to other libtool libraries.
maude_LDADD_LDADD variable. For instance, this should be used for objects
determined by configure (see Linking).
_LDADD and _LIBADD are inappropriate for passing
program-specific linker flags (except for -l, -L,
-dlopen and -dlpreopen). Use the _LDFLAGS variable
for this purpose.
For instance, if your configure.ac uses AC_PATH_XTRA, you
could link your program against the X libraries like so:
maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
We recommend that you use -l and -L only when
referring to third-party libraries, and give the explicit file names
of any library built by your package. Doing so will ensure that
maude_DEPENDENCIES (see below) is correctly defined by default.
maude_LDFLAGSAM_LDFLAGS variable.
maude_LIBTOOLFLAGSAM_LIBTOOLFLAGS variable.
These options are output before libtool's --mode=MODE
option, so they should not be mode-specific options (those belong to
the compiler or linker flags). See Libtool Flags.
maude_DEPENDENCIES_DEPENDENCIES variable. Each
target depends on the contents of such a variable, but no further
interpretation is done.
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).
If _DEPENDENCIES is not supplied, it is computed by Automake.
The automatically-assigned value is the contents of _LDADD or
_LIBADD, with most configure substitutions, -l, -L,
-dlopen and -dlpreopen options removed. The configure
substitutions that are left in are only ‘$(LIBOBJS)’ and
‘$(ALLOCA)’; these are left because it is known that they will not
cause an invalid value for _DEPENDENCIES to be generated.
_DEPENDENCIES is more likely used to perform conditional
compilation using an AC_SUBST variable that contains a list of
objects. See Conditional Sources, and Conditional Libtool Sources.
maude_LINK_LINK variable must hold the name of a
command that can be passed all the .o file names as arguments.
Note that the name of the underlying program is not passed to
_LINK; typically one uses ‘$@’:
maude_LINK = $(CCLD) -magic -o $@
maude_CCASFLAGSmaude_CFLAGSmaude_CPPFLAGSmaude_CXXFLAGSmaude_FFLAGSmaude_GCJFLAGSmaude_LFLAGSmaude_OBJCFLAGSmaude_RFLAGSmaude_UPCFLAGSmaude_YFLAGSWhen using a per-target compilation flag, Automake will choose a
different name for the intermediate object files. Ordinarily a file
like sample.c will be compiled to produce sample.o.
However, if the program's _CFLAGS variable is set, then the
object file will be named, for instance, maude-sample.o. (See
also Renamed Objects.) The use of per-target compilation flags
with C sources requires that the macro AM_PROG_CC_C_O be called
from configure.ac.
In compilations with per-target flags, the ordinary ‘AM_’ form of
the flags variable is not automatically included in the
compilation (however, the user form of the variable is included).
So for instance, if you want the hypothetical maude compilations
to also use the value of AM_CFLAGS, you would need to write:
maude_CFLAGS = ... your flags ... $(AM_CFLAGS)
See Flag Variables Ordering, for more discussion about the
interaction between user variables, ‘AM_’ shadow variables, and
per-target variables.
maude_SHORTNAME bin_PROGRAMS = maude
maude_CPPFLAGS = -DSOMEFLAG
maude_SHORTNAME = m
maude_SOURCES = sample.c ...
the object file would be named m-sample.o rather than maude-sample.o.
This facility is rarely needed in practice, and we recommend avoiding it until you find it is required.
_SOURCES
_SOURCES variables are used to specify source files of programs
(see A Program), libraries (see A Library), and Libtool
libraries (see A Shared Library).
When no such variable is specified for a target, Automake will define
one itself. The default is to compile a single C file whose base name
is the name of the target itself, with any extension replaced by
AM_DEFAULT_SOURCE_EXT, which defaults to .c.
For example if you have the following somewhere in your
Makefile.am with no corresponding libfoo_a_SOURCES:
lib_LIBRARIES = libfoo.a sub/libc++.a
libfoo.a will be built using a default source file named
libfoo.c, and sub/libc++.a will be built from
sub/libc++.c. (In older versions sub/libc++.a
would be built from sub_libc___a.c, i.e., the default source
was the canonized name of the target, with .c appended.
We believe the new behavior is more sensible, but for backward
compatibility automake will use the old name if a file or a rule
with that name exists and AM_DEFAULT_SOURCE_EXT is not used.)
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, and test3 will be built from test1.cpp, test2.cpp, and test3.cpp. Without the last line, they will be built from test1.c, test2.c, and test3.c.
Another case where this is convenient is building many Libtool modules (moduleN.la), each defined in its own file (moduleN.c).
AM_LDFLAGS = -module
lib_LTLIBRARIES = module1.la module2.la module3.la
Finally, there is one situation where this default source computation
needs to be avoided: when a target should not be built from sources.
We already saw such an example in true; this happens when all
the constituents of a target have already been compiled and just need
to be combined using a _LDADD variable. Then it is necessary
to define an empty _SOURCES variable, so that automake does not
compute a default.
bin_PROGRAMS = target
target_SOURCES =
target_LDADD = libmain.a libmisc.a
LIBOBJS and ALLOCAThe ‘$(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 by configure.
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)’.
Using these variables is very similar to doing conditional compilation
using AC_SUBST variables, as described in Conditional Sources. That is, when building a program, ‘$(LIBOBJS)’ and
‘$(ALLOCA)’ should be added to the associated ‘*_LDADD’
variable, or to the ‘*_LIBADD’ variable when building a library.
However there is no need to list the corresponding sources in
‘EXTRA_*_SOURCES’ nor to define ‘*_DEPENDENCIES’. Automake
automatically adds ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ to the
dependencies, and it will discover the list of corresponding source
files automatically (by tracing the invocations of the
AC_LIBSOURCE Autoconf macros). However, if you have already
defined ‘*_DEPENDENCIES’ explicitly for an unrelated reason, then
you have to add these variables manually.
These variables are usually used to build a portability library that
is linked with all the programs of the project. We now review a
sample setup. First, configure.ac contains some checks that
affect either LIBOBJS or ALLOCA.
# 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
...
AC_CONFIG_FILES([
lib/Makefile
src/Makefile
])
AC_OUTPUT
The AC_CONFIG_LIBOBJ_DIR tells Autoconf that the source files
of these object files are to be found in the lib/ directory.
Automake can also use this information, otherwise it expects the
source files are to be in the directory where the ‘$(LIBOBJS)’
and ‘$(ALLOCA)’ variables are used.
The lib/ directory should therefore contain malloc.c, memcmp.c, strdup.c, alloca.c. Here is its Makefile.am:
# lib/Makefile.am
noinst_LIBRARIES = libcompat.a
libcompat_a_SOURCES =
libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
The library can have any name, of course, and anyway it is not going
to be installed: it just holds the replacement versions of the missing
or broken functions so we can later link them in. Many projects
also include extra functions, specific to the project, in that
library: they are simply added on the _SOURCES line.
There is a small trap here, though: ‘$(LIBOBJS)’ and
‘$(ALLOCA)’ might be empty, and building an empty library is not
portable. You should ensure that there is always something to put in
libcompat.a. Most projects will also add some utility
functions in that directory, and list them in
libcompat_a_SOURCES, so in practice libcompat.a cannot
be empty.
Finally here is how this library could be used from the src/ directory.
# src/Makefile.am
# Link all programs in this directory with libcompat.a
LDADD = ../lib/libcompat.a
bin_PROGRAMS = tool1 tool2 ...
tool1_SOURCES = ...
tool2_SOURCES = ...
When option subdir-objects is not used, as in the above
example, the variables ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ can only
be used in the directory where their sources lie. E.g., here it would
be wrong to use ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ in
src/Makefile.am. However if both subdir-objects and
AC_CONFIG_LIBOBJ_DIR are used, it is OK to use these variables
in other directories. For instance src/Makefile.am could be
changed as follows.
# src/Makefile.am
AUTOMAKE_OPTIONS = subdir-objects
LDADD = $(LIBOBJS) $(ALLOCA)
bin_PROGRAMS = tool1 tool2 ...
tool1_SOURCES = ...
tool2_SOURCES = ...
Because ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ contain object
file names that end with ‘.$(OBJEXT)’, they are not suitable for
Libtool libraries (where the expected object extension is .lo):
LTLIBOBJS and LTALLOCA should be used instead.
LTLIBOBJS is defined automatically by Autoconf and should not
be defined by hand (as in the past), however at the time of writing
LTALLOCA still needs to be defined from ALLOCA manually.
See AC_LIBOBJ vs. LIBOBJS.
Occasionally it is useful to know which Makefile variables Automake uses for compilations, and in which order (see Flag Variables Ordering); for instance, you might need to do your own compilation in some special cases.
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_CPPFLAGSAutomake already provides some -I options automatically, in a
separate variable that is also passed to every compilation that invokes
the C preprocessor. In particular it generates ‘-I.’,
‘-I$(srcdir)’, and a -I pointing to the directory holding
config.h (if you've used AC_CONFIG_HEADERS or
AM_CONFIG_HEADER). You can disable the default -I
options using the nostdinc option.
AM_CPPFLAGS is ignored in preference to a per-executable (or
per-library) _CPPFLAGS variable if it is defined.
INCLUDESAM_CPPFLAGS (or any per-target
_CPPFLAGS variable if it is used). It is an older name for the
same functionality. This variable is deprecated; we suggest using
AM_CPPFLAGS and per-target _CPPFLAGS instead.
AM_CFLAGS_CFLAGS.
COMPILEAM_LDFLAGS_LDFLAGS.
LINKCFLAGS); it takes as “arguments” the names of the object files
and libraries to link in.
Automake has somewhat idiosyncratic support for Yacc and Lex.
Automake assumes that the .c file generated by yacc (or lex) should be named using the basename of the input file. That is, for a yacc source file foo.y, Automake will cause the intermediate file to be named foo.c (as opposed to y.tab.c, which is more traditional).
The extension of a yacc source file is used to determine the extension of the resulting C or C++ file. Files with the extension .y will be turned into .c files; likewise, .yy will become .cc; .y++, c++; .yxx, .cxx; and .ypp, .cpp.
Likewise, lex source files can be used to generate C or C++; the extensions .l, .ll, .l++, .lxx, and .lpp are recognized.
You should never explicitly mention the intermediate (C or C++) file
in any SOURCES variable; only list the source file.
The intermediate files generated by yacc (or lex) will be included in any distribution that is made. That way the user doesn't need to have yacc or lex.
If a yacc source file is seen, then your configure.ac must
define the variable YACC. This is most easily done by invoking
the macro AC_PROG_YACC (see Particular Program Checks).
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.
AM_YFLAGS is usually used to pass the -d option to
yacc. Automake knows what this means and will automatically
adjust its rules to update and distribute the header file built by
‘yacc -d’. What Automake cannot guess, though, is where this
header will be used: it is up to you to ensure the header gets built
before it is first used. Typically this is necessary in order for
dependency tracking to work when the header is included by another
file. The common solution is listing the header file in
BUILT_SOURCES (see Sources) as follows.
BUILT_SOURCES = parser.h
AM_YFLAGS = -d
bin_PROGRAMS = foo
foo_SOURCES = ... parser.y ...
If a lex source file is seen, then your configure.ac
must define the variable LEX. You can use AC_PROG_LEX
to do this (see Particular Program Checks), but using AM_PROG_LEX macro
(see Macros) is recommended.
When lex is invoked, it is passed LFLAGS and
AM_LFLAGS. The former is a user variable and the latter is
intended for the Makefile.am author.
When AM_MAINTAINER_MODE (see maintainer-mode) is used, the
rebuild rule for distributed Yacc and Lex sources are only used when
maintainer-mode is enabled, or when the files have been erased.
When lex or yacc sources are used, automake
-i automatically installs an auxiliary program called
ylwrap in your package (see Auxiliary Programs). This
program is used by the build rules to rename the output of these
tools, and makes it possible to include multiple yacc (or
lex) source files in a single directory. (This is necessary
because yacc's output file name is fixed, and a parallel make could
conceivably invoke more than one instance of yacc
simultaneously.)
For yacc, simply managing locking is insufficient. The output of yacc always uses the same symbol names internally, so it isn't possible to link two yacc parsers into the same executable.
We recommend using the following renaming hack used in gdb:
#define yymaxdepth c_maxdepth
#define yyparse c_parse
#define yylex c_lex
#define yyerror c_error
#define yylval c_lval
#define yychar c_char
#define yydebug c_debug
#define yypact c_pact
#define yyr1 c_r1
#define yyr2 c_r2
#define yydef c_def
#define yychk c_chk
#define yypgo c_pgo
#define yyact c_act
#define yyexca c_exca
#define yyerrflag c_errflag
#define yynerrs c_nerrs
#define yyps c_ps
#define yypv c_pv
#define yys c_s
#define yy_yys c_yys
#define yystate c_state
#define yytmp c_tmp
#define yyv c_v
#define yy_yyv c_yyv
#define yyval c_val
#define yylloc c_lloc
#define yyreds c_reds
#define yytoks c_toks
#define yylhs c_yylhs
#define yylen c_yylen
#define yydefred c_yydefred
#define yydgoto c_yydgoto
#define yysindex c_yysindex
#define yyrindex c_yyrindex
#define yygindex c_yygindex
#define yytable c_yytable
#define yycheck c_yycheck
#define yyname c_yyname
#define yyrule c_yyrule
For each define, replace the ‘c_’ prefix with whatever you like.
These defines work for bison, byacc, and
traditional yaccs. If you find a parser generator that uses a
symbol not covered here, please report the new name so it can be added
to the list.
Automake includes full support for C++.
Any 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:
CXXCXXFLAGSAM_CXXFLAGSCXXFLAGS.
CXXCOMPILECXXLINKAutomake includes some support for Objective C.
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:
OBJCOBJCFLAGSAM_OBJCFLAGSOBJCFLAGS.
OBJCCOMPILEOBJCLINKAutomake includes some support for Unified Parallel C.
Any package including Unified Parallel C code must define the output
variable UPC in configure.ac; the simplest way to do
this is to use the AM_PROG_UPC macro (see Public Macros).
A few additional variables are defined when a Unified Parallel C source file is seen:
UPCUPCFLAGSAM_UPCFLAGSUPCFLAGS.
UPCCOMPILEUPCLINKAutomake includes some support for assembly code. There are two forms
of assembler files: normal (*.s) and preprocessed by CPP
(*.S or *.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 -c and -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.
Only the suffixes .s, .S, and .sx are recognized by automake as being files containing assembly code.
Automake includes full support for Fortran 77.
Any package including Fortran 77 code must define the output variable
F77 in configure.ac; the simplest way to do this is to use
the AC_PROG_F77 macro (see Particular Program Checks).
A few additional variables are defined when a Fortran 77 source file is seen:
F77FFLAGSAM_FFLAGSFFLAGS.
RFLAGSAM_RFLAGSRFLAGS.
F77COMPILEFLINKAutomake can handle preprocessing Fortran 77 and Ratfor source files in addition to compiling them5. Automake also contains some support for creating programs and shared libraries that are a mixture of Fortran 77 and other languages (see Mixing Fortran 77 With C and C++).
These issues are covered in the following sections.
N.f is made automatically from N.F or N.r. This rule runs just the preprocessor to convert a preprocessable Fortran 77 or Ratfor source file into a strict Fortran 77 source file. The precise command used is as follows:
$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
$(AM_FFLAGS) $(FFLAGS)
$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)
N.o is made automatically from N.f, N.F or N.r by running the Fortran 77 compiler. The precise command used is as follows:
$(F77) -c $(AM_FFLAGS) $(FFLAGS)
$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)
$(AM_FFLAGS) $(FFLAGS)
$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)
Automake currently provides limited support for creating programs and shared libraries that are a mixture of Fortran 77 and C and/or C++. However, there are many other issues related to mixing Fortran 77 with other languages that are not (currently) handled by Automake, but that are handled by other packages6.
Automake can help in two ways:
These extra Fortran 77 linker flags are supplied in the output variable
FLIBS by the AC_F77_LIBRARY_LDFLAGS Autoconf macro
supplied with newer versions of Autoconf (Autoconf version 2.13 and
later). See Fortran Compiler Characteristics.
If Automake detects that a program or shared library (as mentioned in
some _PROGRAMS or _LTLIBRARIES primary) contains source
code that is a mixture of Fortran 77 and C and/or C++, then it requires
that the macro AC_F77_LIBRARY_LDFLAGS be called in
configure.ac, and that either $(FLIBS)
appear in the appropriate _LDADD (for programs) or _LIBADD
(for shared libraries) variables. It is the responsibility of the
person writing the Makefile.am to make sure that ‘$(FLIBS)’
appears in the appropriate _LDADD or
_LIBADD variable.
For example, consider the following Makefile.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 in configure.ac. Also, if ‘$(FLIBS)’ hadn't
been mentioned in foo_LDADD and libfoo_la_LIBADD, then
Automake would have issued a warning.
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.)
GCJLINK)
CXXLINK)
F77LINK)
FCLINK)
OBJCLINK)
UPCLINK)
LINK)
For example, if Fortran 77, C and C++ source code is compiled
into a program, then the C++ linker will be used. In this case, if the
C or Fortran 77 linkers required any special libraries that weren't
included by the C++ linker, then they must be manually added to an
_LDADD or _LIBADD variable by the user writing the
Makefile.am.
Automake only looks at the file names listed in _SOURCES
variables to choose the linker, and defaults to the C linker.
Sometimes this is inconvenient because you are linking against a
library written in another language and would like to set the linker
more appropriately. See Libtool Convenience Libraries, for a
trick with nodist_EXTRA_..._SOURCES.
Automake includes support for Fortran 9x.
Any package including Fortran 9x code must define the output variable
FC in configure.ac; the simplest way to do this is to use
the AC_PROG_FC macro (see Particular Program Checks).
A few additional variables are defined when a Fortran 9x source file is seen:
FCFCFLAGSAM_FCFLAGSFCFLAGS.
FCCOMPILEFCLINKN.o is made automatically from N.f90, N.f95, N.f03, or N.f08 by running the Fortran 9x compiler. The precise command used is as follows:
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<
Automake includes support for compiled Java, using gcj, the Java front end to the GNU Compiler Collection.
Any package including Java code to be compiled must define the output
variable GCJ in configure.ac; the variable GCJFLAGS
must also be defined somehow (either in configure.ac or
Makefile.am). The simplest way to do this is to use the
AM_PROG_GCJ macro.
By default, programs including Java source files are linked with gcj.
As always, the contents of AM_GCJFLAGS are passed to every
compilation invoking gcj (in its role as an ahead-of-time
compiler, when invoking it to create .class files,
AM_JAVACFLAGS is used instead). If it is necessary to pass
options to gcj from Makefile.am, this variable, and not
the user variable GCJFLAGS, should be used.
gcj can be used to compile .java, .class, .zip, or .jar files.
When linking, gcj requires that the main class be specified
using the --main= option. The easiest way to do this is to use
the _LDFLAGS variable for the program.
Automake provides initial support for Vala (http://www.vala-project.org/). This requires valac version 0.7.0 or later, and currently requires the user to use GNU make.
foo_SOURCES = foo.vala bar.vala zardoc.c
Any .vala file listed in a _SOURCES variable will be
compiled into C code by the Vala compiler. The generated .c files are
distributed. The end user does not need to have a Vala compiler installed.
Automake ships with an Autoconf macro called AM_PROG_VALAC
that will locate the Vala compiler and optionally check its version
number.
Try to find a Vala compiler in PATH. If it is found, the variable
VALACis set. Optionally a minimum release number of the compiler can be requested:AM_PROG_VALAC([0.7.0])
There are a few variables that are used when compiling Vala sources:
VALACVALAFLAGSAM_VALAFLAGSVALAFLAGS.
lib_LTLIBRARIES = libfoo.la
libfoo_la_SOURCES = foo.vala
Note that currently, you cannot use per-target *_VALAFLAGS
(see Renamed Objects) to produce different C files from one Vala
source file.
Automake currently only includes full support for C, C++ (see C++ Support), Objective C (see Objective C Support), Fortran 77 (see Fortran 77 Support), Fortran 9x (see Fortran 9x Support), and Java (see Java Support). There is only rudimentary support for other languages, support for which will be improved based on user demand.
Some limited support for adding your own languages is available via the suffix rule handling (see Suffixes).
The features described in this section are obsolete; you should not used any of them in new code, and they may be withdrawn in future Automake releases.
When the C language was standardized in 1989, there was a long transition period where package developers needed to worry about porting to older systems that did not support ANSI C by default. These older systems are no longer in practical use and are no longer supported by their original suppliers, so developers need not worry about this problem any more.
Automake allows you to write packages that are portable to K&R C by de-ANSI-fying each source file before the actual compilation takes place.
If the Makefile.am variable AUTOMAKE_OPTIONS
(see Options) contains the option ansi2knr then code to
handle de-ANSI-fication is inserted into the generated
Makefile.in.
This causes each C source file in the directory to be treated as ANSI C. If an ANSI C compiler is available, it is used. If no ANSI C compiler is available, the ansi2knr program is used to convert the source files into K&R C, which is then compiled.
The ansi2knr program is simple-minded. It assumes the source code will be formatted in a particular way; see the ansi2knr man page for details.
Support for the obsolete de-ANSI-fication feature
requires the source files ansi2knr.c
and ansi2knr.1 to be in the same package as the ANSI C source;
these files are distributed with Automake. Also, the package
configure.ac must call the macro AM_C_PROTOTYPES
(see Macros).
Automake also handles finding the ansi2knr support files in some other directory in the current package. This is done by prepending the relative path to the appropriate directory to the ansi2knr option. For instance, suppose the package has ANSI C code in the src and lib subdirectories. The files ansi2knr.c and ansi2knr.1 appear in lib. Then this could appear in src/Makefile.am:
AUTOMAKE_OPTIONS = ../lib/ansi2knr
If no directory prefix is given, the files are assumed to be in the current directory.
Note that automatic de-ANSI-fication will not work when the package is being built for a different host architecture. That is because automake currently has no way to build ansi2knr for the build machine.
Using LIBOBJS with source de-ANSI-fication used to require
hand-crafted code in configure to append ‘$U’ to basenames
in LIBOBJS. This is no longer true today. Starting with version
2.54, Autoconf takes care of rewriting LIBOBJS and
LTLIBOBJS. (see AC_LIBOBJ vs. LIBOBJS)
As a developer it is often painful to continually update the Makefile.in whenever the include-file dependencies change in a project. Automake supplies a way to automatically track dependency changes (see Dependency Tracking).
Automake always uses complete dependencies for a compilation, including system headers. Automake's model is that dependency computation should be a side effect of the build. To this end, dependencies are computed by running all compilations through a special wrapper program called depcomp. depcomp understands how to coax many different C and C++ compilers into generating dependency information in the format it requires. ‘automake -a’ will install depcomp into your source tree for you. If depcomp can't figure out how to properly invoke your compiler, dependency tracking will simply be disabled for your build.
Experience with earlier versions of Automake (see Dependency Tracking Evolution) taught us that it is not reliable to generate dependencies only on the maintainer's system, as configurations vary too much. So instead Automake implements dependency tracking at build time.
Automatic dependency tracking can be suppressed by putting
no-dependencies in the variable AUTOMAKE_OPTIONS, or
passing no-dependencies as an argument to AM_INIT_AUTOMAKE
(this should be the preferred way). Or, you can invoke automake
with the -i option. Dependency tracking is enabled by default.
The person building your package also can choose to disable dependency tracking by configuring with --disable-dependency-tracking.
On some platforms, such as Windows, executables are expected to have an extension such as .exe. On these platforms, some compilers (GCC among them) will automatically generate foo.exe when asked to generate foo.
Automake provides mostly-transparent support for this. Unfortunately mostly doesn't yet mean fully. Until the English dictionary is revised, you will have to assist Automake if your package must support those platforms.
One thing you must be aware of is that, internally, Automake rewrites something like this:
bin_PROGRAMS = liver
to this:
bin_PROGRAMS = liver$(EXEEXT)
The targets Automake generates are likewise given the ‘$(EXEEXT)’ extension.
The variables TESTS and XFAIL_TESTS (see Simple Tests) are also
rewritten if they contain filenames that have been declared as programs
in the same Makefile. (This is mostly useful when some programs
from check_PROGRAMS are listed in TESTS.)
However, Automake cannot apply this rewriting to configure substitutions. This means that if you are conditionally building a program using such a substitution, then your configure.ac must take care to add ‘$(EXEEXT)’ when constructing the output variable.
With Autoconf 2.13 and earlier, you must explicitly use AC_EXEEXT
to get this support. With Autoconf 2.50, AC_EXEEXT is run
automatically if you configure a compiler (say, through
AC_PROG_CC).
Sometimes maintainers like to write an explicit link rule for their program. Without executable extension support, this is easy—you simply write a rule whose target is the name of the program. However, when executable extension support is enabled, you must instead add the ‘$(EXEEXT)’ suffix.
Unfortunately, due to the change in Autoconf 2.50, this means you must
always add this extension. However, this is a problem for maintainers
who know their package will never run on a platform that has
executable extensions. For those maintainers, the no-exeext
option (see Options) will disable this feature. This works in a
fairly ugly way; if no-exeext is seen, then the presence of a
rule for a target named foo in Makefile.am will override
an automake-generated rule for ‘foo$(EXEEXT)’. Without
the no-exeext option, this use will give a diagnostic.
Automake can handle derived objects that are not C programs. Sometimes the support for actually building such objects must be explicitly supplied, but Automake will still automatically handle installation and distribution.
It is possible to define and install programs that are scripts. Such
programs are listed using the SCRIPTS primary name. When the
script is distributed in its final, installable form, the
Makefile usually looks as follows:
# Install my_script in $(bindir) and distribute it.
dist_bin_SCRIPTS = my_script
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.
Scripts can be installed in bindir, sbindir,
libexecdir, or pkgdatadir.
Scripts that need not be installed can be listed in
noinst_SCRIPTS, and among them, those which are needed only by
‘make check’ should go in check_SCRIPTS.
When a script needs to be built, the Makefile.am should include the appropriate rules. For instance the automake program itself is a Perl script that is generated from automake.in. Here is how this is handled:
bin_SCRIPTS = automake
CLEANFILES = $(bin_SCRIPTS)
EXTRA_DIST = automake.in
do_subst = sed -e 's,[@]datadir[@],$(datadir),g' \
-e 's,[@]PERL[@],$(PERL),g' \
-e 's,[@]PACKAGE[@],$(PACKAGE),g' \
-e 's,[@]VERSION[@],$(VERSION),g' \
...
automake: automake.in Makefile
$(do_subst) < $(srcdir)/automake.in > automake
chmod +x automake
Such scripts for which a build rule has been supplied need to be
deleted explicitly using CLEANFILES (see Clean), and their
sources have to be distributed, usually with EXTRA_DIST
(see Basics of Distribution).
Another common way to build scripts is to process them from
configure with AC_CONFIG_FILES. In this situation
Automake knows which files should be cleaned and distributed, and what
the rebuild rules should look like.
For instance if configure.ac contains
AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
to build src/my_script from src/my_script.in, then a
src/Makefile.am to install this script in $(bindir) can
be as simple as
bin_SCRIPTS = my_script
CLEANFILES = $(bin_SCRIPTS)
There is no need for EXTRA_DIST or any build rule: Automake
infers them from AC_CONFIG_FILES (see Requirements).
CLEANFILES is still useful, because by default Automake will
clean targets of AC_CONFIG_FILES in distclean, not
clean.
Although this looks simpler, building scripts this way has one
drawback: directory variables such as $(datadir) are not fully
expanded and may refer to other directory variables.
Header files that must be installed are specified by the
HEADERS family of variables. Headers can be installed in
includedir, oldincludedir, pkgincludedir or any
other directory you may have defined (see Uniform). For instance,
include_HEADERS = foo.h bar/bar.h
will install the two files as $(includedir)/foo.h and $(includedir)/bar.h.
The nobase_ prefix is also supported,
nobase_include_HEADERS = foo.h bar/bar.h
will install the two files as $(includedir)/foo.h and $(includedir)/bar/bar.h (see Alternative).
Usually, only header files that accompany installed libraries need to
be installed. Headers used by programs or convenience libraries are
not installed. The noinst_HEADERS variable can be used for
such headers. However when the header actually belongs to a single
convenience library or program, we recommend listing it in the
program's or library's _SOURCES variable (see Program Sources) instead of in noinst_HEADERS. This is clearer for
the Makefile.am reader. noinst_HEADERS would be the
right variable to use in a directory containing only headers and no
associated library or program.
All header files must be listed somewhere; in a _SOURCES
variable or in a _HEADERS variable. Missing ones will not
appear in the distribution.
For header files that are built and must not be distributed, use the
nodist_ prefix as in nodist_include_HEADERS or
nodist_prog_SOURCES. If these generated headers are needed
during the build, you must also ensure they exist before they are
used (see Sources).
Automake supports the installation of miscellaneous data files using the
DATA family of variables.
Such data can be installed in the directories datadir,
sysconfdir, sharedstatedir, localstatedir, or
pkgdatadir.
By default, data files are not included in a distribution. Of
course, you can use the dist_ prefix to change this on a
per-variable basis.
Here is how Automake declares its auxiliary data files:
dist_pkgdata_DATA = clean-kr.am clean.am ...
Because Automake's automatic dependency tracking works as a side-effect of compilation (see Dependencies) there is a bootstrap issue: a target should not be compiled before its dependencies are made, but these dependencies are unknown until the target is first compiled.
Ordinarily this is not a problem, because dependencies are distributed sources: they preexist and do not need to be built. Suppose that foo.c includes foo.h. When it first compiles foo.o, make only knows that foo.o depends on foo.c. As a side-effect of this compilation depcomp records the foo.h dependency so that following invocations of make will honor it. In these conditions, it's clear there is no problem: either foo.o doesn't exist and has to be built (regardless of the dependencies), or accurate dependencies exist and they can be used to decide whether foo.o should be rebuilt.
It's a different story if foo.h doesn't exist by the first make run. For instance, there might be a rule to build foo.h. This time file.o's build will fail because the compiler can't find foo.h. make failed to trigger the rule to build foo.h first by lack of dependency information.
The BUILT_SOURCES variable is a workaround for this problem. A
source file listed in BUILT_SOURCES is made on ‘make all’
or ‘make check’ (or even ‘make install’) before other
targets are processed. However, such a source file is not
compiled unless explicitly requested by mentioning it in some
other _SOURCES variable.
So, to conclude our introductory example, we could use ‘BUILT_SOURCES = foo.h’ to ensure foo.h gets built before any other target (including foo.o) during ‘make all’ or ‘make check’.
BUILT_SOURCES is actually a bit of a misnomer, as any file which
must be created early in the build process can be listed in this
variable. Moreover, all built sources do not necessarily have to be
listed in BUILT_SOURCES. For instance, a generated .c file
doesn't need to appear in BUILT_SOURCES (unless it is included by
another source), because it's a known dependency of the associated
object.
It might be important to emphasize that BUILT_SOURCES is
honored only by ‘make all’, ‘make check’ and ‘make
install’. This means you cannot build a specific target (e.g.,
‘make foo’) in a clean tree if it depends on a built source.
However it will succeed if you have run ‘make all’ earlier,
because accurate dependencies are already available.
The next section illustrates and discusses the handling of built sources on a toy example.
Suppose that foo.c includes bindir.h, which is
installation-dependent and not distributed: it needs to be built. Here
bindir.h defines the preprocessor macro bindir to the
value of the make variable bindir (inherited from
configure).
We suggest several implementations below. It's not meant to be an exhaustive listing of all ways to handle built sources, but it will give you a few ideas if you encounter this issue.
This first implementation will illustrate the bootstrap issue mentioned in the previous section (see Sources).
Here is a tentative Makefile.am.
# This won't work.
bin_PROGRAMS = foo
foo_SOURCES = foo.c
nodist_foo_SOURCES = bindir.h
CLEANFILES = bindir.h
bindir.h: Makefile
echo '#define bindir "$(bindir)"' >$@
This setup doesn't work, because Automake doesn't know that foo.c includes bindir.h. Remember, automatic dependency tracking works as a side-effect of compilation, so the dependencies of foo.o will be known only after foo.o has been compiled (see Dependencies). The symptom is as follows.
% make
source='foo.c' object='foo.o' libtool=no \
depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
depmode=gcc /bin/sh ./depcomp \
gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
foo.c:2: bindir.h: No such file or directory
make: *** [foo.o] Error 1
In this example bindir.h is not distributed nor installed, and
it is not even being built on-time. One may wonder if the
‘nodist_foo_SOURCES = bindir.h’ line has any use at all. This
line simply states that bindir.h is a source of foo, so
for instance, it should be inspected while generating tags
(see Tags). In other words, it does not help our present problem,
and the build would fail identically without it.
BUILT_SOURCESA solution is to require bindir.h to 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)"' >$@
See how bindir.h gets built first:
% make
echo '#define bindir "/usr/local/bin"' >bindir.h
make all-am
make[1]: Entering directory `/home/adl/tmp'
source='foo.c' object='foo.o' libtool=no \
depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
depmode=gcc /bin/sh ./depcomp \
gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
gcc -g -O2 -o foo foo.o
make[1]: Leaving directory `/home/adl/tmp'
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:
% make clean
test -z "bindir.h" || rm -f bindir.h
test -z "foo" || rm -f foo
rm -f *.o
% : > .deps/foo.Po # Suppress previously recorded dependencies
% make foo
source='foo.c' object='foo.o' libtool=no \
depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
depmode=gcc /bin/sh ./depcomp \
gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
foo.c:2: bindir.h: No such file or directory
make: *** [foo.o] Error 1
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
the Makefile.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 all the dependencies of foo.o explicitly, only those that might need to be built. If a dependency already exists, it will not hinder the first compilation and will be recorded by the normal dependency tracking code. (Note that after this first compilation the dependency tracking code will also have recorded the dependency between foo.o and bindir.h; so our explicit dependency is really useful to the first build only.)
Adding explicit dependencies like this can be a bit dangerous if you are not careful enough. This is due to the way Automake tries not to overwrite your rules (it assumes you know better than it). ‘foo.$(OBJEXT): bindir.h’ supersedes any rule Automake may want to output to build ‘foo.$(OBJEXT)’. It happens to work in this case because Automake doesn't have to output any ‘foo.$(OBJEXT):’ target: it relies on a suffix rule instead (i.e., ‘.c.$(OBJEXT):’). Always check the generated Makefile.in if you do this.
It's possible to define this preprocessor macro from configure,
either in config.h (see Defining Directories), or by processing a
bindir.h.in file using AC_CONFIG_FILES
(see Configuration Actions).
At this point it should be clear that building bindir.h from configure works well for this example. bindir.h will exist before you build any target, hence will not cause any dependency issue.
The Makefile can be shrunk as follows. We do not even have to mention bindir.h.
bin_PROGRAMS = foo
foo_SOURCES = foo.c
However, it's not always possible to build sources from configure, especially when these sources are generated by a tool that needs to be built first.
Another attractive idea is to define bindir as a variable or
function exported from bindir.o, and build bindir.c
instead of bindir.h.
noinst_PROGRAMS = foo
foo_SOURCES = foo.c bindir.h
nodist_foo_SOURCES = bindir.c
CLEANFILES = bindir.c
bindir.c: Makefile
echo 'const char bindir[] = "$(bindir)";' >$@
bindir.h contains just the variable's declaration and doesn't need to be built, so it won't cause any trouble. bindir.o is always dependent on bindir.c, so bindir.c will get built first.
There is no panacea, of course. Each solution has its merits and drawbacks.
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 ./configure is not always possible, neither is converting .h files into .c files.
Since Automake is primarily intended to generate Makefile.ins for use in GNU programs, it tries hard to interoperate with other GNU tools.
Automake provides some support for Emacs Lisp. The LISP primary
is used to hold a list of .el files. Possible prefixes for this
primary are lisp_ and noinst_. Note that if
lisp_LISP is defined, then configure.ac must run
AM_PATH_LISPDIR (see Macros).
Lisp sources are not distributed by default. You can prefix the
LISP primary with dist_, as in dist_lisp_LISP or
dist_noinst_LISP, to indicate that these files should be
distributed.
Automake will byte-compile all Emacs Lisp source files using the Emacs
found by AM_PATH_LISPDIR, if any was found.
Byte-compiled Emacs Lisp files are not portable among all versions of Emacs, so it makes sense to turn this off if you expect sites to have more than one version of Emacs installed. Furthermore, many packages don't actually benefit from byte-compilation. Still, we recommend that you byte-compile your Emacs Lisp sources. It is probably better for sites with strange setups to cope for themselves than to make the installation less nice for everybody else.
There are two ways to avoid byte-compiling. Historically, we have recommended the following construct.
lisp_LISP = file1.el file2.el
ELCFILES =
ELCFILES is an internal Automake variable that normally lists
all .elc files that must be byte-compiled. Automake defines
ELCFILES automatically from lisp_LISP. Emptying this
variable explicitly prevents byte-compilation.
Since Automake 1.8, we now recommend using lisp_DATA instead. As
in
lisp_DATA = file1.el file2.el
Note that these two constructs are not equivalent. _LISP will
not install a file if Emacs is not installed, while _DATA will
always install its files.
If AM_GNU_GETTEXT is seen in configure.ac, then Automake
turns on support for GNU gettext, a message catalog system for
internationalization
(see Introduction).
The gettext support in Automake requires the addition of one or
two subdirectories to the package: po and possibly also intl.
The latter is needed if AM_GNU_GETTEXT is not invoked with the
‘external’ argument, or if AM_GNU_GETTEXT_INTL_SUBDIR is used.
Automake ensures that these directories exist and are mentioned in
SUBDIRS.
Automake provides support for GNU Libtool (see Introduction) with the LTLIBRARIES primary.
See A Shared Library.
Automake provides some minimal support for Java compilation with the
JAVA primary.
Any .java files listed in a _JAVA variable will be
compiled with JAVAC at build time. By default, .java
files are not included in the distribution, you should use the
dist_ prefix to distribute them.
Here is a typical setup for distributing .java files and installing the .class files resulting from their compilation.
javadir = $(datadir)/java
dist_java_JAVA = a.java b.java ...
Currently Automake enforces the restriction that only one _JAVA
primary can be used in a given Makefile.am. The reason for this
restriction is that, in general, it isn't possible to know which
.class files were generated from which .java files, so
it would be impossible to know which files to install where. For
instance, a .java file can define multiple classes; the resulting
.class file names cannot be predicted without parsing the
.java file.
There are a few variables that are used when compiling Java sources:
JAVACJAVACFLAGSAM_JAVACFLAGSJAVACFLAGS, should be used when it is necessary to put Java
compiler flags into Makefile.am.
JAVAROOTjavac. It defaults to ‘$(top_builddir)’.
CLASSPATH_ENVjavac command line.
(In the future we will probably handle class path setting differently.)
Automake provides support for Python compilation with the
PYTHON primary. A typical setup is to call
AM_PATH_PYTHON in configure.ac and use a line like the
following in Makefile.am:
python_PYTHON = tree.py leave.py
Any files listed in a _PYTHON variable will be byte-compiled
with py-compile at install time. py-compile
actually creates both standard (.pyc) and optimized
(.pyo) byte-compiled versions of the source files. Note that
because byte-compilation occurs at install time, any files listed in
noinst_PYTHON will not be compiled. Python source files are
included in the distribution by default, prepend nodist_ (as in
nodist_python_PYTHON) to omit them.
Automake ships with an Autoconf macro called AM_PATH_PYTHON
that will determine some Python-related directory variables (see
below). If you have called AM_PATH_PYTHON from
configure.ac, then you may use the variables
python_PYTHON or pkgpython_PYTHON to list Python source
files in your Makefile.am, depending on where you want your files
installed (see the definitions of pythondir and
pkgpythondir below).
Search for a Python interpreter on the system. This macro takes three optional arguments. The first argument, if present, is the minimum version of Python required for this package:
AM_PATH_PYTHONwill skip any Python interpreter that is older than VERSION. If an interpreter is found and satisfies VERSION, then ACTION-IF-FOUND is run. Otherwise, ACTION-IF-NOT-FOUND is run.If ACTION-IF-NOT-FOUND is not specified, as in the following example, the default is to abort configure.
AM_PATH_PYTHON([2.2])This is fine when Python is an absolute requirement for the package. If Python >= 2.5 was only optional to the package,
AM_PATH_PYTHONcould be called as follows.AM_PATH_PYTHON([2.5],, [:])
AM_PATH_PYTHONcreates the following output variables based on the Python installation found during configuration.
PYTHONAssuming ACTION-IF-NOT-FOUND is used (otherwise ./configure
will abort if Python is absent), the value of PYTHON can be used
to setup a conditional in order to disable the relevant part of a build
as follows.
AM_PATH_PYTHON(,, [:])
AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
PYTHON_VERSIONPYTHON_PREFIXPYTHON_EXEC_PREFIXPYTHON_PLATFORMpythondirpkgpythondirpythondir that is named after the
package. That is, it is ‘$(pythondir)/$(PACKAGE)’. It is provided
as a convenience.
pyexecdir pyexec_LTLIBRARIES = quaternion.la
quaternion_SOURCES = quaternion.c support.c support.h
quaternion_la_LDFLAGS = -avoid-version -module
pkgpyexecdirAll these directory variables have values that start with either ‘${prefix}’ or ‘${exec_prefix}’ unexpanded. This works fine in Makefiles, but it makes these variables hard to use in configure. This is mandated by the GNU coding standards, so that the user can run ‘make prefix=/foo install’. The Autoconf manual has a section with more details on this topic (see Installation Directory Variables). See also Hard-Coded Install Paths.
Currently Automake provides support for Texinfo and man pages.
If the current directory contains Texinfo source, you must declare it
with the TEXINFOS primary. Generally Texinfo files are converted
into info, and thus the info_TEXINFOS variable is most commonly used
here. Any Texinfo source file must end in the .texi,
.txi, or .texinfo extension. We recommend .texi
for new manuals.
Automake generates rules to build .info, .dvi, .ps, .pdf and .html files from your Texinfo sources. Following the GNU Coding Standards, only the .info files are built by ‘make all’ and installed by ‘make install’ (unless you use no-installinfo, see below). Furthermore, .info files are automatically distributed so that Texinfo is not a prerequisite for installing your package.
Other documentation formats can be built on request by ‘make dvi’, ‘make ps’, ‘make pdf’ and ‘make html’, and they can be installed with ‘make install-dvi’, ‘make install-ps’, ‘make install-pdf’ and ‘make install-html’ explicitly. ‘make uninstall’ will remove everything: the Texinfo documentation installed by default as well as all the above optional formats.
All these targets can be extended using ‘-local’ rules (see Extending).
If the .texi file @includes version.texi, then
that file will be automatically generated. The file version.texi
defines four Texinfo flag you can reference using
@value{EDITION}, @value{VERSION},
@value{UPDATED}, and @value{UPDATED-MONTH}.
EDITIONVERSIONUPDATEDUPDATED-MONTHThe version.texi support requires the mdate-sh script; this script is supplied with Automake and automatically included when automake is invoked with the --add-missing option.
If you have multiple Texinfo files, and you want to use the version.texi feature, then you have to have a separate version file for each Texinfo file. Automake will treat any include in a Texinfo file that matches vers*.texi just as an automatically generated version file.
Sometimes an info file actually depends on more than one .texi
file. For instance, in GNU Hello, hello.texi includes the file
gpl.texi. You can tell Automake about these dependencies using
the texi_TEXINFOS variable. Here is how GNU Hello does it:
info_TEXINFOS = hello.texi
hello_TEXINFOS = gpl.texi
By default, Automake requires the file texinfo.tex to appear in
the same directory as the Makefile.am file that lists the
.texi files. If you used AC_CONFIG_AUX_DIR in
configure.ac (see Finding `configure' Input), then texinfo.tex is looked for
there. In both cases, automake then supplies texinfo.tex if
--add-missing is given, and takes care of its distribution.
However, if you set the TEXINFO_TEX variable (see below),
it overrides the location of the file and turns off its installation
into the source as well as its distribution.
The option no-texinfo.tex can be used to eliminate the
requirement for the file texinfo.tex. Use of the variable
TEXINFO_TEX is preferable, however, because that allows the
dvi, ps, and pdf targets to still work.
Automake generates an install-info rule; some people apparently
use this. By default, info pages are installed by ‘make
install’, so running make install-info is pointless. This can
be prevented via the no-installinfo option. In this case,
.info files are not installed by default, and user must
request this explicitly using ‘make install-info’.
The following variables are used by the Texinfo build rules.
MAKEINFOMAKEINFOHTMLMAKEINFOFLAGSAM_MAKEINFOFLAGSAM_MAKEINFOHTMLFLAGSMAKEINFOFLAGS, these variables are meant to be defined by
maintainers in Makefile.am. ‘$(AM_MAKEINFOFLAGS)’ is
passed to makeinfo when building .info files; and
‘$(AM_MAKEINFOHTMLFLAGS)’ is used when building .html
files.
For instance, the following setting can be used to obtain one single .html file per manual, without node separators.
AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
AM_MAKEINFOHTMLFLAGS defaults to ‘$(AM_MAKEINFOFLAGS)’.
This means that defining AM_MAKEINFOFLAGS without defining
AM_MAKEINFOHTMLFLAGS will impact builds of both .info
and .html files.
TEXI2DVITEXI2PDFDVIPSTEXINFO_TEXTEXINFO_TEX to tell Automake where to find the canonical
texinfo.tex for your package. The value of this variable should
be the relative path from the current Makefile.am to
texinfo.tex:
TEXINFO_TEX = ../doc/texinfo.tex
A package can also include man pages (but see the GNU standards on this
matter, Man Pages.) Man
pages are declared using the MANS primary. Generally the
man_MANS variable is used. Man pages are automatically installed in
the correct subdirectory of mandir, based on the file extension.
File extensions such as .1c are handled by looking for the valid
part of the extension and using that to determine the correct
subdirectory of mandir. Valid section names are the digits
‘0’ through ‘9’, and the letters ‘l’ and ‘n’.
Sometimes developers prefer to name a man page something like
foo.man in the source, and then rename it to have the correct
suffix, for example foo.1, when installing the file. Automake
also supports this mode. For a valid section named SECTION,
there is a corresponding directory named ‘manSECTIONdir’,
and a corresponding _MANS variable. Files listed in such a
variable are installed in the indicated section. If the file already
has a valid suffix, then it is installed as-is; otherwise the file
suffix is changed to match the section.
For instance, consider this example:
man1_MANS = rename.man thesame.1 alsothesame.1c
In this case, rename.man will be renamed to rename.1 when installed, but the other files will keep their names.
By default, man pages are installed by ‘make install’. However, since the GNU project does not require man pages, many maintainers do not expend effort to keep the man pages up to date. In these cases, the no-installman option will prevent the man pages from being installed by default. The user can still explicitly install them via ‘make install-man’.
For fast installation, with many files it is preferable to use ‘manSECTION_MANS’ over ‘man_MANS’ as well as files that do not need to be renamed.
Man pages are not currently considered to be source, because it is not
uncommon for man pages to be automatically generated. Therefore they
are not automatically included in the distribution. However, this can
be changed by use of the dist_ prefix. For instance here is
how to distribute and install the two man pages of GNU cpio
(which includes both Texinfo documentation and man pages):
dist_man_MANS = cpio.1 mt.1
The nobase_ prefix is meaningless for man pages and is
disallowed.
Executables and manpages may be renamed upon installation
(see Renaming). For manpages this can be avoided by use of the
notrans_ prefix. For instance, suppose an executable ‘foo’
allowing to access a library function ‘foo’ from the command line.
The way to avoid renaming of the foo.3 manpage is:
man_MANS = foo.1
notrans_man_MANS = foo.3
‘notrans_’ must be specified first when used in conjunction with either ‘dist_’ or ‘nodist_’ (see Fine-grained Distribution Control). For instance:
notrans_dist_man3_MANS = bar.3
Naturally, Automake handles the details of actually installing your program once it has been built. All files named by the various primaries are automatically installed in the appropriate places when the user runs ‘make install’.
A file named in a primary is installed by copying the built file into the appropriate directory. The base name of the file is used when installing.
bin_PROGRAMS = hello subdir/goodbye
In this example, both ‘hello’ and ‘goodbye’ will be installed in ‘$(bindir)’.
Sometimes it is useful to avoid the basename step at install time. For
instance, you might have a number of header files in subdirectories of
the source tree that are laid out precisely how you want to install
them. In this situation you can use the nobase_ prefix to
suppress the base name step. For example:
nobase_include_HEADERS = stdio.h sys/types.h
will install stdio.h in ‘$(includedir)’ and types.h in ‘$(includedir)/sys’.
For most file types, Automake will install multiple files at once, while avoiding command line length issues (see Length Limitations). Since some install programs will not install the same file twice in one invocation, you may need to ensure that file lists are unique within one variable such as ‘nobase_include_HEADERS’ above.
You should not rely on the order in which files listed in one variable are installed. Likewise, to cater for parallel make, you should not rely on any particular file installation order even among different file types (library dependencies are an exception here).
Automake generates separate install-data and install-exec
rules, in case the installer is installing on multiple machines that
share directory structure—these targets allow the machine-independent
parts to be installed only once. install-exec installs
platform-dependent files, and install-data installs
platform-independent files. The install target depends on both
of these targets. While Automake tries to automatically segregate
objects into the correct category, the Makefile.am author is, in
the end, responsible for making sure this is done correctly.
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.
It is possible to extend this mechanism by defining an
install-exec-local or install-data-local rule. If these
rules exist, they will be run at ‘make install’ time. These
rules can do almost anything; care is required.
Automake also supports two install hooks, install-exec-hook and
install-data-hook. These hooks are run after all other install
rules of the appropriate type, exec or data, have completed. So, for
instance, it is possible to perform post-installation modifications
using an install hook. See Extending, for some examples.
Automake generates support for the DESTDIR variable in all
install rules. DESTDIR is used during the ‘make install’
step to relocate install objects into a staging area. Each object and
path is prefixed with the value of DESTDIR before being copied
into the install area. Here is an example of typical DESTDIR usage:
mkdir /tmp/staging &&
make DESTDIR=/tmp/staging install
The mkdir command avoids a security problem if the attacker creates a symbolic link from /tmp/staging to a victim area; then make places install objects in a directory tree built under /tmp/staging. If /gnu/bin/foo and /gnu/share/aclocal/foo.m4 are to be installed, the above command would install /tmp/staging/gnu/bin/foo and /tmp/staging/gnu/share/aclocal/foo.m4.
This feature is commonly used to build install images and packages (see DESTDIR).
Support for DESTDIR is implemented by coding it directly into
the install rules. If your Makefile.am uses a local install
rule (e.g., install-exec-local) or an install hook, then you
must write that code to respect DESTDIR.
See Makefile Conventions, for another usage example.
Automake also generates rules for targets uninstall,
installdirs, and install-strip.
Automake supports uninstall-local and uninstall-hook.
There is no notion of separate uninstalls for “exec” and “data”, as
these features would not provide additional functionality.
Note that uninstall is not meant as a replacement for a real
packaging tool.
The GNU Makefile Standards specify a number of different clean rules. See Standard Targets for Users.
Generally the files that can be cleaned are determined automatically by
Automake. Of course, Automake also recognizes some variables that can
be defined to specify additional files to clean. These variables are
MOSTLYCLEANFILES, CLEANFILES, DISTCLEANFILES, and
MAINTAINERCLEANFILES.
When cleaning involves more than deleting some hard-coded list of
files, it is also possible to supplement the cleaning rules with your
own commands. Simply define a rule for any of the
mostlyclean-local, clean-local, distclean-local,
or maintainer-clean-local targets (see Extending). A common
case is deleting a directory, for instance, a directory created by the
test suite:
clean-local:
-rm -rf testSubDir
Since make allows only one set of rules for a given target, a more extensible way of writing this is to use a separate target listed as a dependency:
clean-local: clean-local-check
.PHONY: clean-local-check
clean-local-check:
-rm -rf testSubDir
As the GNU Standards aren't always explicit as to which files should be removed by which rule, we've adopted a heuristic that we believe was first formulated by François Pinard:
mostlyclean should delete it.
clean should delete it.
distclean should delete it.
maintainer-clean should delete it. However
maintainer-clean should not delete anything that needs to exist
in order to run ‘./configure && make’.
We recommend that you follow this same set of heuristics in your Makefile.am.
The dist rule in the generated Makefile.in can be used
to generate a gzipped tar file and other flavors of archive for
distribution. The file is named based on the PACKAGE and
VERSION variables defined by AM_INIT_AUTOMAKE
(see Macros); more precisely the gzipped tar file is named
‘package-version.tar.gz’.
You can use the make variable GZIP_ENV to control how gzip
is run. The default setting is --best.
For the most part, the files to distribute are automatically found by
Automake: all source files are automatically included in a distribution,
as are all Makefile.ams and Makefile.ins. Automake also
has a built-in list of commonly used files that are automatically
included if they are found in the current directory (either physically,
or as the target of a Makefile.am rule). This list is printed by
‘automake --help’. Also, files that are read by configure
(i.e. the source files corresponding to the files specified in various
Autoconf macros such as AC_CONFIG_FILES and siblings) are
automatically distributed. Files included in Makefile.ams (using
include) or in configure.ac (using m4_include), and
helper scripts installed with ‘automake --add-missing’ are also
distributed.
Still, sometimes there are files that must be distributed, but which
are not covered in the automatic rules. These files should be listed in
the EXTRA_DIST variable. You can mention files from
subdirectories in EXTRA_DIST.
You can also mention a directory in EXTRA_DIST; in this case the
entire directory will be recursively copied into the distribution.
Please note that this will also copy everything in the directory,
including CVS/RCS version control files. We recommend against using
this feature.
If you define SUBDIRS, Automake will recursively include the
subdirectories in the distribution. If SUBDIRS is defined
conditionally (see Conditionals), Automake will normally include
all directories that could possibly appear in SUBDIRS in the
distribution. If you need to specify the set of directories
conditionally, you can set the variable DIST_SUBDIRS to the
exact list of subdirectories to include in the distribution
(see Conditional Subdirectories).
Sometimes you need tighter control over what does not go into the
distribution; for instance, you might have source files that are
generated and that you do not want to distribute. In this case
Automake gives fine-grained control using the dist and
nodist prefixes. Any primary or _SOURCES variable can be
prefixed with dist_ to add the listed files to the distribution.
Similarly, nodist_ can be used to omit the files from the
distribution.
As an example, here is how you would cause some data to be distributed while leaving some source code out of the distribution:
dist_data_DATA = distribute-this
bin_PROGRAMS = foo
nodist_foo_SOURCES = do-not-distribute.c
Occasionally it is useful to be able to change the distribution before
it is packaged up. If the dist-hook rule exists, it is run
after the distribution directory is filled, but before the actual tar
(or shar) file is created. One way to use this is for distributing
files in subdirectories for which a new Makefile.am is overkill:
dist-hook:
mkdir $(distdir)/random
cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
Another way to use this is for removing unnecessary files that get recursively included by specifying a directory in EXTRA_DIST:
EXTRA_DIST = doc
dist-hook:
rm -rf `find $(distdir)/doc -name CVS`
Two variables that come handy when writing dist-hook rules are
‘$(distdir)’ and ‘$(top_distdir)’.
‘$(distdir)’ points to the directory where the dist rule
will copy files from the current directory before creating the
tarball. If you are at the top-level directory, then ‘distdir =
$(PACKAGE)-$(VERSION)’. When used from subdirectory named
foo/, then ‘distdir = ../$(PACKAGE)-$(VERSION)/foo’.
‘$(distdir)’ can be a relative or absolute path, do not assume
any form.
‘$(top_distdir)’ always points to the root directory of the distributed tree. At the top-level it's equal to ‘$(distdir)’. In the foo/ subdirectory ‘top_distdir = ../$(PACKAGE)-$(VERSION)’. ‘$(top_distdir)’ too can be a relative or absolute path.
Note that when packages are nested using AC_CONFIG_SUBDIRS
(see Subpackages), then ‘$(distdir)’ and
‘$(top_distdir)’ are relative to the package where ‘make
dist’ was run, not to any sub-packages involved.
Automake also generates a distcheck rule that can be of help to
ensure that a given distribution will actually work. distcheck
makes a distribution, then tries to do a VPATH build
(see VPATH Builds), run the test suite, and finally make another
tarball to ensure the distribution is self-contained.
Building the package involves running ‘./configure’. If you need
to supply additional flags to configure, define them in the
DISTCHECK_CONFIGURE_FLAGS variable, either in your top-level
Makefile.am, or on the command line when invoking make.
If the distcheck-hook rule is defined in your top-level
Makefile.am, then it will be invoked by distcheck after
the new distribution has been unpacked, but before the unpacked copy
is configured and built. Your distcheck-hook can do almost
anything, though as always caution is advised. Generally this hook is
used to check for potential distribution errors not caught by the
standard mechanism. Note that distcheck-hook as well as
DISTCHECK_CONFIGURE_FLAGS are not honored in a subpackage
Makefile.am, but the DISTCHECK_CONFIGURE_FLAGS are
passed down to the configure script of the subpackage.
Speaking of potential distribution errors, distcheck also
ensures that the distclean rule actually removes all built
files. This is done by running ‘make distcleancheck’ at the end of
the VPATH build. By default, distcleancheck will run
distclean and then make sure the build tree has been emptied by
running ‘$(distcleancheck_listfiles)’. Usually this check will
find generated files that you forgot to add to the DISTCLEANFILES
variable (see Clean).
The distcleancheck behavior should be OK for most packages,
otherwise you have the possibility to override the definition of
either the distcleancheck rule, or the
‘$(distcleancheck_listfiles)’ variable. For instance, to disable
distcleancheck completely, add the following rule to your
top-level Makefile.am:
distcleancheck:
@:
If you want distcleancheck to ignore built files that have not
been cleaned because they are also part of the distribution, add the
following definition instead:
distcleancheck_listfiles = \
find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
sh '{}' ';'
The above definition is not the default because it's usually an error if
your Makefiles cause some distributed files to be rebuilt when the user
build the package. (Think about the user missing the tool required to
build the file; or if the required tool is built by your package,
consider the cross-compilation case where it can't be run.) There is
an entry in the FAQ about this (see distcleancheck), make sure you
read it before playing with distcleancheck_listfiles.
distcheck also checks that the uninstall rule works
properly, both for ordinary and DESTDIR builds. It does this
by invoking ‘make uninstall’, and then it checks the install tree
to see if any files are left over. This check will make sure that you
correctly coded your uninstall-related rules.
By default, the checking is done by the distuninstallcheck rule,
and the list of files in the install tree is generated by
‘$(distuninstallcheck_listfiles)’ (this is a variable whose value is
a shell command to run that prints the list of files to stdout).
Either of these can be overridden to modify the behavior of
distcheck. For instance, to disable this check completely, you
would write:
distuninstallcheck:
@:
Automake generates rules to provide archives of the project for distributions in various formats. Their targets are:
dist-bzip2dist-gzipdist-lzmadist-shardist-xzdist-zipdist-tarZThe 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.
Automake supports three forms of test suites, the first two of which are very similar.
If the variable TESTS is defined, its value is taken to be a
list of programs or scripts to run in order to do the testing.
Programs needing data files should look for them in srcdir
(which is both an environment variable and a make variable) so they
work when building in a separate directory (see Build Directories), and in
particular for the distcheck rule (see Checking the Distribution).
For each of the TESTS, the result of execution is printed along
with the test name, where PASS denotes a successful test,
FAIL denotes a failed test, XFAIL an expected failure,
XPASS an unexpected pass for a test that is supposed to fail,
and SKIP denotes a skipped test.
The number of failures will be printed at the end of the run. If a given test program exits with a status of 77, then its result is ignored in the final count. This feature allows non-portable tests to be ignored in environments where they don't make sense.
If the Automake option color-tests is used (see Options)
and standard output is connected to a capable terminal, then the test
results and the summary are colored appropriately. The user can disable
colored output by setting the make variable
‘AM_COLOR_TESTS=no’, or force colored output even without a connecting
terminal with ‘AM_COLOR_TESTS=always’.
The variable TESTS_ENVIRONMENT can be used to set environment
variables for the test run; the environment variable srcdir is
set in the rule. If all your test programs are scripts, you can also
set TESTS_ENVIRONMENT to an invocation of the shell (e.g.
‘$(SHELL) -x’ can be useful for debugging the tests), or any other
interpreter. For instance the following setup is used by the Automake
package to run four tests in Perl.
TESTS_ENVIRONMENT = $(PERL) -Mstrict -I $(top_srcdir)/lib -w
TESTS = Condition.pl DisjConditions.pl Version.pl Wrap.pl
You may define the variable XFAIL_TESTS to a list of tests
(usually a subset of TESTS) that are expected to fail. This will
reverse the result of those tests.
Automake ensures that each file listed in TESTS is built before
any tests are run; you can list both source and derived programs (or
scripts) in TESTS; the generated rule will look both in
srcdir and .. For instance, you might want to run a C
program as a test. To do this you would list its name in TESTS
and also in check_PROGRAMS, and then specify it as you would
any other program.
Programs listed in check_PROGRAMS (and check_LIBRARIES,
check_LTLIBRARIES...) are only built during make check,
not during make all. You should list there any program needed
by your tests that does not need to be built by make all. Note
that check_PROGRAMS are not automatically added to
TESTS because check_PROGRAMS usually lists programs used
by the tests, not the tests themselves. Of course you can set
TESTS = $(check_PROGRAMS) if all your programs are test cases.
The option parallel-tests (see Options) enables a test
suite driver that is mostly compatible to the simple test driver described
in the previous section, but provides a few more features and slightly different
semantics. It features concurrent execution of tests with make -j,
allows to specify inter-test dependencies, lazy reruns of tests that
have not completed in a prior run, summary and verbose output in
‘RST’ (reStructuredText) and ‘HTML’ format, and hard errors
for exceptional failures. Similar to the simple test driver,
TESTS_ENVIRONMENT, AM_COLOR_TESTS, XFAIL_TESTS, and
the check_* variables are honored, and the environment variable
srcdir is set during test execution.
This test driver is still experimental and may undergo changes in order to satisfy additional portability requirements.
The driver operates by defining a set of make rules to create
a summary log file, TEST_SUITE_LOG, which defaults to
test-suite.log and requires a .log suffix. This file
depends upon log files created for each single test program listed in
TESTS, which in turn contain all output produced by the
corresponding tests.
Each log file is created when the corresponding test has completed.
The set of log files is listed in the read-only variable
TEST_LOGS, and defaults to TESTS, with the executable
extension if any (see EXEEXT), as well as any suffix listed in
TEST_EXTENSIONS removed, and .log appended.
TEST_EXTENSIONS defaults to .test. Results are undefined
if a test file name ends in several concatenated suffixes.
For tests that match an extension .ext listed in
TEST_EXTENSIONS, you can provide a test driver using the variable
ext_LOG_COMPILER (note the upper-case extension) and pass
options in AM_ext_LOG_FLAGS and allow the user to pass
options in ext_LOG_FLAGS. It will cause all tests with
this extension to be called with this driver. For all tests without a
registered extension, the variables LOG_COMPILER,
AM_LOG_FLAGS, and LOG_FLAGS may be used. For example,
TESTS = foo.pl bar.py baz
TEST_EXTENSIONS = .pl .py
PL_LOG_COMPILER = $(PERL)
AM_PL_LOG_FLAGS = -w
PY_LOG_COMPILER = $(PYTHON)
AM_PY_LOG_FLAGS = -v
LOG_COMPILER = ./wrapper-script
AM_LOG_FLAGS = -d
will invoke ‘$(PERL) -w foo.pl’, ‘$(PYTHON) -v bar.py’, and ‘./wrapper-script -d baz’ to produce foo.log, bar.log, and baz.log, respectively. The ‘TESTS_ENVIRONMENT’ variable is still expanded before the driver, but should be reserved for the user.
As with the simple driver above, by default one status line is printed per completed test, and a short summary after the suite has completed. However, standard output and standard error of the test are redirected to a per-test log file, so that parallel execution does not produce intermingled output. The output from failed tests is collected in the test-suite.log file. If the variable ‘VERBOSE’ is set, this file is output after the summary. For best results, the tests should be verbose by default now.
With make check-html, the log files may be converted from RST
(reStructuredText, see http://docutils.sourceforge.net/rst.html)
to HTML using ‘RST2HTML’, which defaults to rst2html or
rst2html.py. The variable ‘TEST_SUITE_HTML’ contains the
set of converted log files. The log and HTML files are removed upon
make mostlyclean.
Even in the presence of expected failures (see XFAIL_TESTS, there
may be conditions under which a test outcome needs attention. For
example, with test-driven development, you may write tests for features
that you have not implemented yet, and thus mark these tests as expected
to fail. However, you may still be interested in exceptional conditions,
for example, tests that fail due to a segmentation violation or another
error that is independent of the feature awaiting implementation.
Tests can exit with an exit status of 99 to signal such a hard
error. Unless the variable DISABLE_HARD_ERRORS is set to a
nonempty value, such tests will be counted as failed.
By default, the test suite driver will run all tests, but there are several ways to limit the set of tests that are run:
TESTS variable, similarly to how you can with
the simple test driver from the previous section. For example, you can
use a command like this to run only a subset of the tests:
env TESTS="foo.test bar.test" make -e check
TEST_LOGS variable. By default, this variable is
computed at make run time from the value of TESTS as
described above. For example, you can use the following:
set x subset*.log; shift
env TEST_LOGS="foo.log $*" make -e check
RECHECK_LOGS contains the set of log files which are removed.
RECHECK_LOGS defaults to TEST_LOGS, which means all tests
need to be rechecked. By overriding this variable, you can choose which
tests need to be reconsidered. For example, you can lazily rerun only
those tests which are outdated, i.e., older than their prerequisite test
files, by setting this variable to the empty value:
env RECHECK_LOGS= make -e check
make recheck in the test directory.
This convenience target will set RECHECK_LOGS appropriately
before invoking the main test driver. The recheck-html target
does the same as recheck but again converts the resulting log
file in HTML format, like the check-html target.
In order to guarantee an ordering between tests even with make
-jN, dependencies between the corresponding log files may be
specified through usual make dependencies. For example, the
following snippet lets the test named foo-execute.test depend
upon completion of the test foo-compile.test:
TESTS = foo-compile.test foo-execute.test
foo-execute.log: foo-compile.log
Please note that this ordering ignores the results of required
tests, thus the test foo-execute.test is run even if the test
foo-compile.test failed or was skipped beforehand. Further,
please note that specifying such dependencies currently works only for
tests that end in one of the suffixes listed in TEST_EXTENSIONS.
Tests without such specified dependencies may be run concurrently with parallel make -jN, so be sure they are prepared for concurrent execution.
The combination of lazy test execution and correct dependencies between
tests and their sources may be exploited for efficient unit testing
during development. To further speed up the edit-compile-test cycle, it
may even be useful to specify compiled programs in EXTRA_PROGRAMS
instead of with check_PROGRAMS, as the former allows intertwined
compilation and test execution (but note that EXTRA_PROGRAMS are
not cleaned automatically, see Uniform).
The variables TESTS and XFAIL_TESTS may contain
conditional parts as well as configure substitutions. In the latter
case, however, certain restrictions apply: substituted test names
must end with a nonempty test suffix like .test, so that one of
the inference rules generated by automake can apply. For
literal test names, automake can generate per-target rules
to avoid this limitation.
Please note that it is currently not possible to use $(srcdir)/
or $(top_srcdir)/ in the TESTS variable. This technical
limitation is necessary to avoid generating test logs in the source tree
and has the unfortunate consequence that it is not possible to specify
distributed tests that are themselves generated by means of explicit
rules, in a way that is portable to all make implementations
(see Make Target Lookup, the
semantics of FreeBSD and OpenBSD make conflict with this).
In case of doubt you may want to require to use GNU make,
or work around the issue with inference rules to generate the tests.
If dejagnu appears in
AUTOMAKE_OPTIONS, then a dejagnu-based test suite is
assumed. The variable DEJATOOL is a list of names that are
passed, one at a time, as the --tool argument to
runtest invocations; it defaults to the name of the package.
The variable RUNTESTDEFAULTFLAGS holds the --tool and
--srcdir flags that are passed to dejagnu by default; this can be
overridden if necessary.
The variables EXPECT and RUNTEST can
also be overridden to provide project-specific values. For instance,
you will need to do this if you are testing a compiler toolchain,
because the default values do not take into account host and target
names.
The contents of the variable RUNTESTFLAGS are passed to the
runtest invocation. This is considered a “user variable”
(see User Variables). If you need to set runtest flags in
Makefile.am, you can use AM_RUNTESTFLAGS instead.
Automake will generate rules to create a local site.exp file,
defining various variables detected by configure. This file
is automatically read by DejaGnu. It is OK for the user of a package
to edit this file in order to tune the test suite. However this is
not the place where the test suite author should define new variables:
this should be done elsewhere in the real test suite code.
Especially, site.exp should not be distributed.
For more information regarding DejaGnu test suites, see Top.
In either case, the testing is done via ‘make check’.
The installcheck target is available to the user as a way to
run any tests after the package has been installed. You can add tests
to this by writing an installcheck-local rule.
Automake generates rules to automatically rebuild Makefiles, configure, and other derived files like Makefile.in.
If you are using AM_MAINTAINER_MODE in configure.ac, then
these automatic rebuilding rules are only enabled in maintainer mode.
Sometimes you need to run aclocal with an argument like
-I to tell it where to find .m4 files. Since
sometimes make will automatically run aclocal, you
need a way to specify these arguments. You can do this by defining
ACLOCAL_AMFLAGS; this holds arguments that are passed verbatim
to aclocal. This variable is only useful in the top-level
Makefile.am.
Sometimes it is convenient to supplement the rebuild rules for
configure or config.status with additional dependencies.
The variables CONFIGURE_DEPENDENCIES and
CONFIG_STATUS_DEPENDENCIES can be used to list these extra
dependencies. These variable should be defined in all
Makefiles of the tree (because these two rebuild rules are
output in all them), so it is safer and easier to AC_SUBST them
from configure.ac. For instance, the following statement will
cause configure to be rerun each time version.sh is
changed.
AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
Note the ‘$(top_srcdir)/’ in the file name. Since this variable is to be used in all Makefiles, its value must be sensible at any level in the build hierarchy.
Beware not to mistake CONFIGURE_DEPENDENCIES for
CONFIG_STATUS_DEPENDENCIES.
CONFIGURE_DEPENDENCIES adds dependencies to the
configure rule, whose effect is to run autoconf. This
variable should be seldom used, because automake already tracks
m4_included files. However it can be useful when playing
tricky games with m4_esyscmd or similar non-recommendable
macros with side effects.
CONFIG_STATUS_DEPENDENCIES adds dependencies to the
config.status rule, whose effect is to run configure.
This variable should therefore carry any non-standard source that may
be read as a side effect of running configure, like version.sh
in the example above.
Speaking of version.sh scripts, we recommend against them today. They are mainly used when the version of a package is updated automatically by a script (e.g., in daily builds). Here is what some old-style configure.acs may look like:
AC_INIT
. $srcdir/version.sh
AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
...
Here, version.sh is a shell fragment that sets
VERSION_NUMBER. The problem with this example is that
automake cannot track dependencies (listing version.sh
in CONFIG_STATUS_DEPENDENCIES, and distributing this file is up
to the user), and that it uses the obsolete form of AC_INIT and
AM_INIT_AUTOMAKE. Upgrading to the new syntax is not
straightforward, because shell variables are not allowed in
AC_INIT's arguments. We recommend that version.sh be
replaced by an M4 file that is included by configure.ac:
m4_include([version.m4])
AC_INIT([name], VERSION_NUMBER)
AM_INIT_AUTOMAKE
...
Here version.m4 could contain something like ‘m4_define([VERSION_NUMBER], [1.2])’. The advantage of this second form is that automake will take care of the dependencies when defining the rebuild rule, and will also distribute the file automatically. An inconvenience is that autoconf will now be rerun each time the version number is bumped, when only configure had to be rerun in the previous setup.
Various features of Automake can be controlled by options in the
Makefile.am. Such options are applied on a per-Makefile
basis when listed in a special Makefile variable named
AUTOMAKE_OPTIONS. They are applied globally to all processed
Makefiles when listed in the first argument of
AM_INIT_AUTOMAKE in configure.ac. Currently understood
options are:
dist-bzip2 to dist.
dist-lzma to dist.
dist-shar to dist.
dist-zip to dist.
dist-tarZ to dist.
AM_INIT_AUTOMAKE in
configure.ac, it will be ignored otherwise. It will also be
ignored in sub-packages of nested packages (see Subpackages).
AM_INIT_AUTOMAKE. It will prevent the PACKAGE and
VERSION variables from being AC_DEFINEd.
dist target. This is useful
when a package has its own method for making distributions.
dist-gzip to dist.
foo, it
will override a rule for a target named ‘foo$(EXEEXT)’. This is
necessary when EXEEXT is found to be empty. However, by
default automake will generate an error for this use. The
no-exeext option will disable this error. This is intended for
use only where it is known in advance that the package will not be
ported to Windows, or any other operating system using extensions on
executables.
info and install-info
targets will still be available. This option is disallowed at
gnu strictness and above.
install-man target will still
be available for optional installation. This option is disallowed at
gnu strictness and above.
TESTS that can run tests in parallel
(see Simple Tests using parallel-tests, for more information).
GEN output-file
instead of printing the command that will be executed to update output-file. It can also silence libtool output.
To enable less verbose build rules, both the developer and the user of the package have to take a number of steps. The developer needs to do either of the following:
AM_INIT_AUTOMAKE.
AM_SILENT_RULES macro from within the configure.ac
file.
If the developer has done either of the above, then the user of the package may influence the verbosity at configure run time as well as at make run time:
make V=1 will produce verbose output,
make V=0 less verbose output.
For portability to different make implementations, package authors
are advised to not set the variable V inside the Makefile.am
file, to allow the user to override the value for subdirectories as well.
The current implementation of this feature relies on a non-POSIX, but in practice rather widely supported Makefile construct of nested variable expansion ‘$(var1$(V))’. Do not use the silent-rules option if your package needs to build with make implementations that do not support it. The silent-rules option turns off warnings about recursive variable expansion, which are in turn enabled by -Wportability (see Invoking Automake).
To extend the silent mode to your own rules, you have two choices:
AM_V_GEN as a prefix to
commands that should output a status line in silent mode, and
AM_V_at as a prefix to commands that should not output anything
in silent mode. When output is to be verbose, both of these variables
will expand to the empty string.
AM_V_GEN:
pkg_verbose = $(pkg_verbose_$(V))
pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
pkg_verbose_0 = @echo GEN $@;
foo: foo.in
$(pkg_verbose)cp $(srcdir)/foo.in $@
installcheck rule check that installed scripts and
programs support the --help and --version options.
This also provides a basic check that the program's
run-time dependencies are satisfied after installation.
In a few situations, programs (or scripts) have to be exempted from this
test. For instance, false (from GNU sh-utils) is never
successful, even for --help or --version. You can list
such programs in the variable AM_INSTALLCHECK_STD_OPTIONS_EXEMPT.
Programs (not scripts) listed in this variable should be suffixed by
‘$(EXEEXT)’ for the sake of Win32 or OS/2. For instance, suppose we
build false as a program but true.sh as a script, and that
neither of them support --help or --version:
AUTOMAKE_OPTIONS = std-options
bin_PROGRAMS = false ...
bin_SCRIPTS = true.sh ...
AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
In order to use this option with C sources, you should add
AM_PROG_CC_C_O to configure.ac.