automake

Short Table of Contents

Table of Contents

GNU Automake

This manual is for GNU Automake (version 1.16.5, 1 October 2021), a program that creates GNU standards-compliant Makefiles from template files.

Copyright © 1995–2021 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, using aclocal

Auto-generating aclocal.m4

Autoconf macros supplied with Automake

Directories

Conditional Subdirectories

Building Programs and Libraries

Building a program

Building a Shared Library

Common Issues Related to Libtool’s Use

Yacc and Lex support

Fortran 77 Support

Mixing Fortran 77 With C and C++

Fortran 9x Support

Other Derived Objects

Built Sources

Other GNU Tools

Building documentation

What Gets Installed

What Goes in a Distribution

Support for test suites

Simple Tests

Scripts-based Testsuites

Custom Test Drivers

API for Custom Test Drivers

Using the TAP test protocol

Changing Automake’s Behavior

Miscellaneous Rules

Conditionals

Silencing make

When Automake Isn’t Enough

Frequently Asked Questions about Automake

Copying This Manual

Indices

1 Introduction

Automake is a tool for automatically generating Makefile.ins from files called Makefile.am. Each Makefile.am is basically a series of make variable definitions¹, 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 in The GNU Coding Standards) 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.

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

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.

For more information on bug reports, See Reporting Bugs.

2 An Introduction to the Autotools

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.

2.1 Introducing the GNU Build System

It is a truth universally acknowledged, that as a developer in possession of a new package, you 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 in The GNU Make Manual). You express the recipe to build your 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 in The Autoconf Manual). 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 in The GNU Coding Standards) 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.

2.2 Use Cases for the GNU Build System

In this section we explore several use cases for the GNU Build System. You can replay all of 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.

2.2.1 Basic Installation

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.

2.2.2 Standard Makefile Targets

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 all

Build programs, libraries, documentation, etc. (same as make).

make install

Install what needs to be installed, copying the files from the package’s tree to system-wide directories.

make install-strip

Same as make install, then strip debugging symbols. Some users like to trade space for useful bug reports...

make uninstall

The opposite of make install: erase the installed files. (This needs to be run from the same build tree that was installed.)

make clean

Erase from the build tree the files built by make all.

make distclean

Additionally erase anything ./configure created.

make check

Run the test suite, if any.

make installcheck

Check the installed programs or libraries, if supported.

make dist

Recreate package-version.tar.gz from all the source files.

2.2.3 Standard Directory Variables

The GNU Coding Standards also specify a hierarchy of variables to denote installation directories. Some of these are:

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.

As a user, if you wish to install a package on your own account, you 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.

2.2.4 Standard Configuration Variables

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

CC

C compiler command

CFLAGS

C compiler flags

CXX

C++ compiler command

CXXFLAGS

C++ compiler flags

LDFLAGS

linker flags

CPPFLAGS

C/C++ preprocessor flags

…

configure 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.

2.2.5 Overriding Default Configuration Setting with config.site

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

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 in The Autoconf Manual, for more information about this feature.

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

The GNU Build System distinguishes two trees: the source tree, and the build tree. These are two directories that may be the same, or different.

The source tree is rooted in the directory containing the configure script. It contains all the source files (those that are distributed), and may be arranged using several subdirectories.

The build tree is rooted in the current directory at the time 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 create everything in a build tree (that is, 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 in The GNU Make Manual).

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-ROMs with unpacked source code, before the GNU project grew so big.)

2.2.7 Two-Part Installation

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.

2.2.8 Cross-Compilation

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:

--build=build

The system on which the package is built.

--host=host

The system where built programs and libraries will run.

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

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

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

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

--target=target

When building compiler tools: the system for which the tools will create output.

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 cross-compile a cross-compiler; such a three-way cross-compilation is known as a Canadian cross.

See Specifying the System Type in The Autoconf Manual, for more information about these configure options.

2.2.9 Renaming Programs at Install Time

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.

--program-prefix=prefix

Prepend prefix to installed program names.

--program-suffix=suffix

Append suffix to installed program names.

--program-transform-name=program

Run sed program on installed program names.

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

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

2.2.10 Building Binary Packages Using DESTDIR

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.

2.2.11 Preparing Distributions

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:

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

All of these actions are performed in a temporary directory, so that no root privileges are required. The exact location and the exact structure of such a subdirectory (where the extracted sources are placed, how the temporary build and install directories are named and how deeply they are nested, etc.) is to be considered an implementation detail, which can change at any time; so do not rely on it.

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.

2.2.12 Automatic Dependency Tracking

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.

Automake generates code for automatic dependency tracking by default, unless the developer chooses to override it; for more information, see Dependencies.

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:

--disable-dependency-tracking

Speed up one-time builds.

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.

--enable-dependency-tracking

Do not reject slow dependency extractors.

See Dependency Tracking Evolution in Brief History of Automake, for some discussion about the different dependency tracking schemes used by Automake over the years.

2.2.13 Nested Packages

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 packages 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.

2.3 How Autotools Help

There are several reasons why you may not want to implement the GNU Build System yourself (read: write a configure script and Makefiles yourself).

• As we have seen, the GNU Build System has a lot of features (see Use Cases). Some users may expect features you have not implemented because you did not need them.
• Implementing these features portably is difficult and exhausting. Think of writing portable shell scripts, and portable Makefiles, for systems you may not have handy. See Portable Shell Programming in The Autoconf Manual, to convince yourself.
• You will have to upgrade your setup to follow changes to the GNU Coding Standards.

The GNU Autotools take all this burden off your back and provide:

• Tools to create a portable, complete, and self-contained GNU Build System, from simple instructions. Self-contained meaning the resulting build system does not require the GNU Autotools.
• A central place where fixes and improvements are made: a bug-fix for a portability issue will benefit every package.

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.

2.4 A Small Hello World

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.

2.4.1 Creating amhello-1.0.tar.gz

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.

• src/main.c is the source file for the hello program. We store it in the src/ subdirectory, because later, when the package evolves, it will ease the addition of a man/ directory for man pages, a data/ directory for data files, etc.

  ~/amhello % cat src/main.c
  #include <config.h>
  #include <stdio.h>
  
  int
  main (void)
  {
    puts ("Hello World!");
    puts ("This is " PACKAGE_STRING ".");
    return 0;
  }
  

• README contains some very limited documentation for our little package.

  ~/amhello % cat README
  This is a demonstration package for GNU Automake.
  Type 'info Automake' to read the Automake manual.
  

• Makefile.am and src/Makefile.am contain Automake instructions for these two directories.

  ~/amhello % cat src/Makefile.am
  bin_PROGRAMS = hello
  hello_SOURCES = main.c
  ~/amhello % cat Makefile.am
  SUBDIRS = src
  dist_doc_DATA = README
  

• Finally, configure.ac contains Autoconf instructions to create the configure script.

  ~/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'
configure.ac: installing './compile'
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 of 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.

2.4.2 amhello’s configure.ac Setup Explained

Let us begin with the contents of configure.ac.

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

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 in The Autoconf Manual).

The macros prefixed with AC_ are Autoconf macros, documented in the Autoconf manual (see Autoconf Macro Index in The Autoconf Manual). 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 quite large, 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 in The Autoconf Manual).

2.4.3 amhello’s Makefile.am Setup Explained

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.

One thing not covered in this example is accessing the installation directory values (see Standard Directory Variables) from your program code, that is, converting them into defined macros. For this, see Defining Directories in The Autoconf Manual.

3 General ideas

The following sections cover a few basic ideas that will help you understand how Automake works.

3.1 General Operation

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 mostly verbatim into the generated file, with all variable definitions preceding all rules. This allows you to add almost 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 the 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.

Automake tries to keep comments grouped with any adjoining rules or variable definitions.

Generally, Automake is not particularly smart in the parsing of unusual Makefile constructs, so you’re advised to avoid fancy constructs or “creative” use of whitespace. For example, TAB characters cannot be used between a target name and the following “:” character, and variable assignments shouldn’t be indented with TAB characters. Also, using more complex macros in target names can cause trouble:

% cat Makefile.am
$(FOO:=x): bar
% automake
Makefile.am:1: bad characters in variable name '$(FOO'
Makefile.am:1: ':='-style assignments are not portable

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 often more 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

3.2 Strictness

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—how stringently Automake should enforce conformance with GNU conventions. Each strictness level can be selected using an option of the same name; see Options.

The strictness levels are:

gnu

This is the default level of strictness. Automake will check for basic compliance with the GNU standards for software packaging. See The GNU Coding Standards, for full details of these standards. Currently the following checks are made:

• The files INSTALL, NEWS, README, AUTHORS, and ChangeLog, plus one of COPYING.LIB, COPYING.LESSER or COPYING, are required at the topmost directory of the package.

  If the --add-missing option is given, automake will add a generic version of the INSTALL file as well as the COPYING file containing the text of the current version of the GNU General Public License existing at the time of this Automake release (version 3 as this is written, https://www.gnu.org/copyleft/gpl.html). However, an existing COPYING file will never be overwritten by automake.

• The options no-installman and no-installinfo are prohibited.

Future versions of Automake will add more checks at this level of strictness; it is advisable to be familiar with the precise requirements of the GNU standards.

Future versions of Automake may, at this level of strictness, require certain non-standard GNU tools to be available to maintainer-only Makefile rules. For instance, in the future pathchk (see pathchk invocation in GNU Coreutils) may be required to run ‘make dist’.

foreign

Automake will check for only those things that are absolutely required for proper operation. For instance, whereas GNU standards dictate the existence of a NEWS file, it will not be required in this mode. This strictness will also turn off some warnings by default (among them, portability warnings).

gnits

Automake will check for compliance to the as-yet-unwritten Gnits standards. These are based on the GNU standards, but are even more detailed. Unless you are a Gnits standards contributor, it is recommended that you avoid this option until such time as the Gnits standard is published (which is unlikely to ever happen).

Currently, --gnits does all the checks that --gnu does, and checks the following as well:

• ‘make installcheck’ will check to make sure that the --help and --version print a usage message and a version string, respectively. This is the std-options option (see Options).
• ‘make dist’ will check to make sure the NEWS file has been updated to the current version.
• VERSION is checked to make sure its format complies with Gnits standards.
• If VERSION indicates that this is an alpha release, and the file README-alpha appears in the topmost directory of a package, then it is included in the distribution. This is done in --gnits mode, and no other, because this mode is the only one where version number formats are constrained, and hence the only mode where Automake can automatically determine whether README-alpha should be included.
• The file THANKS is required.

3.3 The Uniform Naming Scheme

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 in The GNU Coding Standards). 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 (but see below how to override the check if you need to). 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

This feature can also be used to override the sanity checks Automake performs to diagnose suspicious directory/primary couples (in the unlikely case that you need to omit these checks). For example, Automake would error out on this input:

# Forbidden directory combinations, automake will error out on this.
pkglib_PROGRAMS = foo
doc_LIBRARIES = libquux.a

but it will succeed with this:

# Work around forbidden directory combinations.  Do not use this
# without a very good reason!
my_execbindir = $(pkglibdir)
my_doclibdir = $(docdir)
my_execbin_PROGRAMS = foo
my_doclib_LIBRARIES = libquux.a

The ‘exec’ substring of the ‘my_execbindir’ variable lets the files be installed at the right time (see The Two Parts of Install).

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’, ‘LTLIBRARIES’, ‘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).

3.4 Staying below the command line length limit

Traditionally, most unix-like systems have a length limitation for the command line arguments and environment contents when creating new processes (see for example https://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 systems’ make commands may prepend VPATH prefixes like ‘${srcdir}/’ to file names from the source tree automatically (see Automatic Rule Rewriting in The Autoconf Manual). 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).

3.5 How derived variables are named

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.

3.6 Variables reserved for the user

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.

3.7 Programs automake might require

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.

ar-lib

This is a wrapper primarily for the Microsoft lib archiver, to make it more POSIX-like.

compile

This is a wrapper for compilers that do not accept options -c and -o at the same time. It is only used when absolutely required. Such compilers are rare, with the Microsoft C/C++ Compiler as the most notable exception. This wrapper also makes the following common options available for that compiler, while performing file name translation where needed: -I, -L, -l, -Wl, and -Xlinker.

config.guess

config.sub

These two programs compute the canonical triplets for the given build, host, or target architecture. These programs are updated regularly to support new architectures and fix probes broken by changes in new kernel versions. Each new release of Automake comes with up-to-date copies of these programs. If your copy of Automake is getting old, you are encouraged to fetch the latest versions of these files from https://savannah.gnu.org/git/?group=config before making a release.

depcomp

This program understands how to run a compiler so that it will generate not only the desired output but also dependency information that is then used by the automatic dependency tracking feature (see Dependencies).

install-sh

This is a replacement for the install program that works on platforms where install is unavailable or unusable.

mdate-sh

This script is used to generate a version.texi file. It examines a file and prints some date information about it.

missing

This wraps a number of programs that are typically only required by maintainers. If the program in question doesn’t exist, or seems too old, missing will print an informative warning before failing out, to provide the user with more context and information.

mkinstalldirs

This script used to be a wrapper around ‘mkdir -p’, which is not portable. Now we prefer to use ‘install-sh -d’ when configure finds that ‘mkdir -p’ does not work, this makes one less script to distribute.

For 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-compile

This is used to byte-compile Python scripts.

test-driver

This implements the default test driver offered by the parallel testsuite harness.

texinfo.tex

When Texinfo sources are in the package, this file is required for ‘make dvi’, ‘make ps’ and ‘make pdf’. The latest version can be downloaded from https://www.gnu.org/software/texinfo/. A working TeX distribution, or at least a tex program, is also required. Furthermore, ‘make dist’ invokes ‘make dvi’, so these become requirements for making a distribution with Texinfo sources.

ylwrap

This program wraps lex and yacc to rename their output files. It also ensures that, for instance, multiple yacc instances can be invoked in a single directory in parallel.

4 Some example packages

This 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.

4.1 A simple example, start to finish

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!

4.2 Building true and false

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

As it turns out, there is also a much easier way to do this same task. Some of the above technique is 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. 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.)

5 Creating a Makefile.in

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-missing

Automake requires certain common files to exist in certain situations; for instance, config.guess is required if configure.ac invokes AC_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

Look for Automake data files in directory dir instead of in the installation directory. This is typically used for debugging.

The environment variable AUTOMAKE_LIBDIR provides another way to set the directory containing Automake data files. However --libdir takes precedence over it.

--print-libdir

Print the path of the installation directory containing Automake-provided scripts and data files (e.g., texinfo.texi and install-sh).

-c

--copy

When used with --add-missing, causes installed files to be copied. The default is to make a symbolic link.

-f

--force-missing

When used with --add-missing, causes standard files to be reinstalled even if they already exist in the source tree. This involves removing the file from the source tree before creating the new symlink (or, with --copy, copying the new file).

--foreign

Set the global strictness to foreign. For more information, see Strictness.

--gnits

Set the global strictness to gnits. For more information, see Strictness.

--gnu

Set the global strictness to gnu. For more information, see Strictness. This is the default strictness.

--help

Print a summary of the command line options and exit.

-i

--ignore-deps

This disables the dependency tracking feature in generated Makefiles; see Dependencies.

--include-deps

This enables the dependency tracking feature. This feature is enabled by default. This option is provided for historical reasons only and probably should not be used.

--no-force

Ordinarily automake creates all Makefile.ins mentioned in configure.ac. This option causes it to only update those Makefile.ins that are out of date with respect to one of their dependents.

-o dir

--output-dir=dir

Put the generated Makefile.in in the directory dir. Ordinarily each Makefile.in is created in the directory of the corresponding Makefile.am. This option is deprecated and will be removed in a future release.

-v

--verbose

Cause Automake to print information about which files are being read or created.

--version

Print the version number of Automake and exit.

-W category[,category...]

--warnings=category[,category...]

Output warnings about a category of potential problems with the package. category can be any of:

cross

Constructs compromising the ability to cross-compile the package.

gnu

Minor deviations from the GNU Coding Standards (see The GNU Coding Standards).

obsolete

Obsolete features or constructions.

override

Redefinitions of Automake rules or variables.

portability

Portability issues (e.g., use of make features that are known to be not portable).

portability-recursive

Recursive, or nested, Make variable expansions ($(foo$(x))). These are not universally supported, but are more portable than the other non-portable constructs diagnosed by -Wportability. These warnings are turned on by -Wportability but can then be turned off specifically by -Wno-portability-recursive.

extra-portability

Extra portability issues, related to rarely-used tools such as the Microsoft lib archiver.

syntax

Questionable syntax, unused variables, typos, etc.

unsupported

Unsupported or incomplete features.

all

Turn on all the above categories of warnings.

none

Turn off all the above categories of warnings.

error

Treat warnings as errors.

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

Warnings in the ‘gnu’, ‘obsolete’, ‘portability’, ‘syntax’, and ‘unsupported’ categories are turned on by default. The ‘gnu’ and ‘portability’ categories are turned off in --foreign strictness.

Turning off ‘portability’ will also turn off ‘extra-portability’, and similarly turning on ‘extra-portability’ will also turn on ‘portability’. However, turning on ‘portability’ or turning off ‘extra-portability’ will not affect the other category.

Unknown warning categories supplied as an argument to -W will themselves produce a warning, in the ‘unsupported’ category. This warning is never treated as an error.

The environment variable WARNINGS can contain a comma separated list of categories to enable. -W settings on the command line take precedence; for instance, -Wnone also turns off any warning categories enabled by WARNINGS.

Unknown warning categories named in WARNINGS are silently ignored.

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.

6 Scanning configure.ac, using aclocal

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.

6.1 Configuration requirements

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_FILES

AC_OUTPUT

These two macros are usually invoked as follows near the end of configure.ac.

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

Automake uses these to determine which files to create (see Creating Output Files in The Autoconf Manual). 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 of 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:

• Use literals for Makefiles, and for other files whenever possible.
• Use ‘$file’ (or ‘${file}’ without ‘AC_SUBST([file])’) for files that automake should ignore.
• Use ‘${file}’ and ‘AC_SUBST([file])’ for files that automake should not ignore.

6.2 Other things Automake recognizes

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_BUILD

AC_CANONICAL_HOST

AC_CANONICAL_TARGET

Automake will ensure that config.guess and config.sub exist. Also, the Makefile variables build_triplet, host_triplet and target_triplet are introduced. See Getting the Canonical System Type in The Autoconf Manual.

AC_CONFIG_AUX_DIR

Automake will look for various helper scripts, such as install-sh, in the directory named in this macro invocation. (The full list of scripts is: ar-lib, config.guess, config.sub, depcomp, compile, install-sh, ltmain.sh, mdate-sh, missing, mkinstalldirs, py-compile, test-driver, texinfo.tex, ylwrap.) Not all scripts are always searched for; some scripts will only be sought if the generated Makefile.in requires them.

If AC_CONFIG_AUX_DIR is used, it must be given before the call to AM_INIT_AUTOMAKE; Automake will warn about this if it is not so. All other AC_CONFIG_... macros are conventionally called after AM_INIT_AUTOMAKE, though they may or may not work in other locations, with or without warnings.

If 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 in The Autoconf Manual.

Required files from AC_CONFIG_AUX_DIR are automatically distributed, even if there is no Makefile.am in this directory.

AC_CONFIG_LIBOBJ_DIR

Automake will require the sources file declared with AC_LIBSOURCE (see below) in the directory specified by this macro.

AC_CONFIG_HEADERS

Automake will generate rules to rebuild these headers from the corresponding templates (usually, the template for a foo.h header being foo.h.in).

As with AC_CONFIG_FILES (see Requirements), parts of the specification using shell variables will be ignored as far as cleaning, distributing, and rebuilding is concerned.

Older versions of Automake required the use of AM_CONFIG_HEADER; this is no longer the case, and that macro has indeed been removed.

AC_CONFIG_LINKS

Automake will generate rules to remove configure generated links on ‘make distclean’ and to distribute named source files as part of ‘make dist’.

As with 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_LIBOBJ

AC_LIBSOURCE

AC_LIBSOURCES

Automake will automatically distribute any file listed in AC_LIBSOURCE or AC_LIBSOURCES.

Note that the AC_LIBOBJ macro calls AC_LIBSOURCE. So if an Autoconf macro is documented to call ‘AC_LIBOBJ([file])’, 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 in The Autoconf Manual.

AC_PROG_RANLIB

This is required if any libraries are built in the package. See Particular Program Checks in The Autoconf Manual.

AC_PROG_CXX

This is required if any C++ source is included. See Particular Program Checks in The Autoconf Manual.

AC_PROG_OBJC

This is required if any Objective C source is included. See Particular Program Checks in The Autoconf Manual.

AC_PROG_OBJCXX

This is required if any Objective C++ source is included. See Particular Program Checks in The Autoconf Manual.

AC_PROG_F77

This is required if any Fortran 77 source is included. See Particular Program Checks in The Autoconf Manual.

AC_F77_LIBRARY_LDFLAGS

This is required for programs and shared libraries that are a mixture of languages that include Fortran 77 (see Mixing Fortran 77 With C and C++). See Autoconf macros supplied with Automake.

AC_FC_SRCEXT

Automake will add the flags computed by AC_FC_SRCEXT to compilation of files with the respective source extension (see Fortran Compiler Characteristics in The Autoconf Manual).

AC_PROG_FC

This is required if any Fortran 90/95 source is included. This macro is distributed with Autoconf version 2.58 and later. See Particular Program Checks in The Autoconf Manual.

AC_PROG_LIBTOOL

Automake will turn on processing for libtool (see Introduction in The Libtool Manual).

AC_PROG_YACC

If a Yacc source file is seen, then you must either use this macro or define the variable YACC in configure.ac. The former is preferred (see Particular Program Checks in The Autoconf Manual).

AC_PROG_LEX

If a Lex source file is seen, then this macro must be used. See Particular Program Checks in The Autoconf Manual.

AC_REQUIRE_AUX_FILE

For each AC_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 in The Autoconf Manual.

AC_SUBST

The first argument is automatically defined as a variable in each generated Makefile.in, unless AM_SUBST_NOTMAKE is also used for this variable. See Setting Output Variables in The Autoconf Manual.

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_CONDITIONAL

This introduces an Automake conditional (see Conditionals).

AM_COND_IF

This macro allows automake 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_GETTEXT

This macro is required for packages that use GNU gettext (see gettext). It is distributed with gettext. If Automake sees this macro it ensures that the package meets some of gettext’s requirements.

AM_GNU_GETTEXT_INTL_SUBDIR

This macro specifies that the intl/ subdirectory is to be built, even if the AM_GNU_GETTEXT macro was invoked with a first argument of ‘external’.

AM_MAINTAINER_MODE([default-mode])

This macro adds an --enable-maintainer-mode option to configure. If this is used, automake will cause “maintainer-only” rules to be turned off by default in the generated Makefile.ins, unless default-mode is ‘enable’. This macro defines the MAINTAINER_MODE conditional, which you can use in your own Makefile.am. See maintainer-mode.

AM_SUBST_NOTMAKE(var)

Prevent Automake from defining a variable var, even if it is substituted by config.status. Normally, Automake defines a make variable for each configure substitution, i.e., for each 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_include

Files included by configure.ac using this macro will be detected by Automake and automatically distributed. They will also appear as dependencies in Makefile rules.

m4_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 aclocal Invocation).

6.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros that can be used in your package (see Macros); some of them are 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 should 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 The Autoconf Manual) in order to trace the macros that are 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.

6.3.1 aclocal Options

aclocal accepts the following options:

--automake-acdir=dir

Look for the automake-provided macro files in dir instead of in the installation directory. This is typically used for debugging.

The environment variable ACLOCAL_AUTOMAKE_DIR provides another way to set the directory containing automake-provided macro files. However --automake-acdir takes precedence over it.

--system-acdir=dir

Look for the system-wide third-party macro files (and the special dirlist file) in dir instead of in the installation directory. This is typically used for debugging.

--diff[=command]

Run command on the M4 file that would be installed or overwritten by --install. The default command is ‘diff -u’. This option implies --install and --dry-run.

--dry-run

Do not overwrite (or create) aclocal.m4 and M4 files installed by --install.

--help

Print a summary of the command line options and exit.

-I dir

Add the directory dir to the list of directories searched for .m4 files.

--install

Install system-wide third-party macros into the first directory specified with ‘-I dir’ instead of copying them in the output file. Note that this will happen also if dir is an absolute path.

When 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).

--force

Always overwrite the output file. The default is to overwrite the output file only when needed, i.e., when its contents change or if one of its dependencies is younger.

This 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

Cause the output to be put into file instead of aclocal.m4.

--print-ac-dir

Prints the name of the directory that aclocal will search to find third-party .m4 files. When this option is given, normal processing is suppressed. This option was used in the past by third-party packages to determine where to install .m4 macro files, but this usage is today discouraged, since it causes ‘$(prefix)’ not to be thoroughly honored (which violates the GNU Coding Standards), and similar semantics can be better obtained with the ACLOCAL_PATH environment variable; see Extending aclocal.

--verbose

Print the names of the files it examines.

--version

Print the version number of Automake and exit.

-W CATEGORY

--warnings=category

Output warnings falling in category. category can be one of:

syntax

dubious syntactic constructs, underquoted macros, unused macros, etc.

unsupported

unknown macros

all

all the warnings, this is the default

none

turn off all the warnings

error

treat warnings as errors

All warnings are output by default.

The environment variable WARNINGS is honored in the same way as it is for automake (see automake Invocation).

6.3.2 Macro Search Path

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

acdir-APIVERSION

This is where the .m4 macros distributed with Automake itself are stored. APIVERSION depends on the Automake release used; for example, for Automake 1.11.x, APIVERSION = 1.11.

acdir

This directory is intended for third party .m4 files, and is configured when automake itself is built. This is @datadir@/aclocal/, which typically expands to ${prefix}/share/aclocal/. To find the compiled-in value of acdir, use the --print-ac-dir option (see aclocal Options).

As an example, suppose that automake-1.11.2 was configured with --prefix=/usr/local. Then, the search path would be:

1. /usr/local/share/aclocal-1.11.2/
2. /usr/local/share/aclocal/

The paths for the acdir and acdir-APIVERSION directories can be changed respectively through aclocal options --system-acdir and --automake-acdir (see aclocal Options). Note however that these options are only intended for use by the internal Automake test suite, or for debugging under highly unusual situations; they are not ordinarily needed by end-users.

As explained in (see aclocal Options), there are several options that can be used to change or extend this search path.

Modifying the Macro Search Path: ‘-I dir’

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:

1. /foo
2. /bar
3. acdir-APIVERSION
4. acdir

Modifying the Macro Search Path: dirlist

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

1. /foo
2. /bar
3. acdir-APIVERSION
4. acdir
5. /test1
6. /test2

and all directories with path names starting with /test3.

If the --system-acdir=dir option is used, then aclocal will search for the dirlist file in dir; but remember the warnings above against the use of --system-acdir.

dirlist is useful in the following situation: suppose that automake version 1.11.2 is installed with ‘--prefix=/usr’ by the system vendor. Thus, the default search directories are

1. /usr/share/aclocal-1.11/
2. /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

1. /usr/share/aclocal-1.11/
2. /usr/share/aclocal/
3. /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 them 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.

Modifying the Macro Search Path: ACLOCAL_PATH

The fourth and last mechanism to customize the macro search path is also the simplest. Any directory included in the colon-separated environment variable ACLOCAL_PATH is added to the search path and takes precedence over system directories (including those found via dirlist), with the exception of the versioned directory acdir-APIVERSION (see Macro Search Path). However, directories passed via -I will take precedence over directories in ACLOCAL_PATH.

Also note that, if the --install option is used, any .m4 file containing a required macro that is found in a directory listed in ACLOCAL_PATH will be installed locally. In this case, serial numbers in .m4 are honored too, see Serials.

Conversely to dirlist, ACLOCAL_PATH is useful if you are using a global copy of Automake and want aclocal to look for macros somewhere under your home directory.

Planned future incompatibilities

The order in which the directories in the macro search path are currently looked up is confusing and/or suboptimal in various aspects, and is probably going to be changed in the future Automake release. In particular, directories in ACLOCAL_PATH and acdir might end up taking precedence over acdir-APIVERSION, and directories in acdir/dirlist might end up taking precedence over acdir. This is a possible future incompatibility!

6.3.3 Writing your own aclocal macros

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). It might also be helpful to suggest to the user to add the $(datadir)/aclocal directory to his ACLOCAL_PATH variable (see ACLOCAL_PATH) so that aclocal will find the .m4 files installed by your package automatically.

A file of macros should be a series of properly quoted AC_DEFUN’s (see Macro Definitions in The Autoconf Manual). The aclocal programs also understands AC_REQUIRE (see Prerequisite Macros in The Autoconf Manual), 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 warns about all underquoted calls to AC_DEFUN. We realize this annoys some 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 of these third party .m4 files, maybe several times, even including files that end up not being needed. Doing so should alleviate many problems of the current implementation; however, it requires a stricter style from macro authors. Hopefully it is easy to revise the existing macros. For instance,

# bad style
AC_PREREQ(2.68)
AC_DEFUN(AX_FOOBAR,
[AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
])

should be rewritten as

AC_DEFUN([AX_FOOBAR],
[AC_PREREQ([2.68])dnl
AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
])

Wrapping the AC_PREREQ call inside the macro ensures that Autoconf 2.68 will not be required if AX_FOOBAR is not 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.68 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.

6.3.4 Handling 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/. Then it’s enough to update configure.ac by adding a proper call to AC_CONFIG_MACRO_DIRS:

AC_CONFIG_MACRO_DIRS([m4])

aclocal will then take care of automatically adding m4/ to its search path for m4 files.

When ‘aclocal’ 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. In fact, 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 the option --install to copy these system-wide third-party macros in your local macro directory, helping to solve the above problem.

With this setup, system-wide macros will be copied to m4/ the first time you run aclocal. 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.

6.3.5 Serial Numbers

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 contain 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

AC_CONFIG_MACRO_DIRS([m4])

in its configure.ac.

Initially the m4/ directory is empty. The first time we run aclocal --install, it will notice that

• configure.ac uses AX_THIRD_PARTY
• No local macros define AX_THIRD_PARTY
• /usr/share/aclocal/thirdparty.m4 defines AX_THIRD_PARTY with serial number 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 --install’ is run, something different happens. aclocal notices that

• configure.ac uses AX_THIRD_PARTY
• m4/thirdparty.m4 defines AX_THIRD_PARTY with serial number 1.
• /usr/share/aclocal/thirdparty.m4 defines AX_THIRD_PARTY with serial number 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 --install’ is run the situation is the following:

• configure.ac uses AX_THIRD_PARTY
• m4/thirdparty.m4 defines AX_THIRD_PARTY with serial number 1.
• /usr/share/aclocal/thirdparty.m4 defines 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 --diff’ to review the changes ‘aclocal --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 --install’.

6.3.6 The Future of aclocal

Ideally, aclocal should not be part of Automake. Automake should focus on generating Makefiles; dealing with M4 macros is more 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 or autogen.sh, that will just call aclocal, libtoolize, gettextize or autopoint, autoconf, autoheader, and automake in the right order. In fact, this is precisely what autoreconf can do for you. If your package has such a bootstrap or autogen.sh script, consider using autoreconf. That should simplify its logic a lot (less things to maintain, all to the good), 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 easy provided all macros are properly written (see Extending aclocal).

6.4 Autoconf macros supplied with Automake

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.

6.4.1 Public Macros

AM_INIT_AUTOMAKE([OPTIONS])

Runs many macros required for proper operation of the generated Makefiles.

Today, 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).

This macro can also be called in another, deprecated form: AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE]). In this form, there are two required arguments: the package and the version number. This usage is mostly obsolete because the package and version can be obtained from Autoconf’s AC_INIT macro. However, differently from what happens for AC_INIT invocations, this AM_INIT_AUTOMAKE invocation supports shell variables’ expansions in the PACKAGE and VERSION arguments (which otherwise defaults, respectively, to the PACKAGE_TARNAME and PACKAGE_VERSION defined via the AC_INIT invocation; see The AC_INIT macro in The Autoconf Manual); and this can still be useful in some selected situations. Our hope is that future Autoconf versions will improve their support for package versions defined dynamically at configure runtime; when (and if) this happens, support for the two-args AM_INIT_AUTOMAKE invocation will likely be removed from Automake.

If your configure.ac has:

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

you should 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 (see List of Automake options):

AM_INIT_AUTOMAKE([no-define ...])

AM_PATH_LISPDIR

Searches for the program emacs, and, if found, sets the output variable lispdir 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_AR([act-if-fail])

You must use this macro when you use the archiver in your project, if you want support for unusual archivers such as Microsoft lib. The content of the optional argument is executed if the archiver interface is not recognized; the default action is to abort configure with an error message.

AM_PROG_AS

Use this macro when you have assembly code in your project. This will choose the assembler for you (by default the C compiler) and set CCAS, and will also set CCASFLAGS if required.

AM_PROG_CC_C_O

This is an obsolescent macro that checks that the C compiler supports the -c and -o options together. Note that, since Automake 1.14, the AC_PROG_CC is rewritten to implement such checks itself, and thus the explicit use of AM_PROG_CC_C_O should no longer be required.

AM_PROG_LEX

Like AC_PROG_LEX (see Particular Program Checks in The Autoconf Manual), but uses the missing script on systems that do not have lex. HP-UX 10 is one such system.

AM_PROG_GCJ

This macro finds the gcj program or causes an error. It sets GCJ and GCJFLAGS. gcj is the Java front-end to the GNU Compiler Collection.

AM_PROG_UPC([compiler-search-list])

Find a compiler for Unified Parallel C and define the UPC variable. The default compiler-search-list is ‘upcc upc’. This macro will abort configure if no Unified Parallel C compiler is found.

AM_MISSING_PROG(name, program)

Find a maintainer tool program and define the name environment variable with its location. If program is not detected, then name will instead invoke the missing script, in order to give useful advice to the user about the missing maintainer tool. See maintainer-mode, for more information on when the missing script is appropriate.

AM_SILENT_RULES

Control the machinery for less verbose build output (see Automake Silent Rules).

AM_WITH_DMALLOC

Add support for the Dmalloc package. If the user runs configure with --with-dmalloc, then define WITH_DMALLOC and add -ldmalloc to LIBS.

6.4.2 Obsolete Macros

Although using some of the following macros was required in past releases, you should not use any of them in new code. All these macros will be removed in the next major Automake version; if you are still using them, running autoupdate should adjust your configure.ac automatically (see Using autoupdate to Modernize configure.ac in The Autoconf Manual). Do it NOW!

AM_PROG_MKDIR_P

From Automake 1.8 to 1.9.6 this macro used to define the output variable mkdir_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 in The Autoconf Manual), however this defines the output variable MKDIR_P instead. In case you are still using the AM_PROG_MKDIR_P macro in your configure.ac, or its provided variable $(mkdir_p) in your Makefile.am, you are advised to switch ASAP to the more modern Autoconf-provided interface instead; both the macro and the variable might be removed in a future major Automake release.

6.4.3 Private Macros

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_DEPENDENCIES

AM_SET_DEPDIR

AM_DEP_TRACK

AM_OUTPUT_DEPENDENCY_COMMANDS

These macros are used to implement Automake’s automatic dependency tracking scheme. They are called automatically by Automake when required, and there should be no need to invoke them manually.

AM_MAKE_INCLUDE

This macro is used to discover how the user’s make handles include statements. This macro is automatically invoked when needed; there should be no need to invoke it manually.

AM_PROG_INSTALL_STRIP

This is used to find a version of install that can be used to strip a program at installation time. This macro is automatically included when required.

AM_SANITY_CHECK

This checks to make sure that a file created in the build directory is newer than a file in the source directory. This can fail on systems where the clock is set incorrectly. This macro is automatically run from AM_INIT_AUTOMAKE.

7 Directories

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 example, there could be a directory for the program’s source, one for the testsuite, and one for the documentation; or, for very large projects, there could be one directory per program, per library or per module.

The traditional approach is to build these subdirectories recursively, employing make recursion: each directory contains its own Makefile, and when make is run from the top-level directory, it enters each subdirectory in turn, and invokes there a new make instance to build the directory’s contents.

Because this approach is very widespread, Automake offers built-in support for it. However, it is worth noting that the use of make recursion has its own serious issues and drawbacks, and that it’s well possible to have packages with a multi directory layout that make little or no use of such recursion (examples of such packages are GNU Bison and GNU Automake itself); see also the Alternative section below.

7.1 Recursing subdirectories

In packages using make recursion, 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.

In addition to the built-in recursive targets defined by Automake (all, check, etc.), the developer can also define his own recursive targets. That is done by passing the names of such targets as arguments to the m4 macro AM_EXTRA_RECURSIVE_TARGETS in configure.ac. Automake generates rules to handle the recursion for such targets; and the developer can define real actions for them by defining corresponding -local targets.

% cat configure.ac
AC_INIT([pkg-name], [1.0])
AM_INIT_AUTOMAKE
AM_EXTRA_RECURSIVE_TARGETS([foo])
AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
AC_OUTPUT
% cat Makefile.am
SUBDIRS = sub
foo-local:
        @echo This will be run by "make foo".
% cat sub/Makefile.am
SUBDIRS = src
% cat sub/src/Makefile.am
foo-local:
        @echo This too will be run by a "make foo" issued either in
        @echo the 'sub/src/' directory, the 'sub/' directory, or the
        @echo top-level directory.

7.2 Conditional Subdirectories

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 set up a project like this. You can use Automake conditionals (see Conditionals) or use Autoconf AC_SUBST variables (see Setting Output Variables in The Autoconf Manual). Using Automake conditionals is the preferred solution. Before we illustrate these two possibilities, let’s introduce DIST_SUBDIRS.

7.2.1 SUBDIRS vs. DIST_SUBDIRS

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

SUBDIRS contains the subdirectories of the current directory that must be built (see Subdirectories). It must be defined manually; Automake will never guess a directory is to be built. 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.

7.2.2 Subdirectories with AM_CONDITIONAL

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

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

Then SUBDIRS can be defined in the top-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.

7.2.3 Subdirectories with AC_SUBST

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

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

In this case the top-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.

7.2.4 Unconfigured Subdirectories

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 a 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.

7.3 An Alternative Approach to Subdirectories

If you’ve ever read Peter Miller’s excellent paper, Recursive Make Considered Harmful, the preceding sections on the use of make recursion 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 is intended to have sufficient cross-directory support to enable you to write a single Makefile.am for a complex multi-directory package. (If it seems to be lacking, please report the issue as usual.)

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.

7.4 Nesting Packages

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 Configuring Other Packages in Subdirectories in The Autoconf Manual).

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
AM_PROG_AR
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 look like a gain in size (a few kilobytes), but more importantly, it is 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.

8 Building Programs and Libraries

A large part of Automake’s functionality is dedicated to making it easy to build programs and libraries.

8.1 Building a program

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).

8.1.1 Defining program sources

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, 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.

8.1.2 Linking the program

If you need to link against libraries that are not found by configure, you can use LDADD to do so. This variable is used to specify additional objects or libraries to link with; it is inappropriate for specifying specific linker flags; you should use AM_LDFLAGS for this purpose.

Sometimes, multiple programs are built in one directory but do not share the same link-time requirements. In this case, you can use the prog_LDADD variable (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 in fact part of that program. This can be done using either the prog_DEPENDENCIES or the EXTRA_prog_DEPENDENCIES variable. Each program depends on the contents both variables, 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.

The EXTRA_prog_DEPENDENCIES may be useful for cases where you merely want to augment the automake-generated prog_DEPENDENCIES rather than replacing it.

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.

8.1.3 Conditional compilation of sources

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.

Conditional Compilation using _LDADD Substitutions

Automake must know all the source files that could possibly go into a program, even if not all the files are built in every circumstance. Any files that are only conditionally built should be listed in the appropriate EXTRA_ variable. For instance, 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 set up 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.

Conditional Compilation using Automake Conditionals

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 set up 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

8.1.4 Conditional compilation of programs

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.

Conditional Programs using configure Substitutions

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}'])’.

Conditional Programs using Automake Conditionals

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

8.2 Building a library

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). You should also call AM_PROG_AR to define AR, in order to support unusual archivers such as Microsoft lib. ARFLAGS will default to cru; you can override this variable by setting it in your Makefile.am or by AC_SUBSTing it from your configure.ac. You can override the AR variable 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

8.3 Building a Shared Library

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

8.3.1 The Libtool Concept

Libtool abstracts shared and static libraries into a unified concept henceforth called libtool libraries. Libtool libraries are files using the .la suffix, and can designate a static library, a shared library, or maybe both. 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 LT_INIT macro in The Libtool Manual.)

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 in The Libtool Manual). 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 detail, it should be noted that the libtool manual also has a section about how to use Automake with libtool (see Using Automake with Libtool in The Libtool Manual).

8.3.2 Building Libtool Libraries

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

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

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.

8.3.3 Building Libtool Libraries Conditionally

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

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

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 …

8.3.4 Libtool Libraries with Conditional Sources

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

8.3.5 Libtool Convenience Libraries

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 (this is in fact 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 a 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.

8.3.6 Libtool Modules

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).

8.3.7 _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS

As shown in previous sections, the ‘library_LIBADD’ variable should be used to list extra libtool objects (.lo files) or libtool libraries (.la) to add to library.

The ‘library_LDFLAGS’ variable is the place to list additional libtool linking flags, such as -version-info, -static, and a lot more. See Link mode in The Libtool Manual.

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 in The Libtool Manual for more options). They 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 by the Automake support for silent rules (see Automake Silent Rules).

8.3.8 LTLIBOBJS and LTALLOCA

Where 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 in The Autoconf Manual).

8.3.9 Common Issues Related to Libtool’s Use

8.3.9.1 Error: ‘required file `./ltmain.sh' not found’

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 in The Autoconf Manual). If you do not want to remember what to run and when, just learn the autoreconf command. Hopefully, replacing existing bootstrap or autogen.sh scripts by a call to autoreconf should also free you from any similar incompatible change in the future.

8.3.9.2 Objects ‘created with both libtool and without’

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 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-target 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.

8.4 Program and Library Variables

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

This variable, if it exists, lists all the source files that are compiled to build the program. These files are added to the distribution by default. When building the program, Automake will cause each source file to be compiled to a single .o file (or .lo when using libtool). Normally these object files are named after the source file, but other factors can change this. If a file in the _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 projects prefer or require this mode of operation. You can specify subdir-objects in AUTOMAKE_OPTIONS (see Options).

When subdir-objects is specified, and source files which lie outside the current directory tree are nevertheless specified, as in foo_SOURCES = ../lib/other.c, Automake will still remove ../lib/other.o, in fact, ../lib/*.o (e.g., at make clean, even though it is arguably wrong for one subdirectory to clean in a sibling. This may or may not be changed in the future.

EXTRA_maude_SOURCES

Automake needs to know the list of files you intend to compile statically. For one thing, this is the only way Automake has of knowing what sort of language support a given Makefile.in requires. (There are other, more obscure reasons for this limitation as well.) This means that, for example, you can’t put a configure substitution like ‘@my_sources@’ into a ‘_SOURCES’ variable. If you intend to conditionally compile source files and use configure to substitute the appropriate object names into, e.g., _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

A static library is created by default by invoking ‘$(AR) $(ARFLAGS)’ followed by the name of the library and then the objects being put into the library. You can override this by setting the _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

Extra objects can be added to a library using the _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

Extra objects (*.$(OBJEXT)) and libraries (*.a, *.la) can be added to a program by listing them in the _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_LDFLAGS

This variable is used to pass extra flags to the link step of a program or a shared library. It overrides the AM_LDFLAGS variable, even if it is defined only in a false branch of a conditional; in other words, if prog_LDFLAGS is defined at all, AM_LDFLAGS will not be used.

maude_LIBTOOLFLAGS

This variable is used to pass extra options to libtool. It overrides the AM_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

EXTRA_maude_DEPENDENCIES

It is also occasionally useful to have a target (program or library) depend on some other file that is not in fact part of that target. This can be done using the _DEPENDENCIES variable. Each target depends on the contents of such a variable, but no further interpretation is done.

Since these dependencies are associated with 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.

The EXTRA_*_DEPENDENCIES variable may be useful for cases where you merely want to augment the automake-generated _DEPENDENCIES variable rather than replacing it.

maude_LINK

You can override the linker on a per-program basis. By default the linker is chosen according to the languages used by the program. For instance, a program that includes C++ source code would use the C++ compiler to link. The _LINK variable must hold the name of a command that can be passed all the .o file names and libraries to link against as arguments. Note that the name of the underlying program is not passed to _LINK; typically one uses ‘$@’:

maude_LINK = $(CCLD) -magic -o $@

If a _LINK variable is not supplied, it may still be generated and used by Automake due to the use of per-target link flags such as _CFLAGS, _LDFLAGS or _LIBTOOLFLAGS, in cases where they apply.

If the variable AM_V_*_LINK exists, it is used to output a status line in silent mode; otherwise, AM_V_GEN is used.

maude_CCASFLAGS

maude_CFLAGS

maude_CPPFLAGS

maude_CXXFLAGS

maude_FFLAGS

maude_GCJFLAGS

maude_LFLAGS

maude_OBJCFLAGS

maude_OBJCXXFLAGS

maude_RFLAGS

maude_UPCFLAGS

maude_YFLAGS

Automake allows you to set compilation flags on a per-program (or per-library) basis. A single source file can be included in several programs, and it will potentially be compiled with different flags for each program. This works for any language directly supported by Automake. These per-target compilation flags are ‘_CCASFLAGS’, ‘_CFLAGS’, ‘_CPPFLAGS’, ‘_CXXFLAGS’, ‘_FFLAGS’, ‘_GCJFLAGS’, ‘_LFLAGS’, ‘_OBJCFLAGS’, ‘_OBJCXXFLAGS’, ‘_RFLAGS’, ‘_UPCFLAGS’, and ‘_YFLAGS’.

When 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.)

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

On some platforms the allowable file names are very short. In order to support these systems and per-target compilation flags at the same time, Automake allows you to set a “short name” that will influence how intermediate object files are named. For instance, in the following example,

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.

8.5 Default _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 canonicalized 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

8.6 Special handling for LIBOBJS and ALLOCA

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

These variables are defined by Autoconf macros such as AC_LIBOBJ, AC_REPLACE_FUNCS (see Generic Function Checks in The Autoconf Manual), or AC_FUNC_ALLOCA (see Particular Function Checks in The Autoconf Manual). 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). If you have already defined ‘*_DEPENDENCIES’ explicitly for an unrelated reason, then you either need to add these variables manually, or use ‘EXTRA_*_DEPENDENCIES’ instead of ‘*_DEPENDENCIES’.

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 in The Autoconf Manual.

8.7 Variables used when building a program

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_CPPFLAGS

The contents of this variable are passed to every compilation that invokes the C preprocessor; it is a list of arguments to the preprocessor. For instance, -I and -D options should be listed here.

Automake 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). You can disable the default -I options using the nostdinc option.

When a file to be included is generated during the build and not part of a distribution tarball, its location is under $(builddir), not under $(srcdir). This matters especially for packages that use header files placed in sub-directories and want to allow builds outside the source tree (see VPATH Builds). In that case we recommend using a pair of -I options, such as, e.g., ‘-Isome/subdir -I$(srcdir)/some/subdir’ or ‘-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir’. Note that the reference to the build tree should come before the reference to the source tree, so that accidentally leftover generated files in the source directory are ignored.

AM_CPPFLAGS is ignored in preference to a per-executable (or per-library) _CPPFLAGS variable if it is defined.

INCLUDES

This does the same job as AM_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

This is the variable the Makefile.am author can use to pass in additional C compiler flags. In some situations, this is not used, in preference to the per-executable (or per-library) _CFLAGS.

COMPILE

This is the command used to compile a C source file. The file name is appended to form the complete command line.

AM_LDFLAGS

This is the variable the Makefile.am author can use to pass in additional linker flags. In some situations, this is not used, in preference to the per-executable (or per-library) _LDFLAGS.

LINK

This is the command used to link a C program. It already includes ‘-o $@’ and the usual variable references (for instance, CFLAGS); it takes as “arguments” the names of the object files and libraries to link in. This variable is not used when the linker is overridden with a per-target _LINK variable or per-target flags cause Automake to define such a _LINK variable.

8.8 Yacc and Lex support

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++ source and header files. Be aware that header files are generated only when the option -d is given to Yacc; see below for more information about this flag, and how to specify it. Files with the extension .y will thus be turned into .c sources and .h headers; likewise, .yy will become .cc and .hh, .y++ will become c++ and h++, .yxx will become .cxx and .hxx, and .ypp will become .cpp and .hpp.

Similarly, 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 in The Autoconf Manual).

When yacc is invoked, it is passed AM_YFLAGS and YFLAGS. The latter is a user variable and the former 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’. Caveat: automake recognizes -d in AM_YFLAGS only if it is not clustered with other options; for example, it won’t be recognized if AM_YFLAGS is -dt, but it will be if AM_YFLAGS is -d -t or -t -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 in The Autoconf Manual), but using the AM_PROG_LEX macro (see Macros) is recommended.

When lex is invoked, it is passed AM_LFLAGS and LFLAGS. The latter is a user variable and the former is intended for the Makefile.am author.

When AM_MAINTAINER_MODE (see maintainer-mode) is in effect, the rebuild rules for distributed Yacc and Lex sources are only used when maintainer-mode is enabled, or when the files have been erased.

When Yacc or Lex sources are used, automake -a 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 invoke more than one instance of yacc simultaneously.

8.8.1 Linking Multiple Yacc Parsers

Linking Multiple Yacc Parsers

For yacc, simply managing locking as with ylwrap 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.

8.9 C++ Support

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 in The Autoconf Manual).

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

CXX

The name of the C++ compiler.

CXXFLAGS

Any flags to pass to the C++ compiler.

AM_CXXFLAGS

The maintainer’s variant of CXXFLAGS.

CXXCOMPILE

The command used to compile a C++ source file. The file name is appended to form the complete command line.

CXXLINK

The command used to link a C++ program.

8.10 Objective C Support

Automake 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 in The Autoconf Manual).

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

OBJC

The name of the Objective C compiler.

OBJCFLAGS

Any flags to pass to the Objective C compiler.

AM_OBJCFLAGS

The maintainer’s variant of OBJCFLAGS.

OBJCCOMPILE

The command used to compile an Objective C source file. The file name is appended to form the complete command line.

OBJCLINK

The command used to link an Objective C program.

8.11 Objective C++ Support

Automake includes some support for Objective C++.

Any package including Objective C++ code must define the output variable OBJCXX in configure.ac; the simplest way to do this is to use the AC_PROG_OBJCXX macro (see Particular Program Checks in The Autoconf Manual).

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

OBJCXX

The name of the Objective C++ compiler.

OBJCXXFLAGS

Any flags to pass to the Objective C++ compiler.

AM_OBJCXXFLAGS

The maintainer’s variant of OBJCXXFLAGS.

OBJCXXCOMPILE

The command used to compile an Objective C++ source file. The file name is appended to form the complete command line.

OBJCXXLINK

The command used to link an Objective C++ program.

8.12 Unified Parallel C Support

Automake 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:

UPC

The name of the Unified Parallel C compiler.

UPCFLAGS

Any flags to pass to the Unified Parallel C compiler.

AM_UPCFLAGS

The maintainer’s variant of UPCFLAGS.

UPCCOMPILE

The command used to compile a Unified Parallel C source file. The file name is appended to form the complete command line.

UPCLINK

The command used to link a Unified Parallel C program.

8.13 Assembly Support

Automake 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.

8.14 Fortran 77 Support

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 in The Autoconf Manual).

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

F77

The name of the Fortran 77 compiler.

FFLAGS

Any flags to pass to the Fortran 77 compiler.

AM_FFLAGS

The maintainer’s variant of FFLAGS.

RFLAGS

Any flags to pass to the Ratfor compiler.

AM_RFLAGS

The maintainer’s variant of RFLAGS.

F77COMPILE

The command used to compile a Fortran 77 source file. The file name is appended to form the complete command line.

FLINK

The command used to link a pure Fortran 77 program or shared library.

Automake can handle preprocessing Fortran 77 and Ratfor source files in addition to compiling them². 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.

8.14.1 Preprocessing Fortran 77

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: