GNU Automake ************ This manual is for GNU Automake (version 1.10.1, 21 January 2008), a program that creates GNU standards-compliant Makefiles from template files. Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 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." 1 Introduction ************** Automake is a tool for automatically generating `Makefile.in's from files called `Makefile.am'. Each `Makefile.am' is basically a series of `make' variable definitions(1), with rules being thrown in occasionally. The generated `Makefile.in's are compliant with the GNU Makefile standards. The GNU Makefile Standards Document (*note Makefile Conventions: (standards)Makefile Conventions.) is long, complicated, and subject to change. The goal of Automake is to remove the burden of Makefile maintenance from the back of the individual GNU maintainer (and put it on the back of the Automake maintainers). The typical Automake input file is simply a series of variable definitions. Each such file is processed to create a `Makefile.in'. There should generally be one `Makefile.am' per directory of a project. Automake does constrain a project in certain ways; for instance, it assumes that the project uses Autoconf (*note Introduction: (autoconf)Top.), and enforces certain restrictions on the `configure.ac' contents(2). Automake requires `perl' in order to generate the `Makefile.in's. However, the distributions created by Automake are fully GNU standards-compliant, and do not require `perl' in order to be built. Mail suggestions and bug reports for Automake to . ---------- Footnotes ---------- (1) These variables are also called "make macros" in Make terminology, however in this manual we reserve the term "macro" for Autoconf's macros. (2) Older Autoconf versions used `configure.in'. Autoconf 2.50 and greater promotes `configure.ac' over `configure.in'. The rest of this documentation will refer to `configure.ac', but Automake also supports `configure.in' for backward compatibility. 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 (http://www-src.lip6.fr/~Alexandre.Duret-Lutz/autotools.html). 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 a developer in possession of a new package, must be in want of a build system. In the Unix world, such a build system is traditionally achieved using the command `make' (*note Overview: (make)Top.). The developer expresses the recipe to build his package in a `Makefile'. This file is a set of rules to build the files in the package. For instance the program `prog' may be built by running the linker on the files `main.o', `foo.o', and `bar.o'; the file `main.o' may be built by running the compiler on `main.c'; etc. Each time `make' is run, it reads `Makefile', checks the existence and modification time of the files mentioned, decides what files need to be built (or rebuilt), and runs the associated commands. When a package needs to be built on a different platform than the one it was developed on, its `Makefile' usually needs to be adjusted. For instance the compiler may have another name or require more options. In 1991, David J. MacKenzie got tired of customizing `Makefile' for the 20 platforms he had to deal with. Instead, he handcrafted a little shell script called `configure' to automatically adjust the `Makefile' (*note Genesis: (autoconf)Genesis.). Compiling his package was now as simple as running `./configure && make'. Today this process has been standardized in the GNU project. The GNU Coding Standards (*note The Release Process: (standards)Managing Releases.) 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 `Makefile's. 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 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 `Makefile's. In this toy example there are only two `Makefile's, 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: Directory variable Default value ------------------------------------------------------- `prefix' `/usr/local' `exec_prefix' `${prefix}' `bindir' `${exec_prefix}/bin' `libdir' `${exec_prefix}/lib' ... `includedir' `${prefix}/include' `datarootdir' `${prefix}/share' `datadir' `${datarootdir}' `mandir' `${datarootdir}/man' `infodir' `${datarootdir}/info' `docdir' `${datarootdir}/doc/${PACKAGE}' ... Each of these directories has a role which is often obvious from its name. In a package, any installable file will be installed in one of these directories. For instance in `amhello-1.0', the program `hello' is to be installed in BINDIR, the directory for binaries. The default value for this directory is `/usr/local/bin', but the user can supply a different value when calling `configure'. Also the file `README' will be installed into DOCDIR, which defaults to `/usr/local/share/doc/amhello'. A user who wishes to install a package on his own account could proceed as follows: ~/amhello-1.0 % ./configure --prefix ~/usr ... ~/amhello-1.0 % make ... ~/amhello-1.0 % make install ... This would install `~/usr/bin/hello' and `~/usr/share/doc/amhello/README'. The list of all such directory options is shown by `./configure --help'. 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 ... *Note Setting Site Defaults: (autoconf)Site Defaults, 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. The source tree is rooted in the directory containing `configure'. It contains all the sources files (those that are distributed), and may be arranged using several subdirectories. The build tree is rooted in the directory in which `configure' was run, and is populated with all object files, programs, libraries, and other derived files built from the sources (and hence not distributed). The build tree usually has the same subdirectory layout as the source tree; its subdirectories are created automatically by the build system. If `configure' is executed in its own directory, the source and build trees are combined: derived files are constructed in the same directories as their sources. This was the case in our first installation example (*note Basic Installation::). A common request from users is that they want to confine all derived files to a single directory, to keep their source directories uncluttered. Here is how we could run `configure' to build everything in a subdirectory called `build/'. ~ % tar zxf ~/amhello-1.0.tar.gz ~ % cd amhello-1.0 ~/amhello-1.0 % mkdir build && cd build ~/amhello-1.0/build % ../configure ... ~/amhello-1.0/build % make ... These setups, where source and build trees are different, are often called "parallel builds" or "VPATH builds". The expression _parallel build_ is misleading: the word _parallel_ is a reference to the way the build tree shadows the source tree, it is not about some concurrency in the way build commands are run. For this reason we refer to such setups using the name _VPATH builds_ in the following. _VPATH_ is the name of the `make' feature used by the `Makefile's to allow these builds (*note `VPATH': Search Path for All Prerequisites: (make)General Search.). 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 the that installer has configured `sudo' so it can execute `make install' with root privileges; it is more convenient than using `su' like in *note Basic Installation::). On the second host, you would do exactly the same, possibly at the same time: [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure ... [HOST2] /tmp/amh % make && sudo make install ... In this scenario, nothing forbids the `/nfs/src/amhello-1.0' directory from being read-only. In fact VPATH builds are also a means of building packages from a read-only medium such as a CD-ROM. (The FSF used to sell CD-ROM with unpacked source code, before the GNU project grew so big.) 2.2.7 Two-Part Installation --------------------------- In our last example (*note 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 (*note 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'. *Note 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' (*note 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 actually cross-compile a cross-compiler; such a three-way cross-compilation is known as a "Canadian cross". *Note Specifying the System Type: (autoconf)Specifying Names, 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 before they are installed. 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 ../file.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 ../file.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' (*note Two-Part Install::) to gather architecture-independent files in a single package. *Note 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 (*note Basic Installation::), unpacking the newly constructed tarball, running `make', `make check', `make install', as well as `make installcheck', and even `make dist', * it tests VPATH builds with read-only source tree (*note VPATH Builds::), * it makes sure `make clean', `make distclean', and `make uninstall' do not omit any file (*note Standard Targets::), * and it checks that `DESTDIR' installations work (*note DESTDIR::). All of these actions are performed in a temporary subdirectory, so that no root privileges are required. Releasing a package that fails `make distcheck' means that one of the scenarios we presented will not work and some users will be disappointed. Therefore it is a good practice to release a package only after a successful `make distcheck'. This of course does not imply that the package will be flawless, but at least it will prevent some of the embarrassing errors you may find in packages released by people who have never heard about `distcheck' (like `DESTDIR' not working because of a typo, or a distributed file being erased by `make clean', or even `VPATH' builds not working). *Note Creating amhello::, to recreate `amhello-1.0.tar.gz' using `make distcheck'. *Note Dist::, 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. 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. *Note Dependency Tracking Evolution::, 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 a package A will distribute one of the libraries it needs in a subdirectory. This library B is a complete package with its own GNU Build System. The `configure' script of A will run the `configure' script of B as part of its execution, building and installing A will also build and install B. Generating a distribution for A will also include B. It is possible to gather several package like this. GCC is a heavy user of this feature. This gives installers a single package to configure, build and install, while it allows developers to work on subpackages independently. When configuring nested packages, the `configure' options given to the top-level `configure' are passed recursively to nested `configure's. 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. *Note 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 `Makefile's yourself). * As we have seen, the GNU Build System has a lot of features (*note 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 `Makefile's, for systems you may not have handy. *Note Portable Shell Programming: (autoconf)Portable Shell, 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 #include 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' 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 (*note Standard Targets::). For instance: ~/amhello % make ... ~/amhello % src/hello Hello World! This is amhello 1.0. ~/amhello % make distcheck ... ============================================= amhello-1.0 archives ready for distribution: amhello-1.0.tar.gz ============================================= Note that running `autoreconf' is only needed initially when the GNU Build System does not exist. When you later change some instructions in a `Makefile.am' or `configure.ac', the relevant part of the build system will be regenerated automatically when you execute `make'. `autoreconf' is a script that calls `autoconf', `automake', and a bunch of other commands in the right order. If you are beginning with these tools, it is not important to figure out in which order all these tools should be invoked and why. However, because Autoconf and Automake have separate manuals, the important point to understand is that `autoconf' is in charge of creating `configure' from `configure.ac', while `automake' is in charge of creating `Makefile.in's from `Makefile.am's and `configure.ac'. This should at least direct you to the right manual when seeking answers. 2.4.2 `amhello-1.0' Explained ----------------------------- Let us begin with the contents of `configure.ac'. AC_INIT([amhello], [1.0], [bug-automake@gnu.org]) AM_INIT_AUTOMAKE([-Wall -Werror foreign]) AC_PROG_CC AC_CONFIG_HEADERS([config.h]) AC_CONFIG_FILES([ Makefile src/Makefile ]) AC_OUTPUT This file is read by both `autoconf' (to create `configure.ac') and `automake' (to create the various `Makefile.in's). 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 (*note Writing `configure.ac': (autoconf)Writing configure.ac.). The macros prefixed with `AC_' are Autoconf macros, documented in the Autoconf manual (*note Autoconf Macro Index: (autoconf)Autoconf Macro Index.). The macros that start with `AM_' are Automake macros, documented later in this manual (*note 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' (*note Options::). `-Wall' and `-Werror' ask `automake' to turn on all warnings and report them as errors. We are speaking of *Automake* warnings here, such as dubious instructions in `Makefile.am'. This has absolutely nothing to do with how the compiler will be called, even though it may support options with similar names. Using `-Wall -Werror' is a safe setting when starting to work on a package: you do not want to miss any issues. Later you may decide to relax things a bit. The `foreign' option tells Automake that this package will not follow the GNU Standards. GNU packages should always distribute additional files such as `ChangeLog', `AUTHORS', etc. We do not want `automake' to complain about these missing files in our small example. The `AC_PROG_CC' line causes the `configure' script to search for a C compiler and define the variable `CC' with its name. The `src/Makefile.in' file generated by Automake uses the variable `CC' to build `hello', so when `configure' creates `src/Makefile' from `src/Makefile.in', it will define `CC' with the value it has found. If Automake is asked to create a `Makefile.in' that uses `CC' but `configure.ac' does not define it, it will suggest you add a call to `AC_PROG_CC'. The `AC_CONFIG_HEADERS([config.h])' invocation causes the `configure' script to create a `config.h' file gathering `#define's defined by other macros in `configure.ac'. In our case, the `AC_INIT' macro already defined a few of them. Here is an excerpt of `config.h' after `configure' has run: ... /* Define to the address where bug reports for this package should be sent. */ #define PACKAGE_BUGREPORT "bug-automake@gnu.org" /* Define to the full name and version of this package. */ #define PACKAGE_STRING "amhello 1.0" ... As you probably noticed, `src/main.c' includes `config.h' so it can use `PACKAGE_STRING'. In a real-world project, `config.h' can grow really big, with one `#define' per feature probed on the system. The `AC_CONFIG_FILES' macro declares the list of files that `configure' should create from their `*.in' templates. Automake also scans this list to find the `Makefile.am' files it must process. (This is important to remember: when adding a new directory to your project, you should add its `Makefile' to this list, otherwise Automake will never process the new `Makefile.am' you wrote in that directory.) Finally, the `AC_OUTPUT' line is a closing command that actually produces the part of the script in charge of creating the files registered with `AC_CONFIG_HEADERS' and `AC_CONFIG_FILES'. When starting a new project, we suggest you start with such a simple `configure.ac', and gradually add the other tests it requires. The command `autoscan' can also suggest a few of the tests your package may need (*note Using `autoscan' to Create `configure.ac': (autoconf)autoscan Invocation.). 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.am's 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 (*note 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'. 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 verbatim into the generated file. This allows you to add arbitrary code into the generated `Makefile.in'. For instance, the Automake distribution includes a non-standard rule for the `git-dist' target, which the Automake maintainer uses to make distributions from his source control system. Note that most GNU make extensions are not recognized by Automake. Using such extensions in a `Makefile.am' will lead to errors or confusing behavior. A special exception is that the GNU make append operator, `+=', is supported. This operator appends its right hand argument to the variable specified on the left. Automake will translate the operator into an ordinary `=' operator; `+=' will thus work with any make program. Automake tries to keep comments grouped with any adjoining rules or variable definitions. A rule defined in `Makefile.am' generally overrides any such rule of a similar name that would be automatically generated by `automake'. Although this is a supported feature, it is generally best to avoid making use of it, as sometimes the generated rules are very particular. Similarly, a variable defined in `Makefile.am' or `AC_SUBST'ed from `configure.ac' will override any definition of the variable that `automake' would ordinarily create. This feature is more often useful than the ability to override a rule. Be warned that many of the variables generated by `automake' are considered to be for internal use only, and their names might change in future releases. When examining a variable definition, Automake will recursively examine variables referenced in the definition. For example, if Automake is looking at the content of `foo_SOURCES' in this snippet xs = a.c b.c foo_SOURCES = c.c $(xs) it would use the files `a.c', `b.c', and `c.c' as the contents of `foo_SOURCES'. Automake also allows a form of comment that is _not_ copied into the output; all lines beginning with `##' (leading spaces allowed) are completely ignored by Automake. It is customary to make the first line of `Makefile.am' read: ## Process this file with automake to produce Makefile.in 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"--the strictness indicating how stringently Automake should check standards conformance. The valid strictness levels are: `foreign' Automake will check for only those things that are absolutely required for proper operations. For instance, whereas GNU standards dictate the existence of a `NEWS' file, it will not be required in this mode. The name comes from the fact that Automake is intended to be used for GNU programs; these relaxed rules are not the standard mode of operation. `gnu' Automake will check--as much as possible--for compliance to the GNU standards for packages. This is the default. `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 actually published (which may never happen). *Note Gnits::, for more information on the precise implications of the strictness level. Automake also has a special "cygnus" mode that is similar to strictness but handled differently. This mode is useful for packages that are put into a "Cygnus" style tree (e.g., the GCC tree). *Note Cygnus::, for more information on this mode. 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 (*note Directory Variables: (standards)Directory Variables.). Automake extends this list with `pkglibdir', `pkgincludedir', and `pkgdatadir'; these are the same as the non-`pkg' versions, but with `$(PACKAGE)' appended. For instance, `pkglibdir' is defined as `$(libdir)/$(PACKAGE)'. For each primary, there is one additional variable named by prepending `EXTRA_' to the primary name. This variable is used to list objects that may or may not be built, depending on what `configure' decides. This variable is required because Automake must statically know the entire list of objects that may be built in order to generate a `Makefile.in' that will work in all cases. For instance, `cpio' decides at configure time which programs should be built. Some of the programs are installed in `bindir', and some are installed in `sbindir': EXTRA_PROGRAMS = mt rmt bin_PROGRAMS = cpio pax sbin_PROGRAMS = $(MORE_PROGRAMS) Defining a primary without a prefix as a variable, e.g., `PROGRAMS', is an error. Note that the common `dir' suffix is left off when constructing the variable names; thus one writes `bin_PROGRAMS' and not `bindir_PROGRAMS'. Not every sort of object can be installed in every directory. Automake will flag those attempts it finds in error. Automake will also diagnose obvious misspellings in directory names. Sometimes the standard directories--even as augmented by Automake--are not enough. In particular it is sometimes useful, for clarity, to install objects in a subdirectory of some predefined directory. To this end, Automake allows you to extend the list of possible installation directories. A given prefix (e.g., `zar') is valid if a variable of the same name with `dir' appended is defined (e.g., `zardir'). For instance, the following snippet will install `file.xml' into `$(datadir)/xml'. xmldir = $(datadir)/xml xml_DATA = file.xml The special prefix `noinst_' indicates that the objects in question should be built but not installed at all. This is usually used for objects required to build the rest of your package, for instance static libraries (*note A Library::), or helper scripts. The special prefix `check_' indicates that the objects in question should not be built until the `make check' command is run. Those objects are not installed either. The current primary names are `PROGRAMS', `LIBRARIES', `LISP', `PYTHON', `JAVA', `SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'. Some primaries also allow additional prefixes that control other aspects of `automake''s behavior. The currently defined prefixes are `dist_', `nodist_', and `nobase_'. These prefixes are explained later (*note Program and Library Variables::). 3.4 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.5 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. *Note Flag Variables Ordering::, for more discussion about these variables and how they interact with per-target variables. 3.6 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. `ansi2knr.c' `ansi2knr.1' These two files are used by the obsolete de-ANSI-fication support (*note ANSI::). `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. `config.guess' `config.sub' These two programs compute the canonical triplets for the given build, host, or target architecture. These programs are updated regularly to support new architectures and fix probes broken by changes in new kernel versions. Each new release of Automake comes with up-to-date copies of these programs. If your copy of Automake is getting old, you are encouraged to fetch the latest versions of these files from `http://savannah.gnu.org/cvs/?group=config' before making a release. `config-ml.in' This file is not a program, it is a `configure' fragment used for multilib support (*note Multilibs::). This file is maintained in the GCC tree at `http://gcc.gnu.org/svn.html'. `depcomp' This program understands how to run a compiler so that it will generate not only the desired output but also dependency information that is then used by the automatic dependency tracking feature (*note Dependencies::). `elisp-comp' This program is used to byte-compile Emacs Lisp code. `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, `missing' prints an informative warning and attempts to fix things so that the build can continue. `mkinstalldirs' This script used to be a wrapper around `mkdir -p', which is not portable. Now we prefer to use `install-sh -d' 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. `symlink-tree' This program duplicates a tree of directories, using symbolic links instead of copying files. Such operation is performed when building multilibs (*note Multilibs::). This file is maintained in the GCC tree at `http://gcc.gnu.org/svn.html'. `texinfo.tex' Not a program, this file is required for `make dvi', `make ps' and `make pdf' to work when Texinfo sources are in the package. The latest version can be downloaded from `http://www.gnu.org/software/texinfo/'. `ylwrap' This program 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 (*note Complete::) assumes you have an existing project already using Autoconf, with handcrafted `Makefile's, 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 (*note Hello World::). The second example (*note 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.in's 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', and define rules to compile `true.o' and link `true'. The `true.o: true.c' rule supplied by the above `Makefile.am', will override the Automake generated rule to build `true.o'. `false_SOURCES' is defined to be empty--that way no implicit value is substituted. Because we have not listed the source of `false', we have to tell Automake how to link the program. This is the purpose of the `false_LDADD' line. A `false_DEPENDENCIES' variable, holding the dependencies of the `false' target will be automatically generated by Automake from the content of `false_LDADD'. The above rules won't work if your compiler doesn't accept both `-c' and `-o'. The simplest fix for this is to introduce a bogus dependency (to avoid problems with a parallel `make'): true.o: true.c false.o $(COMPILE) -DEXIT_CODE=0 -c true.c false.o: true.c $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o Also, these explicit rules do not work if the obsolete de-ANSI-fication feature is used (*note ANSI::). Supporting de-ANSI-fication requires a little more work: true_.o: true_.c false_.o $(COMPILE) -DEXIT_CODE=0 -c true_.c false_.o: true_.c $(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o As it turns out, there is also a much easier way to do this same task. Some of the above techniques are useful enough that we've kept the example in the manual. However if you were to build `true' and `false' in real life, you would probably use per-program compilation flags, like so: bin_PROGRAMS = false true false_SOURCES = true.c false_CPPFLAGS = -DEXIT_CODE=1 true_SOURCES = true.c true_CPPFLAGS = -DEXIT_CODE=0 In this case Automake will cause `true.c' to be compiled twice, with different flags. De-ANSI-fication will work automatically. In this instance, the names of the object files would be chosen by automake; they would be `false-true.o' and `true-true.o'. (The name of the object files rarely matters.) 5 Creating a `Makefile.in' ************************** To create all the `Makefile.in's 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'; *note 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.ac's, 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' runs `AC_CANONICAL_HOST'. Automake is distributed with several of these files (*note 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 (*note Optional::). `--libdir=DIR' Look for Automake data files in directory DIR instead of in the installation directory. This is typically used for debugging. `-c' `--copy' When used with `--add-missing', causes installed files to be copied. The default is to make a symbolic link. `--cygnus' Causes the generated `Makefile.in's to follow Cygnus rules, instead of GNU or Gnits rules. For more information, see *note Cygnus::. `-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 *note Strictness::. `--gnits' Set the global strictness to `gnits'. For more information, see *note Gnits::. `--gnu' Set the global strictness to `gnu'. For more information, see *note Gnits::. 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 `Makefile's; see *note 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.in's mentioned in `configure.ac'. This option causes it to only update those `Makefile.in's 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' `--warnings=CATEGORY' Output warnings falling in CATEGORY. CATEGORY can be one of: `gnu' warnings related to the GNU Coding Standards (*note Top: (standards)Top.). `obsolete' obsolete features or constructions `override' user redefinitions of Automake rules or variables `portability' portability issues (e.g., use of `make' features that are known to be not portable) `syntax' weird syntax, unused variables, typos `unsupported' unsupported or incomplete features `all' all the warnings `none' turn off all the warnings `error' treat warnings as errors A category can be turned off by prefixing its name with `no-'. For instance, `-Wno-syntax' will hide the warnings about unused variables. The categories output by default are `syntax' and `unsupported'. Additionally, `gnu' and `portability' are enabled in `--gnu' and `--gnits' strictness. The environment variable `WARNINGS' can contain a comma separated list of categories to enable. It will be taken into account before the command-line switches, this way `-Wnone' will also ignore any warning category enabled by `WARNINGS'. This variable is also used by other tools like `autoconf'; unknown categories are ignored for this reason. 6 Scanning `configure.ac' ************************* 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 (*note 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 (*note Creating Output Files: (autoconf)Output.). 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 Automake generated. Files created by `AC_CONFIG_FILES', be they Automake `Makefile's or not, are all removed by `make distclean'. Their inputs are automatically distributed, except for inputs that turn out the be outputs 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' if `input' is a source file.) Similarly file=output file2=out:in ... AC_CONFIG_FILES([$file:input],, [file=$file]) AC_CONFIG_FILES([$file2],, [file2=$file2]) will only cause `input' to be distributed. No file will be cleaned automatically (add `DISTCLEANFILES = output out' yourself), and no rebuild rule will be output. Obviously `automake' cannot guess what value `$file' is going to hold later when `configure' is run, and it cannot use the shell variable `$file' in a `Makefile'. However, if you make reference to `$file' as `${file}' (i.e., in a way that is compatible with `make''s syntax) and furthermore use `AC_SUBST' to ensure that `${file}' is meaningful in a `Makefile', then `automake' will be able to use `${file}' to generate all these rules. For instance, here is how the Automake package itself generates versioned scripts for its test suite: AC_SUBST([APIVERSION], ...) ... AC_CONFIG_FILES( [tests/aclocal-${APIVERSION}:tests/aclocal.in], [chmod +x tests/aclocal-${APIVERSION}], [APIVERSION=$APIVERSION]) AC_CONFIG_FILES( [tests/automake-${APIVERSION}:tests/automake.in], [chmod +x tests/automake-${APIVERSION}]) Here cleaning, distributing, and rebuilding are done automatically, because `${APIVERSION}' is known at `make'-time. Note that you should not use shell variables to declare `Makefile' files for which `automake' must create `Makefile.in'. Even `AC_SUBST' does not help here, because `automake' needs to know the file name when it runs in order to check whether `Makefile.am' exists. (In the very hairy case that your setup requires such use of variables, you will have to tell Automake which `Makefile.in's to generate on the command-line.) To summarize: * Use literals for `Makefile's, 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 *note Getting the Canonical System Type: (autoconf)Canonicalizing. `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: `config.guess', `config.sub', `depcomp', `elisp-comp', `compile', `install-sh', `ltmain.sh', `mdate-sh', `missing', `mkinstalldirs', `py-compile', `texinfo.tex', and `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 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. *Note Finding `configure' Input: (autoconf)Input. 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. Older versions of Automake required the use of `AM_CONFIG_HEADER' (*note Macros::); this is no longer the case today. As for `AC_CONFIG_FILES' (*note Requirements::), parts of the specification using shell variables will be ignored as far as cleaning, distributing, and rebuilding is concerned. `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 for `AC_CONFIG_FILES' (*note Requirements::), parts of the specification using shell variables will be ignored as far as cleaning and distributing is concerned. (There is 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. *Note `AC_LIBOBJ' vs. `LIBOBJS': (autoconf)AC_LIBOBJ vs LIBOBJS. `AC_PROG_RANLIB' This is required if any libraries are built in the package. *Note Particular Program Checks: (autoconf)Particular Programs. `AC_PROG_CXX' This is required if any C++ source is included. *Note Particular Program Checks: (autoconf)Particular Programs. `AC_PROG_OBJC' This is required if any Objective C source is included. *Note Particular Program Checks: (autoconf)Particular Programs. `AC_PROG_F77' This is required if any Fortran 77 source is included. This macro is distributed with Autoconf version 2.13 and later. *Note Particular Program Checks: (autoconf)Particular Programs. `AC_F77_LIBRARY_LDFLAGS' This is required for programs and shared libraries that are a mixture of languages that include Fortran 77 (*note Mixing Fortran 77 With C and C++::). *Note Autoconf macros supplied with Automake: Macros. `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. *Note Particular Program Checks: (autoconf)Particular Programs. `AC_PROG_LIBTOOL' Automake will turn on processing for `libtool' (*note Introduction: (libtool)Top.). `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 (*note Particular Program Checks: (autoconf)Particular Programs.). `AC_PROG_LEX' If a Lex source file is seen, then this macro must be used. *Note Particular Program Checks: (autoconf)Particular Programs. `AC_REQUIRE_AUX_FILE' `automake' will ensure each file for which this macro is called 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 requires some supporting files in the aux directory specified with `AC_CONFIG_AUX_DIR' above. *Note Finding `configure' Input: (autoconf)Input. `AC_SUBST' The first argument is automatically defined as a variable in each generated `Makefile.in'. *Note Setting Output Variables: (autoconf)Setting Output Variables. If the Autoconf manual says that a macro calls `AC_SUBST' for VAR, or defines the output variable VAR then VAR will be defined in each `Makefile.in' generated by Automake. E.g. `AC_PATH_XTRA' defines `X_CFLAGS' and `X_LIBS', so you can use these variables in any `Makefile.am' if `AC_PATH_XTRA' is called. `AM_C_PROTOTYPES' This is required when using the obsolete de-ANSI-fication feature; see *note ANSI::. `AM_GNU_GETTEXT' This macro is required for packages that use GNU gettext (*note 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' This macro adds a `--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.in's. This macro defines the `MAINTAINER_MODE' conditional, which you can use in your own `Makefile.am'. *Note maintainer-mode::. `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, *note Invoking aclocal::). 6.3 Auto-generating aclocal.m4 ============================== Automake includes a number of Autoconf macros that can be used in your package (*note Macros::); some of them are actually required by Automake in certain situations. These macros must be defined in your `aclocal.m4'; otherwise they will not be seen by `autoconf'. The `aclocal' program will automatically generate `aclocal.m4' files based on the contents of `configure.ac'. This provides a convenient way to get Automake-provided macros, without having to search around. The `aclocal' mechanism allows other packages to supply their own macros (*note Extending aclocal::). You can also use it to maintain your own set of custom macros (*note Local Macros::). At startup, `aclocal' scans all the `.m4' files it can find, looking for macro definitions (*note 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. (*Note Local Macros::, for an example.) Any macro that is found in a system-wide directory, or via an absolute search path will be copied. So use `-I `pwd`/reldir' instead of `-I reldir' whenever some relative directory need to be considered outside the package. The contents of `acinclude.m4', if this file exists, are also automatically included in `aclocal.m4'. We recommend against using `acinclude.m4' in new packages (*note Local Macros::). While computing `aclocal.m4', `aclocal' runs `autom4te' (*note Using `Autom4te': (autoconf)Using autom4te.) in order to trace the macros that are really used, and omit from `aclocal.m4' all macros that are mentioned but otherwise unexpanded (this can happen when a macro is called conditionally). `autom4te' is expected to be in the `PATH', just as `autoconf'. Its location can be overridden using the `AUTOM4TE' environment variable. 6.3.1 aclocal options --------------------- `aclocal' accepts the following options: `--acdir=DIR' Look for the macro files in DIR instead of the installation directory. This is typically used for debugging. `--diff[=COMMAND]' Run COMMAND on 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 actually 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. 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 (*note Serials::). `--force' Always overwrite the output file. The default is to overwrite the output file only when really needed, i.e., when its contents changes or if one of its dependencies is younger. This option forces the update 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 can be used by a package to determine where to install a macro file. `--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' (*note Invoking Automake::). 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 automake 1.6.x, APIVERSION = `1.6'. `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 (*note aclocal options::). As an example, suppose that `automake-1.6.2' was configured with `--prefix=/usr/local'. Then, the search path would be: 1. `/usr/local/share/aclocal-1.6/' 2. `/usr/local/share/aclocal/' As explained in (*note aclocal options::), there are several options that can be used to change or extend this search path. 6.3.2.1 Modifying the macro search path: `--acdir' .................................................. The most erroneous option to modify the search path is `--acdir=DIR', which changes default directory and drops the APIVERSION directory. For example, if one specifies `--acdir=/opt/private/', then the search path becomes: 1. `/opt/private/' This option, `--acdir', is intended for use by the internal automake test suite only; it is not ordinarily needed by end-users. 6.3.2.2 Modifying the macro search path: `-I DIR' ................................................. Any extra directories specified using `-I' options (*note 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 6.3.2.3 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 `--acdir=DIR' option is used, then `aclocal' will search for the `dirlist' file in DIR. In the `--acdir=/opt/private/' example above, `aclocal' would look for `/opt/private/dirlist'. Again, however, the `--acdir' option is intended for use by the internal automake test suite only; `--acdir' is not ordinarily needed by end-users. `dirlist' is useful in the following situation: suppose that `automake' version `1.6.2' is installed with `--prefix=/usr' by the system vendor. Thus, the default search directories are 1. `/usr/share/aclocal-1.6/' 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.6/' 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 it to work around local system-dependent tool installation directories. Similarly, `dirlist' can be handy if you have installed a local copy Automake on your account and want `aclocal' to look for macros installed at other places on the system. 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'. *Note Hard-Coded Install Paths::, for arguments. A file of macros should be a series of properly quoted `AC_DEFUN''s (*note Macro Definitions: (autoconf)Macro Definitions.). The `aclocal' programs also understands `AC_REQUIRE' (*note Prerequisite Macros: (autoconf)Prerequisite Macros.), so it is safe to put each macro in a separate file. Each file should have no side effects but macro definitions. Especially, any call to `AC_PREREQ' should be done inside the defined macro, not at the beginning of the file. Starting with Automake 1.8, `aclocal' will warn about all underquoted calls to `AC_DEFUN'. We realize this will annoy a lot of people, because `aclocal' was not so strict in the past and many third party macros are underquoted; and we have to apologize for this temporary inconvenience. The reason we have to be stricter is that a future implementation of `aclocal' (*note Future of aclocal::) will have to temporarily include all these third party `.m4' files, maybe several times, including even files that are not actually needed. Doing so should alleviate many problems of the current implementation, however it requires a stricter style from the macro authors. Hopefully it is easy to revise the existing macros. For instance, # bad style AC_PREREQ(2.57) AC_DEFUN(AX_FOOBAR, [AC_REQUIRE([AX_SOMETHING])dnl AX_FOO AX_BAR ]) should be rewritten as AC_DEFUN([AX_FOOBAR], [AC_PREREQ([2.57])dnl AC_REQUIRE([AX_SOMETHING])dnl AX_FOO AX_BAR ]) Wrapping the `AC_PREREQ' call inside the macro ensures that Autoconf 2.57 will not be required if `AX_FOOBAR' is not actually used. Most importantly, quoting the first argument of `AC_DEFUN' allows the macro to be redefined or included twice (otherwise this first argument would be expanded during the second definition). For consistency we like to quote even arguments such as `2.57' that do not require it. If you have been directed here by the `aclocal' diagnostic but are not the maintainer of the implicated macro, you will want to contact the maintainer of that macro. Please make sure you have the last version of the macro and that the problem already hasn't 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, *note 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/'. To build `aclocal.m4', one should therefore instruct `aclocal' to scan `m4/'. From the command line, this is done with `aclocal -I m4'. The top-level `Makefile.am' should also be updated to define ACLOCAL_AMFLAGS = -I m4 `ACLOCAL_AMFLAGS' contains options to pass to `aclocal' when `aclocal.m4' is to be rebuilt by `make'. This line is also used by `autoreconf' (*note Using `autoreconf' to Update `configure' Scripts: (autoconf)autoreconf Invocation.) to run `aclocal' with suitable options, or by `autopoint' (*note Invoking the `autopoint' Program: (gettext)autopoint Invocation.) and `gettextize' (*note Invoking the `gettextize' Program: (gettext)gettextize Invocation.) to locate the place where Gettext's macros should be installed. So even if you do not really care about the rebuild rules, you should define `ACLOCAL_AMFLAGS'. When `aclocal -I m4' is run, it will build a `aclocal.m4' that `m4_include's any file from `m4/' that defines a required macro. Macros not found locally will still be searched in system-wide directories, as explained in *note Macro search path::. Custom macros should be distributed for the same reason that `configure.ac' is: so that other people have all the sources of your package if they want to work on it. Actually, this distribution happens automatically because all `m4_include'd 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 (*note Extending aclocal::). For instance, Guile ships with a file called `guile.m4' that contains the macro `GUILE_FLAGS' that can be used to define setup compiler and linker flags appropriate for using Guile. Using `GUILE_FLAGS' in `configure.ac' will cause `aclocal' to copy `guile.m4' into `aclocal.m4', but as `guile.m4' is not part of the project, it will not be distributed. Technically, that means a user who needs to rebuild `aclocal.m4' will have to install Guile first. This is probably OK, if Guile already is a requirement to build the package. However, if Guile is only an optional feature, or if your package might run on architectures where Guile cannot be installed, this requirement will hinder development. An easy solution is to copy such third-party macros in your local `m4/' directory so they get distributed. Since Automake 1.10, `aclocal' offers an option to copy these system-wide third-party macros in your local macro directory, solving the above problem. Simply use: ACLOCAL_AMFLAGS = -I m4 --install With this setup, system-wide macros will be copied to `m4/' the first time you run `autoreconf'. Then the locally installed macros will have precedence over the system-wide installed macros each time `aclocal' is run again. One reason why you should keep `--install' in the flags even after the first run is that when you later edit `configure.ac' and depend on a new macro, this macro will be installed in your `m4/' automatically. Another one is that serial numbers (*note 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 exists in your search path, and if at least one of them use a `#serial' line, `aclocal' will ignore the file that has the older `#serial' line (or the file that has none). Note that a serial number applies to a whole M4 file, not to any macro it contains. A file can contains multiple macros, but only one serial. Here is a use case that illustrate 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 *note Local Macros::, and has ACLOCAL_AMFLAGS = -I m4 --install in its top-level `Makefile.am'. Initially the `m4/' directory is empty. The first time we run `autoreconf', it will fetch the options to pass to `aclocal' in `Makefile.am', and run `aclocal -I m4 --install'. `aclocal' will notice that * `configure.ac' uses `AX_THIRD_PARTY' * No local macros define `AX_THIRD_PARTY' * `/usr/share/aclocal/thirdparty.m4' defines `AX_THIRD_PARTY' with serial 1. Because `/usr/share/aclocal/thirdparty.m4' is a system-wide macro and `aclocal' was given the `--install' option, it will copy this file in `m4/thirdparty.m4', and output an `aclocal.m4' that contains `m4_include([m4/thirdparty.m4])'. The next time `aclocal -I m4 --install' is run (either via `autoreconf', by hand, or from the `Makefile' rebuild rules) something different happens. `aclocal' notices that * `configure.ac' uses `AX_THIRD_PARTY' * `m4/thirdparty.m4' defines `AX_THIRD_PARTY' with serial 1. * `/usr/share/aclocal/thirdparty.m4' defines `AX_THIRD_PARTY' with serial 1. Because both files have the same serial number, `aclocal' uses the first it found in its search path order (*note Macro search path::). `aclocal' therefore ignores `/usr/share/aclocal/thirdparty.m4' and outputs an `aclocal.m4' that contains `m4_include([m4/thirdparty.m4])'. Local directories specified with `-I' are always searched before system-wide directories, so a local file will always be preferred to the system-wide file in case of equal serial numbers. Now suppose the system-wide third-party macro is changed. This can happen if the package installing this macro is updated. Let's suppose the new macro has serial number 2. The next time `aclocal -I m4 --install' is run the situation is the following: * `configure.ac' uses `AX_THIRD_PARTY' * `m4/thirdparty.m4' defines `AX_THIRD_PARTY' with serial 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 -I m4 --diff' to review the changes `aclocal -I m4 --install' would perform on these macros. Finally, note that the `--force' option of `aclocal' has absolutely no effect on the files installed by `--install'. For instance, if you have modified your local macros, do not expect `--install --force' to replace the local macros by their system-wide versions. If you want to do so, simply erase the local macros you want to revert, and run `aclocal -I m4 --install'. 6.3.6 The Future of `aclocal' ----------------------------- `aclocal' is expected to disappear. This feature really should not be offered by Automake. Automake should focus on generating `Makefile's; dealing with M4 macros really is Autoconf's job. 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 *note 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 itself to that non-trivial task. From the user point of view, `aclocal''s removal might turn out to be painful. There is a simple precaution that you may take to make that switch more seamless: never call `aclocal' yourself. Keep this guy under the exclusive control of `autoreconf' and Automake's rebuild rules. Hopefully you won't need to worry about things breaking, when `aclocal' disappears, because everything will have been taken care of. If otherwise you used to call `aclocal' directly yourself or from some script, you will quickly notice the change. Many packages come with a script called `bootstrap.sh' or `autogen.sh', that will just call `aclocal', `libtoolize', `gettextize' or `autopoint', `autoconf', `autoheader', and `automake' in the right order. Actually this is precisely what `autoreconf' can do for you. If your package has such a `bootstrap.sh' or `autogen.sh' script, consider using `autoreconf'. That should simplify its logic a lot (less things to maintain, yum!), it's even likely you will not need the script anymore, and more to the point you will not call `aclocal' directly anymore. For the time being, third-party packages should continue to install public macros into `/usr/share/aclocal/'. If `aclocal' is replaced by another tool it might make sense to rename the directory, but supporting `/usr/share/aclocal/' for backward compatibility should be really easy provided all macros are properly written (*note 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_ENABLE_MULTILIB' This is used when a "multilib" library is being built. The first optional argument is the name of the `Makefile' being generated; it defaults to `Makefile'. The second option argument is used to find the top source directory; it defaults to the empty string (generally this should not be used unless you are familiar with the internals). *Note Multilibs::. `AM_INIT_AUTOMAKE([OPTIONS])' `AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])' Runs many macros required for proper operation of the generated Makefiles. This macro has two forms, the first of which is preferred. In this form, `AM_INIT_AUTOMAKE' is called with a single argument: a space-separated list of Automake options that should be applied to every `Makefile.am' in the tree. The effect is as if each option were listed in `AUTOMAKE_OPTIONS' (*note Options::). The second, deprecated, form of `AM_INIT_AUTOMAKE' has two required arguments: the package and the version number. This form is obsolete because the PACKAGE and VERSION can be obtained from Autoconf's `AC_INIT' macro (which itself has an old and a new form). If your `configure.ac' has: AC_INIT([src/foo.c]) AM_INIT_AUTOMAKE([mumble], [1.5]) you can modernize it as follows: AC_INIT([mumble], [1.5]) AC_CONFIG_SRCDIR([src/foo.c]) AM_INIT_AUTOMAKE Note that if you're upgrading your `configure.ac' from an earlier version of Automake, it is not always correct to simply move the package and version arguments from `AM_INIT_AUTOMAKE' directly to `AC_INIT', as in the example above. The first argument to `AC_INIT' should be the name of your package (e.g., `GNU Automake'), not the tarball name (e.g., `automake') that you used to pass to `AM_INIT_AUTOMAKE'. Autoconf tries to derive a tarball name from the package name, which should work for most but not all package names. (If it doesn't work for yours, you can use the four-argument form of `AC_INIT' to provide the tarball name explicitly). By default this macro `AC_DEFINE''s `PACKAGE' and `VERSION'. This can be avoided by passing the `no-define' option, as in: AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2]) or by passing a third non-empty argument to the obsolete form. `AM_PATH_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_AS' Use this macro when you have assembly code in your project. This will choose the assembler for you (by default the C compiler) and set `CCAS', and will also set `CCASFLAGS' if required. `AM_PROG_CC_C_O' This is like `AC_PROG_CC_C_O', but it generates its results in the manner required by automake. You must use this instead of `AC_PROG_CC_C_O' when you need this functionality, that is, when using per-target flags or subdir-objects with C sources. `AM_PROG_LEX' Like `AC_PROG_LEX' (*note Particular Program Checks: (autoconf)Particular Programs.), 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_WITH_DMALLOC' Add support for the Dmalloc package (http://dmalloc.com/). If the user runs `configure' with `--with-dmalloc', then define `WITH_DMALLOC' and add `-ldmalloc' to `LIBS'. `AM_WITH_REGEX' Adds `--with-regex' to the `configure' command line. If specified (the default), then the `regex' regular expression library is used, `regex.o' is put into `LIBOBJS', and `WITH_REGEX' is defined. If `--without-regex' is given, then the `rx' regular expression library is used, and `rx.o' is put into `LIBOBJS'. 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. Running `autoupdate' should adjust your `configure.ac' automatically (*note Using `autoupdate' to Modernize `configure.ac': (autoconf)autoupdate Invocation.). `AM_C_PROTOTYPES' Check to see if function prototypes are understood by the compiler. If so, define `PROTOTYPES' and set the output variables `U' and `ANSI2KNR' to the empty string. Otherwise, set `U' to `_' and `ANSI2KNR' to `./ansi2knr'. Automake uses these values to implement the obsolete de-ANSI-fication feature. `AM_CONFIG_HEADER' Automake will generate rules to automatically regenerate the config header. This obsolete macro is a synonym of `AC_CONFIG_HEADERS' today (*note Optional::). `AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL' If the use of `TIOCGWINSZ' requires `', then define `GWINSZ_IN_SYS_IOCTL'. Otherwise `TIOCGWINSZ' can be found in `'. This macro is obsolete, you should use Autoconf's `AC_HEADER_TIOCGWINSZ' instead. `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' (*note Particular Program Checks: (autoconf)Particular Programs.), however this defines the output variable `MKDIR_P' instead. Therefore `AM_PROG_MKDIR_P' has been rewritten as a thin wrapper around `AC_PROG_MKDIR_P' to define `mkdir_p' to the same value as `MKDIR_P' for backward compatibility. If you are using Automake, there is normally no reason to call this macro, because `AM_INIT_AUTOMAKE' already does so. However, make sure that the custom rules in your `Makefile's use `$(MKDIR_P)' and not `$(mkdir_p)'. Even if both variables still work, the latter should be considered obsolete. If you are not using Automake, please call `AC_PROG_MKDIR_P' instead of `AM_PROG_MKDIR_P'. `AM_SYS_POSIX_TERMIOS' Check to see if POSIX termios headers and functions are available on the system. If so, set the shell variable `am_cv_sys_posix_termios' to `yes'. If not, set the variable to `no'. This macro is obsolete, you should use Autoconf's `AC_SYS_POSIX_TERMIOS' instead. 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 distributes all files in the same directory it is enough to have a single `Makefile.am' that builds everything in place. In larger projects it is common to organize files in different directories, in a tree. For instance one directory per program, per library or per module. The traditional approach is to build these subdirectory recursively: each directory contains its `Makefile' (generated from `Makefile.am'), and when `make' is run from the top level directory it enters each subdirectory in turn to build its contents. 7.1 Recursing subdirectories ============================ In packages with subdirectories, the top level `Makefile.am' must tell Automake which subdirectories are to be built. This is done via the `SUBDIRS' variable. The `SUBDIRS' variable holds a list of subdirectories in which building of various sorts can occur. The rules for many targets (e.g., `all') in the generated `Makefile' will run commands both locally and in all specified subdirectories. Note that the directories listed in `SUBDIRS' are not required to contain `Makefile.am's; only `Makefile's (after configuration). This allows inclusion of libraries from packages that do not use Automake (such as `gettext'; see also *note Third-Party Makefiles::). In packages that use subdirectories, the top-level `Makefile.am' is often very short. For instance, here is the `Makefile.am' from the GNU Hello distribution: EXTRA_DIST = BUGS ChangeLog.O README-alpha SUBDIRS = doc intl po src tests When Automake invokes `make' in a subdirectory, it uses the value of the `MAKE' variable. It passes the value of the variable `AM_MAKEFLAGS' to the `make' invocation; this can be set in `Makefile.am' if there are flags you must always pass to `make'. The directories mentioned in `SUBDIRS' are usually direct children of the current directory, each subdirectory containing its own `Makefile.am' with a `SUBDIRS' pointing to deeper subdirectories. Automake can be used to construct packages of arbitrary depth this way. By default, Automake generates `Makefiles' that work depth-first in postfix order: the subdirectories are built before the current directory. However, it is possible to change this ordering. You can do this by putting `.' into `SUBDIRS'. For instance, putting `.' first will cause a prefix ordering of directories. Using SUBDIRS = lib src . test will cause `lib/' to be built before `src/', then the current directory will be built, finally the `test/' directory will be built. It is customary to arrange test directories to be built after everything else since they are meant to test what has been constructed. All `clean' rules are run in reverse order of build rules. 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 setup a project like this. You can use Automake conditionals (*note Conditionals::) or use Autoconf `AC_SUBST' variables (*note Setting Output Variables: (autoconf)Setting Output Variables.). 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 (*note 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' come 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 possibles 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 Conditional 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 Conditional 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 Non-configured Subdirectories ----------------------------------- The semantic of `DIST_SUBDIRS' is 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. * `SUBDIRS' should always be a subset of `DIST_SUBDIRS'. It makes little sense to have a directory in `SUBDIRS' that is not in `DIST_SUBDIRS'. Think of the former as a way to tell which directories listed in the latter should be built. * Any directory listed in `DIST_SUBDIRS' and `SUBDIRS' must be configured. I.e., the `Makefile' must exists or the recursive `make' rules will not be able to process the directory. * Any configured directory must be listed in `DIST_SUBDIRS'. So that the cleaning rule remove the generated `Makefile's. It would be correct to see `DIST_SUBDIRS' as a variable that lists all the directories that have been configured. In order to prevent recursion in some non-configured directory you must therefore ensure that this directory does not appear in `DIST_SUBDIRS' (and `SUBDIRS'). For instance, if you define `SUBDIRS' conditionally using `AC_SUBST' and do not define `DIST_SUBDIRS' explicitly, it will be default to `$(SUBDIRS)'; another possibility is to force `DIST_SUBDIRS = $(SUBDIRS)'. Of course, directories that are omitted from `DIST_SUBDIRS' will not be distributed unless you make other arrangements for this to happen (for instance, always running `make dist' in a configuration where all directories are known to appear in `DIST_SUBDIRS'; or writing a `dist-hook' target to distribute these directories). In few packages, non-configured 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 exist. 7.3 An Alternative Approach to Subdirectories ============================================= If you've ever read Peter Miller's excellent paper, Recursive Make Considered Harmful (http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html), the preceding sections on the use of subdirectories will probably come as unwelcome advice. For those who haven't read the paper, Miller's main thesis is that recursive `make' invocations are both slow and error-prone. Automake provides sufficient cross-directory support (1) to enable you to write a single `Makefile.am' for a complex multi-directory package. By default an installable file specified in a subdirectory will have its directory name stripped before installation. For instance, in this example, the header file will be installed as `$(includedir)/stdio.h': include_HEADERS = inc/stdio.h However, the `nobase_' prefix can be used to circumvent this path stripping. In this example, the header file will be installed as `$(includedir)/sys/types.h': nobase_include_HEADERS = sys/types.h `nobase_' should be specified first when used in conjunction with either `dist_' or `nodist_' (*note Dist::). For instance: nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg Finally, note that a variable using the `nobase_' prefix can always be replaced by several variables, one for each destination directory (*note 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. ---------- Footnotes ---------- (1) We