automake

最新推荐文章于 2024-05-11 13:50:34 发布
最新推荐文章于 2024-05-11 13:50:34 发布
阅读量1.4w 收藏 4
点赞数
分类专栏： Linux 文章标签： variables dependencies fortran macros compilation library

automake

Table of Contents

Next:  ,Up:  (dir)

GNU Automake

This manual is for GNU Automake (version 1.11.2,21 December 2011), a program that creates GNU standards-compliantMakefiles from template files.

Copyright © 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free SoftwareFoundation, Inc.

Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License,Version 1.3 or any later version published by the Free SoftwareFoundation; with no Invariant Sections, with no Front-Cover texts,and with no Back-Cover Texts. A copy of the license is included in thesection entitled “GNU Free Documentation License.”

--- The Detailed Node Listing ---

An Introduction to the Autotools

Use Cases for the GNU Build System

A Small Hello World

General ideas

Some example packages

  • Complete: A simple example, start to finish
  • true: Building true and false

Scanning configure.ac, using aclocal

Auto-generating aclocal.m4

Autoconf macros supplied with Automake

Directories

Conditional Subdirectories

Building Programs and Libraries

Building a program

Building a Shared Library

Common Issues Related to Libtool's Use

Fortran 77 Support

Mixing Fortran 77 With C and C++

Fortran 9x Support

Other Derived Objects

Built Sources

Other GNU Tools

Building documentation

What Gets Installed

What Goes in a Distribution

Support for test suites

Miscellaneous Rules

  • Tags: Interfacing to etags and mkid
  • Suffixes: Handling new file extensions
  • Multilibs: Support for multilibs.

Conditionals

Silencing Make

When Automake Isn't Enough

Frequently Asked Questions about Automake

History of Automake

Dependency Tracking in Automake

Copying This Manual

Indices

Next:  ,Previous:  Top,Up:  Top

1 Introduction

Automake is a tool for automatically generating Makefile.insfrom files calledMakefile.am. Each Makefile.am isbasically a series ofmake variabledefinitions1, with rules being thrown inoccasionally. The generatedMakefile.ins are compliant withthe GNU Makefile standards.

The GNU Makefile Standards Document(seeMakefile Conventions)is long, complicated, and subject to change. The goal of Automake is toremove the burden of Makefile maintenance from the back of theindividual GNU maintainer (and put it on the back of the Automakemaintainers).

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

Automake does constrain a project in certain ways; for instance, itassumes that the project uses Autoconf (seeIntroduction), and enforces certain restrictions ontheconfigure.ac contents2.

Automake requiresperl in order to generate theMakefile.ins. However, the distributions created by Automake arefully GNU standards-compliant, and do not requireperl in orderto be built.

For more information on bug reports, SeeReporting Bugs.

Next:  ,Previous:  Introduction,Up:  Top

2 An Introduction to the Autotools

If you are new to Automake, maybe you know that it is part of a set oftools calledThe Autotools. Maybe you've already delved into apackage full of files namedconfigure, 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 probablyfuzzy. 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 neverinstalled or seen such a package, do not worry: this chapter will walkyou through it.

If you need some teaching material, more illustrations, or a lessautomake-centered continuation, some slides for thisintroduction are available in Alexandre Duret-Lutz'sAutotools Tutorial. This chapter is the written version of the first part of his tutorial.

Next:  ,Up:  Autotools Introduction

2.1 Introducing the GNU Build System

It is a truth universally acknowledged, that as a developer inpossession of a new package, you must be in want of a build system.

In the Unix world, such a build system is traditionally achieved usingthe commandmake (see Overview). You express the recipe to build your package in aMakefile. This file is a set of rules to build the files inthe package. For instance the program prog may be built byrunning the linker on the filesmain.o, foo.o, andbar.o; the filemain.o may be built by running thecompiler onmain.c; etc. Each time make is run, itreadsMakefile, checks the existence and modification time ofthe 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 oneit was developed on, itsMakefile usually needs to be adjusted. For instance the compiler may have another name or require moreoptions. In 1991, David J. MacKenzie got tired of customizingMakefile for the 20 platforms he had to deal with. Instead, hehandcrafted a little shell script calledconfigure toautomatically adjust the Makefile (see Genesis). Compiling his package was nowas simple as running./configure && make.

Today this process has been standardized in the GNU project. The GNUCoding Standards (seeThe Release Process) explains how each package of theGNU project should have aconfigure script, and the minimalinterface it should have. TheMakefile too should follow someestablished conventions. The result? A unified build system thatmakes all packages almost indistinguishable by the installer. In itssimplest scenario, all the installer has to do is to unpack thepackage, run ./configure && make && make install, and repeatwith the next package to install.

We call this build system the GNU Build System, since it wasgrown out of the GNU project. However it is used by a vast number ofother packages: following any existing convention has its advantages.

The Autotools are tools that will create a GNU Build System for yourpackage. Autoconf mostly focuses onconfigure and Automake onMakefiles. It is entirely possible to create a GNU BuildSystem without the help of these tools. However it is ratherburdensome and error-prone. We will discuss this again after someillustration of the GNU Build System in action.

Next:  ,Previous:  GNU Build System,Up:  Autotools Introduction

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 theamhello-1.0.tar.gzpackage distributed with Automake. If Automake is installed on yoursystem, you should find a copy of this file inprefix/share/doc/automake/amhello-1.0.tar.gz, whereprefix is the installation prefix specified during configuration(prefix defaults to/usr/local, however if Automake wasinstalled by some GNU/Linux distribution it most likely has been setto/usr). If you do not have a copy of Automake installed,you can find a copy of this file inside thedoc/ directory ofthe Automake package.

Some of the following use cases present features that are in factextensions to the GNU Build System. Read: they are not specified bythe GNU Coding Standards, but they are nonetheless part of the buildsystem created by the Autotools. To keep things simple, we do notpoint out the difference. Our objective is to show you many of thefeatures that the build system created by the Autotools will offer toyou.

Next:  ,Up:  Use Cases

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 followingexamples, we will use the non-portabletar zxf command forsimplicity. On a system without GNU tar installed, thiscommand should readgunzip -c amhello-1.0.tar.gz | tar xf -.

The user then enters the newly created directory to run theconfigure script. This script probes the system for variousfeatures, and finally creates theMakefiles. In this toyexample there are only twoMakefiles, but in real-world projects,there may be many more, usually oneMakefile per directory.

It is now possible to run make. This will construct all theprograms, libraries, and scripts that need to be constructed for thepackage. In our example, this compiles thehello program. All files are constructed in place, in the source tree; we will seelater how this can be changed.

make check causes the package's tests to be run. This step isnot mandatory, but it is often good to make sure the programs thathave been built behave as they should, before you decide to installthem. Our example does not contain any tests, so running makecheck is a no-op.

After everything has been built, and maybe tested, it is time toinstall it on the system. That means copying the programs,libraries, header files, scripts, and other data files from thesource directory to their final destination on the system. Thecommand make install will do that. However, by defaulteverything 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 writableby any user, so we assume that we have to become root before we canrun make install. In our example, runningmake installwill copy the program hello into/usr/local/binand README into/usr/local/share/doc/amhello.

A last and optional step is to run make installcheck. Thiscommand may run tests on the installed files.make check teststhe files in the source tree, while make installcheck teststheir installed copies. The tests run by the latter can be differentfrom those run by the former. For instance, there are tests thatcannot be run in the source tree. Conversely, some packages are setup so that make installcheck will run the very same tests asmake check, only on different files (non-installedvs. installed). It can make a difference, for instance when thesource 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 testsbecause the existence ofinstallcheck is little known, and itsusefulness is neglected. Our little toy package is no better:makeinstallcheck does nothing.

Next:  ,Previous:  Basic Installation,Up:  Use Cases

2.2.2 Standard Makefile Targets

So far we have come across four ways to run make in the GNUBuild System:make, make check, make install, andmake installcheck. The wordscheck, install, andinstallcheck, passed as arguments tomake, are calledtargets. 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 Standardsspecify.

make all
Build programs, libraries, documentation, etc. (same as make).
make install
Install what needs to be installed, copying the files from thepackage's tree to system-wide directories.
make install-strip
Same as make install, then strip debugging symbols. Someusers 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 sourcefiles.

Next:  ,Previous:  Standard Targets,Up:  Use Cases

2.2.3 Standard Directory Variables

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

Directory variableDefault 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 itsname. In a package, any installable file will be installed in one ofthese directories. For instance inamhello-1.0, the programhello is to be installed inbindir, the directory forbinaries. The default value for this directory is/usr/local/bin, but the user can supply a different value whencallingconfigure. Also the file README will beinstalled intodocdir, which defaults to/usr/local/share/doc/amhello.

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

Next:  ,Previous:  Standard Directory Variables,Up:  Use Cases

2.2.4 Standard Configuration Variables

The GNU Coding Standards also define a set of standard configurationvariables 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 appropriatevalues for these variables, but there are cases where you may want tooverride them. For instance you may have several versions of acompiler installed and would like to use another one, you may haveheader files installed outside the default search path of thecompiler, or even libraries out of the way of the linker.

Here is how one would call configure to force it to usegcc-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.

Next:  ,Previous:  Standard Configuration Variables,Up:  Use Cases

2.2.5 Overriding Default Configuration Setting with config.site

When installing several packages using the same setup, it can beconvenient to create a file to capture common settings. If a file namedprefix/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 willalways want to use these definitions ofCC, CPPFLAGS, andLDFLAGS, 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~/usrprefix, it will execute the above config.site and definethese three variables.

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

See Setting Site Defaults, for more information about this feature.

Next:  ,Previous:  config.site,Up:  Use Cases

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

The GNU Build System distinguishes two trees: the source tree, andthe build tree.

The source tree is rooted in the directory containingconfigure. It contains all the sources files (those that aredistributed), and may be arranged using several subdirectories.

The build tree is rooted in the directory in which configurewas run, and is populated with all object files, programs, libraries,and other derived files built from the sources (and hence notdistributed). The build tree usually has the same subdirectory layoutas the source tree; its subdirectories are created automatically bythe build system.

If configure is executed in its own directory, the source andbuild trees are combined: derived files are constructed in the samedirectories as their sources. This was the case in our firstinstallation example (seeBasic Installation).

A common request from users is that they want to confine all derivedfiles to a single directory, to keep their source directoriesuncluttered. Here is how we could runconfigure to buildeverything in a subdirectory calledbuild/.

     ~ % 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 oftencalled parallel builds or VPATH builds. The expressionparallel build is misleading: the wordparallel is areference to the way the build tree shadows the source tree, it is notabout some concurrency in the way build commands are run. For thisreason we refer to such setups using the nameVPATH builds inthe following. VPATH is the name of the make featureused by theMakefiles to allow these builds (see VPATH Search Path for All Prerequisites).

VPATH builds have other interesting uses. One is to build the samesources 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 thesame sources on different machines. For instance, suppose that thesources are installed on a directory shared by two hosts:HOST1and HOST2, which may be different platforms.

     ~ % cd /nfs/src
     /nfs/src % tar zxf ~/amhello-1.0.tar.gz

On the first host, you could create a local build directory:

     [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh
     [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure
     ...
     [HOST1] /tmp/amh % make && sudo make install
     ...

(Here we assume that the installer has configured sudo so itcan executemake install with root privileges; it is more convenientthan using su like in Basic Installation).

On the second host, you would do exactly the same, possibly atthe 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.0directory from being read-only. In fact VPATH builds are also a meansof building packages from a read-only medium such as a CD-ROM. (TheFSF used to sell CD-ROM with unpacked source code, before the GNUproject grew so big.)

Next:  ,Previous:  VPATH Builds,Up:  Use Cases

2.2.7 Two-Part Installation

In our last example (see VPATH Builds), a source tree was sharedby two hosts, but compilation and installation were done separately oneach host.

The GNU Build System also supports networked setups where part of theinstalled files should be shared amongst multiple hosts. It does soby distinguishing architecture-dependent files fromarchitecture-independent files, and providing twoMakefiletargets to install each of these classes of files.

These targets areinstall-exec for architecture-dependent filesand install-data for architecture-independent files. The command we used up to now,make install, can be thought ofas a shorthand for make install-exec install-data.

From the GNU Build System point of view, the distinction betweenarchitecture-dependent files and architecture-independent files isbased exclusively on the directory variable used to specify theirinstallation destination. In the list of directory variables weprovided earlier (see Standard Directory Variables), all thevariables based onexec-prefix designate architecture-dependentdirectories whose files will be installed bymake install-exec. The others designate architecture-independent directories and willserve files installed bymake install-data. See The Two Parts of Install, for more details.

Here is how we could revisit our two-host installation example,assuming that (1) we want to install the package directly in/usr, and (2) the directory/usr/share is shared by thetwo 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 thearchitecture-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 runmake installcheck (seeBasic Installation) to verify thatthe package works correctly despite the apparent partial installation.

Next:  ,Previous:  Two-Part Install,Up:  Use Cases

2.2.8 Cross-Compilation

To cross-compile is to build on one platform a binary that willrun on another platform. When speaking of cross-compilation, it isimportant to distinguish between thebuild platform on whichthe compilation is performed, and the host platform on which theresulting executable is expected to run. The followingconfigure 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 forthe cross-compiling suite for this platform. Cross-compilation toolscommonly have their target architecture as prefix of their name. Forinstance my cross-compiler for MinGW32 has its binaries calledi586-mingw32msvc-gcc,i586-mingw32msvc-ld,i586-mingw32msvc-as, etc.

Here is how we could buildamhello-1.0 fori586-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 weneed for cross-compiling. The only exception is if the package beingbuilt is itself a cross-compiler: we need a third option to specifyits target architecture.

--target=target
When building compiler tools: the system for which the tools willcreate output.

For instance when installing GCC, the GNU Compiler Collection, we canuse --target=target to specify that we want to buildGCC as a cross-compiler fortarget. Mixing --build and--target, we can actually cross-compile a cross-compiler;such a three-way cross-compilation is known as aCanadian cross.

See Specifying the System Type, for more information about theseconfigureoptions.

Next:  ,Previous:  Cross-Compilation,Up:  Use Cases

2.2.9 Renaming Programs at Install Time

The GNU Build System provides means to automatically renameexecutables and manpages before they are installed (see Man Pages). This is especially convenientwhen installing a GNU package on a system that already has aproprietary implementation you do not want to overwrite. For instance,you may want to install GNUtar as gtar so you candistinguish it from your vendor'star.

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 helloas/usr/local/bin/test-hello, for instance.

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

Next:  ,Previous:  Renaming,Up:  Use Cases

2.2.10 Building Binary Packages Using DESTDIR

The GNU Build System's make install andmake uninstallinterface does not exactly fit the needs of a system administratorwho has to deploy and upgrade packages on lots of hosts. In otherwords, the GNU Build System does not replace a package manager.

Such package managers usually need to know which files have beeninstalled by a package, so a meremake install isinappropriate.

The DESTDIR variable can be used to perform a stagedinstallation. The package should be configured as if it was going tobe installed in its final location (e.g.,--prefix /usr), butwhen running make install, the DESTDIR should be set tothe absolute name of a directory into which the installation will bediverted. From this directory it is easy to review which files arebeing installed where, and finally copy them to their final locationby some means.

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

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

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

Note that when building packages for several architectures, it mightbe convenient to usemake install-data and makeinstall-exec (see Two-Part Install) to gatherarchitecture-independent files in a single package.

See Install, for more information.

Next:  ,Previous:  DESTDIR,Up:  Use Cases

2.2.11 Preparing Distributions

We have already mentionedmake dist. This target collects allyour source files and the necessary parts of the build system tocreate a tarball namedpackage-version.tar.gz.

Another, more useful command ismake distcheck. Thedistcheck target constructspackage-version.tar.gz just as well asdist,but it additionally ensures most of the use cases presented so farwork:

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

All of these actions are performed in a temporary subdirectory, sothat no root privileges are required.

Releasing a package that fails make distcheck means that one ofthe scenarios we presented will not work and some users will bedisappointed. Therefore it is a good practice to release a packageonly after a successfulmake distcheck. This of course doesnot imply that the package will be flawless, but at least it willprevent some of the embarrassing errors you may find in packagesreleased by people who have never heard aboutdistcheck (likeDESTDIR not working because of a typo, or a distributed filebeing erased bymake clean, or even VPATH builds notworking).

See Creating amhello, to recreate amhello-1.0.tar.gz usingmake distcheck. SeeChecking the Distribution, for moreinformation aboutdistcheck.

Next:  ,Previous:  Preparing Distributions,Up:  Use Cases

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 itslist of dependencies (in C these are the header files included by thesource being compiled). Later, any time make is run and adependency appears to have changed, the dependent files will berebuilt.

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

When configure is executed, you can see it probing eachcompiler for the dependency mechanism it supports (several mechanismscan be used):

     ~/amhello-1.0 % ./configure --prefix /usr
     ...
     checking dependency style of gcc... gcc3
     ...

Because dependencies are only computed as a side-effect of thecompilation, no dependency information exists the first time a packageis 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 buildsand there is aconfigure option to disable this:

--disable-dependency-tracking
Speed up one-time builds.

Some compilers do not offer any practical way to derive the list ofdependencies as a side-effect of the compilation, requiring a separaterun (maybe of another tool) to compute these dependencies. Theperformance penalty implied by these methods is important enough todisable them by default. The option --enable-dependency-trackingmust be passed toconfigure to activate them.

--enable-dependency-tracking
Do not reject slow dependency extractors.

See Dependency Tracking Evolution, for some discussion about thedifferent dependency tracking schemes used by Automake over the years.

Previous:  Dependency Tracking,Up:  Use Cases

2.2.13 Nested Packages

Although nesting packages isn't something we would recommend tosomeone who is discovering the Autotools, it is a nice feature worthyof mention in this small advertising tour.

Autoconfiscated packages (that means packages whose build system havebeen created by Autoconf and friends) can be nested to arbitrarydepth.

A typical setup is that package A will distribute one of the librariesit needs in a subdirectory. This library B is a complete package withits own GNU Build System. Theconfigure script of A willrun the configure script of B as part of its execution,building and installing A will also build and install B. Generating adistribution for A will also include B.

It is possible to gather several packages like this. GCC is a heavyuser of this feature. This gives installers a single package toconfigure, build and install, while it allows developers to work onsubpackages independently.

When configuring nested packages, the configure optionsgiven to the top-levelconfigure are passed recursively tonestedconfigures. A package that does not understand anoption will ignore it, assuming it is meaningful to some otherpackage.

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

See Subpackages, for an example setup.

Next:  ,Previous:  Use Cases,Up:  Autotools Introduction

2.3 How Autotools Help

There are several reasons why you may not want to implement the GNUBuild System yourself (read: write aconfigure script andMakefiles yourself).

  • As we have seen, the GNU Build System has a lot offeatures (see Use Cases). Some users may expect features you have not implemented becauseyou did not need them.
  • Implementing these features portably is difficult and exhausting. Think of writing portable shell scripts, and portableMakefiles, for systems you may not have handy. SeePortable Shell Programming, toconvince yourself.
  • You will have to upgrade your setup to follow changes to the GNUCoding Standards.

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

  • Tools to create a portable, complete, and self-contained GNU BuildSystem, from simple instructions.Self-contained meaning the resulting build system does notrequire 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 theAutotools... For instance you may be already using (or used to)another incompatible build system. Autotools will only be useful ifyou do accept the concepts of the GNU Build System. People who have theirown idea of how a build system should work will feel frustrated by theAutotools.

Previous:  Why Autotools,Up:  Autotools Introduction

2.4 A Small Hello World

In this section we recreate theamhello-1.0 package fromscratch. The first subsection shows how to call the Autotools toinstantiate the GNU Build System, while the second explains themeaning of theconfigure.ac and Makefile.am files readby the Autotools.

Next:  ,Up:  Hello World

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 5files. (You may copy them from the finalamhello-1.0.tar.gzthat 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. Westore it in the src/ subdirectory, because later, when the packageevolves, it will ease the addition of aman/ directory for manpages, a data/ directory for data files, etc. 
              ~/amhello % cat src/main.c
          #include <config.h>
          #include <stdio.h>
          
          int
          main (void)
          {
            puts ("Hello World!");
            puts ("This is " PACKAGE_STRING ".");
            return 0;
          }
  • README contains some very limited documentation for our littlepackage. 
              ~/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 Automakeinstructions 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 tocreate theconfigure 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 toinstantiate the build system. Do this using theautoreconfcommand 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 seethat 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 thesystem byconfigure under the names config.h,Makefile, andsrc/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 seeMakefile, src/Makefile, andconfig.hbeing created at the end after configure has probed thesystem. It is now possible to run all the targets we wish(seeStandard 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 whenthe GNU Build System does not exist. When you later change someinstructions in aMakefile.am or configure.ac, therelevant part of the build system will be regenerated automaticallywhen you executemake.

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 figureout in which order all these tools should be invoked and why. However,because Autoconf and Automake have separate manuals, the importantpoint to understand is thatautoconf is in charge ofcreating configure from configure.ac, whileautomake is in charge of creatingMakefile.ins fromMakefile.ams andconfigure.ac. This should at leastdirect you to the right manual when seeking answers.

Next:  ,Previous:  Creating amhello,Up:  Hello World

2.4.2 amhello's configure.ac Setup Explained

Let us begin with the contents ofconfigure.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 createconfigure) andautomake (to create the variousMakefile.ins). It contains a series of M4 macros that will beexpanded as shell code to finally form theconfigure script. We will not elaborate on the syntax of this file, because the Autoconfmanual has a whole section about it (seeWriting configure.ac).

The macros prefixed with AC_ are Autoconf macros, documentedin the Autoconf manual (seeAutoconf Macro Index). The macros that start withAM_ are Automake macros, documented later in this manual(seeMacro Index).

The first two lines of configure.ac initialize Autoconf andAutomake.AC_INIT takes in as parameters the name of the package,its version number, and a contact address for bug-reports about thepackage (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 themailing list of your package, or your own mail address.

The argument toAM_INIT_AUTOMAKE is a list of options forautomake (seeOptions). -Wall and-Werror askautomake to turn on all warnings andreport them as errors. We are speaking ofAutomake warningshere, such as dubious instructions in Makefile.am. This hasabsolutely nothing to do with how the compiler will be called, eventhough it may support options with similar names. Using-Wall-Werror is a safe setting when starting to work on a package: you donot want to miss any issues. Later you may decide to relax things abit. Theforeign option tells Automake that this packagewill not follow the GNU Standards. GNU packages should alwaysdistribute additional files such asChangeLog, AUTHORS,etc. We do not wantautomake to complain about thesemissing files in our small example.

The AC_PROG_CC line causes the configure script tosearch for a C compiler and define the variableCC with itsname. The src/Makefile.in file generated by Automake uses thevariableCC to build hello, so when configurecreates src/Makefile fromsrc/Makefile.in, it will defineCC with the value it has found. If Automake is asked to createaMakefile.in that uses CC but configure.ac doesnot define it, it will suggest you add a call toAC_PROG_CC.

The AC_CONFIG_HEADERS([config.h]) invocation causes theconfigure script to create aconfig.h file gathering‘#define’s defined by other macros inconfigure.ac. In ourcase, the AC_INIT macro already defined a few of them. Hereis an excerpt ofconfig.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 includesconfig.h soit can use PACKAGE_STRING. In a real-world project,config.h can grow really big, with one ‘#define’ perfeature probed on the system.

The AC_CONFIG_FILES macro declares the list of files thatconfigure should create from their*.in templates. Automake also scans this list to find theMakefile.am files it mustprocess. (This is important to remember: when adding a new directoryto your project, you should add itsMakefile to this list,otherwise Automake will never process the newMakefile.am youwrote in that directory.)

Finally, the AC_OUTPUT line is a closing command that actuallyproduces the part of the script in charge of creating the filesregistered withAC_CONFIG_HEADERS and AC_CONFIG_FILES.

When starting a new project, we suggest you start with such a simpleconfigure.ac, and gradually add the other tests it requires. The commandautoscan can also suggest a few of the testsyour package may need (seeUsing autoscan to Createconfigure.ac).

Previous:  amhello's configure.ac Setup Explained,Up:  Hello World

2.4.3 amhello's Makefile.am Setup Explained

We now turn tosrc/Makefile.am. This file containsAutomake instructions to build and installhello.

     bin_PROGRAMS = hello
     hello_SOURCES = main.c

A Makefile.am has the same syntax as an ordinaryMakefile. Whenautomake processes aMakefile.am it copies the entire file into the outputMakefile.in (that will be later turned intoMakefile byconfigure) but will react to certain variable definitionsby generating some build rules and other variables. OftenMakefile.ams contain only a list of variable definitions asabove, but they can also contain other variable and rule definitions thatautomake will pass along without interpretation.

Variables that end with _PROGRAMS are special variablesthat list programs that the resultingMakefile should build. In Automake speak, this_PROGRAMS suffix is called aprimary; Automake recognizes other primaries such as_SCRIPTS,_DATA, _LIBRARIES, etc. correspondingto different types of files.

The ‘bin’ part of the bin_PROGRAMS tellsautomake that the resulting programs should be installed inbindir. Recall that the GNU Build System uses a set of variablesto denote destination directories and allow users to customize theselocations (seeStandard Directory Variables). Any such directoryvariable can be put in front of a primary (omitting thedirsuffix) to tell automake where to install the listed files.

Programs need to be built from source files, so for each programprog listed in a_PROGRAMS variable,automake will look for another variable namedprog_SOURCES listing its source files. There may be morethan one source file: they will all be compiled and linked together.

Automake also knows that source files need to be distributed whencreating a tarball (unlike built programs). So a side-effect of thishello_SOURCES declaration is thatmain.c will bepart of the tarball created bymake dist.

Finally here are some explanations regarding the top-levelMakefile.am.

     SUBDIRS = src
     dist_doc_DATA = README

SUBDIRS is a special variable listing all directories thatmake should recurse into before processing the currentdirectory. So this line is responsible formake buildingsrc/hello even though we run it from the top-level. This linealso causesmake install to install src/hello beforeinstallingREADME (not that this order matters).

The line dist_doc_DATA = README causes README to bedistributed and installed indocdir. Files listed with the_DATA primary are not automatically part of the tarball builtwithmake dist, so we add the dist_ prefix so they getdistributed. However, forREADME it would not have beennecessary: automake automatically distributes anyREADME file it encounters (the list of other filesautomatically distributed is presented byautomake --help). The only important effect of this second line is therefore to installREADME duringmake install.

One thing not covered in this example is accessing the installationdirectory values (seeStandard Directory Variables) from yourprogram code, that is, converting them into defined macros. For this,seeDefining Directories.

Next:  ,Previous:  Autotools Introduction,Up:  Top

3 General ideas

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

Next:  ,Up:  Generalities

3.1 General Operation

Automake works by reading a Makefile.am and generating aMakefile.in. Certain variables and rules defined in theMakefile.am instruct Automake to generate more specialized code;for instance, a bin_PROGRAMS variable definition will cause rulesfor compiling and linking programs to be generated.

The variable definitions and rules in theMakefile.am arecopied mostly verbatim into the generated file, with all variabledefinitions preceding all rules. This allows you to add almostarbitrary code into the generatedMakefile.in. For instance,the Automake distribution includes a non-standard rule for thegit-dist target, which the Automake maintainer uses to makedistributions from the source control system.

Note that most GNU make extensions are not recognized by Automake. Usingsuch extensions in aMakefile.am will lead to errors or confusingbehavior.

A special exception is that the GNU make append operator, ‘+=’, issupported. This operator appends its right hand argument to the variablespecified on the left. Automake will translate the operator intoan ordinary ‘=’ operator; ‘+=’ will thus work with any make program.

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

Generally, Automake is not particularly smart in the parsing of unusualMakefile constructs, so you're advised to avoid fancy constructs or“creative” use of whitespaces. For example, <TAB> characters cannot be used between a target nameand the following “:” character, and variable assignmentsshouldn't be indented with <TAB> characters. Also, using more complex macro in target names can cause trouble:

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

A rule defined inMakefile.am generally overrides any suchrule of a similar name that would be automatically generated byautomake. Although this is a supported feature, it is generallybest to avoid making use of it, as sometimes the generated rules arevery particular.

Similarly, a variable defined inMakefile.am orAC_SUBSTed fromconfigure.ac will override anydefinition of the variable thatautomake would ordinarilycreate. This feature is more often useful than the ability tooverride a rule. Be warned that many of the variables generated byautomake are considered to be for internal use only, and theirnames might change in future releases.

When examining a variable definition, Automake will recursively examinevariables referenced in the definition. For example, if Automake islooking 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, andc.c as thecontents of foo_SOURCES.

Automake also allows a form of comment that isnot copied intothe 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

Next:  ,Previous:  General Operation,Up:  Generalities

3.2 Strictness

While Automake is intended to be used by maintainers of GNU packages, itdoes make some effort to accommodate those who wish to use it, but donot want to use all the GNU conventions.

To this end, Automake supports three levels of strictness—thestrictness indicating how stringently Automake should check standardsconformance.

The valid strictness levels are:

foreign
Automake will check for only those things that are absolutelyrequired for proper operations. For instance, whereas GNU standardsdictate the existence of a NEWS file, it will not be required inthis mode. The name comes from the fact that Automake is intended to beused for GNU programs; these relaxed rules are not the standard mode ofoperation.
gnu
Automake will check—as much as possible—for compliance to the GNUstandards for packages. This is the default.
gnits
Automake will check for compliance to the as-yet-unwritten Gnitsstandards. These are based on the GNU standards, but are even moredetailed. Unless you are a Gnits standards contributor, it isrecommended that you avoid this option until such time as the Gnitsstandard is actually published (which may never happen).

See Gnits, for more information on the precise implications of thestrictness level.

Automake also has a special “cygnus” mode that is similar tostrictness but handled differently. This mode is useful for packagesthat are put into a “Cygnus” style tree (e.g., the GCC tree). SeeCygnus, for more information on this mode.

Next:  ,Previous:  Strictness,Up:  Generalities

3.3 The Uniform Naming Scheme

Automake variables generally follow auniform naming scheme thatmakes it easy to decide how programs (and other derived objects) arebuilt, and how they are installed. This scheme also supportsconfigure time determination of what should be built.

Atmake time, certain variables are used to determine whichobjects are to be built. The variable names are made of several piecesthat are concatenated together.

The piece that tells automake what is being built is commonly calledtheprimary. For instance, the primary PROGRAMS holds alist of programs that are to be compiled and linked.A different set of names is used to decide where the built objectsshould be installed. These names are prefixes to the primary, and theyindicate which standard directory should be used as the installationdirectory. The standard directory names are given in the GNU standards(see Directory Variables). Automake extends this list withpkgdatadir, pkgincludedir,pkglibdir, and pkglibexecdir; these are the same as thenon-‘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 listobjects that may or may not be built, depending on whatconfigure decides. This variable is required because Automakemust statically know the entire list of objects that may be built inorder to generate aMakefile.in that will work in all cases.

For instance,cpio decides at configure time which programsshould be built. Some of the programs are installed inbindir,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 thevariable names; thus one writes ‘bin_PROGRAMS’ and not‘bindir_PROGRAMS’.

Not every sort of object can be installed in every directory. Automakewill flag those attempts it finds in error (but see below how to overridethe check if you really need to). Automake will also diagnose obvious misspellings in directory names.

Sometimes the standard directories—even as augmented byAutomake—are not enough. In particular it is sometimes useful, forclarity, to install objects in a subdirectory of some predefineddirectory. To this end, Automake allows you to extend the list ofpossible installation directories. A given prefix (e.g., ‘zar’)is valid if a variable of the same name with ‘dir’ appended isdefined (e.g., ‘zardir’).

For instance, the following snippet will install file.xml into‘$(datadir)/xml’.

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

This feature can also be used to override the sanity checks Automakeperforms to diagnose suspicious directory/primary couples (in theunlikely case these checks are undesirable, and you really know whatyou're doing). For example, Automake would error out on this input:

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

but it will succeed with this:

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

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

The special prefix ‘noinst_’ indicates that the objects in questionshould be built but not installed at all. This is usually used forobjects required to build the rest of your package, for instance staticlibraries (seeA Library), or helper scripts.

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

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

Next:  ,Previous:  Uniform,Up:  Generalities

3.4 Staying below the command line length limit

Traditionally, most unix-like systems have a length limitation for thecommand line arguments and environment contents when creating newprocesses (see for examplehttp://www.in-ulm.de/~mascheck/various/argmax/ for anoverview on this issue),which of course also applies to commands spawned bymake. POSIX requires this limit to be at least 4096 bytes, and most modernsystems have quite high limits (or are unlimited).

In order to create portable Makefiles that do not trip over theselimits, it is necessary to keep the length of file lists bounded. Unfortunately, it is not possible to do so fully transparently withinAutomake, so your help may be needed. Typically, you can split longfile lists manually and use different installation directory names foreach list. For example,

     data_DATA = file1 ... fileN fileN+1 ... file2N

may also be written as

     data_DATA = file1 ... fileN
     data2dir = $(datadir)
     data2_DATA = fileN+1 ... file2N

and will cause Automake to treat the two lists separately duringmake install. SeeThe Two Parts of Install for choosingdirectory names that will keep the ordering of the two parts ofinstallation Note thatmake dist may still only work on a hostwith a higher length limit in this example.

Automake itself employs a couple of strategies to avoid long commandlines. For example, when ‘${srcdir}/’ is prepended to filenames, as can happen with above$(data_DATA) lists, it limitsthe amount of arguments passed to external commands.

Unfortunately, some system's make commands may prependVPATH prefixes like ‘${srcdir}/’ to file names from thesource tree automatically (seeAutomatic Rule Rewriting). In this case, the usermay have to switch to use GNU Make, or refrain from using VPATH builds,in order to stay below the length limit.

For libraries and programs built from many sources, convenience archivesmay be used as intermediates in order to limit the object list length(seeLibtool Convenience Libraries).

Next:  ,Previous:  Length Limitations,Up:  Generalities

3.5 How derived variables are named

Sometimes a Makefile variable name is derived from some text themaintainer 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 thatprogram names and the like do not have to follow Makefile variable namingrules. All characters in the name except for letters, numbers, thestrudel (@), and the underscore are turned into underscores when makingvariable references.

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

The strudel is an addition, to make the use of Autoconf substitutions invariable names less obfuscating.

Next:  ,Previous:  Canonicalization,Up:  Generalities

3.6 Variables reserved for the user

SomeMakefile variables are reserved by the GNU Coding Standardsfor the use of the “user”—the person building the package. Forinstance,CFLAGS is one such variable.

Sometimes package developers are tempted to set user variables such asCFLAGS because it appears to make their job easier. However,the package itself should never set a user variable, particularly notto include switches that are required for proper compilation of thepackage. Since these variables are documented as being for thepackage builder, that person rightfully expects to be able to overrideany of these variables at build time.

To get around this problem, Automake introduces an automake-specificshadow variable for each user flag variable. (Shadow variables arenot introduced for variables likeCC, where they would make nosense.) The shadow variable is named by prepending ‘AM_’ to theuser variable's name. For instance, the shadow variable forYFLAGS isAM_YFLAGS. The package maintainer—that is,the author(s) of the Makefile.am and configure.acfiles—may adjust these shadow variables however necessary.

See Flag Variables Ordering, for more discussion about thesevariables and how they interact with per-target variables.

Previous:  User Variables,Up:  Generalities

3.7 Programs automake might require

Automake sometimes requires helper programs so that the generatedMakefile can do its work properly. There are a fairly largenumber of them, and we list them here.

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

ar-lib
This is a wrapper primarily for the Microsoft lib archiver, to makeit more POSIX-like.
ansi2knr.c ansi2knr.1
These two files are used for de-ANSI-fication support (they aredeprecated now, and will be removed in the next major Automakerelease; see ANSI).
compile
This is a wrapper for compilers that do not accept options -cand -o at the same time. It is only used when absolutelyrequired. Such compilers are rare, with the Microsoft C/C++ Compileras the most notable exception. This wrapper also makes the followingcommon options available for that compiler, while performing file nametranslation where needed: -I, -L, -l, -Wl, and -Xlinker.
config.guess config.sub
These two programs compute the canonical triplets for the given build,host, or target architecture. These programs are updated regularly tosupport new architectures and fix probes broken by changes in newkernel versions. Each new release of Automake comes with up-to-datecopies of these programs. If your copy of Automake is getting old,you are encouraged to fetch the latest versions of these files from http://savannah.gnu.org/git/?group=config before making arelease.
config-ml.in
This file is not a program, it is a configure fragment used formultilib support (see Multilibs). This file is maintained in theGCC tree at http://gcc.gnu.org/svn.html.
depcomp
This program understands how to run a compiler so that it willgenerate not only the desired output but also dependency informationthat is then used by the automatic dependency tracking feature(see Dependencies).
elisp-comp
This program is used to byte-compile Emacs Lisp code.
install-sh
This is a replacement for the install program that works onplatforms where install is unavailable or unusable.
mdate-sh
This script is used to generate a version.texi file. It examinesa file and prints some date information about it.
missing
This wraps a number of programs that are typically only required bymaintainers. If the program in question doesn't exist, missing prints an informative warning and attempts to fixthings so that the build can continue.
mkinstalldirs
This script used to be a wrapper around ‘ mkdir -p’, which is notportable. Now we prefer to use ‘ install-sh -d’ when configurefinds that ‘ mkdir -p’ does not work, this makes one less script todistribute.

For backward compatibility mkinstalldirs is still used anddistributed whenautomake finds it in a package. But it is nolonger 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 linksinstead of copying files. Such an operation is performed when buildingmultilibs (see Multilibs). This file is maintained in the GCCtree at http://gcc.gnu.org/svn.html.
texinfo.tex
Not a program, this file is required for ‘ make dvi’, ‘ makeps’ and ‘ make pdf’ to work when Texinfo sources are in thepackage. The latest version can be downloaded from http://www.gnu.org/software/texinfo/.
ylwrap
This program wraps lex and yacc to rename theiroutput files. It also ensures that, for instance, multiple yacc instances can be invoked in a single directory inparallel.

Next:  ,Previous:  Generalities,Up:  Top

4 Some example packages

This section contains two small examples.

The first example (see Complete) assumes you have an existingproject already using Autoconf, with handcraftedMakefiles, andthat you want to convert it to using Automake. If you are discoveringboth tools, it is probably better that you look at the Hello Worldexample presented earlier (seeHello World).

The second example (see true) shows how two programs can be builtfrom the same file, using different compilation parameters. Itcontains some technical digressions that are probably best skipped onfirst read.

  • Complete: A simple example, start to finish
  • true: Building true and false

Next:  ,Up:  Examples

4.1 A simple example, start to finish

Let's suppose you just finished writingzardoz, a program to makeyour head float from vortex to vortex. You've been using Autoconf toprovide a portability framework, but yourMakefile.ins have beenad-hoc. You want to make them bulletproof, so you turn to Automake.

The first step is to update yourconfigure.ac to include thecommands that automake needs. The way to do this is to add anAM_INIT_AUTOMAKE call just afterAC_INIT:

     AC_INIT([zardoz], [1.0])
     AM_INIT_AUTOMAKE
     ...

Since your program doesn't have any complicating factors (e.g., itdoesn't use gettext, it doesn't want to build a shared library),you're done with this part. That was easy!

Now you must regenerateconfigure. But to do that, you'll needto tellautoconf how to find the new macro you've used. Theeasiest way to do this is to use theaclocal program togenerate your aclocal.m4 for you. But wait... maybe youalready have anaclocal.m4, because you had to write some hairymacros for your program. Theaclocal program lets you putyour own macros intoacinclude.m4, so simply rename and thenrun:

     mv aclocal.m4 acinclude.m4
     aclocal
     autoconf

Now it is time to write yourMakefile.am for zardoz. Sincezardoz is a user program, you want to install it where therest of the user programs go:bindir. Additionally,zardoz has some Texinfo documentation. Yourconfigure.acscript 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 yourMakefile.in and grab any auxiliary files you might need, andyou're done!

Previous:  Complete,Up:  Examples

4.2 Building true and false

Here is another, trickier example. It shows how to generate twoprograms (true and false) from the same source file(true.c). The difficult part is that each compilation oftrue.c requires differentcpp 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 willimplicitly assume that there is a source file namedtrue.c(see Default _SOURCES), anddefine rules to compile true.o and linktrue. The‘true.o: true.c’ rule supplied by the aboveMakefile.am,will override the Automake generated rule to buildtrue.o.

false_SOURCES is defined to be empty—that way no implicit valueis substituted. Because we have not listed the source offalse, we have to tell Automake how to link the program. This isthe purpose of thefalse_LDADD line. A false_DEPENDENCIESvariable, holding the dependencies of thefalse target will beautomatically generated by Automake from the content offalse_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 abogus dependency (to avoid problems with a parallelmake):

     true.o: true.c false.o
             $(COMPILE) -DEXIT_CODE=0 -c true.c
     
     false.o: true.c
             $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o

As it turns out, there is also a much easier way to do this same task. Some of the above technique is useful enough that we've kept theexample in the manual. However if you were to buildtrue andfalse in real life, you would probably use per-programcompilation flags, like so:

     bin_PROGRAMS = false true
     
     false_SOURCES = true.c
     false_CPPFLAGS = -DEXIT_CODE=1
     
     true_SOURCES = true.c
     true_CPPFLAGS = -DEXIT_CODE=0

In this case Automake will cause true.c to be compiled twice,with different flags. In this instance, the names of the object fileswould be chosen by automake; they would befalse-true.o andtrue-true.o. (The name of the object files rarely matters.)

Next:  ,Previous:  Examples,Up:  Top

5 Creating a Makefile.in

To create all theMakefile.ins for a package, run theautomake program in the top level directory, with noarguments.automake will automatically find eachappropriateMakefile.am (by scanning configure.ac;seeconfigure) and generate the corresponding Makefile.in. Note thatautomake has a rather simplistic view of whatconstitutes a package; it assumes that a package has only oneconfigure.ac, at the top. If your package has multipleconfigure.acs, then you must run automake in eachdirectory holding aconfigure.ac. (Alternatively, you may relyon Autoconf'sautoreconf, which is able to recurse yourpackage tree and runautomake where appropriate.)

You can optionally give automake an argument;.am isappended to the argument and the result is used as the name of theinput file. This feature is generally only used to automaticallyrebuild an out-of-dateMakefile.in. Note thatautomake must always be run from the topmost directory of aproject, even if being used to regenerate theMakefile.in insome subdirectory. This is necessary becauseautomake mustscan configure.ac, and becauseautomake uses theknowledge that a Makefile.in is in a subdirectory to change itsbehavior in some cases.

Automake will run autoconf to scanconfigure.ac andits dependencies (i.e., aclocal.m4 and any included file),therefore autoconf must be in your PATH. If there isanAUTOCONF variable in your environment it will be usedinstead ofautoconf, this allows you to select a particularversion of Autoconf. By the way, don't misunderstand this paragraph:automake runsautoconf to scan yourconfigure.ac, this won't buildconfigure and you stillhave to run autoconf yourself for this purpose.

automake accepts the following options:

-a --add-missing
Automake requires certain common files to exist in certain situations;for instance, config.guess is required if configure.ac invokes AC_CANONICAL_HOST. Automake is distributed with several of thesefiles (see Auxiliary Programs); this option will cause the missingones to be automatically added to the package, whenever possible. Ingeneral if Automake tells you a file is missing, try using this option. By default Automake tries to make a symbolic link pointing to its owncopy of the missing file; this can be changed with --copy.

Many of the potentially-missing files are common scripts whoselocation may be specified via theAC_CONFIG_AUX_DIR macro. Therefore, AC_CONFIG_AUX_DIR's setting affects whether afile is considered missing, and where the missing file is added(seeOptional).

In some strictness modes, additional files are installed, see Gnitsfor more information.

--libdir= dir
Look for Automake data files in directory dir instead of in theinstallation directory. This is typically used for debugging.
-c
--copy
When used with --add-missing, causes installed files to becopied. The default is to make a symbolic link.
--cygnus
Causes the generated Makefile.ins to follow Cygnus rules, insteadof GNU or Gnits rules. For more information, see Cygnus.
-f
--force-missing
When used with --add-missing, causes standard files to be reinstalledeven if they already exist in the source tree. This involves removingthe file from the source tree before creating the new symlink (or, with --copy, copying the new file).
--foreign
Set the global strictness to foreign. For more information, see Strictness.
--gnits
Set the global strictness to gnits. For more information, see Gnits.
--gnu
Set the global strictness to gnu. For more information, see 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 Makefiles; see Dependencies.
--include-deps
This enables the dependency tracking feature. This feature is enabledby default. This option is provided for historical reasons only andprobably should not be used.
--no-force
Ordinarily automake creates all Makefile.ins mentioned in configure.ac. This option causes it to only update those Makefile.ins that are out of date with respect to one of theirdependents.
-o dir --output-dir= dir
Put the generated Makefile.in in the directory dir. Ordinarily each Makefile.in is created in the directory of thecorresponding Makefile.am. This option is deprecated and will beremoved in a future release.
-v --verbose
Cause Automake to print information about which files are being read orcreated.
--version
Print the version number of Automake and exit.
-W CATEGORY --warnings= category
Output warnings falling in category. category can beone of:
gnu
warnings related to the GNU Coding Standards(see Top).
obsolete
obsolete features or constructions
override
user redefinitions of Automake rules or variables
portability
portability issues (e.g., use of make features that areknown to be not portable)
extra-portability
extra portability issues related to obscure tools. One example of sucha tool is the Microsoft lib archiver.
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-’. Forinstance,-Wno-syntax will hide the warnings about unusedvariables.

The categories output by default are ‘syntax’ and‘unsupported’. Additionally, ‘gnu’ and ‘portability’are enabled in --gnu and --gnits strictness. On the other hand, thesilent-rules options (see Options)turns off portability warnings about recursive variable expansions.

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

The environment variable WARNINGS can contain a comma separatedlist of categories to enable. It will be taken into account before thecommand-line switches, this way-Wnone will also ignore anywarning category enabled byWARNINGS. This variable is also usedby other tools likeautoconf; unknown categories are ignoredfor this reason.

If the environment variable AUTOMAKE_JOBS contains a positivenumber, it is taken as the maximum number of Perl threads to use inautomake for generating multiple Makefile.in filesconcurrently. This is an experimental feature.

Next:  ,Previous:  Invoking Automake,Up:  Top

6 Scanning configure.ac, usingaclocal

Automake scans the package's configure.ac to determine certaininformation about the package. Someautoconf macros are requiredand some variables must be defined inconfigure.ac. Automakewill also use information fromconfigure.ac to further tailor itsoutput.

Automake also supplies some Autoconf macros to make the maintenanceeasier. These macros can automatically be put into youraclocal.m4 using theaclocal program.

Next:  ,Up:  configure

6.1 Configuration requirements

The one real requirement of Automake is that yourconfigure.accall AM_INIT_AUTOMAKE. This macro does several things that arerequired for proper Automake operation (seeMacros).

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

AC_CONFIG_FILES AC_OUTPUT
These two macros are usually invoked as follows near the end of configure.ac. 
          ...
          AC_CONFIG_FILES([
            Makefile
            doc/Makefile
            src/Makefile
            src/lib/Makefile
            ...
          ])
          AC_OUTPUT

Automake uses these to determine which files to create (see Creating Output Files). A listed fileis considered to be an Automake generatedMakefile if thereexists a file with the same name and the.am extension appended. Typically, ‘AC_CONFIG_FILES([foo/Makefile])’ will cause Automake togeneratefoo/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 forwhich a .am file exists. If no such file exists the outputfile is not considered to be generated by Automake.

Files created by AC_CONFIG_FILES, be they AutomakeMakefiles or not, are all removed by ‘make distclean’. Their inputs are automatically distributed, unless theyare the output of prior AC_CONFIG_FILES commands. Finally, rebuild rules are generated in the AutomakeMakefileexisting in the subdirectory of the output file, if there is one, orin the top-levelMakefile otherwise.

The above machinery (cleaning, distributing, and rebuilding) worksfine if the AC_CONFIG_FILES specifications contain onlyliterals. If part of the specification uses shell variables,automake will not be able to fulfill this setup, and you willhave to complete the missing bits by hand. For instance, on 

          file=input
          ...
          AC_CONFIG_FILES([output:$file],, [file=$file])

automake will output rules to cleanoutput, andrebuild it. However the rebuild rule will not depend oninput,and this file will not be distributed either. (You must add‘EXTRA_DIST = input’ to yourMakefile.am if input is asource 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 becleaned automatically (add ‘DISTCLEANFILES = output out’yourself), and no rebuild rule will be output.

Obviously automake cannot guess what value ‘$file’ isgoing to hold later whenconfigure is run, and it cannot usethe shell variable ‘$file’ in aMakefile. However, if youmake reference to ‘$file’ as ‘${file}’ (i.e., in a waythat is compatible withmake's syntax) and furthermore useAC_SUBST to ensure that ‘${file}’ is meaningful in aMakefile, thenautomake will be able to use‘${file}’ to generate all these rules. For instance, here ishow the Automake package itself generates versioned scripts for itstest 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 atmake-time.

Note that you should not use shell variables to declareMakefile files for whichautomake must createMakefile.in. EvenAC_SUBST does not help here, becauseautomake needs to know the file name when it runs in orderto check whetherMakefile.am exists. (In the very hairy casethat your setup requires such use of variables, you will have to tellAutomake whichMakefile.ins to generate on the command-line.)

It is possible to let automake emit conditional rules forAC_CONFIG_FILES with the help ofAM_COND_IF(see Optional).

To summarize:

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

Next:  ,Previous:  Requirements,Up:  configure

6.2 Other things Automake recognizes

Every time Automake is run it calls Autoconf to traceconfigure.ac. This way it can recognize the use of certainmacros 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.subexist. Also, the Makefile variables build_triplet, host_triplet and target_triplet are introduced. See Getting the Canonical System Type.
AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as install-sh, in the directory named in this macro invocation. (The full list of scripts is: ar-lib, config.guess, config.sub, depcomp, 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 scriptswill only be sought if the generated Makefile.in requires them.

If AC_CONFIG_AUX_DIR is not given, the scripts are looked for intheir standard locations. Formdate-sh,texinfo.tex, andylwrap, the standard location is thesource directory corresponding to the currentMakefile.am. Forthe rest, the standard location is the first one of., ..,or../.. (relative to the top source directory) that provides anyone of the helper scripts. SeeFinding `configure' Input.

Required files from AC_CONFIG_AUX_DIR are automaticallydistributed, even if there is noMakefile.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 thismacro.
AC_CONFIG_HEADERS
Automake will generate rules to rebuild these headers. Older versionsof Automake required the use of AM_CONFIG_HEADER(see Macros); this is no longer the case.

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

AC_CONFIG_LINKS
Automake will generate rules to remove configure generatedlinks on ‘ make distclean’ and to distribute named source files aspart of ‘ make dist’.

As for AC_CONFIG_FILES (see Requirements), parts of thespecification using shell variables will be ignored as far as cleaningand distributing is concerned. (There are no rebuild rules for links.)

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

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

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

AC_PROG_RANLIB
This is required if any libraries are built in the package. See Particular Program Checks.
AC_PROG_CXX
This is required if any C++ source is included. See Particular Program Checks.
AC_PROG_OBJC
This is required if any Objective C source is included. See Particular Program Checks.
AC_PROG_F77
This is required if any Fortran 77 source is included. This macro isdistributed with Autoconf version 2.13 and later. See Particular Program Checks.
AC_F77_LIBRARY_LDFLAGS
This is required for programs and shared libraries that are a mixture oflanguages that include Fortran 77 (see Mixing Fortran 77 With C and C++). See Autoconf macros supplied with Automake.
AC_FC_SRCEXT
Automake will add the flags computed by AC_FC_SRCEXT to compilationof files with the respective source extension (see Fortran Compiler Characteristics).
AC_PROG_FC
This is required if any Fortran 90/95 source is included. This macro isdistributed with Autoconf version 2.58 and later. See Particular Program Checks.
AC_PROG_LIBTOOL
Automake will turn on processing for libtool (see Introduction).
AC_PROG_YACC
If a Yacc source file is seen, then you must either use this macro ordefine the variable YACC in configure.ac. The former ispreferred (see Particular Program Checks).
AC_PROG_LEX
If a Lex source file is seen, then this macro must be used. See Particular Program Checks.
AC_REQUIRE_AUX_FILE
For each AC_REQUIRE_AUX_FILE([ file ]), automake will ensure that file exists in theaux directory, and will complain otherwise. Itwill also automatically distribute the file. This macro should beused by third-party Autoconf macros that require some supportingfiles in the aux directory specified with AC_CONFIG_AUX_DIRabove. See Finding configure Input.
AC_SUBST
The first argument is automatically defined as a variable in eachgenerated Makefile.in, unless AM_SUBST_NOTMAKE is alsoused for this variable. See Setting Output Variables.

For every substituted variable var, automake will adda linevar = value to each Makefile.in file. Many Autoconf macros invokeAC_SUBST to set output variablesthis way, e.g., AC_PATH_XTRA definesX_CFLAGS andX_LIBS. Thus, you can access these variables as$(X_CFLAGS) and$(X_LIBS) in any Makefile.amifAC_PATH_XTRA is called.

AM_C_PROTOTYPES
This is required when using the deprecated de-ANSI-fication feature;see ANSI. It will be removed in the next major Automakerelease.
AM_CONDITIONAL
This introduces an Automake conditional (see Conditionals).
AM_COND_IF
This macro allows automake to detect subsequent access within configure.ac to a conditional previously introduced with AM_CONDITIONAL, thus enabling conditional AC_CONFIG_FILES(see Usage of Conditionals).
AM_GNU_GETTEXT
This macro is required for packages that use GNU gettext(see gettext). It is distributed with gettext. If Automake seesthis macro it ensures that the package meets some of gettext'srequirements.
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 argumentof ‘ external’.
AM_MAINTAINER_MODE( [ default-mode ] )
This macro adds an --enable-maintainer-mode option to configure. If this is used, automake will cause“maintainer-only” rules to be turned off by default in thegenerated Makefile.ins, unless default-mode is‘ enable’. This macro defines the MAINTAINER_MODEconditional, which you can use in your own Makefile.am. See maintainer-mode.
AM_SUBST_NOTMAKE( var )
Prevent Automake from defining a variable var, even if it issubstituted by config.status. Normally, Automake defines a make variable for each configure substitution,i.e., for each AC_SUBST([ var ]). This macro prevents thatdefinition from Automake. If AC_SUBST has not been calledfor this variable, then AM_SUBST_NOTMAKE has no effects. Preventing variable definitions may be useful for substitution ofmulti-line values, where var = @ value @ might yieldunintended results.
m4_include
Files included by configure.ac using this macro will bedetected by Automake and automatically distributed. They will alsoappear as dependencies in Makefile rules.

m4_include is seldom used by configure.ac authors, butcan appear inaclocal.m4 when aclocal detects thatsome required macros come from files local to your package (as opposedto macros installed in a system-wide directory, seeInvoking aclocal).

Next:  ,Previous:  Optional,Up:  configure

6.3 Auto-generating aclocal.m4

Automake includes a number of Autoconf macros that can be used inyour package (seeMacros); some of them are actually required byAutomake in certain situations. These macros must be defined in youraclocal.m4; otherwise they will not be seen byautoconf.

The aclocal program will automatically generateaclocal.m4 files based on the contents ofconfigure.ac. This provides a convenient way to get Automake-provided macros,without having to search around. Theaclocal mechanismallows other packages to supply their own macros (seeExtending aclocal). You can also use it to maintain your own set of custommacros (seeLocal Macros).

At startup, aclocal scans all the .m4 files it canfind, looking for macro definitions (seeMacro Search Path). Thenit scans configure.ac. Any mention of one of the macros foundin the first step causes that macro, and any macros it in turnrequires, to be put intoaclocal.m4.

Putting the file that contains the macro definition intoaclocal.m4 is usually done by copying the entire text of thisfile, including unused macro definitions as well as both ‘#’ and‘dnl’ comments. If you want to make a comment that will becompletely ignored byaclocal, use ‘##’ as the commentleader.

When a file selected by aclocal is located in a subdirectoryspecified as a relative search path withaclocal's -Iargument,aclocal assumes the file belongs to the packageand usesm4_include instead of copying it intoaclocal.m4. This makes the package smaller, eases dependencytracking, and cause the file to be distributed automatically. (SeeLocal Macros, for an example.) Any macro that is found in asystem-wide directory, or via an absolute search path will be copied. So use ‘-I `pwd`/reldir’ instead of ‘-I reldir’ wheneversome relative directory should be considered outside the package.

The contents of acinclude.m4, if this file exists, are alsoautomatically included inaclocal.m4. We recommend againstusing acinclude.m4 in new packages (see Local Macros).

While computingaclocal.m4, aclocal runsautom4te (seeUsing Autom4te) in order to trace the macros that arereally used, and omit fromaclocal.m4 all macros that arementioned but otherwise unexpanded (this can happen when a macro iscalled conditionally).autom4te is expected to be in thePATH, just asautoconf. Its location can beoverridden using theAUTOM4TE environment variable.

Next:  ,Up:  Invoking aclocal

6.3.1 aclocal Options

aclocal accepts the following options:

--automake-acdir= dir
Look for the automake-provided macro files in dir instead ofin the installation directory. This is typically used for debugging.
--system-acdir= dir
Look for the system-wide third-party macro files (and the special dirlist file) in dir instead of in the installationdirectory. This is typically used for debugging.
--acdir= dir
Deprecated shorthand for “ --automake-acdir=dir--system-acdir=dir”. Will be removed in future aclocal versions.
--diff[= command ]
Run command on M4 file that would be installed or overwrittenby --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 M4files 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 directoryspecified with ‘ -Idir’ instead of copying them in theoutput file.

When this option is used, and only when this option is used,aclocal will also honor ‘#serialnumber’ linesthat appear in macros: an M4 file is ignored if there exists anotherM4 file with the same basename and a greater serial number in thesearch path (seeSerials).

--force
Always overwrite the output file. The default is to overwrite the outputfile only when really needed, i.e., when its contents changes or if oneof its dependencies is younger.

This option forces the update of aclocal.m4 (or the filespecified with--output below) and only this file, it hasabsolutely 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 tofind third-party .m4 files. When this option is given, normalprocessing is suppressed. This option was used in the past bythird-party packages to determine where to install .m4 macrofiles, but this usage is today discouraged, since it causes‘ $(prefix)’ not to be thoroughly honoured (which violates theGNU Coding Standards), and a similar semantics can be better obtainedwith the ACLOCAL_PATH environment variable; see Extending aclocal.
--verbose
Print the names of the files it examines.
--version
Print the version number of Automake and exit.
-W CATEGORY
--warnings= category
Output warnings falling in category. category can beone 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 sameway as it is forautomake (see Invoking Automake).

Next:  ,Previous:  aclocal Options,Up:  Invoking aclocal

6.3.2 Macro Search Path

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

acdir-APIVERSION
This is where the .m4 macros distributed with Automake itselfare stored. APIVERSION depends on the Automake release used;for example, for Automake 1.11.x, APIVERSION = 1.11.
acdir
This directory is intended for third party .m4 files, and isconfigured when automake itself is built. This is @datadir@/aclocal/, which typicallyexpands to ${prefix}/share/aclocal/. To find the compiled-invalue of acdir, use the --print-ac-dir option(see aclocal Options).

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

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

The paths for the acdir and acdir-APIVERSION directories canbe changed respectively through aclocal options--system-acdirand --automake-acdir (seeaclocal Options). Note howeverthat these options are only intended for use by the internal Automaketest suite, or for debugging under highly unusual situations; they arenot ordinarily needed by end-users.

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

Modifying the Macro Search Path: ‘-Idir’

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

  1. /foo
  2. /bar
  3. acdir-APIVERSION
  4. acdir
Modifying the Macro Search Path: dirlist

There is a third mechanism for customizing the search path. If adirlist file exists inacdir, then that file is assumed tocontain a list of directory patterns, one per line.aclocalexpands these patterns to directory names, and adds them to the searchlistafter all other directories. dirlist entries mayuse shell wildcards such as ‘*’, ‘?’, or[...].

For example, supposeacdir/dirlist contains the following:

     /test1
     /test2
     /test3*

and that aclocal was called with the ‘-I /foo -I /bar’ options. Then, the search path would be

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

and all directories with path names starting with /test3.

If the --system-acdir=dir option is used, thenaclocal will search for thedirlist file indir; but remember the warnings above against the use of--system-acdir.

dirlist is useful in the following situation: suppose thatautomake version1.11.2 is installed with‘--prefix=/usr’ by the system vendor. Thus, the default searchdirectories are

  1. /usr/share/aclocal-1.11/
  2. /usr/share/aclocal/

However, suppose further that many packages have been manuallyinstalled on the system, with $prefix=/usr/local, as is typical. Inthat 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 toalways call ‘aclocal -I /usr/local/share/aclocal’. This isinconvenient. Withdirlist, one may create a file/usr/share/aclocal/dirlist containing only the single line

     /usr/local/share/aclocal

Now, the “default” search path on the affected system is

  1. /usr/share/aclocal-1.11/
  2. /usr/share/aclocal/
  3. /usr/local/share/aclocal/

without the need for -I options; -I options can be reservedfor project-specific needs (my-source-dir/m4/), rather thanusing it to work around local system-dependent tool installationdirectories.

Similarly, dirlist can be handy if you have installed a localcopy of Automake in your account and wantaclocal to look formacros installed at other places on the system.

Modifying the Macro Search Path: ACLOCAL_PATH

The fourth and last mechanism to customize the macro search path isalso the simplest. Any directory included in the colon-separatedenvironment variableACLOCAL_PATH is added to the search pathand takes precedence over system directories (including those found viadirlist), with the exception of the versioned directoryacdir-APIVERSION (see Macro Search Path). However, directoriespassed via-I will take precedence over directories inACLOCAL_PATH.

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

Conversely to dirlist, ACLOCAL_PATH is useful if you areusing a global copy of Automake and wantaclocal to look formacros somewhere under your home directory.

Planned future incompatibilities

The order in which the directories in the macro search path are currentlylooked up is confusing and/or suboptimal in various aspects, and isprobably going to be changed in the future Automake release. Inparticular, directories inACLOCAL_PATH and acdirmight end up taking precedence overacdir-APIVERSION, anddirectories in acdir/dirlist might end up taking precedenceoveracdir. This is a possible future incompatibility!

Next:  ,Previous:  Macro Search Path,Up:  Invoking aclocal

6.3.3 Writing your own aclocal macros

Theaclocal program doesn't have any built-in knowledge of anymacros, so it is easy to extend it with your own macros.

This can be used by libraries that want to supply their own Autoconfmacros for use by other programs. For instance, thegettextlibrary supplies a macro AM_GNU_GETTEXT that should be used byany package usinggettext. When the library is installed, itinstalls this macro so thataclocal will find it.

A macro file's name should end in .m4. Such files should beinstalled 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 onthe result of ‘aclocal --print-ac-dir’ (seeHard-Coded Install Paths, for arguments). It might also be helpful to suggest tothe user to add the$(datadir)/aclocal directory to hisACLOCAL_PATH variable (seeACLOCAL_PATH) so thataclocal will find the.m4 files installed by yourpackage automatically.

A file of macros should be a series of properly quotedAC_DEFUN's (seeMacro Definitions). The aclocal programs also understandsAC_REQUIRE (seePrerequisite 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 toAC_PREREQ should be done inside thedefined macro, not at the beginning of the file.

Starting with Automake 1.8,aclocal will warn about allunderquoted calls toAC_DEFUN. We realize this will annoy alot of people, because aclocal was not so strict in the pastand many third party macros are underquoted; and we have to apologizefor this temporary inconvenience. The reason we have to be stricteris that a future implementation of aclocal (seeFuture of aclocal) will have to temporarily include all these third party.m4 files, maybe several times, including even files that arenot actually needed. Doing so should alleviate many problems of thecurrent implementation, however it requires a stricter style from themacro 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 thatAutoconf 2.57 will not be required ifAX_FOOBAR is not actuallyused. Most importantly, quoting the first argument ofAC_DEFUNallows the macro to be redefined or included twice (otherwise thisfirst argument would be expanded during the second definition). Forconsistency we like to quote even arguments such as2.57 thatdo not require it.

If you have been directed here by the aclocal diagnostic butare not the maintainer of the implicated macro, you will want tocontact the maintainer of that macro. Please make sure you have thelatest version of the macro and that the problem hasn't already beenreported before doing so: people tend to work faster when they aren'tflooded by mails.

Another situation where aclocal is commonly used is tomanage macros that are used locally by the package,Local Macros.

Next:  ,Previous:  Extending aclocal,Up:  Invoking aclocal

6.3.4 Handling Local Macros

Feature tests offered by Autoconf do not cover all needs. Peopleoften have to supplement existing tests with their own macros, orwith third-party macros.

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

The first possibility (the historical practice) is to list all yourmacros in acinclude.m4. This file will be included inaclocal.m4 when you runaclocal, and its macro(s) willhenceforth be visible toautoconf. However if it containsnumerous macros, it will rapidly become difficult to maintain, and itwill be almost impossible to share macros between packages.

The second possibility, which we do recommend, is to write each macroin its own file and gather all these files in a directory. Thisdirectory is usually calledm4/. To build aclocal.m4,one should therefore instructaclocal to scan m4/. From the command line, this is done with ‘aclocal -I m4’. Thetop-levelMakefile.am should also be updated to define

     ACLOCAL_AMFLAGS = -I m4

ACLOCAL_AMFLAGS contains options to pass to aclocalwhenaclocal.m4 is to be rebuilt by make. This line isalso used byautoreconf (see Using autoreconf to Update configure Scripts) to runaclocal with suitableoptions, or by autopoint (see Invoking the autopoint Program)and gettextize (see Invoking the gettextize Program) to locatethe place where Gettext's macros should be installed. So even if youdo not really care about the rebuild rules, you should defineACLOCAL_AMFLAGS.

When ‘aclocal -I m4’ is run, it will build anaclocal.m4that m4_includes any file fromm4/ that defines arequired macro. Macros not found locally will still be searched insystem-wide directories, as explained inMacro Search Path.

Custom macros should be distributed for the same reason thatconfigure.ac is: so that other people have all the sources ofyour package if they want to work on it. Actually, this distributionhappens automatically because all m4_included files aredistributed.

However there is no consensus on the distribution of third-partymacros that your package may use. Many libraries install their ownmacro in the system-wideaclocal directory (see Extending aclocal). For instance, Guile ships with a file calledguile.m4 that contains the macroGUILE_FLAGS that canbe used to define setup compiler and linker flags appropriate forusing Guile. UsingGUILE_FLAGS in configure.ac willcauseaclocal to copy guile.m4 intoaclocal.m4, but asguile.m4 is not part of the project,it will not be distributed. Technically, that means a user whoneeds to rebuildaclocal.m4 will have to install Guile first. This is probably OK, if Guile already is a requirement to build thepackage. However, if Guile is only an optional feature, or if yourpackage might run on architectures where Guile cannot be installed,this requirement will hinder development. An easy solution is to copysuch third-party macros in your localm4/ directory so they getdistributed.

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

     ACLOCAL_AMFLAGS = -I m4 --install

With this setup, system-wide macros will be copied to m4/the first time you runautoreconf. Then the locallyinstalled macros will have precedence over the system-wide installedmacros each timeaclocal is run again.

One reason why you should keep --install in the flags evenafter the first run is that when you later editconfigure.acand depend on a new macro, this macro will be installed in yourm4/ automatically. Another one is that serial numbers(seeSerials) can be used to update the macros in your source treeautomatically when new system-wide versions are installed. A serialnumber should be a single line of the form

     #serial nnn

where nnn contains only digits and dots. It should appear inthe M4 file before any macro definition. It is a good practice tomaintain a serial number for each macro you distribute, even if you donot use the--install option of aclocal: this allowsother people to use it.

Next:  ,Previous:  Local Macros,Up:  Invoking aclocal

6.3.5 Serial Numbers

Because third-party macros defined in *.m4 files are naturallyshared between multiple projects, some people like to version them. This makes it easier to tell which of two M4 files is newer. Since atleast 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 anddots. Usually people use a single integer, and they increment it eachtime they change the macro (hence the name of “serial”). Such aline 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 byaclocal andautoconf, like any genuine comment. However when usingaclocal's --install feature, theseserial numbers will modify the wayaclocal selects themacros to install in the package: if two files with the same basenameexist in your search path, and if at least one of them uses a‘#serial’ line,aclocal will ignore the file that hasthe older ‘#serial’ line (or the file that has none).

Note that a serial number applies to a whole M4 file, not to any macroit contains. A file can contains multiple macros, but only oneserial.

Here is a use case that illustrates the use of --install andits interaction with serial numbers. Let's assume we maintain apackage called MyPackage, theconfigure.ac of which requires athird-party macroAX_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 asexplained inLocal Macros, and has

     ACLOCAL_AMFLAGS = -I m4 --install

in its top-level Makefile.am.

Initially the m4/ directory is empty. The first time we runautoreconf, it will fetch the options to pass toaclocal inMakefile.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 definesAX_THIRD_PARTYwith serial 1.

Because /usr/share/aclocal/thirdparty.m4 is a system-wide macroandaclocal was given the --install option, it willcopy this file inm4/thirdparty.m4, and output anaclocal.m4 that contains ‘m4_include([m4/thirdparty.m4])’.

The next time ‘aclocal -I m4 --install’ is run (either viaautoreconf, by hand, or from theMakefile rebuildrules) something different happens.aclocal notices that

  • configure.ac uses AX_THIRD_PARTY
  • m4/thirdparty.m4 defines AX_THIRD_PARTYwith serial 1.
  • /usr/share/aclocal/thirdparty.m4 definesAX_THIRD_PARTYwith serial 1.

Because both files have the same serial number, aclocal usesthe first it found in its search path order (seeMacro Search Path). aclocal therefore ignores/usr/share/aclocal/thirdparty.m4 and outputs anaclocal.m4 that contains ‘m4_include([m4/thirdparty.m4])’.

Local directories specified with -I are always searched beforesystem-wide directories, so a local file will always be preferred tothe system-wide file in case of equal serial numbers.

Now suppose the system-wide third-party macro is changed. This canhappen if the package installing this macro is updated. Let's supposethe 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_PARTYwith serial 1.
  • /usr/share/aclocal/thirdparty.m4 definesAX_THIRD_PARTYwith serial 2.

When aclocal sees a greater serial number, it immediatelyforgets anything it knows from files that have the same basename and asmaller serial number. So after it has found/usr/share/aclocal/thirdparty.m4 with serial 2,aclocal will proceed as if it had never seenm4/thirdparty.m4. This brings us back to a situation similarto that at the beginning of our example, where no local file definedthe macro. aclocal will install the new version of themacro inm4/thirdparty.m4, in this case overriding the oldversion. MyPackage just had its macro updated as a side effect ofrunningaclocal.

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 ofaclocal hasabsolutely no effect on the files installed by--install. Forinstance, if you have modified your local macros, do not expect--install --force to replace the local macros by theirsystem-wide versions. If you want to do so, simply erase the localmacros you want to revert, and run ‘aclocal -I m4 --install’.

Previous:  Serials,Up:  Invoking aclocal

6.3.6 The Future of aclocal

aclocal is expected to disappear. This feature reallyshould not be offered by Automake. Automake should focus ongeneratingMakefiles; dealing with M4 macros really isAutoconf's job. The fact that some people install Automake just to useaclocal, but do not useautomake otherwise is anindication of how that feature is misplaced.

The new implementation will probably be done slightly differently. For instance, it could enforce them4/-style layout discussed inLocal Macros.

We have no idea when and how this will happen. This has beendiscussed several times in the past, but someone still has to committo that non-trivial task.

From the user point of view, aclocal's removal might turnout to be painful. There is a simple precaution that you may take tomake that switch more seamless: never callaclocal yourself. Keep this guy under the exclusive control ofautoreconf andAutomake's rebuild rules. Hopefully you won't need to worry aboutthings breaking, whenaclocal disappears, because everythingwill have been taken care of. If otherwise you used to callaclocal directly yourself or from some script, you willquickly notice the change.

Many packages come with a script called bootstrap.sh orautogen.sh, that will just callaclocal,libtoolize,gettextize or autopoint,autoconf,autoheader, and automake inthe right order. Actually this is precisely whatautoreconfcan do for you. If your package has such abootstrap.sh orautogen.sh script, consider usingautoreconf. Thatshould simplify its logic a lot (less things to maintain, yum!), it'seven likely you will not need the script anymore, and more to the pointyou will not callaclocal directly anymore.

For the time being, third-party packages should continue to installpublic macros into/usr/share/aclocal/. If aclocalis replaced by another tool it might make sense to rename thedirectory, but supporting/usr/share/aclocal/ for backwardcompatibility should be really easy provided all macros are properlywritten (seeExtending aclocal).

Previous:  Invoking aclocal,Up:  configure

6.4 Autoconf macros supplied with Automake

Automake ships with several Autoconf macros that you can use from yourconfigure.ac. When you use one of them it will be included byaclocal inaclocal.m4.

Next:  ,Up:  Macros

6.4.1 Public Macros
AM_ENABLE_MULTILIB
This is used when a “multilib” library is being built. The firstoptional argument is the name of the Makefile being generated; itdefaults to ‘ Makefile’. The second optional argument is used to findthe top source directory; it defaults to the empty string (generallythis should not be used unless you are familiar with the internals). See Multilibs.
AM_INIT_AUTOMAKE([OPTIONS]) AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
Runs many macros required for proper operation of the generated Makefiles.

This macro has two forms, the first of which is preferred. In this form,AM_INIT_AUTOMAKE is called with asingle argument: a space-separated list of Automake options that shouldbe applied to everyMakefile.am in the tree. The effect is as ifeach option were listed inAUTOMAKE_OPTIONS (see Options).

The second, deprecated, form of AM_INIT_AUTOMAKE has two requiredarguments: the package and the version number. This form isobsolete because thepackage and version can be obtainedfrom Autoconf's AC_INIT macro (which itself has an old and a newform).

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 earlierversion of Automake, it is not always correct to simply move thepackage and version arguments fromAM_INIT_AUTOMAKE directly toAC_INIT, as in the example above. The first argument toAC_INIT should be the name of your package (e.g., ‘GNUAutomake’), not the tarball name (e.g., ‘automake’) that you usedto pass to AM_INIT_AUTOMAKE. Autoconf tries to derive atarball name from the package name, which should work for most but notall package names. (If it doesn't work for yours, you can use thefour-argument form ofAC_INIT to provide the tarball nameexplicitly).

By default this macroAC_DEFINE's PACKAGE andVERSION. This can be avoided by passing theno-defineoption, as in: 

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

or by passing a third non-empty argument to the obsolete form.

AM_PATH_LISPDIR
Searches for the program emacs, and, if found, sets theoutput variable lispdir to the full path to Emacs' site-lispdirectory.

Note that this test assumes the emacs found to be a versionthat supports Emacs Lisp (such as GNU Emacs or XEmacs). Otheremacsen can cause this test to hang (some, like old versions ofMicroEmacs, start up in interactive mode, requiring C-x C-c toexit, which is hardly obvious for a non-emacs user). In most cases,however, you should be able to useC-c to kill the test. Inorder to avoid problems, you can set EMACS to “no” in theenvironment, or use the--with-lispdir option toconfigure to explicitly set the correct path (if you're sureyou have anemacs that supports Emacs Lisp).

AM_PROG_AR( [ act-if-fail ] )
You must use this macro when you use the archiver in your project, ifyou want support for unusual archivers such as Microsoft lib. The content of the optional argument is executed if the archiverinterface is not recognized; the default action is to abort configurewith an error message.
AM_PROG_AS
Use this macro when you have assembly code in your project. This willchoose 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 inthe manner required by Automake. You must use this instead of AC_PROG_CC_C_O when you need this functionality, that is, whenusing per-target flags or subdir-objects with C sources.
AM_PROG_LEX
Like AC_PROG_LEX (see Particular Program Checks), but uses the missing script on systems that do not have lex. HP-UX 10 is one such system.
AM_PROG_GCJ
This macro finds the gcj program or causes an error. It sets GCJ and GCJFLAGS. gcj is the Java front-end to theGNU Compiler Collection.
AM_PROG_UPC([ compiler-search-list ])
Find a compiler for Unified Parallel C and define the UPCvariable. The default compiler-search-list is ‘ upcc upc’. This macro will abort configure if no Unified Parallel Ccompiler is found.
AM_SILENT_RULES
Enable the machinery for less verbose build output (see Options).
AM_WITH_DMALLOC
Add support for the Dmalloc package. Ifthe user runs configure with --with-dmalloc, thendefine WITH_DMALLOC and add -ldmalloc to LIBS.
AM_WITH_REGEX
Adds --with-regex to the configure command line. Ifspecified (the default), then the ‘ regex’ regular expressionlibrary is used, regex.o is put into LIBOBJS, and WITH_REGEX is defined. If --without-regex is given, thenthe rx regular expression library is used, and rx.o is putinto LIBOBJS.

Next:  ,Previous:  Public Macros,Up:  Macros

6.4.2 Obsolete Macros

Although using some of the following macros was required in pastreleases, you should not use any of them in new code. Runningautoupdate should adjust your configure.acautomatically (seeUsing autoupdate to Modernizeconfigure.ac).

AM_C_PROTOTYPES
Check to see if function prototypes are understood by the compiler. Ifso, define ‘ PROTOTYPES’ and set the output variables U and ANSI2KNR to the empty string. Otherwise, set U to‘ _’ and ANSI2KNR to ‘ ./ansi2knr’. Automake used thesevalues to implement the deprecated de-ANSI-fication feature; however,support for that feature will be removed in the next major Automakerelease, and then these macros and variables will go away as well.
AM_CONFIG_HEADER
Automake will generate rules to automatically regenerate the configheader. This obsolete macro is a synonym of AC_CONFIG_HEADERStoday (see Optional).
AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
If the use of TIOCGWINSZ requires <sys/ioctl.h>, thendefine GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can befound in <termios.h>. This macro is obsolete, you shoulduse Autoconf's AC_HEADER_TIOCGWINSZ instead.
AM_PROG_MKDIR_P
From Automake 1.8 to 1.9.6 this macro used to define the outputvariable mkdir_p to one of mkdir -p, install-sh-d, or mkinstalldirs.

Nowadays Autoconf provides a similar functionality withAC_PROG_MKDIR_P (seeParticular Program Checks), however this definesthe output variableMKDIR_P instead. ThereforeAM_PROG_MKDIR_P has been rewritten as a thin wrapper aroundAC_PROG_MKDIR_P to definemkdir_p to the same value asMKDIR_P for backward compatibility.

If you are using Automake, there is normally no reason to call thismacro, becauseAM_INIT_AUTOMAKE already does so. However, makesure that the custom rules in yourMakefiles use$(MKDIR_P) and not$(mkdir_p). Even if both variablesstill work, the latter should be considered obsolete.

If you are not using Automake, please call AC_PROG_MKDIR_Pinstead ofAM_PROG_MKDIR_P.

AM_SYS_POSIX_TERMIOS
Check to see if POSIX termios headers and functions are available on thesystem. 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.

Previous:  Obsolete Macros,Up:  Macros

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 notrely on them, as they might be changed in a future version. Considerthem 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 dependencytracking scheme. They are called automatically by Automake whenrequired, 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 whenneeded; 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 tostrip a program at installation time. This macro is automaticallyincluded when required.
AM_SANITY_CHECK
This checks to make sure that a file created in the build directory isnewer than a file in the source directory. This can fail on systemswhere the clock is set incorrectly. This macro is automatically runfrom AM_INIT_AUTOMAKE.

Next:  ,Previous:  configure,Up:  Top

7 Directories

For simple projects that distribute all files in the same directoryit is enough to have a singleMakefile.am that buildseverything in place.

In larger projects it is common to organize files in differentdirectories, in a tree. For instance one directory per program, perlibrary or per module. The traditional approach is to build thesesubdirectories recursively: each directory contains itsMakefile(generated from Makefile.am), and whenmake is runfrom the top level directory it enters each subdirectory in turn tobuild its contents.

Next:  ,Up:  Directories

7.1 Recursing subdirectories

In packages with subdirectories, the top levelMakefile.am musttell Automake which subdirectories are to be built. This is done viatheSUBDIRS variable. The SUBDIRS variable holds a list of subdirectories in whichbuilding of various sorts can occur. The rules for many targets(e.g.,all) in the generated Makefile will run commandsboth locally and in all specified subdirectories. Note that thedirectories listed inSUBDIRS are not required to containMakefile.ams; onlyMakefiles (after configuration). This allows inclusion of libraries from packages that do not useAutomake (such asgettext; see also Third-Party Makefiles).

In packages that use subdirectories, the top-level Makefile.am isoften very short. For instance, here is theMakefile.am from theGNU 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 valueof theMAKE variable. It passes the value of the variableAM_MAKEFLAGS to themake invocation; this can be set inMakefile.am if there are flags you must always pass tomake.The directories mentioned inSUBDIRS are usually directchildren of the current directory, each subdirectory containing itsownMakefile.am with a SUBDIRS pointing to deepersubdirectories. Automake can be used to construct packages ofarbitrary depth this way.

By default, Automake generates Makefiles that work depth-firstin postfix order: the subdirectories are built before the currentdirectory. However, it is possible to change this ordering. You cando this by putting ‘.’ into SUBDIRS. For instance,putting ‘.’ first will cause a prefix ordering ofdirectories.

Using

     SUBDIRS = lib src . test

will cause lib/ to be built beforesrc/, then thecurrent directory will be built, finally thetest/ directorywill be built. It is customary to arrange test directories to bebuilt after everything else since they are meant to test what hasbeen constructed.

All clean rules are run in reverse order of build rules.

Next:  ,Previous:  Subdirectories,Up:  Directories

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 ofthe entire package.

To illustrate how this works, let's assume we have two directoriessrc/ andopt/. src/ should always be built, but wewant to decide inconfigure whether opt/ will be builtor not. (For this example we will assume thatopt/ should bebuilt when the variable ‘$want_opt’ was set to ‘yes’.)

Running make should thus recurse intosrc/ always, andthen maybe in opt/.

However ‘make dist’ should always recurse into bothsrc/and opt/. Becauseopt/ should be distributed even if itis not needed in the current configuration. This meansopt/Makefile should be createdunconditionally.

There are two ways to setup a project like this. You can use Automakeconditionals (seeConditionals) or use Autoconf AC_SUBSTvariables (seeSetting Output Variables). Using Automakeconditionals is the preferred solution. Before we illustrate thesetwo possibilities, let's introduceDIST_SUBDIRS.

Next:  ,Up:  Conditional Subdirectories

7.2.1 SUBDIRS vs. DIST_SUBDIRS

Automake considers two sets of directories, defined by the variablesSUBDIRS andDIST_SUBDIRS.

SUBDIRS contains the subdirectories of the current directorythat must be built (seeSubdirectories). It must be definedmanually; Automake will never guess a directory is to be built. As wewill see in the next two sections, it is possible to define itconditionally so that some directory will be omitted from the build.

DIST_SUBDIRS is used in rules that need to recurse in alldirectories, even those that have been conditionally left out of thebuild. Recall our example where we may not want to build subdirectoryopt/, but yet we want to distribute it? This is whereDIST_SUBDIRS comes into play: ‘opt’ may not appear inSUBDIRS, but it must appear inDIST_SUBDIRS.

Precisely, DIST_SUBDIRS is used by ‘makemaintainer-clean’, ‘make distclean’ and ‘make dist’. Allother recursive rules useSUBDIRS.

If SUBDIRS is defined conditionally using Automakeconditionals, Automake will defineDIST_SUBDIRS automaticallyfrom the possible values of SUBDIRS in all conditions.

If SUBDIRS contains AC_SUBST variables,DIST_SUBDIRS will not be defined correctly because Automakedoes not know the possible values of these variables. In this caseDIST_SUBDIRS needs to be defined manually.

Next:  ,Previous:  SUBDIRS vs DIST_SUBDIRS,Up:  Conditional Subdirectories

7.2.2 Subdirectories with AM_CONDITIONAL

configure should output the Makefile for each directoryand define a condition into whichopt/ 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.amas follows.

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

As you can see, running make will rightly recurse intosrc/ and maybeopt/.

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

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

Next:  ,Previous:  Subdirectories with AM_CONDITIONAL,Up:  Conditional Subdirectories

7.2.3 Subdirectories with AC_SUBST

Another possibility is to define MAYBE_OPT from./configure usingAC_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 possiblevalues of MAYBE_OPT are, it is necessary to defineDIST_SUBDIRS.

Previous:  Subdirectories with AC_SUBST,Up:  Conditional Subdirectories

7.2.4 Unconfigured Subdirectories

The semantics ofDIST_SUBDIRS are often misunderstood by someusers that try to configure and build subdirectoriesconditionally. Here by configuring we mean creating theMakefile (it might also involve running a nestedconfigure script: this is a costly operation that explainswhy people want to do it conditionally, but only theMakefileis 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 reasonis that we want ‘make dist’ to distribute even the directoriesthat are not being built (e.g., platform-dependent code), hencemake dist must recurse into the subdirectory, hence thisdirectory must be configured and appear inDIST_SUBDIRS.

Building packages that do not configure every subdirectory is a trickybusiness, and we do not recommend it to the novice as it is easy toproduce an incomplete tarball by mistake. We will not discuss thistopic in depth here, yet for the adventurous here are a few rules toremember.

  • SUBDIRS should always be a subset of DIST_SUBDIRS.

    It makes little sense to have a directory in SUBDIRS thatis not inDIST_SUBDIRS. Think of the former as a way to tellwhich directories listed in the latter should be built.

  • Any directory listed in DIST_SUBDIRS and SUBDIRSmust be configured.

    I.e., the Makefile must exists or the recursivemakerules will not be able to process the directory.

  • Any configured directory must be listed in DIST_SUBDIRS.

    So that the cleaning rules remove the generated Makefiles. It would be correct to seeDIST_SUBDIRS as a variable thatlists all the directories that have been configured.

In order to prevent recursion in some unconfigured directory youmust therefore ensure that this directory does not appear inDIST_SUBDIRS (andSUBDIRS). For instance, if you defineSUBDIRS conditionally usingAC_SUBST and do not defineDIST_SUBDIRS explicitly, it will be default to‘$(SUBDIRS)’; another possibility is to forceDIST_SUBDIRS= $(SUBDIRS).

Of course, directories that are omitted from DIST_SUBDIRS willnot be distributed unless you make other arrangements for this tohappen (for instance, always running ‘make dist’ in aconfiguration where all directories are known to appear inDIST_SUBDIRS; or writing a dist-hook target todistribute these directories).

In few packages, unconfigured directories are not even expected tobe distributed. Although these packages do not require theaforementioned extra arrangements, there is another pitfall. If thename of a directory appears in SUBDIRS or DIST_SUBDIRS,automake will make sure the directory exists. Consequentlyautomake cannot be run on such a distribution when onedirectory has been omitted. One way to avoid this check is to use theAC_SUBST method to declare conditional directories; sinceautomake does not know the values ofAC_SUBSTvariables it cannot ensure the corresponding directory exists.

Next:  ,Previous:  Conditional Subdirectories,Up:  Directories

7.3 An Alternative Approach to Subdirectories

If you've ever read Peter Miller's excellent paper,Recursive Make Considered Harmful, the preceding sections on the use ofsubdirectories will probably come as unwelcome advice. For those whohaven't read the paper, Miller's main thesis is that recursivemake invocations are both slow and error-prone.

Automake provides sufficient cross-directory support 3 to enable youto write a single Makefile.am for a complex multi-directorypackage.

By default an installable file specified in a subdirectory will have itsdirectory name stripped before installation. For instance, in thisexample, 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 pathstripping. 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 witheither ‘dist_’ or ‘nodist_’ (seeFine-grained Distribution Control). For instance:

     nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg

Finally, note that a variable using the ‘nobase_’ prefix canoften be replaced by several variables, one for each destinationdirectory (seeUniform). For instance, the last example could berewritten 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 destinationdirectory without changing the layout of the source tree.

Currently, ‘nobase_*_LTLIBRARIES’ are the only exception to thisrule, in that there is no particular installation order guarantee foran otherwise equivalent set of variables without ‘nobase_’ prefix.

Previous:  Alternative,Up:  Directories

7.4 Nesting Packages

In the GNU Build System, packages can be nested to arbitrary depth. This means that a package can embed other packages with their ownconfigure,Makefiles, etc.

These other packages should just appear as subdirectories of theirparent package. They must be listed inSUBDIRS like otherordinary directories. However the subpackage's Makefilesshould be output by its own configure script, not by theparent'sconfigure. This is achieved using theAC_CONFIG_SUBDIRS Autoconf macro (seeAC_CONFIG_SUBDIRS).

Here is an example package for an arm program that links witha hand library that is a nested package in subdirectoryhand/.

arm's configure.ac:

     AC_INIT([arm], [1.0])
     AC_CONFIG_AUX_DIR([.])
     AM_INIT_AUTOMAKE
     AC_PROG_CC
     AC_CONFIG_FILES([Makefile])
     # Call hand's ./configure script recursively.
     AC_CONFIG_SUBDIRS([hand])
     AC_OUTPUT

arm's Makefile.am:

     # Build the library in the hand subdirectory first.
     SUBDIRS = hand
     
     # Include hand's header when compiling this directory.
     AM_CPPFLAGS = -I$(srcdir)/hand
     
     bin_PROGRAMS = arm
     arm_SOURCES = arm.c
     # link with the hand library.
     arm_LDADD = hand/libhand.a

Now here is hand's hand/configure.ac:

     AC_INIT([hand], [1.2])
     AC_CONFIG_AUX_DIR([.])
     AM_INIT_AUTOMAKE
     AC_PROG_CC
     AM_PROG_AR
     AC_PROG_RANLIB
     AC_CONFIG_FILES([Makefile])
     AC_OUTPUT

and its hand/Makefile.am:

     lib_LIBRARIES = libhand.a
     libhand_a_SOURCES = hand.c

When ‘make dist’ is run from the top-level directory it willcreate an archivearm-1.0.tar.gz that contains the armcode as well as thehand subdirectory. This package can bebuilt and installed like any ordinary package, with the usual‘./configure && make && make install’ sequence (thehandsubpackage will be built and installed by the process).

When ‘make dist’ is run from the hand directory, it will create aself-containedhand-1.2.tar.gz archive. So although it appearsto be embedded in another package, it can still be used separately.

The purpose of the ‘AC_CONFIG_AUX_DIR([.])’ instruction is toforce Automake and Autoconf to search for auxiliary scripts in thecurrent directory. For instance, this means that there will be twocopies ofinstall-sh: one in the top-level of the armpackage, and another one in the hand/ subdirectory for thehand package.

The historical default is to search for these auxiliary scripts inthe parent directory and the grandparent directory. So if the‘AC_CONFIG_AUX_DIR([.])’ line was removed fromhand/configure.ac, that subpackage would share the auxiliaryscript of the arm package. This may looks like a gain in size(a few kilobytes), but it is actually a loss of modularity as thehand subpackage is no longer self-contained (‘make dist’in the subdirectory will not work anymore).

Packages that do not use Automake need more work to be integrated thisway. SeeThird-Party Makefiles.

Next:  ,Previous:  Directories,Up:  Top

8 Building Programs and Libraries

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

Next:  ,Up:  Programs

8.1 Building a program

In order to build a program, you need to tell Automake which sourcesare part of it, and which libraries it should be linked with.

This section also covers conditional compilation of sources orprograms. Most of the comments about these also apply to libraries(seeA Library) and libtool libraries (see A Shared Library).

Next:  ,Up:  A Program

8.1.1 Defining program sources

In a directory containing source that gets built into a program (asopposed to a library or a script), thePROGRAMS primary is used. Programs can be installed in bindir,sbindir,libexecdir, pkglibexecdir, or not at all(noinst_). They can also be built only for ‘make check’, inwhich case the prefix is ‘check_’.

For instance:

     bin_PROGRAMS = hello

In this simple case, the resulting Makefile.in will contain codeto generate a program namedhello.

Associated with each program are several assisting variables that arenamed after the program. These variables are all optional, and havereasonable defaults. Each variable, its use, and default is spelled outbelow; we use the “hello” example throughout.

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

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

This causes each mentioned .c file to be compiled into thecorresponding.o. Then all are linked to produce hello.

Ifhello_SOURCES is not specified, then it defaults to the singlefile hello.c (see Default _SOURCES).Multiple programs can be built in a single directory. Multiple programscan share a single source file, which must be listed in each_SOURCES definition.

Header files listed in a_SOURCES definition will be included inthe distribution but otherwise ignored. In case it isn't obvious, youshould not include the header file generated byconfigure in a_SOURCES variable; this file should not be distributed. Lex(.l) and Yacc (.y) files can also be listed; seeYacc and Lex.

Next:  ,Previous:  Program Sources,Up:  A Program

8.1.2 Linking the program

If you need to link against libraries that are not found byconfigure, you can useLDADD to do so. This variable isused to specify additional objects or libraries to link with; it isinappropriate for specifying specific linker flags, you should useAM_LDFLAGS for this purpose.Sometimes, multiple programs are built in one directory but do not sharethe same link-time requirements. In this case, you can use theprog_LDADD variable (where prog is the name of theprogram as it appears in some_PROGRAMS variable, and usuallywritten in lowercase) to override LDADD. If this variable existsfor a given program, then that program is not linked usingLDADD. For instance, in GNU cpio,pax, cpio and mt arelinked against the librarylibcpio.a. However, rmt isbuilt in the same directory, and has no such link requirement. Also,mt andrmt are only built on certain architectures. Hereis what cpio's src/Makefile.am looks like (abridged):

     bin_PROGRAMS = cpio pax $(MT)
     libexec_PROGRAMS = $(RMT)
     EXTRA_PROGRAMS = mt rmt
     
     LDADD = ../lib/libcpio.a $(INTLLIBS)
     rmt_LDADD =
     
     cpio_SOURCES = ...
     pax_SOURCES = ...
     mt_SOURCES = ...
     rmt_SOURCES = ...

prog_LDADD is inappropriate for passing program-specificlinker flags (except for-l, -L,-dlopen and-dlpreopen). So, use theprog_LDFLAGS variable forthis purpose.

It is also occasionally useful to have a program depend on some othertarget that is not actually part of that program. This can be doneusing the prog_DEPENDENCIES variable. Each programdepends on the contents of such a variable, but no furtherinterpretation is done.

Since these dependencies are associated to the link rule used tocreate the programs they should normally list files used by the linkcommand. That is*.$(OBJEXT), *.a, or*.lafiles. In rare cases you may need to add other kinds of files such aslinker scripts, butlisting a source file in_DEPENDENCIES is wrong. If some source file needs to be builtbefore all the components of a program are built, consider using theBUILT_SOURCES variable instead (seeSources).

If prog_DEPENDENCIES is not supplied, it is computed byAutomake. The automatically-assigned value is the contents ofprog_LDADD, with most configure substitutions,-l,-L,-dlopen and -dlpreopen options removed. Theconfigure substitutions that are left in are only ‘$(LIBOBJS)’ and‘$(ALLOCA)’; these are left because it is known that they will notcause an invalid value for prog_DEPENDENCIES to begenerated.

Conditional Sources shows a situation where_DEPENDENCIESmay be used.

We recommend that you avoid using-l options in LDADDor prog_LDADD when referring to libraries built by yourpackage. Instead, write the file name of the library explicitly as inthe abovecpio example. Use -l only to listthird-party libraries. If you follow this rule, the default value ofprog_DEPENDENCIES will list all your local libraries andomit the other ones.

Next:  ,Previous:  Linking,Up:  A Program

8.1.3 Conditional compilation of sources

You can't put a configure substitution (e.g., ‘@FOO@’ or‘$(FOO)’ whereFOO is defined via AC_SUBST) into a_SOURCES variable. The reason for this is a bit hard toexplain, but suffice to say that it simply won't work. Automake willgive an error if you try to do this.

Fortunately there are two other ways to achieve the same result. One isto use configure substitutions in_LDADD variables, the other isto use an Automake conditional.

Conditional Compilation using _LDADD Substitutions

Automake must know all the source files that could possibly go into aprogram, even if not all the files are built in every circumstance. Anyfiles that are only conditionally built should be listed in theappropriate EXTRA_ variable. For instance, ifhello-linux.c orhello-generic.c were conditionally includedinhello, the Makefile.am would contain:

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

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

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

In this case, the variable HELLO_SYSTEM should be replaced byeitherhello-linux.o or hello-generic.o, and added tobothhello_DEPENDENCIES and hello_LDADD in order to bebuilt and linked in.

Conditional Compilation using Automake Conditionals

An often simpler way to compile source files conditionally is to useAutomake conditionals. For instance, you could use thisMakefile.am construct to build the samehello example:

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

In this case, configure.ac should setup theLINUXconditional using AM_CONDITIONAL (see Conditionals).

When using conditionals like this you don't need to use theEXTRA_ variable, because Automake will examine the contents ofeach variable to construct the complete list of source files.

If your program uses a lot of files, you will probably prefer aconditional ‘+=’.

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

Previous:  Conditional Sources,Up:  A Program

8.1.4 Conditional compilation of programs

Sometimes it is useful to determine the programs that are to be builtat configure time. For instance, GNUcpio only buildsmt and rmt under special circumstances. The means toachieve conditional compilation of programs are the same you can useto compile source files conditionally: substitutions or conditionals.

Conditional Programs using configure Substitutions

In this case, you must notify Automake of all the programs that canpossibly be built, but at the same time cause the generatedMakefile.in to use the programs specified by configure. This is done by havingconfigure substitute values into each_PROGRAMS definition, while listing all optionally built programsinEXTRA_PROGRAMS.

     bin_PROGRAMS = cpio pax $(MT)
     libexec_PROGRAMS = $(RMT)
     EXTRA_PROGRAMS = mt rmt

As explained in EXEEXT, Automake will rewritebin_PROGRAMS,libexec_PROGRAMS, andEXTRA_PROGRAMS, appending ‘$(EXEEXT)’ to each binary. Obviously it cannot rewrite values obtained at run-time throughconfigure substitutions, therefore you should take care ofappending ‘$(EXEEXT)’ yourself, as in ‘AC_SUBST([MT],['mt${EXEEXT}'])’.

Conditional Programs using Automake Conditionals

You can also use Automake conditionals (see Conditionals) toselect programs to be built. In this case you don't have to worryabout ‘$(EXEEXT)’ orEXTRA_PROGRAMS.

     bin_PROGRAMS = cpio pax
     if WANT_MT
       bin_PROGRAMS += mt
     endif
     if WANT_RMT
       libexec_PROGRAMS = rmt
     endif

Next:  ,Previous:  A Program,Up:  Programs

8.2 Building a library

Building a library is much like building a program. In this case, thename of the primary isLIBRARIES. Libraries can be installed inlibdir or pkglibdir.

See A Shared Library, for information on how to build sharedlibraries using libtool and theLTLIBRARIES primary.

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

     noinst_LIBRARIES = libcpio.a
     libcpio_a_SOURCES = ...

The sources that go into a library are determined exactly as they arefor programs, via the_SOURCES variables. Note that the libraryname is canonicalized (see Canonicalization), so the _SOURCESvariable corresponding to libcpio.a is ‘libcpio_a_SOURCES’,not ‘libcpio.a_SOURCES’.

Extra objects can be added to a library using thelibrary_LIBADD variable. This should be used for objectsdetermined byconfigure. Again from cpio:

     libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)

In addition, sources for extra objects that will not exist untilconfigure-time must be added to theBUILT_SOURCES variable(see Sources).

Building a static library is done by compiling all object files, thenby invoking ‘$(AR) $(ARFLAGS)’ followed by the name of thelibrary and the list of objects, and finally by calling‘$(RANLIB)’ on that library. You should callAC_PROG_RANLIB from your configure.ac to defineRANLIB (Automake will complain otherwise). You should alsocallAM_PROG_AR to define AR, in order to support unusualarchivers such as Microsoft lib.ARFLAGS will default tocru; you can override this variable by setting it in yourMakefile.am or byAC_SUBSTing it from yourconfigure.ac. You can override theAR variable bydefining a per-library maude_AR variable (seeProgram and Library Variables).

Be careful when selecting library components conditionally. Becausebuilding an empty library is not portable, you should ensure that anylibrary always contains at least one object.

To use a static library when building a program, add it toLDADD for this program. In the following example, the programcpio is statically linked with the librarylibcpio.a.

     noinst_LIBRARIES = libcpio.a
     libcpio_a_SOURCES = ...
     
     bin_PROGRAMS = cpio
     cpio_SOURCES = cpio.c ...
     cpio_LDADD = libcpio.a

Next:  ,Previous:  A Library,Up:  Programs

8.3 Building a Shared Library

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

Next:  ,Up:  A Shared Library

8.3.1 The Libtool Concept

Libtool abstracts shared and static libraries into a unified concepthenceforth called libtool libraries. Libtool libraries arefiles using the .la suffix, and can designate a static library,a shared library, or maybe both. Their exact nature cannot bedetermined until./configure is run: not all platforms supportall kinds of libraries, and users can explicitly select whichlibraries should be built. (However the package's maintainers cantune the default, seeThe AC_PROG_LIBTOOL macro.)

Because object files for shared and static libraries must be compileddifferently, libtool is also used during compilation. Object filesbuilt by libtool are calledlibtool objects: these are filesusing the .lo suffix. Libtool libraries are built from theselibtool objects.

You should not assume anything about the structure of .la or.lo files and how libtool constructs them: this is libtool'sconcern, and the last thing one wants is to learn about libtool'sguts. However the existence of these files matters, because they areused as targets and dependencies inMakefiles rules whenbuilding libtool libraries. There are situations where you may haveto refer to these, for instance when expressing dependencies forbuilding source files conditionally (seeConditional Libtool Sources).

People considering writing a plug-in system, with dynamically loadedmodules, should look intolibltdl: libtool's dlopening library(see Using libltdl). This offers a portable dlopening facility to load libtool librariesdynamically, and can also achieve static linking where unavoidable.

Before we discuss how to use libtool with Automake in details, itshould be noted that the libtool manual also has a section about howto use Automake with libtool (seeUsing Automake with Libtool).

Next:  ,Previous:  Libtool Concept,Up:  A Shared Library

8.3.2 Building Libtool Libraries

Automake uses libtool to build libraries declared with theLTLIBRARIES primary. Each_LTLIBRARIES variable is alist of libtool libraries to build. For instance, to create a libtoollibrary namedlibgettext.la, and install it in libdir,write:

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

Automake predefines the variable pkglibdir, so you can usepkglib_LTLIBRARIES to install libraries in‘$(libdir)/@PACKAGE@/’.

If gettext.h is a public header file that needs to be installedin order for people to use the library, it should be declared using a_HEADERS variable, not inlibgettext_la_SOURCES. Headers listed in the latter should be internal headers that are notpart of the public interface.

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

A package can build and install such a library along with otherprograms that use it. This dependency should be specified usingLDADD. The following example builds a program namedhello that is linked withlibgettext.la.

     lib_LTLIBRARIES = libgettext.la
     libgettext_la_SOURCES = gettext.c ...
     
     bin_PROGRAMS = hello
     hello_SOURCES = hello.c ...
     hello_LDADD = libgettext.la

Whether hello is statically or dynamically linked withlibgettext.la is not yet known: this will depend on theconfiguration of libtool and the capabilities of the host.

Next:  ,Previous:  Libtool Libraries,Up:  A Shared Library

8.3.3 Building Libtool Libraries Conditionally

Like conditional programs (seeConditional Programs), there aretwo main ways to build conditional libraries: using Automakeconditionals or using AutoconfAC_SUBSTitutions.

The important implementation detail you have to be aware of is thatthe place where a library will be installed matters to libtool: itneeds to be indicatedat link-time using the -rpathoption.

For libraries whose destination directory is known when Automake runs,Automake will automatically supply the appropriate-rpathoption to libtool. This is the case for libraries listed explicitly insome installable_LTLIBRARIES variables such aslib_LTLIBRARIES.

However, for libraries determined at configure time (and thusmentioned in EXTRA_LTLIBRARIES), Automake does not know thefinal installation directory. For such libraries you must add the-rpath option to the appropriate_LDFLAGS variable byhand.

The examples below illustrate the differences between these two methods.

Here is an example where WANTEDLIBS is an AC_SUBSTedvariable set at./configure-time to either libfoo.la,libbar.la, both, or none. Although ‘$(WANTEDLIBS)’appears in thelib_LTLIBRARIES, Automake cannot guess itrelates to libfoo.la orlibbar.la at the time it createsthe link rule for these two libraries. Therefore the-rpathargument must be explicitly supplied.

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

Here is how the same Makefile.am would look using Automakeconditionals namedWANT_LIBFOO and WANT_LIBBAR. NowAutomake is able to compute the-rpath setting itself, becauseit's clear that both libraries will end up in ‘$(libdir)’ if theyare installed.

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

Next:  ,Previous:  Conditional Libtool Libraries,Up:  A Shared Library

8.3.4 Libtool Libraries with Conditional Sources

Conditional compilation of sources in a library can be achieved in thesame way as conditional compilation of sources in a program(seeConditional Sources). The only difference is that_LIBADD should be used instead of_LDADD and that itshould mention libtool objects (.lo files).

So, to mimic the hello example from Conditional Sources,we could build a libhello.la library using eitherhello-linux.c orhello-generic.c with the followingMakefile.am.

     lib_LTLIBRARIES = libhello.la
     libhello_la_SOURCES = hello-common.c
     EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
     libhello_la_LIBADD = $(HELLO_SYSTEM)
     libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)

And make sure configure definesHELLO_SYSTEM aseither hello-linux.lo orhello-generic.lo.

Or we could simply use an Automake conditional as follows.

     lib_LTLIBRARIES = libhello.la
     libhello_la_SOURCES = hello-common.c
     if LINUX
     libhello_la_SOURCES += hello-linux.c
     else
     libhello_la_SOURCES += hello-generic.c
     endif

Next:  ,Previous:  Conditional Libtool Sources,Up:  A Shared Library

8.3.5 Libtool Convenience Libraries

Sometimes you want to build libtool libraries that should not beinstalled. These are called libtool convenience libraries andare typically used to encapsulate many sublibraries, later gatheredinto one big installed library.

Libtool convenience libraries are declared by directory-less variablessuch as noinst_LTLIBRARIES, check_LTLIBRARIES, or evenEXTRA_LTLIBRARIES. Unlike installed libtool libraries they donot need an-rpath flag at link time (actually this is the onlydifference).

Convenience libraries listed in noinst_LTLIBRARIES are alwaysbuilt. Those listed incheck_LTLIBRARIES are built only upon‘make check’. Finally, libraries listed inEXTRA_LTLIBRARIES are never built explicitly: Automake outputsrules to build them, but if the library does not appear as a Makefiledependency anywhere it won't be built (this is whyEXTRA_LTLIBRARIES is used for conditional compilation).

Here is a sample setup merging libtool convenience libraries fromsubdirectories into one mainlibtop.la library.

     # -- Top-level Makefile.am --
     SUBDIRS = sub1 sub2 ...
     lib_LTLIBRARIES = libtop.la
     libtop_la_SOURCES =
     libtop_la_LIBADD = \
       sub1/libsub1.la \
       sub2/libsub2.la \
       ...
     
     # -- sub1/Makefile.am --
     noinst_LTLIBRARIES = libsub1.la
     libsub1_la_SOURCES = ...
     
     # -- sub2/Makefile.am --
     # showing nested convenience libraries
     SUBDIRS = sub2.1 sub2.2 ...
     noinst_LTLIBRARIES = libsub2.la
     libsub2_la_SOURCES =
     libsub2_la_LIBADD = \
       sub21/libsub21.la \
       sub22/libsub22.la \
       ...

When using such setup, beware that automake will assumelibtop.la is to be linked with the C linker. This is becauselibtop_la_SOURCES is empty, soautomake picks C asdefault language. Iflibtop_la_SOURCES was not empty,automake would select the linker as explained inHow the Linker is Chosen.

If one of the sublibraries contains non-C source, it is important thatthe appropriate linker be chosen. One way to achieve this is topretend that there is such a non-C file among the sources of thelibrary, thus forcingautomake to select the appropriatelinker. Here is the top-levelMakefile of our example updatedto force C++ linking.

     SUBDIRS = sub1 sub2 ...
     lib_LTLIBRARIES = libtop.la
     libtop_la_SOURCES =
     # Dummy C++ source to cause C++ linking.
     nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
     libtop_la_LIBADD = \
       sub1/libsub1.la \
       sub2/libsub2.la \
       ...

‘EXTRA_*_SOURCES’ variables are used to keep track of sourcefiles that might be compiled (this is mostly useful when doingconditional compilation usingAC_SUBST, see Conditional Libtool Sources), and thenodist_ prefix means the listedsources are not to be distributed (seeProgram and Library Variables). In effect the filedummy.cxx does not need toexist in the source tree. Of course if you have some real source fileto list inlibtop_la_SOURCES there is no point in cheating withnodist_EXTRA_libtop_la_SOURCES.

Next:  ,Previous:  Libtool Convenience Libraries,Up:  A Shared Library

8.3.6 Libtool Modules

These are libtool libraries meant to be dlopened. They areindicated to libtool by passing-module at link-time.

     pkglib_LTLIBRARIES = mymodule.la
     mymodule_la_SOURCES = doit.c
     mymodule_la_LDFLAGS = -module

Ordinarily, Automake requires that a library's name start withlib. However, when building a dynamically loadable module youmight wish to use a "nonstandard" name. Automake will not complainabout such nonstandard names if it knows the library being built is alibtool module, i.e., if -module explicitly appears in thelibrary's_LDFLAGS variable (or in the common AM_LDFLAGSvariable when no per-library_LDFLAGS variable is defined).

As always, AC_SUBST variables are black boxes to Automake sincetheir values are not yet known whenautomake is run. Therefore if -module is set via such a variable, Automakecannot notice it and will proceed as if the library was an ordinarylibtool library, with strict naming.

If mymodule_la_SOURCES is not specified, then it defaults tothe single filemymodule.c (see Default _SOURCES).

Next:  ,Previous:  Libtool Modules,Up:  A Shared Library

8.3.7 _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS

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

The ‘library_LDFLAGS’ variable is the place to listadditional libtool linking flags, such as-version-info,-static, and a lot more. SeeLink mode.

The libtool command has two kinds of options: mode-specificoptions and generic options. Mode-specific options such as theaforementioned linking flags should be lumped with the other flagspassed to the tool invoked by libtool (hence the use of‘library_LDFLAGS’ for libtool linking flags). Genericoptions include--tag=tag and --silent(seeInvoking libtool for more options) should appear before the modeselection on the command line; inMakefile.ams they shouldbe listed in the ‘library_LIBTOOLFLAGS’ variable.

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

These flags are passed to libtool after the --tag=tagoption computed by Automake (if any), so‘library_LIBTOOLFLAGS’ (orAM_LIBTOOLFLAGS) is agood place to override or supplement the --tag=tagsetting.

The libtool rules also use a LIBTOOLFLAGS variable that shouldnot be set inMakefile.am: this is a user variable (see Flag Variables Ordering. It allows users to run ‘makeLIBTOOLFLAGS=--silent’, for instance. Note that the verbosity oflibtool can also be influenced with the Automakesilent-rules option (see Options).

Next:  ,Previous:  Libtool Flags,Up:  A Shared Library

8.3.8 LTLIBOBJS and LTALLOCA

Where an ordinary library might include ‘$(LIBOBJS)’ or‘$(ALLOCA)’ (seeLIBOBJS), a libtool library must use‘$(LTLIBOBJS)’ or ‘$(LTALLOCA)’. This is required becausethe object files that libtool operates on do not necessarily end in.o.

Nowadays, the computation of LTLIBOBJS from LIBOBJS isperformed automatically by Autoconf (seeAC_LIBOBJ vs. LIBOBJS).

Previous:  LTLIBOBJS,Up:  A Shared Library

8.3.9 Common Issues Related to Libtool's Use

Next:  ,Up:  Libtool Issues

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

Libtool comes with a tool called libtoolize that willinstall libtool's supporting files into a package. Running thiscommand will installltmain.sh. You should execute it beforeaclocal andautomake.

People upgrading old packages to newer autotools are likely to facethis issue because older Automake versions used to calllibtoolize. Therefore old build scripts do not calllibtoolize.

Since Automake 1.6, it has been decided that runninglibtoolize was none of Automake's business. Instead, thatfunctionality has been moved into theautoreconf command(see Using autoreconf). If you do not want to remember what to run andwhen, just learn theautoreconf command. Hopefully,replacing existingbootstrap.sh or autogen.sh scripts bya call toautoreconf should also free you from any similarincompatible change in the future.

Previous:  Error required file ltmain.sh not found,Up:  Libtool Issues

8.3.9.2 Objects ‘created with both libtool and without’

Sometimes, the same source file is used both to build a libtoollibrary and to build another non-libtool target (be it a program oranother library).

Let's consider the following Makefile.am.

     bin_PROGRAMS = prog
     prog_SOURCES = prog.c foo.c ...
     
     lib_LTLIBRARIES = libfoo.la
     libfoo_la_SOURCES = foo.c ...

(In this trivial case the issue could be avoided by linkinglibfoo.la withprog instead of listing foo.c inprog_SOURCES. But let's assume we really want to keepprog andlibfoo.la separate.)

Technically, it means that we should build foo.$(OBJEXT) forprog, andfoo.lo for libfoo.la. The problem isthat in the course of creatingfoo.lo, libtool may erase (orreplace) foo.$(OBJEXT), and this cannot be avoided.

Therefore, when Automake detects this situation it will complainwith a message such as

     object `foo.$(OBJEXT)' created both with libtool and without

A workaround for this issue is to ensure that these two objects getdifferent basenames. As explained inRenamed Objects, thishappens automatically when per-targets flags are used.

     bin_PROGRAMS = prog
     prog_SOURCES = prog.c foo.c ...
     prog_CFLAGS = $(AM_CFLAGS)
     
     lib_LTLIBRARIES = libfoo.la
     libfoo_la_SOURCES = foo.c ...

Adding ‘prog_CFLAGS = $(AM_CFLAGS)’ is almost a no-op, becausewhen theprog_CFLAGS is defined, it is used instead ofAM_CFLAGS. However as a side effect it will causeprog.c andfoo.c to be compiled asprog-prog.$(OBJEXT) andprog-foo.$(OBJEXT), which solvesthe issue.

Next:  ,Previous:  A Shared Library,Up:  Programs

8.4 Program and Library Variables

Associated with each program is a collection of variables that can beused to modify how that program is built. There is a similar list ofsuch variables for each library. The canonical name of the program (orlibrary) is used as a base for naming these variables.

In the list below, we use the name “maude” to refer to the program orlibrary. In yourMakefile.am you would replace this with thecanonical name of your program. This list also refers to “maude” as aprogram, but in general the same rules apply for both static and dynamiclibraries; the documentation below notes situations where programs andlibraries differ.

maude_SOURCES
This variable, if it exists, lists all the source files that arecompiled to build the program. These files are added to thedistribution by default. When building the program, Automake will causeeach source file to be compiled to a single .o file (or .lo when using libtool). Normally these object files are namedafter the source file, but other factors can change this. If a file inthe _SOURCES variable has an unrecognized extension, Automakewill do one of two things with it. If a suffix rule exists for turningfiles with the unrecognized extension into .o files, then automake will treat this file as it will any other source file(see Support for Other Languages). Otherwise, the file will beignored as though it were a header file.

The prefixes dist_ and nodist_ can be used to controlwhether files listed in a_SOURCES variable are distributed. dist_ is redundant, as sources are distributed by default, but itcan be specified for clarity if desired.

It is possible to have both dist_ and nodist_ variants ofa given_SOURCES variable at once; this lets you easilydistribute some files and not others, for instance:

          nodist_maude_SOURCES = nodist.c
          dist_maude_SOURCES = dist-me.c

By default the output file (on Unix systems, the .o file) willbe put into the current build directory. However, if the optionsubdir-objects is in effect in the current directory then the.o file will be put into the subdirectory named after thesource file. For instance, withsubdir-objects enabled,sub/dir/file.c will be compiled tosub/dir/file.o. Somepeople prefer this mode of operation. You can specifysubdir-objects inAUTOMAKE_OPTIONS (see Options).

EXTRA_maude_SOURCES
Automake needs to know the list of files you intend to compile statically. For one thing, this is the only way Automake has ofknowing what sort of language support a given Makefile.inrequires. 4 This means that, for example, you can't put aconfigure substitution like ‘ @my_sources@’ into a ‘ _SOURCES’variable. If you intend to conditionally compile source files and use configure to substitute the appropriate object names into, e.g., _LDADD (see below), then you should list the corresponding sourcefiles in the EXTRA_ variable.

This variable also supports dist_ and nodist_ prefixes. For instance,nodist_EXTRA_maude_SOURCES would list extrasources that may need to be built, but should not be distributed.

maude_AR
A static library is created by default by invoking ‘ $(AR)$(ARFLAGS)’ followed by the name of the library and then the objectsbeing put into the library. You can override this by setting the _AR variable. This is usually used with C++; some C++compilers require a special invocation in order to instantiate all thetemplates that should go into a library. For instance, the SGI C++compiler likes this variable set like so: 
          libmaude_a_AR = $(CXX) -ar -o

maude_LIBADD
Extra objects can be added to a library using the _LIBADDvariable. For instance, this should be used for objects determined by configure (see A Library).

In the case of libtool libraries, maude_LIBADD can also referto other libtool libraries.

maude_LDADD
Extra objects ( *.$(OBJEXT)) and libraries ( *.a, *.la) can be added to a program by listing them in the _LDADD variable. For instance, this should be used for objectsdetermined by configure (see Linking).

_LDADD and _LIBADD are inappropriate for passingprogram-specific linker flags (except for-l, -L,-dlopen and-dlpreopen). Use the _LDFLAGS variablefor this purpose.

For instance, if your configure.ac usesAC_PATH_XTRA, youcould link your program against the X libraries like so:

          maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)

We recommend that you use -l and -L only whenreferring to third-party libraries, and give the explicit file namesof any library built by your package. Doing so will ensure thatmaude_DEPENDENCIES (see below) is correctly defined by default.

maude_LDFLAGS
This variable is used to pass extra flags to the link step of a programor a shared library. It overrides the AM_LDFLAGS variable.
maude_LIBTOOLFLAGS
This variable is used to pass extra options to libtool. It overrides the AM_LIBTOOLFLAGS variable. These options are output before libtool's --mode=modeoption, so they should not be mode-specific options (those belong tothe compiler or linker flags). See Libtool Flags.
maude_DEPENDENCIES
It is also occasionally useful to have a target (program or library)depend on some other file that is not actually part of that target. This can be done using the _DEPENDENCIES variable. Eachtarget depends on the contents of such a variable, but no furtherinterpretation is done.

Since these dependencies are associated to the link rule used tocreate the programs they should normally list files used by the linkcommand. That is*.$(OBJEXT), *.a, or*.la filesfor programs; *.lo and*.la files for Libtool libraries;and *.$(OBJEXT) files for static libraries. In rare cases youmay need to add other kinds of files such as linker scripts, butlisting a source file in_DEPENDENCIES is wrong. Ifsome source file needs to be built before all the components of aprogram are built, consider using theBUILT_SOURCES variable(see Sources).

If _DEPENDENCIES is not supplied, it is computed by Automake. The automatically-assigned value is the contents of_LDADD or_LIBADD, with most configure substitutions, -l, -L,-dlopen and-dlpreopen options removed. The configuresubstitutions that are left in are only ‘$(LIBOBJS)’ and‘$(ALLOCA)’; these are left because it is known that they will notcause an invalid value for _DEPENDENCIES to be generated.

_DEPENDENCIES is more likely used to perform conditionalcompilation using anAC_SUBST variable that contains a list ofobjects. See Conditional Sources, and Conditional Libtool Sources.

maude_LINK
You can override the linker on a per-program basis. By default thelinker is chosen according to the languages used by the program. Forinstance, a program that includes C++ source code would use the C++compiler to link. The _LINK variable must hold the name of acommand that can be passed all the .o file names and librariesto link against as arguments. Note that the name of the underlyingprogram is not passed to _LINK; typically one uses‘ $@’: 
          maude_LINK = $(CCLD) -magic -o $@

If a _LINK variable is not supplied, it may still be generatedand used by Automake due to the use of per-target link flags such as_CFLAGS,_LDFLAGS or _LIBTOOLFLAGS, in cases wherethey apply.

maude_CCASFLAGS maude_CFLAGS maude_CPPFLAGS maude_CXXFLAGS maude_FFLAGS maude_GCJFLAGS maude_LFLAGS maude_OBJCFLAGS maude_RFLAGS maude_UPCFLAGS maude_YFLAGS
Automake allows you to set compilation flags on a per-program (orper-library) basis. A single source file can be included in severalprograms, and it will potentially be compiled with different flags foreach program. This works for any language directly supported byAutomake. These per-target compilation flags are‘ _CCASFLAGS’,‘ _CFLAGS’,‘ _CPPFLAGS’,‘ _CXXFLAGS’,‘ _FFLAGS’,‘ _GCJFLAGS’,‘ _LFLAGS’,‘ _OBJCFLAGS’,‘ _RFLAGS’,‘ _UPCFLAGS’, and‘ _YFLAGS’.

When using a per-target compilation flag, Automake will choose adifferent name for the intermediate object files. Ordinarily a filelikesample.c will be compiled to produce sample.o. However, if the program's _CFLAGS variable is set, then theobject file will be named, for instance,maude-sample.o. (Seealso Renamed Objects.) The use of per-target compilation flagswith C sources requires that the macroAM_PROG_CC_C_O be calledfrom configure.ac.

In compilations with per-target flags, the ordinary ‘AM_’ form ofthe flags variable isnot automatically included in thecompilation (however, the user form of the variableis included). So for instance, if you want the hypothetical maude compilationsto also use the value ofAM_CFLAGS, you would need to write: 

          maude_CFLAGS = ... your flags ... $(AM_CFLAGS)

See Flag Variables Ordering, for more discussion about theinteraction between user variables, ‘AM_’ shadow variables, andper-target variables.

maude_SHORTNAME
On some platforms the allowable file names are very short. In order tosupport these systems and per-target compilation flags at the sametime, Automake allows you to set a “short name” that will influencehow intermediate object files are named. For instance, in the followingexample, 
          bin_PROGRAMS = maude
          maude_CPPFLAGS = -DSOMEFLAG
          maude_SHORTNAME = m
          maude_SOURCES = sample.c ...

the object file would be named m-sample.o rather thanmaude-sample.o.

This facility is rarely needed in practice,and we recommend avoiding it until you find it is required.

Next:  ,Previous:  Program and Library Variables,Up:  Programs

8.5 Default _SOURCES

_SOURCES variables are used to specify source files of programs(see A Program), libraries (see A Library), and Libtoollibraries (seeA Shared Library).

When no such variable is specified for a target, Automake will defineone itself. The default is to compile a single C file whose base nameis the name of the target itself, with any extension replaced byAM_DEFAULT_SOURCE_EXT, which defaults to.c.

For example if you have the following somewhere in yourMakefile.am with no correspondinglibfoo_a_SOURCES:

     lib_LIBRARIES = libfoo.a sub/libc++.a

libfoo.a will be built using a default source file namedlibfoo.c, andsub/libc++.a will be built fromsub/libc++.c. (In older versionssub/libc++.awould be built from sub_libc___a.c, i.e., the default sourcewas the canonized name of the target, with.c appended. We believe the new behavior is more sensible, but for backwardcompatibilityautomake will use the old name if a file or a rulewith that name exists andAM_DEFAULT_SOURCE_EXT is not used.)

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

     check_PROGRAMS = test1 test2 test3
     AM_DEFAULT_SOURCE_EXT = .cpp

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

Another case where this is convenient is building many Libtool modules(modulen.la), each defined in its own file(modulen.c).

     AM_LDFLAGS = -module
     lib_LTLIBRARIES = module1.la module2.la module3.la

Finally, there is one situation where this default source computationneeds to be avoided: when a target should not be built from sources. We already saw such an example in true; this happens when allthe constituents of a target have already been compiled and just needto be combined using a_LDADD variable. Then it is necessaryto define an empty _SOURCES variable, so thatautomakedoes not compute a default.

     bin_PROGRAMS = target
     target_SOURCES =
     target_LDADD = libmain.a libmisc.a

Next:  ,Previous:  Default _SOURCES,Up:  Programs

8.6 Special handling for LIBOBJS and ALLOCA

The ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables list objectfiles that should be compiled into the project to provide animplementation for functions that are missing or broken on the hostsystem. They are substituted by configure.

These variables are defined by Autoconf macros such asAC_LIBOBJ,AC_REPLACE_FUNCS (see Generic Function Checks), orAC_FUNC_ALLOCA (seeParticular Function Checks). Many other Autoconfmacros callAC_LIBOBJ or AC_REPLACE_FUNCS topopulate ‘$(LIBOBJS)’.

Using these variables is very similar to doing conditional compilationusingAC_SUBST variables, as described in Conditional Sources. That is, when building a program, ‘$(LIBOBJS)’ and‘$(ALLOCA)’ should be added to the associated ‘*_LDADD’variable, or to the ‘*_LIBADD’ variable when building a library. However there is no need to list the corresponding sources in‘EXTRA_*_SOURCES’ nor to define ‘*_DEPENDENCIES’. Automakeautomatically adds ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ to thedependencies, and it will discover the list of corresponding sourcefiles automatically (by tracing the invocations of theAC_LIBSOURCE Autoconf macros). However, if you have alreadydefined ‘*_DEPENDENCIES’ explicitly for an unrelated reason, thenyou have to add these variables manually.

These variables are usually used to build a portability library thatis linked with all the programs of the project. We now review asample setup. First,configure.ac contains some checks thataffect eitherLIBOBJS or ALLOCA.

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

The AC_CONFIG_LIBOBJ_DIR tells Autoconf that the source filesof these object files are to be found in thelib/ directory. Automake can also use this information, otherwise it expects thesource files are to be in the directory where the ‘$(LIBOBJS)’and ‘$(ALLOCA)’ variables are used.

The lib/ directory should therefore containmalloc.c,memcmp.c,strdup.c, alloca.c. Here is itsMakefile.am:

     # lib/Makefile.am
     
     noinst_LIBRARIES = libcompat.a
     libcompat_a_SOURCES =
     libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)

The library can have any name, of course, and anyway it is not goingto be installed: it just holds the replacement versions of the missingor broken functions so we can later link them in. Many projectsalso include extra functions, specific to the project, in thatlibrary: they are simply added on the _SOURCES line.

There is a small trap here, though: ‘$(LIBOBJS)’ and‘$(ALLOCA)’ might be empty, and building an empty library is notportable. You should ensure that there is always something to put inlibcompat.a. Most projects will also add some utilityfunctions in that directory, and list them inlibcompat_a_SOURCES, so in practicelibcompat.a cannotbe empty.

Finally here is how this library could be used from the src/directory.

     # src/Makefile.am
     
     # Link all programs in this directory with libcompat.a
     LDADD = ../lib/libcompat.a
     
     bin_PROGRAMS = tool1 tool2 ...
     tool1_SOURCES = ...
     tool2_SOURCES = ...

When option subdir-objects is not used, as in the aboveexample, the variables ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ can onlybe used in the directory where their sources lie. E.g., here it wouldbe wrong to use ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ insrc/Makefile.am. However if bothsubdir-objects andAC_CONFIG_LIBOBJ_DIR are used, it is OK to use these variablesin other directories. For instancesrc/Makefile.am could bechanged as follows.

     # src/Makefile.am
     
     AUTOMAKE_OPTIONS = subdir-objects
     LDADD = $(LIBOBJS) $(ALLOCA)
     
     bin_PROGRAMS = tool1 tool2 ...
     tool1_SOURCES = ...
     tool2_SOURCES = ...

Because ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ contain objectfile names that end with ‘.$(OBJEXT)’, they are not suitable forLibtool libraries (where the expected object extension is .lo):LTLIBOBJS andLTALLOCA should be used instead.

LTLIBOBJS is defined automatically by Autoconf and should notbe defined by hand (as in the past), however at the time of writingLTALLOCA still needs to be defined fromALLOCA manually. See AC_LIBOBJ vs. LIBOBJS.

Next:  ,Previous:  LIBOBJS,Up:  Programs

8.7 Variables used when building a program

Occasionally it is useful to know which Makefile variablesAutomake uses for compilations, and in which order (seeFlag Variables Ordering); for instance, you might need to do your owncompilation in some special cases.

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

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

Automake already provides some -I options automatically, in aseparate variable that is also passed to every compilation that invokesthe C preprocessor. In particular it generates ‘-I.’,‘-I$(srcdir)’, and a -I pointing to the directory holdingconfig.h (if you've usedAC_CONFIG_HEADERS orAM_CONFIG_HEADER). You can disable the default-Ioptions using the nostdinc option.

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

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

INCLUDES
This does the same job as AM_CPPFLAGS (or any per-target _CPPFLAGS variable if it is used). It is an older name for thesame functionality. This variable is deprecated; we suggest using AM_CPPFLAGS and per-target _CPPFLAGS instead.
AM_CFLAGS
This is the variable the Makefile.am author can use to passin additional C compiler flags. It is more fully documented elsewhere. In some situations, this is not used, in preference to theper-executable (or per-library) _CFLAGS.
COMPILE
This is the command used to actually compile a C source file. Thefile name is appended to form the complete command line.
AM_LDFLAGS
This is the variable the Makefile.am author can use to passin additional linker flags. In some situations, this is not used, inpreference to the per-executable (or per-library) _LDFLAGS.
LINK
This is the command used to actually link a C program. It alreadyincludes ‘ -o $@’ and the usual variable references (for instance, CFLAGS); it takes as “arguments” the names of the object filesand libraries to link in. This variable is not used when the linker isoverridden with a per-target _LINK variable or per-target flagscause Automake to define such a _LINK variable.

Next:  ,Previous:  Program Variables,Up:  Programs

8.8 Yacc and Lex support

Automake has somewhat idiosyncratic support for Yacc and Lex.

Automake assumes that the .c file generated byyacc(or lex) should be named using the basename of the inputfile. That is, for a yacc source filefoo.y, Automake willcause the intermediate file to be namedfoo.c (as opposed toy.tab.c, which is more traditional).

The extension of a yacc source file is used to determine the extensionof the resulting C or C++ file. Files with the extension.ywill be turned into .c files; likewise,.yy will become.cc;.y++, c++;.yxx, .cxx; and.ypp,.cpp.

Likewise, lex source files can be used to generate C or C++; theextensions .l, .ll, .l++, .lxx, and.lpp are recognized.

You should never explicitly mention the intermediate (C or C++) filein any SOURCES variable; only list the source file.

The intermediate files generated by yacc (orlex)will be included in any distribution that is made. That way the userdoesn't need to haveyacc or lex.

If a yacc source file is seen, then yourconfigure.ac mustdefine the variable YACC. This is most easily done by invokingthe macro AC_PROG_YACC (seeParticular Program Checks).

When yacc is invoked, it is passed AM_YFLAGS andYFLAGS. The latter is a user variable and the former isintended for theMakefile.am author.

AM_YFLAGS is usually used to pass the -d option toyacc. Automake knows what this means and will automaticallyadjust its rules to update and distribute the header file built by‘yacc -d’5. What Automake cannot guess, though, is where thisheader will be used: it is up to you to ensure the header gets builtbefore it is first used. Typically this is necessary in order fordependency tracking to work when the header is included by anotherfile. The common solution is listing the header file inBUILT_SOURCES (seeSources) as follows.

     BUILT_SOURCES = parser.h
     AM_YFLAGS = -d
     bin_PROGRAMS = foo
     foo_SOURCES = ... parser.y ...

If a lex source file is seen, then yourconfigure.acmust define the variable LEX. You can use AC_PROG_LEXto do this (see Particular Program Checks), but using AM_PROG_LEX macro(see Macros) is recommended.

When lex is invoked, it is passed AM_LFLAGS andLFLAGS. The latter is a user variable and the former isintended for theMakefile.am author.

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

Whenlex or yacc sources are used,automake-i automatically installs an auxiliary program calledylwrap in your package (seeAuxiliary Programs). Thisprogram is used by the build rules to rename the output of thesetools, and makes it possible to include multipleyacc (orlex) source files in a single directory. (This is necessarybecause yacc's output file name is fixed, and a parallel make couldconceivably invoke more than one instance of yaccsimultaneously.)

For yacc, simply managing locking is insufficient. The output ofyacc always uses the same symbol names internally, so it isn'tpossible to link twoyacc parsers into the same executable.

We recommend using the following renaming hack used in gdb:

     #define yymaxdepth c_maxdepth
     #define yyparse c_parse
     #define yylex   c_lex
     #define yyerror c_error
     #define yylval  c_lval
     #define yychar  c_char
     #define yydebug c_debug
     #define yypact  c_pact
     #define yyr1    c_r1
     #define yyr2    c_r2
     #define yydef   c_def
     #define yychk   c_chk
     #define yypgo   c_pgo
     #define yyact   c_act
     #define yyexca  c_exca
     #define yyerrflag c_errflag
     #define yynerrs c_nerrs
     #define yyps    c_ps
     #define yypv    c_pv
     #define yys     c_s
     #define yy_yys  c_yys
     #define yystate c_state
     #define yytmp   c_tmp
     #define yyv     c_v
     #define yy_yyv  c_yyv
     #define yyval   c_val
     #define yylloc  c_lloc
     #define yyreds  c_reds
     #define yytoks  c_toks
     #define yylhs   c_yylhs
     #define yylen   c_yylen
     #define yydefred c_yydefred
     #define yydgoto  c_yydgoto
     #define yysindex c_yysindex
     #define yyrindex c_yyrindex
     #define yygindex c_yygindex
     #define yytable  c_yytable
     #define yycheck  c_yycheck
     #define yyname   c_yyname
     #define yyrule   c_yyrule

For each define, replace the ‘c_’ prefix with whatever you like. These defines work forbison, byacc, andtraditionalyaccs. If you find a parser generator that uses asymbol not covered here, please report the new name so it can be addedto the list.

Next:  ,Previous:  Yacc and Lex,Up:  Programs

8.9 C++ Support

Automake includes full support for C++.

Any package including C++ code must define the output variableCXX inconfigure.ac; the simplest way to do this is to usetheAC_PROG_CXX macro (see Particular Program Checks).

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

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

Next:  ,Previous:  C++ Support,Up:  Programs

8.10 Objective C Support

Automake includes some support for Objective C.

Any package including Objective C code must define the output variableOBJC inconfigure.ac; the simplest way to do this is to usetheAC_PROG_OBJC macro (see Particular Program Checks).

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

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

Next:  ,Previous:  Objective C Support,Up:  Programs

8.11 Unified Parallel C Support

Automake includes some support for Unified Parallel C.

Any package including Unified Parallel C code must define the outputvariable UPC in configure.ac; the simplest way to dothis is to use theAM_PROG_UPC macro (see Public Macros).

A few additional variables are defined when a Unified Parallel Csource file is seen:

UPC
The name of the Unified Parallel C compiler.
UPCFLAGS
Any flags to pass to the Unified Parallel C compiler.
AM_UPCFLAGS
The maintainer's variant of UPCFLAGS.
UPCCOMPILE
The command used to actually compile a Unified Parallel C source file. The file name is appended to form the complete command line.
UPCLINK
The command used to actually link a Unified Parallel C program.

Next:  ,Previous:  Unified Parallel C Support,Up:  Programs

8.12 Assembly Support

Automake includes some support for assembly code. There are two formsof assembler files: normal (*.s) and preprocessed byCPP(*.S or *.sx).

The variableCCAS holds the name of the compiler used to buildassembly code. This compiler must work a bit like a C compiler; inparticular it must accept-c and -o. The values ofCCASFLAGS andAM_CCASFLAGS (or its per-targetdefinition) is passed to the compilation. For preprocessed files,DEFS,DEFAULT_INCLUDES, INCLUDES, CPPFLAGSand AM_CPPFLAGS are also used.

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

Only the suffixes .s, .S, and.sx are recognized byautomake as being files containing assembly code.

Next:  ,Previous:  Assembly Support,Up:  Programs

8.13 Fortran 77 Support

Automake includes full support for Fortran 77.

Any package including Fortran 77 code must define the output variableF77 inconfigure.ac; the simplest way to do this is to usetheAC_PROG_F77 macro (see Particular Program Checks).

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

F77
The name of the Fortran 77 compiler.
FFLAGS
Any flags to pass to the Fortran 77 compiler.
AM_FFLAGS
The maintainer's variant of FFLAGS.
RFLAGS
Any flags to pass to the Ratfor compiler.
AM_RFLAGS
The maintainer's variant of RFLAGS.
F77COMPILE
The command used to actually compile a Fortran 77 source file. The filename is appended to form the complete command line.
FLINK
The command used to actually link a pure Fortran 77 program or sharedlibrary.

Automake can handle preprocessing Fortran 77 and Ratfor source files inaddition to compiling them6. Automakealso contains some support for creating programs and shared librariesthat are a mixture of Fortran 77 and other languages (see Mixing Fortran 77 With C and C++).

These issues are covered in the following sections.

Next:  ,Up:  Fortran 77 Support

8.13.1 Preprocessing Fortran 77

N.f is made automatically fromN.F or N.r. Thisrule runs just the preprocessor to convert a preprocessable Fortran 77or Ratfor source file into a strict Fortran 77 source file. The precisecommand used is as follows:

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

Next:  ,Previous:  Preprocessing Fortran 77,Up:  Fortran 77 Support

8.13.2 Compiling Fortran 77 Files

N.o is made automatically from N.f,N.F orN.r by running the Fortran 77 compiler. The precise command usedis as follows:

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

Previous:  Compiling Fortran 77 Files,Up:  Fortran 77 Support

8.13.3 Mixing Fortran 77 With C and C++

Automake currently provides limited support for creating programsand shared libraries that are a mixture of Fortran 77 and C and/or C++. However, there are many other issues related to mixing Fortran 77 withother languages that arenot (currently) handled by Automake, butthat are handled by other packages7.

Automake can help in two ways:

  1. Automatic selection of the linker depending on which combinations ofsource code.
  2. Automatic selection of the appropriate linker flags (e.g., -L and-l) to pass to the automatically selected linker in order to linkin the appropriate Fortran 77 intrinsic and run-time libraries.

    These extra Fortran 77 linker flags are supplied in the output variableFLIBS by theAC_F77_LIBRARY_LDFLAGS Autoconf macrosupplied with newer versions of Autoconf (Autoconf version 2.13 andlater). SeeFortran Compiler Characteristics.

If Automake detects that a program or shared library (as mentioned insome _PROGRAMS or _LTLIBRARIES primary) contains sourcecode that is a mixture of Fortran 77 and C and/or C++, then it requiresthat the macroAC_F77_LIBRARY_LDFLAGS be called inconfigure.ac, and that either$(FLIBS)appear in the appropriate _LDADD (for programs) or_LIBADD(for shared libraries) variables. It is the responsibility of theperson writing theMakefile.am to make sure that ‘$(FLIBS)’appears in the appropriate_LDADD or_LIBADD variable.

For example, consider the followingMakefile.am:

     bin_PROGRAMS = foo
     foo_SOURCES  = main.cc foo.f
     foo_LDADD    = libfoo.la $(FLIBS)
     
     pkglib_LTLIBRARIES = libfoo.la
     libfoo_la_SOURCES  = bar.f baz.c zardoz.cc
     libfoo_la_LIBADD   = $(FLIBS)

In this case, Automake will insist that AC_F77_LIBRARY_LDFLAGSis mentioned inconfigure.ac. Also, if ‘$(FLIBS)’ hadn'tbeen mentioned infoo_LDADD and libfoo_la_LIBADD, thenAutomake would have issued a warning.

Up:  Mixing Fortran 77 With C and C++

8.13.3.1 How the Linker is Chosen

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

  1. Native Java (GCJLINK)
  2. C++ (CXXLINK)
  3. Fortran 77 (F77LINK)
  4. Fortran (FCLINK)
  5. Objective C (OBJCLINK)
  6. Unified Parallel C (UPCLINK)
  7. C (LINK)

For example, if Fortran 77, C and C++ source code is compiledinto a program, then the C++ linker will be used. In this case, if theC or Fortran 77 linkers required any special libraries that weren'tincluded by the C++ linker, then they must be manually added to an_LDADD or _LIBADD variable by the user writing theMakefile.am.

Automake only looks at the file names listed in _SOURCESvariables to choose the linker, and defaults to the C linker. Sometimes this is inconvenient because you are linking against alibrary written in another language and would like to set the linkermore appropriately. See Libtool Convenience Libraries, for atrick with nodist_EXTRA_..._SOURCES.

A per-target _LINK variable will override the above selection. Per-target link flags will cause Automake to write a per-target_LINK variable according to the language chosen as above.

Next:  ,Previous:  Fortran 77 Support,Up:  Programs

8.14 Fortran 9x Support

Automake includes support for Fortran 9x.

Any package including Fortran 9x code must define the output variableFC inconfigure.ac; the simplest way to do this is to usetheAC_PROG_FC macro (see Particular Program Checks).

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

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

Up:  Fortran 9x Support

8.14.1 Compiling Fortran 9x Files

file.o is made automatically fromfile.f90,file.f95,file.f03, or file.f08by running the Fortran 9x compiler. The precise command usedis as follows:

.f90
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<
.f95
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<
.f03
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<
.f08
$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<

Next:  ,Previous:  Fortran 9x Support,Up:  Programs

8.15 Compiling Java sources using gcj

Automake includes support for natively compiled Java, using gcj,the Java front end to the GNU Compiler Collection (rudimentary supportfor compiling Java to bytecode using thejavac compiler isalso present, albeit deprecated; seeJava).

Any package including Java code to be compiled must define the outputvariable GCJ in configure.ac; the variable GCJFLAGSmust also be defined somehow (either in configure.ac orMakefile.am). The simplest way to do this is to use theAM_PROG_GCJ macro.

By default, programs including Java source files are linked withgcj.

As always, the contents of AM_GCJFLAGS are passed to everycompilation invokinggcj (in its role as an ahead-of-timecompiler, when invoking it to create.class files,AM_JAVACFLAGS is used instead). If it is necessary to passoptions togcj from Makefile.am, this variable, and notthe user variableGCJFLAGS, should be used.

gcj can be used to compile.java, .class,.zip, or.jar files.

When linking, gcj requires that the main class be specifiedusing the--main= option. The easiest way to do this is to usethe_LDFLAGS variable for the program.

Next:  ,Previous:  Java Support with gcj,Up:  Programs

8.16 Vala Support

Automake provides initial support for Vala(http://www.vala-project.org/). This requires valac version 0.7.0 or later, and currently requiresthe user to use GNU make.

     foo_SOURCES = foo.vala bar.vala zardoc.c

Any .vala file listed in a _SOURCES variable will becompiled into C code by the Vala compiler. The generated.c files aredistributed. The end user does not need to have a Vala compiler installed.

Automake ships with an Autoconf macro called AM_PROG_VALACthat will locate the Vala compiler and optionally check its versionnumber.

— Macro: AM_PROG_VALAC ( [ minimum-version ])

Try to find a Vala compiler in PATH. If it is found, the variableVALAC is set. Optionally a minimum release number of the compilercan be requested:

          AM_PROG_VALAC([0.7.0])

There are a few variables that are used when compiling Vala sources:

VALAC
Path to the Vala compiler.
VALAFLAGS
Additional arguments for the Vala compiler.
AM_VALAFLAGS
The maintainer's variant of VALAFLAGS. 
          lib_LTLIBRARIES = libfoo.la
          libfoo_la_SOURCES = foo.vala

Note that currently, you cannot use per-target *_VALAFLAGS(see Renamed Objects) to produce different C files from one Valasource file.

Next:  ,Previous:  Vala Support,Up:  Programs

8.17 Support for Other Languages

Automake currently only includes full support for C, C++ (see C++ Support), Objective C (see Objective C Support), Fortran 77(seeFortran 77 Support), Fortran 9x (see Fortran 9x Support),and Java (see Java Support with gcj). There is only rudimentarysupport for other languages, support for which will be improved basedon user demand.

Some limited support for adding your own languages is available via thesuffix rule handling (seeSuffixes).

Next:  ,Previous:  Support for Other Languages,Up:  Programs

8.18 Automatic de-ANSI-fication (deprecated, soon to be removed)

The features described in this section are deprecated; you mustnot use any of them in new code, and remove their use from older butstill maintained code: they will be withdrawn in the next majorAutomake release.

When the C language was standardized in 1989, there was a longtransition period where package developers needed to worry aboutporting to older systems that did not support ANSI C by default. These older systems are no longer in practical use and are no longersupported by their original suppliers, so developers need not worryabout this problem any more.

Automake allows you to write packages that are portable to K&R C byde-ANSI-fying each source file before the actual compilation takesplace.

If theMakefile.am variable AUTOMAKE_OPTIONS(seeOptions) contains the option ansi2knr then code tohandle de-ANSI-fication is inserted into the generatedMakefile.in.

This causes each C source file in the directory to be treated as ANSI C. If an ANSI C compiler is available, it is used. If no ANSI C compileris available, theansi2knr program is used to convert the sourcefiles into K&R C, which is then compiled.

The ansi2knr program is simple-minded. It assumes the sourcecode will be formatted in a particular way; see theansi2knr manpage for details.

Support for the obsolete de-ANSI-fication featurerequires the source filesansi2knr.cand ansi2knr.1 to be in the same package as the ANSI C source;these files are distributed with Automake. Also, the packageconfigure.ac must call the macro AM_C_PROTOTYPES(see Macros).

Automake also handles finding the ansi2knr support files in someother directory in the current package. This is done by prepending therelative path to the appropriate directory to theansi2knroption. For instance, suppose the package has ANSI C code in thesrc andlib subdirectories. The files ansi2knr.c andansi2knr.1 appear inlib. Then this could appear insrc/Makefile.am:

     AUTOMAKE_OPTIONS = ../lib/ansi2knr

If no directory prefix is given, the files are assumed to be in thecurrent directory.

Note that automatic de-ANSI-fication will not work when the package isbeing built for a different host architecture. That is becauseautomake currently has no way to buildansi2knrfor the build machine.

UsingLIBOBJS with source de-ANSI-fication used to requirehand-crafted code inconfigure to append ‘$U’ to basenamesinLIBOBJS. This is no longer true today. Starting with version2.54, Autoconf takes care of rewritingLIBOBJS andLTLIBOBJS. (see AC_LIBOBJ vs. LIBOBJS)

Next:  ,Previous:  ANSI,Up:  Programs

8.19 Automatic dependency tracking

As a developer it is often painful to continually update theMakefile.am whenever the include-file dependencies change in aproject. Automake supplies a way to automatically track dependencychanges (seeDependency Tracking).

Automake always uses complete dependencies for a compilation,including system headers. Automake's model is that dependencycomputation should be a side effect of the build. To this end,dependencies are computed by running all compilations through aspecial wrapper program calleddepcomp. depcompunderstands how to coax many different C and C++ compilers intogenerating dependency information in the format it requires. ‘automake -a’ will install depcomp into your sourcetree for you. Ifdepcomp can't figure out how to properlyinvoke your compiler, dependency tracking will simply be disabled foryour build.

Experience with earlier versions of Automake (seeDependency Tracking Evolution) taught us that it is not reliable to generatedependencies only on the maintainer's system, as configurations varytoo much. So instead Automake implements dependency tracking at buildtime.

Automatic dependency tracking can be suppressed by puttingno-dependencies in the variableAUTOMAKE_OPTIONS, orpassing no-dependencies as an argument toAM_INIT_AUTOMAKE(this should be the preferred way). Or, you can invokeautomakewith the -i option. Dependency tracking is enabled by default.

The person building your package also can choose to disable dependencytracking by configuring with--disable-dependency-tracking.

Previous:  Dependencies,Up:  Programs

8.20 Support for executable extensions

On some platforms, such as Windows, executables are expected to have anextension such as.exe. On these platforms, some compilers (GCCamong them) will automatically generatefoo.exe when asked togenerate foo.

Automake provides mostly-transparent support for this. Unfortunatelymostly doesn't yet meanfully. Until the Englishdictionary is revised, you will have to assist Automake if your packagemust support those platforms.

One thing you must be aware of is that, internally, Automake rewritessomething like this:

     bin_PROGRAMS = liver

to this:

     bin_PROGRAMS = liver$(EXEEXT)

The targets Automake generates are likewise given the ‘$(EXEEXT)’extension.

The variables TESTS and XFAIL_TESTS (see Simple Tests)are also rewritten if they contain filenames that have been declared asprograms in the sameMakefile. (This is mostly useful when someprograms fromcheck_PROGRAMS are listed in TESTS.)

However, Automake cannot apply this rewriting to configuresubstitutions. This means that if you are conditionally building aprogram using such a substitution, then yourconfigure.ac musttake care to add ‘$(EXEEXT)’ when constructing the output variable.

With Autoconf 2.13 and earlier, you must explicitly use AC_EXEEXTto get this support. With Autoconf 2.50,AC_EXEEXT is runautomatically if you configure a compiler (say, throughAC_PROG_CC).

Sometimes maintainers like to write an explicit link rule for theirprogram. Without executable extension support, this is easy—yousimply write a rule whose target is the name of the program. However,when executable extension support is enabled, you must instead add the‘$(EXEEXT)’ suffix.

Unfortunately, due to the change in Autoconf 2.50, this means you mustalways add this extension. However, this is a problem for maintainerswho know their package will never run on a platform that hasexecutable extensions. For those maintainers, theno-exeextoption (see Options) will disable this feature. This works in afairly ugly way; if no-exeext is seen, then the presence of arule for a target namedfoo in Makefile.am will overrideanautomake-generated rule for ‘foo$(EXEEXT)’. Withouttheno-exeext option, this use will give a diagnostic.

Next:  ,Previous:  Programs,Up:  Top

9 Other Derived Objects

Automake can handle derived objects that are not C programs. Sometimesthe support for actually building such objects must be explicitlysupplied, but Automake will still automatically handle installation anddistribution.

Next:  ,Up:  Other Objects

9.1 Executable Scripts

It is possible to define and install programs that are scripts. Suchprograms are listed using theSCRIPTS primary name. When thescript is distributed in its final, installable form, theMakefile usually looks as follows:

     # Install my_script in $(bindir) and distribute it.
     dist_bin_SCRIPTS = my_script

Scripts are not distributed by default; as we have just seen, thosethat should be distributed can be specified using adist_prefix as with other primaries.

Scripts can be installed in bindir, sbindir,libexecdir, orpkgdatadir.

Scripts that need not be installed can be listed innoinst_SCRIPTS, and among them, those which are needed only by‘make check’ should go incheck_SCRIPTS.

When a script needs to be built, the Makefile.am should includethe appropriate rules. For instance theautomake programitself is a Perl script that is generated fromautomake.in. Here is how this is handled:

     bin_SCRIPTS = automake
     CLEANFILES = $(bin_SCRIPTS)
     EXTRA_DIST = automake.in
     
     do_subst = sed -e 's,[@]datadir[@],$(datadir),g' \
                 -e 's,[@]PERL[@],$(PERL),g' \
                 -e 's,[@]PACKAGE[@],$(PACKAGE),g' \
                 -e 's,[@]VERSION[@],$(VERSION),g' \
                 ...
     
     automake: automake.in Makefile
             $(do_subst) < $(srcdir)/automake.in > automake
             chmod +x automake

Such scripts for which a build rule has been supplied need to bedeleted explicitly usingCLEANFILES (see Clean), and theirsources have to be distributed, usually withEXTRA_DIST(see Basics of Distribution).

Another common way to build scripts is to process them fromconfigure withAC_CONFIG_FILES. In this situationAutomake knows which files should be cleaned and distributed, and whatthe rebuild rules should look like.

For instance if configure.ac contains

     AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])

to build src/my_script fromsrc/my_script.in, then asrc/Makefile.am to install this script in$(bindir) canbe as simple as

     bin_SCRIPTS = my_script
     CLEANFILES = $(bin_SCRIPTS)

There is no need for EXTRA_DIST or any build rule: Automakeinfers them fromAC_CONFIG_FILES (see Requirements). CLEANFILES is still useful, because by default Automake willclean targets ofAC_CONFIG_FILES in distclean, notclean.

Although this looks simpler, building scripts this way has onedrawback: directory variables such as$(datadir) are not fullyexpanded and may refer to other directory variables.

Next:  ,Previous:  Scripts,Up:  Other Objects

9.2 Header files

Header files that must be installed are specified by theHEADERS family of variables. Headers can be installed inincludedir,oldincludedir, pkgincludedir or anyother directory you may have defined (seeUniform). For instance,

     include_HEADERS = foo.h bar/bar.h

will install the two files as $(includedir)/foo.h and$(includedir)/bar.h.

The nobase_ prefix is also supported,

     nobase_include_HEADERS = foo.h bar/bar.h

will install the two files as $(includedir)/foo.h and$(includedir)/bar/bar.h (seeAlternative).

Usually, only header files that accompany installed libraries need tobe installed. Headers used by programs or convenience libraries arenot installed. Thenoinst_HEADERS variable can be used forsuch headers. However when the header actually belongs to a singleconvenience library or program, we recommend listing it in theprogram's or library's_SOURCES variable (see Program Sources) instead of innoinst_HEADERS. This is clearer forthe Makefile.am reader.noinst_HEADERS would be theright variable to use in a directory containing only headers and noassociated library or program.

All header files must be listed somewhere; in a _SOURCESvariable or in a_HEADERS variable. Missing ones will notappear in the distribution.

For header files that are built and must not be distributed, use thenodist_ prefix as innodist_include_HEADERS ornodist_prog_SOURCES. If these generated headers are neededduring the build, you must also ensure they exist before they areused (seeSources).

Next:  ,Previous:  Headers,Up:  Other Objects

9.3 Architecture-independent data files

Automake supports the installation of miscellaneous data files using theDATA family of variables.Such data can be installed in the directories datadir,sysconfdir, sharedstatedir,localstatedir, orpkgdatadir.

By default, data files are not included in a distribution. Ofcourse, you can use thedist_ prefix to change this on aper-variable basis.

Here is how Automake declares its auxiliary data files:

     dist_pkgdata_DATA = clean-kr.am clean.am ...

Previous:  Data,Up:  Other Objects

9.4 Built Sources

Because Automake's automatic dependency tracking works as a side-effectof compilation (seeDependencies) there is a bootstrap issue: atarget should not be compiled before its dependencies are made, butthese dependencies are unknown until the target is first compiled.

Ordinarily this is not a problem, because dependencies are distributedsources: they preexist and do not need to be built. Suppose thatfoo.c includesfoo.h. When it first compilesfoo.o,make only knows that foo.o depends onfoo.c. As a side-effect of this compilationdepcomprecords the foo.h dependency so that following invocations ofmake will honor it. In these conditions, it's clear there isno problem: either foo.o doesn't exist and has to be built(regardless of the dependencies), or accurate dependencies exist andthey can be used to decide whetherfoo.o should be rebuilt.

It's a different story if foo.h doesn't exist by the firstmake run. For instance, there might be a rule to buildfoo.h. This timefile.o's build will fail because thecompiler can't findfoo.h. make failed to trigger therule to buildfoo.h first by lack of dependency information.

TheBUILT_SOURCES variable is a workaround for this problem. Asource file listed inBUILT_SOURCES is made on ‘make all’or ‘make check’ (or even ‘make install’) before othertargets are processed. However, such a source file is notcompiled unless explicitly requested by mentioning it in someother_SOURCES variable.

So, to conclude our introductory example, we could use‘BUILT_SOURCES = foo.h’ to ensurefoo.h gets built beforeany other target (includingfoo.o) during ‘make all’ or‘make check’.

BUILT_SOURCES is actually a bit of a misnomer, as any file whichmust be created early in the build process can be listed in thisvariable. Moreover, all built sources do not necessarily have to belisted inBUILT_SOURCES. For instance, a generated .c filedoesn't need to appear inBUILT_SOURCES (unless it is included byanother source), because it's a known dependency of the associatedobject.

It might be important to emphasize that BUILT_SOURCES ishonored only by ‘make all’, ‘make check’ and ‘makeinstall’. This means you cannot build a specific target (e.g.,‘make foo’) in a clean tree if it depends on a built source. However it will succeed if you have run ‘make all’ earlier,because accurate dependencies are already available.

The next section illustrates and discusses the handling of built sourceson a toy example.

Up:  Sources

9.4.1 Built Sources Example

Suppose that foo.c includes bindir.h, which isinstallation-dependent and not distributed: it needs to be built. Herebindir.h defines the preprocessor macro bindir to thevalue of the make variablebindir (inherited fromconfigure).

We suggest several implementations below. It's not meant to be anexhaustive listing of all ways to handle built sources, but it will giveyou a few ideas if you encounter this issue.

First Try

This first implementation will illustrate the bootstrap issue mentionedin the previous section (seeSources).

Here is a tentative Makefile.am.

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

This setup doesn't work, because Automake doesn't know that foo.cincludesbindir.h. Remember, automatic dependency tracking worksas a side-effect of compilation, so the dependencies offoo.o willbe known only after foo.o has been compiled (seeDependencies). The symptom is as follows.

     % make
     source='foo.c' object='foo.o' libtool=no \
     depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
     depmode=gcc /bin/sh ./depcomp \
     gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
     foo.c:2: bindir.h: No such file or directory
     make: *** [foo.o] Error 1

In this example bindir.h is not distributed nor installed, andit is not even being built on-time. One may wonder if the‘nodist_foo_SOURCES = bindir.h’ line has any use at all. Thisline simply states that bindir.h is a source offoo, sofor instance, it should be inspected while generating tags(seeTags). In other words, it does not help our present problem,and the build would fail identically without it.

Using BUILT_SOURCES

A solution is to require bindir.h to be built before anythingelse. This is whatBUILT_SOURCES is meant for (see Sources).

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

See how bindir.h gets built first:

     % make
     echo '#define bindir "/usr/local/bin"' >bindir.h
     make  all-am
     make[1]: Entering directory `/home/adl/tmp'
     source='foo.c' object='foo.o' libtool=no \
     depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
     depmode=gcc /bin/sh ./depcomp \
     gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
     gcc  -g -O2   -o foo  foo.o
     make[1]: Leaving directory `/home/adl/tmp'

However, as said earlier, BUILT_SOURCES applies only to theall,check, and install targets. It still failsif you try to run ‘make foo’ explicitly:

     % make clean
     test -z "bindir.h" || rm -f bindir.h
     test -z "foo" || rm -f foo
     rm -f *.o
     % : > .deps/foo.Po # Suppress previously recorded dependencies
     % make foo
     source='foo.c' object='foo.o' libtool=no \
     depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
     depmode=gcc /bin/sh ./depcomp \
     gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
     foo.c:2: bindir.h: No such file or directory
     make: *** [foo.o] Error 1
Recording Dependencies manually

Usually people are happy enough with BUILT_SOURCES because theynever build targets such as ‘make foo’ before ‘make all’, asin the previous example. However if this matters to you, you canavoid BUILT_SOURCES and record such dependencies explicitly intheMakefile.am.

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

You don't have to list all the dependencies of foo.oexplicitly, only those that might need to be built. If a dependencyalready exists, it will not hinder the first compilation and will berecorded by the normal dependency tracking code. (Note that afterthis first compilation the dependency tracking code will also haverecorded the dependency betweenfoo.o andbindir.h; so our explicit dependency is really useful tothe first build only.)

Adding explicit dependencies like this can be a bit dangerous if you arenot careful enough. This is due to the way Automake tries not tooverwrite your rules (it assumes you know better than it). ‘foo.$(OBJEXT): bindir.h’ supersedes any rule Automake may want tooutput to build ‘foo.$(OBJEXT)’. It happens to work in this casebecause Automake doesn't have to output any ‘foo.$(OBJEXT):’target: it relies on a suffix rule instead (i.e., ‘.c.$(OBJEXT):’). Always check the generatedMakefile.in if you do this.

Build bindir.h fromconfigure

It's possible to define this preprocessor macro from configure,either inconfig.h (see Defining Directories), or by processing abindir.h.in file usingAC_CONFIG_FILES(see Configuration Actions).

At this point it should be clear that building bindir.h fromconfigure works well for this example.bindir.h will existbefore you build any target, hence will not cause any dependency issue.

The Makefile can be shrunk as follows. We do not even have to mentionbindir.h.

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c

However, it's not always possible to build sources fromconfigure, especially when these sources are generated by a toolthat needs to be built first.

Build bindir.c, notbindir.h.

Another attractive idea is to define bindir as a variable orfunction exported frombindir.o, and build bindir.cinstead ofbindir.h.

     noinst_PROGRAMS = foo
     foo_SOURCES = foo.c bindir.h
     nodist_foo_SOURCES = bindir.c
     CLEANFILES = bindir.c
     bindir.c: Makefile
             echo 'const char bindir[] = "$(bindir)";' >$@

bindir.h contains just the variable's declaration and doesn'tneed to be built, so it won't cause any trouble.bindir.o isalways dependent on bindir.c, sobindir.c will get builtfirst.

Which is best?

There is no panacea, of course. Each solution has its merits anddrawbacks.

You cannot use BUILT_SOURCES if the ability to run ‘makefoo’ on a clean tree is important to you.

You won't add explicit dependencies if you are leery of overridingan Automake rule by mistake.

Building files from ./configure is not always possible, neitheris converting.h files into .c files.

Next:  ,Previous:  Other Objects,Up:  Top

10 Other GNU Tools

Since Automake is primarily intended to generate Makefile.ins foruse in GNU programs, it tries hard to interoperate with other GNU tools.

Next:  ,Up:  Other GNU Tools

10.1 Emacs Lisp

Automake provides some support for Emacs Lisp. The LISP primaryis used to hold a list of.el files. Possible prefixes for thisprimary arelisp_ and noinst_. Note that iflisp_LISP is defined, thenconfigure.ac must runAM_PATH_LISPDIR (seeMacros).

Lisp sources are not distributed by default. You can prefix theLISP primary withdist_, as in dist_lisp_LISP ordist_noinst_LISP, to indicate that these files should bedistributed.

Automake will byte-compile all Emacs Lisp source files using the Emacsfound byAM_PATH_LISPDIR, if any was found.

Byte-compiled Emacs Lisp files are not portable among all versions ofEmacs, so it makes sense to turn this off if you expect sites to havemore than one version of Emacs installed. Furthermore, many packagesdon't actually benefit from byte-compilation. Still, we recommendthat you byte-compile your Emacs Lisp sources. It is probably betterfor sites with strange setups to cope for themselves than to make theinstallation less nice for everybody else.

There are two ways to avoid byte-compiling. Historically, we haverecommended the following construct.

     lisp_LISP = file1.el file2.el
     ELCFILES =

ELCFILES is an internal Automake variable that normally listsall.elc files that must be byte-compiled. Automake definesELCFILES automatically fromlisp_LISP. Emptying thisvariable explicitly prevents byte-compilation.

Since Automake 1.8, we now recommend using lisp_DATA instead:

     lisp_DATA = file1.el file2.el

Note that these two constructs are not equivalent. _LISP willnot install a file if Emacs is not installed, while_DATA willalways install its files.

Next:  ,Previous:  Emacs Lisp,Up:  Other GNU Tools

10.2 Gettext

IfAM_GNU_GETTEXT is seen in configure.ac, then Automaketurns on support for GNU gettext, a message catalog system forinternationalization(seeIntroduction).

The gettext support in Automake requires the addition of one ortwo subdirectories to the package:po and possibly also intl. The latter is needed ifAM_GNU_GETTEXT is not invoked with the‘external’ argument, or ifAM_GNU_GETTEXT_INTL_SUBDIR is used. Automake ensures that these directories exist and are mentioned inSUBDIRS.

Next:  ,Previous:  gettext,Up:  Other GNU Tools

10.3 Libtool

Automake provides support for GNU Libtool (see Introduction) with theLTLIBRARIES primary. See A Shared Library.

Next:  ,Previous:  Libtool,Up:  Other GNU Tools

10.4 Java bytecode compilation (deprecated)

Automake provides some minimal support for Java bytecode compilation withthe JAVA primary (in addition to the support for compiling Java tonative machine code; seeJava Support with gcj). Note however thatthe interface and most features described here are deprecated; thenext automake release will strive to provide a better and cleanerinterface, which howeverwon't be backward-compatible; the presentinterface will probably be removed altogether in future automake releases(1.13 or later), so don't use it in new code.

Any .java files listed in a _JAVA variable will becompiled withJAVAC at build time. By default, .javafiles are not included in the distribution, you should use thedist_ prefix to distribute them.

Here is a typical setup for distributing .java files andinstalling the.class files resulting from their compilation.

     javadir = $(datadir)/java
     dist_java_JAVA = a.java b.java ...

Currently Automake enforces the restriction that only one_JAVAprimary can be used in a given Makefile.am. The reason for thisrestriction is that, in general, it isn't possible to know which.class files were generated from which.java files, soit would be impossible to know which files to install where. Forinstance, a.java file can define multiple classes; the resulting.class file names cannot be predicted without parsing the.java file.

There are a few variables that are used when compiling Java sources:

JAVAC
The name of the Java compiler. This defaults to ‘ javac’.
JAVACFLAGS
The flags to pass to the compiler. This is considered to be a uservariable (see User Variables).
AM_JAVACFLAGS
More flags to pass to the Java compiler. This, and not JAVACFLAGS, should be used when it is necessary to put Javacompiler flags into Makefile.am.
JAVAROOT
The value of this variable is passed to the -d option to javac. It defaults to ‘ $(top_builddir)’.
CLASSPATH_ENV
This variable is a shell expression that is used to set the CLASSPATH environment variable on the javac command line. (In the future we will probably handle class path setting differently.)

Previous:  Java,Up:  Other GNU Tools

10.5 Python

Automake provides support for Python compilation with thePYTHON primary. A typical setup is to callAM_PATH_PYTHON inconfigure.ac and use a line like thefollowing inMakefile.am:

     python_PYTHON = tree.py leave.py

Any files listed in a _PYTHON variable will be byte-compiledwith py-compile at install time. py-compileactually creates both standard (.pyc) and optimized(.pyo) byte-compiled versions of the source files. Note thatbecause byte-compilation occurs at install time, any files listed innoinst_PYTHON will not be compiled. Python source files areincluded in the distribution by default, prependnodist_ (as innodist_python_PYTHON) to omit them.

Automake ships with an Autoconf macro called AM_PATH_PYTHONthat will determine some Python-related directory variables (seebelow). If you have calledAM_PATH_PYTHON fromconfigure.ac, then you may use the variablespython_PYTHON orpkgpython_PYTHON to list Python sourcefiles in your Makefile.am, depending on where you want your filesinstalled (see the definitions ofpythondir andpkgpythondir below).

— Macro: AM_PATH_PYTHON ( [ version ] , [ action-if-found ] ,

[action-if-not-found])

Search for a Python interpreter on the system. This macro takes threeoptional arguments. The first argument, if present, is the minimumversion of Python required for this package:AM_PATH_PYTHONwill skip any Python interpreter that is older than version. If an interpreter is found and satisfies version, thenaction-if-found is run. Otherwise,action-if-not-found isrun.

If action-if-not-found is not specified, as in the followingexample, the default is to abortconfigure. 

          AM_PATH_PYTHON([2.2])

This is fine when Python is an absolute requirement for the package. If Python >= 2.5 was onlyoptional to the package,AM_PATH_PYTHON could be called as follows.

          AM_PATH_PYTHON([2.5],, [:])

If the PYTHON variable is set when AM_PATH_PYTHON iscalled, then that will be the only Python interpreter that is tried.

AM_PATH_PYTHON creates the following output variables based onthe Python installation found during configuration.

PYTHON
The name of the Python executable, or ‘ :’ if no suitableinterpreter could be found.

Assuming action-if-not-found is used (otherwise ./configurewill abort if Python is absent), the value ofPYTHON can be usedto setup a conditional in order to disable the relevant part of a buildas follows.

          AM_PATH_PYTHON(,, [:])
          AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])

PYTHON_VERSION
The Python version number, in the form major. minor(e.g., ‘ 2.5’). This is currently the value of‘ sys.version[:3]’.
PYTHON_PREFIX
The string ‘ ${prefix}’. This term may be used in future workthat needs the contents of Python's ‘ sys.prefix’, but generalconsensus is to always use the value from configure.
PYTHON_EXEC_PREFIX
The string ‘ ${exec_prefix}’. This term may be used in future workthat needs the contents of Python's ‘ sys.exec_prefix’, but generalconsensus is to always use the value from configure.
PYTHON_PLATFORM
The canonical name used by Python to describe the operating system, asgiven by ‘ sys.platform’. This value is sometimes needed whenbuilding Python extensions.
pythondir
The directory name for the site-packages subdirectory of thestandard Python install tree.
pkgpythondir
This is the directory under pythondir that is named after thepackage. That is, it is ‘ $(pythondir)/$(PACKAGE)’. It is providedas a convenience.
pyexecdir
This is the directory where Python extension modules (shared libraries)should be installed. An extension module written in C could be declaredas follows to Automake: 
          pyexec_LTLIBRARIES = quaternion.la
          quaternion_la_SOURCES = quaternion.c support.c support.h
          quaternion_la_LDFLAGS = -avoid-version -module

pkgpyexecdir
This is a convenience variable that is defined as‘ $(pyexecdir)/$(PACKAGE)’.

All these directory variables have values that start with either‘${prefix}’ or ‘${exec_prefix}’ unexpanded. This worksfine inMakefiles, but it makes these variables hard to use inconfigure. This is mandated by the GNU coding standards, sothat the user can run ‘make prefix=/foo install’. The Autoconfmanual has a section with more details on this topic(see Installation Directory Variables). See also Hard-Coded Install Paths.

Next:  ,Previous:  Other GNU Tools,Up:  Top

11 Building documentation

Currently Automake provides support for Texinfo and man pages.

Next:  ,Up:  Documentation

11.1 Texinfo

If the current directory contains Texinfo source, you must declare itwith the TEXINFOS primary. Generally Texinfo files are convertedinto info, and thus theinfo_TEXINFOS variable is most commonly usedhere. Any Texinfo source file must end in the.texi,.txi, or.texinfo extension. We recommend .texifor new manuals.

Automake generates rules to build .info,.dvi,.ps,.pdf and .html files from your Texinfosources. Following the GNU Coding Standards, only the.infofiles are built by ‘make all’ and installed by ‘makeinstall’ (unless you useno-installinfo, see below). Furthermore,.info files are automatically distributed so thatTexinfo is not a prerequisite for installing your package.

Other documentation formats can be built on request by ‘makedvi’, ‘make ps’, ‘make pdf’ and ‘make html’, and theycan be installed with ‘make install-dvi’, ‘make install-ps’,‘make install-pdf’ and ‘make install-html’ explicitly. ‘make uninstall’ will remove everything: the Texinfodocumentation installed by default as well as all the above optionalformats.

All these targets can be extended using ‘-local’ rules(seeExtending).

If the .texi file @includes version.texi, thenthat file will be automatically generated. The fileversion.texidefines four Texinfo flag you can reference using@value{EDITION},@value{VERSION},@value{UPDATED}, and @value{UPDATED-MONTH}.

EDITION VERSION
Both of these flags hold the version number of your program. They arekept separate for clarity.
UPDATED
This holds the date the primary .texi file was last modified.
UPDATED-MONTH
This holds the name of the month in which the primary .texi filewas last modified.

The version.texi support requires the mdate-shscript; this script is supplied with Automake and automaticallyincluded whenautomake is invoked with the--add-missing option.

If you have multiple Texinfo files, and you want to use theversion.texi feature, then you have to have a separate versionfile for each Texinfo file. Automake will treat any include in aTexinfo file that matchesvers*.texi just as an automaticallygenerated version file.

Sometimes an info file actually depends on more than one .texifile. For instance, in GNU Hello,hello.texi includes the filefdl.texi. You can tell Automake about these dependencies usingthetexi_TEXINFOS variable. Here is how GNU Hello does it:

     info_TEXINFOS = hello.texi
     hello_TEXINFOS = fdl.texi

By default, Automake requires the filetexinfo.tex to appear inthe same directory as theMakefile.am file that lists the.texi files. If you usedAC_CONFIG_AUX_DIR inconfigure.ac (seeFinding `configure' Input), then texinfo.tex is looked forthere. In both cases,automake then supplies texinfo.tex if--add-missing is given, and takes care of its distribution. However, if you set theTEXINFO_TEX variable (see below),it overrides the location of the file and turns off its installationinto the source as well as its distribution.

The option no-texinfo.tex can be used to eliminate therequirement for the filetexinfo.tex. Use of the variableTEXINFO_TEX is preferable, however, because that allows thedvi,ps, and pdf targets to still work.

Automake generates an install-info rule; some people apparentlyuse this. By default, info pages are installed by ‘makeinstall’, so runningmake install-info is pointless. This canbe prevented via the no-installinfo option. In this case,.info files are not installed by default, and user mustrequest this explicitly using ‘make install-info’.

By default, make install-info will try to run theinstall-info program (if available) to update (or create)the${infodir}/dir index. If this is undesired, itcan be prevented by exporting theAM_UPDATE_INFO_DIR variableto "no".

The following variables are used by the Texinfo build rules.

MAKEINFO
The name of the program invoked to build .info files. Thisvariable is defined by Automake. If the makeinfo program isfound on the system then it will be used by default; otherwise missing will be used instead.
MAKEINFOHTML
The command invoked to build .html files. Automakedefines this to ‘ $(MAKEINFO) --html’.
MAKEINFOFLAGS
User flags passed to each invocation of ‘ $(MAKEINFO)’ and‘ $(MAKEINFOHTML)’. This user variable (see User Variables) isnot expected to be defined in any Makefile; it can be used byusers to pass extra flags to suit their needs.
AM_MAKEINFOFLAGS AM_MAKEINFOHTMLFLAGS
Maintainer flags passed to each makeinfo invocation. Unlike MAKEINFOFLAGS, these variables are meant to be defined bymaintainers in Makefile.am. ‘ $(AM_MAKEINFOFLAGS)’ ispassed to makeinfo when building .info files; and‘ $(AM_MAKEINFOHTMLFLAGS)’ is used when building .htmlfiles.

For instance, the following setting can be used to obtain one single.html file per manual, without node separators.

          AM_MAKEINFOHTMLFLAGS = --no-headers --no-split

AM_MAKEINFOHTMLFLAGS defaults to ‘$(AM_MAKEINFOFLAGS)’. This means that definingAM_MAKEINFOFLAGS without definingAM_MAKEINFOHTMLFLAGS will impact builds of both.infoand .html files.

TEXI2DVI
The name of the command that converts a .texi file into a .dvi file. This defaults to ‘ texi2dvi’, a script that shipswith the Texinfo package.
TEXI2PDF
The name of the command that translates a .texi file into a .pdf file. This defaults to ‘ $(TEXI2DVI) --pdf --batch’.
DVIPS
The name of the command that builds a .ps file out of a .dvi file. This defaults to ‘ dvips’.
TEXINFO_TEX
If your package has Texinfo files in many directories, you can use thevariable TEXINFO_TEX to tell Automake where to find the canonical texinfo.tex for your package. The value of this variable shouldbe the relative path from the current Makefile.am to texinfo.tex: 
          TEXINFO_TEX = ../doc/texinfo.tex

Previous:  Texinfo,Up:  Documentation

11.2 Man Pages

A package can also include man pages (but see the GNU standards on thismatter, Man Pages.) Manpages are declared using the MANS primary. Generally theman_MANS variable is used. Man pages are automatically installed inthe correct subdirectory ofmandir, based on the file extension.

File extensions such as .1c are handled by looking for the validpart of the extension and using that to determine the correctsubdirectory ofmandir. Valid section names are the digits‘0’ through ‘9’, and the letters ‘l’ and ‘n’.

Sometimes developers prefer to name a man page something likefoo.man in the source, and then rename it to have the correctsuffix, for examplefoo.1, when installing the file. Automakealso supports this mode. For a valid section namedsection,there is a corresponding directory named ‘mansectiondir’,and a corresponding_MANS variable. Files listed in such avariable are installed in the indicated section. If the file alreadyhas a valid suffix, then it is installed as-is; otherwise the filesuffix is changed to match the section.

For instance, consider this example:

     man1_MANS = rename.man thesame.1 alsothesame.1c

In this case, rename.man will be renamed torename.1 wheninstalled, but the other files will keep their names.

By default, man pages are installed by ‘make install’. However,since the GNU project does not require man pages, many maintainers donot expend effort to keep the man pages up to date. In these cases, theno-installman option will prevent the man pages from beinginstalled by default. The user can still explicitly install them via‘make install-man’.

For fast installation, with many files it is preferable to use‘mansection_MANS’ over ‘man_MANS’ as well as files thatdo not need to be renamed.

Man pages are not currently considered to be source, because it is notuncommon for man pages to be automatically generated. Therefore theyare not automatically included in the distribution. However, this canbe changed by use of thedist_ prefix. For instance here ishow to distribute and install the two man pages of GNUcpio(which includes both Texinfo documentation and man pages):

     dist_man_MANS = cpio.1 mt.1

The nobase_ prefix is meaningless for man pages and isdisallowed.

Executables and manpages may be renamed upon installation(see Renaming). For manpages this can be avoided by use of thenotrans_ prefix. For instance, suppose an executable ‘foo’allowing to access a library function ‘foo’ from the command line. The way to avoid renaming of the foo.3 manpage is:

     man_MANS = foo.1
     notrans_man_MANS = foo.3

‘notrans_’ must be specified first when used in conjunction witheither ‘dist_’ or ‘nodist_’ (seeFine-grained Distribution Control). For instance:

     notrans_dist_man3_MANS = bar.3

Next:  ,Previous:  Documentation,Up:  Top

12 What Gets Installed

Naturally, Automake handles the details of actually installing yourprogram once it has been built. All files named by the variousprimaries are automatically installed in the appropriate places when theuser runs ‘make install’.

Next:  ,Up:  Install

12.1 Basics of Installation

A file named in a primary is installed by copying the built file intothe appropriate directory. The base name of the file is used wheninstalling.

     bin_PROGRAMS = hello subdir/goodbye

In this example, both ‘hello’ and ‘goodbye’ will be installedin ‘$(bindir)’.

Sometimes it is useful to avoid the basename step at install time. Forinstance, you might have a number of header files in subdirectories ofthe source tree that are laid out precisely how you want to installthem. In this situation you can use thenobase_ prefix tosuppress the base name step. For example:

     nobase_include_HEADERS = stdio.h sys/types.h

will install stdio.h in ‘$(includedir)’ andtypes.hin ‘$(includedir)/sys’.

For most file types, Automake will install multiple files at once, whileavoiding command line length issues (seeLength Limitations). Sincesome install programs will not install the same file twice inone invocation, you may need to ensure that file lists are unique withinone variable such as ‘nobase_include_HEADERS’ above.

You should not rely on the order in which files listed in one variableare installed. Likewise, to cater for parallel make, you should notrely on any particular file installation order even among differentfile types (library dependencies are an exception here).

Next:  ,Previous:  Basics of Installation,Up:  Install

12.2 The Two Parts of Install

Automake generates separate install-data and install-execrules, in case the installer is installing on multiple machines thatshare directory structure—these targets allow the machine-independentparts to be installed only once.install-exec installsplatform-dependent files, and install-data installsplatform-independent files. Theinstall target depends on bothof these targets. While Automake tries to automatically segregateobjects into the correct category, theMakefile.am author is, inthe end, responsible for making sure this is done correctly.Variables using the standard directory prefixes ‘data’,‘info’, ‘man’, ‘include’, ‘oldinclude’,‘pkgdata’, or ‘pkginclude’ are installed byinstall-data.

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

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

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

Next:  ,Previous:  The Two Parts of Install,Up:  Install

12.3 Extending Installation

It is possible to extend this mechanism by defining aninstall-exec-local orinstall-data-local rule. If theserules exist, they will be run at ‘make install’ time. Theserules can do almost anything; care is required.Automake also supports two install hooks,install-exec-hook andinstall-data-hook. These hooks are run after all other installrules of the appropriate type, exec or data, have completed. So, forinstance, it is possible to perform post-installation modificationsusing an install hook. See Extending, for some examples.

Next:  ,Previous:  Extending Installation,Up:  Install

12.4 Staged Installs

Automake generates support for the DESTDIR variable in allinstall rules.DESTDIR is used during the ‘make install’step to relocate install objects into a staging area. Each object andpath is prefixed with the value ofDESTDIR before being copiedinto the install area. Here is an example of typical DESTDIR usage:

     mkdir /tmp/staging &&
     make DESTDIR=/tmp/staging install

The mkdir command avoids a security problem if the attackercreates a symbolic link from/tmp/staging to a victim area;then make places install objects in a directory tree built under/tmp/staging. If/gnu/bin/foo and/gnu/share/aclocal/foo.m4 are to be installed, the above commandwould install/tmp/staging/gnu/bin/foo and/tmp/staging/gnu/share/aclocal/foo.m4.

This feature is commonly used to build install images and packages(see DESTDIR).

Support for DESTDIR is implemented by coding it directly intothe install rules. If yourMakefile.am uses a local installrule (e.g.,install-exec-local) or an install hook, then youmust write that code to respectDESTDIR.

See Makefile Conventions,for another usage example.

Previous:  Staged Installs,Up:  Install

12.5 Install Rules for the User

Automake also generates rules for targets uninstall,installdirs, andinstall-strip. Automake supportsuninstall-local and uninstall-hook. There is no notion of separate uninstalls for “exec” and “data”, asthese features would not provide additional functionality.

Note that uninstall is not meant as a replacement for a realpackaging tool.

Next:  ,Previous:  Install,Up:  Top

13 What Gets Cleaned

The GNU Makefile Standards specify a number of different clean rules. SeeStandard Targets for Users.

Generally the files that can be cleaned are determined automatically byAutomake. Of course, Automake also recognizes some variables that canbe defined to specify additional files to clean. These variables areMOSTLYCLEANFILES,CLEANFILES, DISTCLEANFILES, andMAINTAINERCLEANFILES.When cleaning involves more than deleting some hard-coded list offiles, it is also possible to supplement the cleaning rules with yourown commands. Simply define a rule for any of themostlyclean-local,clean-local, distclean-local,or maintainer-clean-local targets (seeExtending). A commoncase is deleting a directory, for instance, a directory created by thetest suite:

     clean-local:
             -rm -rf testSubDir

Since make allows only one set of rules for a given target,a more extensible way of writing this is to use a separate targetlisted as a dependency:

     clean-local: clean-local-check
     .PHONY: clean-local-check
     clean-local-check:
             -rm -rf testSubDir

As the GNU Standards aren't always explicit as to which files shouldbe removed by which rule, we've adopted a heuristic that we believewas first formulated by François Pinard:

  • If make built it, and it is commonly something that one wouldwant to rebuild (for instance, a.o file), thenmostlyclean should delete it.
  • Otherwise, if make built it, then clean should delete it.
  • If configure built it, then distclean should delete it.
  • If the maintainer built it (for instance, a .info file), thenmaintainer-clean should delete it. Howevermaintainer-clean should not delete anything that needs to existin order to run ‘./configure && make’.

We recommend that you follow this same set of heuristics in yourMakefile.am.

Next:  ,Previous:  Clean,Up:  Top

14 What Goes in a Distribution

Next:  ,Up:  Dist

14.1 Basics of Distribution

Thedist rule in the generated Makefile.in can be usedto generate a gzippedtar file and other flavors of archive fordistribution. The file is named based on thePACKAGE andVERSION variables defined by AM_INIT_AUTOMAKE(seeMacros); more precisely the gzipped tar file is named‘package-version.tar.gz’.You can use the make variableGZIP_ENV to control how gzipis run. The default setting is --best.

For the most part, the files to distribute are automatically found byAutomake: all source files are automatically included in a distribution,as are allMakefile.am and Makefile.in files. Automake alsohas a built-in list of commonly used files that are automaticallyincluded if they are found in the current directory (either physically,or as the target of a Makefile.am rule); this list is printed by‘automake --help’. Note that some files in this list are actuallydistributed only if other certain conditions hold (for example,the config.h.top and config.h.bot files are automaticallydistributed only if, e.g., ‘AC_CONFIG_HEADERS([config.h])’ is usedinconfigure.ac). Also, files that are read byconfigure(i.e. the source files corresponding to the files specified in variousAutoconf macros such asAC_CONFIG_FILES and siblings) areautomatically distributed. Files included in aMakefile.am (usinginclude) or inconfigure.ac (using m4_include), andhelper scripts installed with ‘automake --add-missing’ are alsodistributed.

Still, sometimes there are files that must be distributed, but whichare not covered in the automatic rules. These files should be listed intheEXTRA_DIST variable. You can mention files fromsubdirectories in EXTRA_DIST.

You can also mention a directory in EXTRA_DIST; in this case theentire directory will be recursively copied into the distribution. Please note that this will also copyeverything in the directory,including, e.g., Subversion's .svn private directories or CVS/RCSversion control files. We recommend against using this feature.

If you defineSUBDIRS, Automake will recursively include thesubdirectories in the distribution. IfSUBDIRS is definedconditionally (see Conditionals), Automake will normally includeall directories that could possibly appear inSUBDIRS in thedistribution. If you need to specify the set of directoriesconditionally, you can set the variableDIST_SUBDIRS to theexact list of subdirectories to include in the distribution(seeConditional Subdirectories).

Next:  ,Previous:  Basics of Distribution,Up:  Dist

14.2 Fine-grained Distribution Control

Sometimes you need tighter control over what doesnot go into thedistribution; for instance, you might have source files that aregenerated and that you do not want to distribute. In this caseAutomake gives fine-grained control using thedist andnodist prefixes. Any primary or _SOURCES variable can beprefixed withdist_ to add the listed files to the distribution. Similarly, nodist_ can be used to omit the files from thedistribution.

As an example, here is how you would cause some data to be distributedwhile leaving some source code out of the distribution:

     dist_data_DATA = distribute-this
     bin_PROGRAMS = foo
     nodist_foo_SOURCES = do-not-distribute.c

Next:  ,Previous:  Fine-grained Distribution Control,Up:  Dist

14.3 The dist Hook

Occasionally it is useful to be able to change the distribution beforeit is packaged up. If thedist-hook rule exists, it is runafter the distribution directory is filled, but before the actual tar(or shar) file is created. One way to use this is for distributingfiles in subdirectories for which a newMakefile.am is overkill:

     dist-hook:
             mkdir $(distdir)/random
             cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random

Another way to use this is for removing unnecessary files that getrecursively included by specifying a directory in EXTRA_DIST:

     EXTRA_DIST = doc
     
     dist-hook:
             rm -rf `find $(distdir)/doc -type d -name .svn`

Two variables that come handy when writingdist-hook rules are‘$(distdir)’ and ‘$(top_distdir)’.

‘$(distdir)’ points to the directory where thedist rulewill copy files from the current directory before creating thetarball. If you are at the top-level directory, then ‘distdir =$(PACKAGE)-$(VERSION)’. When used from subdirectory namedfoo/, then ‘distdir = ../$(PACKAGE)-$(VERSION)/foo’. ‘$(distdir)’ can be a relative or absolute path, do not assumeany form.

‘$(top_distdir)’ always points to the root directory of thedistributed tree. At the top-level it's equal to ‘$(distdir)’. In thefoo/ subdirectory‘top_distdir = ../$(PACKAGE)-$(VERSION)’. ‘$(top_distdir)’ too can be a relative or absolute path.

Note that when packages are nested using AC_CONFIG_SUBDIRS(see Subpackages), then ‘$(distdir)’ and‘$(top_distdir)’ are relative to the package where ‘makedist’ was run, not to any sub-packages involved.

Next:  ,Previous:  The dist Hook,Up:  Dist

14.4 Checking the Distribution

Automake also generates a distcheck rule that can be of help toensure that a given distribution will actually work.distcheckmakes a distribution, then tries to do a VPATH build(seeVPATH Builds), run the test suite, and finally make anothertarball to ensure the distribution is self-contained.

Building the package involves running ‘./configure’. If you needto supply additional flags toconfigure, define them in theAM_DISTCHECK_CONFIGURE_FLAGS variable in your top-levelMakefile.am. The user can still extend or override the flagsprovided there by defining the DISTCHECK_CONFIGURE_FLAGS variable,on the command line when invokingmake.

Still, developers are encouraged to strive to make their code buildablewithout requiring any special configure option; thus, in general, youshouldn't defineAM_DISTCHECK_CONFIGURE_FLAGS. However, theremight be few scenarios in which the use of this variable is justified. GNUm4 offers an example. GNU m4 configures bydefault with its experimental and seldom used "changeword" featuredisabled; so in its case it is useful to havemake distcheckrun configure with the --with-changeword option, to ensure thatthe code for changeword support still compiles correctly. GNUm4 also employs the AM_DISTCHECK_CONFIGURE_FLAGSvariable to stress-test the use of--program-prefix=g, since atone point them4 build system had a bug where makeinstallcheck was wrongly assuming it could blindly test "m4",rather than the just-installed "gm4".

If the distcheck-hook rule is defined in your top-levelMakefile.am, then it will be invoked bydistcheck afterthe new distribution has been unpacked, but before the unpacked copyis configured and built. Yourdistcheck-hook can do almostanything, though as always caution is advised. Generally this hook isused to check for potential distribution errors not caught by thestandard mechanism. Note thatdistcheck-hook as well asAM_DISTCHECK_CONFIGURE_FLAGS andDISTCHECK_CONFIGURE_FLAGSare not honored in a subpackage Makefile.am, but the flags fromAM_DISTCHECK_CONFIGURE_FLAGS andDISTCHECK_CONFIGURE_FLAGSare passed down to the configure script of the subpackage.

Speaking of potential distribution errors,distcheck alsoensures that the distclean rule actually removes all builtfiles. This is done by running ‘make distcleancheck’ at the end oftheVPATH build. By default, distcleancheck will rundistclean and then make sure the build tree has been emptied byrunning ‘$(distcleancheck_listfiles)’. Usually this check willfind generated files that you forgot to add to the DISTCLEANFILESvariable (see Clean).

The distcleancheck behavior should be OK for most packages,otherwise you have the possibility to override the definition ofeither thedistcleancheck rule, or the‘$(distcleancheck_listfiles)’ variable. For instance, to disabledistcleancheck completely, add the following rule to yourtop-levelMakefile.am:

     distcleancheck:
             @:

If you want distcleancheck to ignore built files that have notbeen cleaned because they are also part of the distribution, add thefollowing definition instead:

     distcleancheck_listfiles = \
       find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
            sh '{}' ';'

The above definition is not the default because it's usually an error ifyour Makefiles cause some distributed files to be rebuilt when the userbuild the package. (Think about the user missing the tool required tobuild the file; or if the required tool is built by your package,consider the cross-compilation case where it can't be run.) There isan entry in the FAQ about this (seedistcleancheck), make sure youread it before playing withdistcleancheck_listfiles.

distcheck also checks that the uninstall rule worksproperly, both for ordinary andDESTDIR builds. It does thisby invoking ‘make uninstall’, and then it checks the install treeto see if any files are left over. This check will make sure that youcorrectly coded youruninstall-related rules.

By default, the checking is done by the distuninstallcheck rule,and the list of files in the install tree is generated by‘$(distuninstallcheck_listfiles)’ (this is a variable whose value isa shell command to run that prints the list of files to stdout).

Either of these can be overridden to modify the behavior ofdistcheck. For instance, to disable this check completely, youwould write:

     distuninstallcheck:
             @:

Previous:  Checking the Distribution,Up:  Dist

14.5 The Types of Distributions

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

dist-bzip2
Generate a bzip2 tar archive of the distribution. bzip2 archives arefrequently smaller than gzipped archives. By default, this rule makes ‘ bzip2’ use a compression option of -9. To make it use a different one, set the BZIP2environment variable. For example, ‘ make dist-bzip2 BZIP2=-7’.
dist-gzip
Generate a gzip tar archive of the distribution.
dist-lzma
Generate an ‘ lzma’ tar archive of the distribution. lzmaarchives are frequently smaller than bzip2-compressed archives. The ‘ lzma’ format is obsolete, you should use the ‘ xz’ formatinstead.
dist-shar
Generate a shar archive of the distribution.
dist-xz
Generate an ‘ xz’ tar archive of the distribution. xzarchives are frequently smaller than bzip2-compressed archives. The ‘ xz’ format displaces the obsolete ‘ lzma’ format. By default, this rule makes ‘ xz’ use a compression option of -e. To make it use a different one, set the XZ_OPTenvironment variable. For example, run this command to use thedefault compression ratio, but with a progress indicator:‘ make dist-xz XZ_OPT=-7e’.
dist-zip
Generate a zip archive of the distribution.
dist-tarZ
Generate a compressed tar archive ofthe distribution.

The rule dist (and its historical synonym dist-all) willcreate archives in all the enabled formats,Options. Bydefault, only the dist-gzip target is hooked todist.

Next:  ,Previous:  Dist,Up:  Top

15 Support for test suites

Automake supports three forms of test suites, the first two of whichare very similar.

Next:  ,Up:  Tests

15.1 Simple Tests

If the variable TESTS is defined, its value is taken to be alist of programs or scripts to run in order to do the testing. Programs needing data files should look for them insrcdir(which is both an environment variable and a make variable) so theywork when building in a separate directory (seeBuild Directories), and inparticular for thedistcheck rule (see Checking the Distribution).

For each of the TESTS, the result of execution is printed alongwith the test name, wherePASS denotes a successful test,FAIL denotes a failed test,XFAIL an expected failure,XPASS an unexpected pass for a test that is supposed to fail,andSKIP denotes a skipped test.

The number of failures will be printed at the end of the run. If agiven test program exits with a status of 77, then its result is ignoredin the final count. This feature allows non-portable tests to beignored in environments where they don't make sense.

If the Automake option color-tests is used (seeOptions)and standard output is connected to a capable terminal, then the testresults and the summary are colored appropriately. The user can disablecolored output by setting themake variable‘AM_COLOR_TESTS=no’, or force colored output even without a connectingterminal with ‘AM_COLOR_TESTS=always’.

Note that the semantics of some make implementations when usedin parallel mode (seeParallel make)can cause the automatic detection of a connection to a capable terminalto fail. In that case, you can still resort to the use of‘AM_COLOR_TESTS=always’.

The variableTESTS_ENVIRONMENT can be used to set environmentvariables for the test run; the environment variablesrcdir isset in the rule. If all your test programs are scripts, you can alsosetTESTS_ENVIRONMENT to an invocation of the shell (e.g. ‘$(SHELL) -x’ can be useful for debugging the tests), or any otherinterpreter. For instance, the following setup may be used to run testswith Perl:

     TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
     TESTS = foo.pl bar.pl baz.pl

Note that the parallel-tests driver provides a more elegantway to achieve the same effect, freeing theTESTS_ENVIRONMENTvariable for the user to override (see Simple Tests using parallel-tests).

You may define the variableXFAIL_TESTS to a list of tests(usually a subset of TESTS) that are expected to fail. This willreverse the result of those tests.

Automake ensures that each file listed in TESTS is built beforeany tests are run; you can list both source and derived programs (orscripts) inTESTS; the generated rule will look both insrcdir and .. For instance, you might want to run a Cprogram as a test. To do this you would list its name inTESTSand also in check_PROGRAMS, and then specify it as you wouldany other program.

Programs listed in check_PROGRAMS (and check_LIBRARIES,check_LTLIBRARIES...) are only built duringmake check,not during make all. You should list there any program neededby your tests that does not need to be built bymake all. Notethat check_PROGRAMS are not automatically added toTESTS becausecheck_PROGRAMS usually lists programs usedby the tests, not the tests themselves. Of course you can setTESTS = $(check_PROGRAMS) if all your programs are test cases.

Next:  ,Previous:  Simple Tests,Up:  Tests

15.2 Simple Tests using ‘parallel-tests’

The optionparallel-tests (see Options) enables a testsuite driver that is mostly compatible to the simple test driver describedin the previous section, but provides a few more features and slightly differentsemantics. It features concurrent execution of tests with make -j,allows to specify inter-test dependencies, lazy reruns of tests thathave not completed in a prior run, summary and verbose output in‘RST’ (reStructuredText) and ‘HTML’ format, and hard errorsfor exceptional failures. Similar to the simple test driver,TESTS_ENVIRONMENT,AM_COLOR_TESTS, XFAIL_TESTS, andthe check_* variables are honored, and the environment variablesrcdir is set during test execution.

This test driver is still experimental and may undergo changes in orderto satisfy additional portability requirements.

The driver operates by defining a set ofmake rules to createa summary log file,TEST_SUITE_LOG, which defaults totest-suite.log and requires a.log suffix. This filedepends upon log files created for each single test program listed inTESTS, which in turn contain all output produced by thecorresponding tests.

Each log file is created when the corresponding test has completed. The set of log files is listed in the read-only variableTEST_LOGS, and defaults toTESTS, with the executableextension if any (see EXEEXT), as well as any suffix listed inTEST_EXTENSIONS removed, and.log appended. Resultsare undefined if a test file name ends in several concatenated suffixes.TEST_EXTENSIONS defaults to .test; it can be overridden bythe user, in which case any extension listed in it must be constitutedby a dot, followed by a non-digit alphabetic character, followed by anynumber of alphabetic characters. For example, ‘.sh’, ‘.T’ and ‘.t1’ are valid extensions,while ‘.x-y’, ‘.6c’ and ‘.t.1’ are not.

For tests that match an extension .ext listed inTEST_EXTENSIONS, you can provide a test driver using the variableext_LOG_COMPILER (note the upper-case extension) and passoptions inAM_ext_LOG_FLAGS and allow the user to passoptions inext_LOG_FLAGS. It will cause all tests withthis extension to be called with this driver. For all tests without aregistered extension, the variablesLOG_COMPILER,AM_LOG_FLAGS, and LOG_FLAGS may be used. For example,

     TESTS = foo.pl bar.py baz
     TEST_EXTENSIONS = .pl .py
     PL_LOG_COMPILER = $(PERL)
     AM_PL_LOG_FLAGS = -w
     PY_LOG_COMPILER = $(PYTHON)
     AM_PY_LOG_FLAGS = -v
     LOG_COMPILER = ./wrapper-script
     AM_LOG_FLAGS = -d

will invoke ‘$(PERL) -w foo.pl’, ‘$(PYTHON) -v bar.py’,and ‘./wrapper-script -d baz’ to producefoo.log,bar.log, andbaz.log, respectively. The‘TESTS_ENVIRONMENT’ variable is still expanded before the driver,but should be reserved for the user.

As with the simple driver above, by default one status line is printedper completed test, and a short summary after the suite has completed. However, standard output and standard error of the test are redirectedto a per-test log file, so that parallel execution does not produceintermingled output. The output from failed tests is collected in thetest-suite.log file. If the variable ‘VERBOSE’ is set, thisfile is output after the summary. For best results, the tests should beverbose by default now.

Withmake check-html, the log files may be converted from RST(reStructuredText, seehttp://docutils.sourceforge.net/rst.html)to HTML using ‘RST2HTML’, which defaults torst2html orrst2html.py. The variable ‘TEST_SUITE_HTML’ contains theset of converted log files. The log and HTML files are removed uponmake mostlyclean.

Even in the presence of expected failures (seeXFAIL_TESTS), theremay be conditions under which a test outcome needs attention. Forexample, with test-driven development, you may write tests for featuresthat you have not implemented yet, and thus mark these tests as expectedto fail. However, you may still be interested in exceptional conditions,for example, tests that fail due to a segmentation violation or anothererror that is independent of the feature awaiting implementation. Tests can exit with an exit status of 99 to signal such aharderror. Unless the variable DISABLE_HARD_ERRORS is set to anonempty value, such tests will be counted as failed.

By default, the test suite driver will run all tests, but there areseveral ways to limit the set of tests that are run:

  • You can set the TESTS variable, similarly to how you can withthe simple test driver from the previous section. For example, you canuse a command like this to run only a subset of the tests: 
              env TESTS="foo.test bar.test" make -e check

    Note however that the command above will unconditionally overwrite thetest-suite.log file, thus clobbering the recorded resultsof any previous testsuite run. This might be undesirable for packageswhose testsuite takes long time to execute. Luckily, this problem caneasily be avoided by overriding alsoTEST_SUITE_LOG at runtime;for example, 

              env TEST_SUITE_LOG=partial.log TESTS="..." make -e check

    will write the result of the partial testsuite runs to thepartial.log, without touchingtest-suite.log.

  • You can set the TEST_LOGS variable. By default, this variable iscomputed atmake run time from the value of TESTS asdescribed above. For example, you can use the following: 
              set x subset*.log; shift
          env TEST_LOGS="foo.log $*" make -e check

    The comments made above about TEST_SUITE_LOG overriding applieshere too.

  • By default, the test driver removes all old per-test log files before itstarts running tests to regenerate them. The variableRECHECK_LOGS contains the set of log files which are removed. RECHECK_LOGS defaults to TEST_LOGS, which means all testsneed to be rechecked. By overriding this variable, you can choose whichtests need to be reconsidered. For example, you can lazily rerun onlythose tests which are outdated, i.e., older than their prerequisite testfiles, by setting this variable to the empty value: 
              env RECHECK_LOGS= make -e check
  • You can ensure that all tests are rerun which have failed or passedunexpectedly, by runningmake recheck in the test directory. This convenience target will setRECHECK_LOGS appropriatelybefore invoking the main test driver. The recheck-html targetdoes the same as recheck but again converts the resulting logfile in HTML format, like thecheck-html target.

In order to guarantee an ordering between tests even with make-jN, dependencies between the corresponding log files may bespecified through usualmake dependencies. For example, thefollowing snippet lets the test namedfoo-execute.test dependupon completion of the testfoo-compile.test:

     TESTS = foo-compile.test foo-execute.test
     foo-execute.log: foo-compile.log

Please note that this ordering ignores the results of requiredtests, thus the testfoo-execute.test is run even if the testfoo-compile.test failed or was skipped beforehand. Further,please note that specifying such dependencies currently works only fortests that end in one of the suffixes listed in TEST_EXTENSIONS.

Tests without such specified dependencies may be run concurrently withparallelmake -jN, so be sure they are prepared forconcurrent execution.

The combination of lazy test execution and correct dependencies betweentests and their sources may be exploited for efficient unit testingduring development. To further speed up the edit-compile-test cycle, itmay even be useful to specify compiled programs in EXTRA_PROGRAMSinstead of withcheck_PROGRAMS, as the former allows intertwinedcompilation and test execution (but note thatEXTRA_PROGRAMS arenot cleaned automatically, see Uniform).

The variables TESTS and XFAIL_TESTS may containconditional parts as well as configure substitutions. In the lattercase, however, certain restrictions apply: substituted test namesmust end with a nonempty test suffix like.test, so that one ofthe inference rules generated byautomake can apply. Forliteral test names,automake can generate per-target rulesto avoid this limitation.

Please note that it is currently not possible to use $(srcdir)/or$(top_srcdir)/ in the TESTS variable. This technicallimitation is necessary to avoid generating test logs in the source treeand has the unfortunate consequence that it is not possible to specifydistributed tests that are themselves generated by means of explicitrules, in a way that is portable to all make implementations(seeMake Target Lookup, thesemantics of FreeBSD and OpenBSDmake conflict with this). In case of doubt you may want to require to use GNUmake,or work around the issue with inference rules to generate the tests.

Next:  ,Previous:  Simple Tests using parallel-tests,Up:  Tests

15.3 DejaGnu Tests

If dejagnu appears inAUTOMAKE_OPTIONS, then adejagnu-based test suite isassumed. The variableDEJATOOL is a list of names that arepassed, one at a time, as the --tool argument toruntest invocations; it defaults to the name of the package.

The variable RUNTESTDEFAULTFLAGS holds the --tool and--srcdir flags that are passed to dejagnu by default; this can beoverridden if necessary.The variables EXPECT andRUNTEST canalso be overridden to provide project-specific values. For instance,you will need to do this if you are testing a compiler toolchain,because the default values do not take into account host and targetnames.The contents of the variableRUNTESTFLAGS are passed to theruntest invocation. This is considered a “user variable”(seeUser Variables). If you need to set runtest flags inMakefile.am, you can useAM_RUNTESTFLAGS instead. Automake will generate rules to create a localsite.exp file,defining various variables detected byconfigure. This fileis automatically read by DejaGnu. It is OK for the user of a packageto edit this file in order to tune the test suite. However this isnot the place where the test suite author should define new variables:this should be done elsewhere in the real test suite code. Especially, site.exp should not be distributed.

Still, if the package author has legitimate reasons to extendsite.exp atmake time, he can do so by definingthe variableEXTRA_DEJAGNU_SITE_CONFIG; the files listedthere will be considered site.exp prerequisites, and theircontent will be appended to it (in the same order in which theyappear inEXTRA_DEJAGNU_SITE_CONFIG). Note that files arenot distributed by default.

For more information regarding DejaGnu test suites, see Top.

In either case, the testing is done via ‘make check’.

Previous:  DejaGnu Tests,Up:  Tests

15.4 Install Tests

The installcheck target is available to the user as a way torun any tests after the package has been installed. You can add teststo this by writing aninstallcheck-local rule.

Next:  ,Previous:  Tests,Up:  Top

16 Rebuilding Makefiles

Automake generates rules to automatically rebuildMakefiles,configure, and other derived files likeMakefile.in.

If you are using AM_MAINTAINER_MODE inconfigure.ac, thenthese automatic rebuilding rules are only enabled in maintainer mode.

Sometimes you need to run aclocal with an argument like-I to tell it where to find.m4 files. Sincesometimes make will automatically runaclocal, youneed a way to specify these arguments. You can do this by definingACLOCAL_AMFLAGS; this holds arguments that are passed verbatimtoaclocal. This variable is only useful in the top-levelMakefile.am.

Sometimes it is convenient to supplement the rebuild rules forconfigure orconfig.status with additional dependencies. The variablesCONFIGURE_DEPENDENCIES andCONFIG_STATUS_DEPENDENCIES can be used to list these extradependencies. These variables should be defined in allMakefiles of the tree (because these two rebuild rules areoutput in all them), so it is safer and easier to AC_SUBST themfromconfigure.ac. For instance, the following statement willcauseconfigure to be rerun each time version.sh ischanged.

     AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])

Note the ‘$(top_srcdir)/’ in the file name. Since this variableis to be used in allMakefiles, its value must be sensible atany level in the build hierarchy.

Beware not to mistake CONFIGURE_DEPENDENCIES forCONFIG_STATUS_DEPENDENCIES.

CONFIGURE_DEPENDENCIES adds dependencies to theconfigure rule, whose effect is to runautoconf. Thisvariable should be seldom used, becauseautomake already tracksm4_included files. However it can be useful when playingtricky games withm4_esyscmd or similar non-recommendablemacros with side effects.

CONFIG_STATUS_DEPENDENCIES adds dependencies to theconfig.status rule, whose effect is to runconfigure. This variable should therefore carry any non-standard source that maybe read as a side effect of runningconfigure, like version.shin the example above.

Speaking of version.sh scripts, we recommend against themtoday. They are mainly used when the version of a package is updatedautomatically by a script (e.g., in daily builds). Here is what someold-styleconfigure.acs may look like:

     AC_INIT
     . $srcdir/version.sh
     AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
     ...

Here, version.sh is a shell fragment that setsVERSION_NUMBER. The problem with this example is thatautomake cannot track dependencies (listingversion.shin CONFIG_STATUS_DEPENDENCIES, and distributing this file is upto the user), and that it uses the obsolete form ofAC_INIT andAM_INIT_AUTOMAKE. Upgrading to the new syntax is notstraightforward, because shell variables are not allowed inAC_INIT's arguments. We recommend thatversion.sh bereplaced by an M4 file that is included byconfigure.ac:

     m4_include([version.m4])
     AC_INIT([name], VERSION_NUMBER)
     AM_INIT_AUTOMAKE
     ...

Here version.m4 could contain something like‘m4_define([VERSION_NUMBER], [1.2])’. The advantage of thissecond form is thatautomake will take care of thedependencies when defining the rebuild rule, and will also distributethe file automatically. An inconvenience is thatautoconfwill now be rerun each time the version number is bumped, when onlyconfigure had to be rerun in the previous setup.

Next:  ,Previous:  Rebuilding,Up:  Top

17 Changing Automake's Behavior

Various features of Automake can be controlled by options. Except wherenoted otherwise, options can be specified in one of several ways: Mostoptions can be applied on a per-Makefile basis when listed in aspecialMakefile variable named AUTOMAKE_OPTIONS. Someof these options only make sense when specified in the toplevelMakefile.am file. Options are applied globally to all processedMakefile files when listed in the first argument ofAM_INIT_AUTOMAKE in configure.ac, and some options whichrequire changes to theconfigure script can only be specifiedthere. These are annotated below.

Currently understood options are:

gnits gnu foreign cygnus
Set the strictness as appropriate. The gnits option alsoimplies options readme-alpha and check-news.
ansi2knr path/ansi2knr
Turn on the deprecated de-ANSI-fication feature (see ANSI). Notethat that feature and this option will be removed in the nextmajor Automake release.

If preceded by apath, the generated Makefile.in will look in the specifieddirectory to find theansi2knr program. The path should be arelative path to another directory in the same distribution (Automakedoes not check this).

check-news
Cause ‘ make dist’ to fail unless the current version number appearsin the first few lines of the NEWS file.
color-tests
Cause output of the simple test suite (see Simple Tests) to becolorized on capable terminals.
dejagnu
Cause dejagnu-specific rules to be generated. See DejaGnu Tests.
dist-bzip2
Hook dist-bzip2 to dist.
dist-lzma
Hook dist-lzma to dist. Obsoleted by dist-xz.
dist-shar
Hook dist-shar to dist.
dist-zip
Hook dist-zip to dist.
dist-tarZ
Hook dist-tarZ to dist.
filename-length-max=99
Abort if file names longer than 99 characters are found during‘ make dist’. Such long file names are generally considered not tobe portable in tarballs. See the tar-v7 and tar-ustaroptions below. This option should be used in the top-level Makefile.am or as an argument of AM_INIT_AUTOMAKE in configure.ac, it will be ignored otherwise. It will also beignored in sub-packages of nested packages (see Subpackages).
no-define
This option is meaningful only when passed as an argument to AM_INIT_AUTOMAKE. It will prevent the PACKAGE and VERSION variables from being AC_DEFINEd.
no-dependencies
This is similar to using --ignore-deps on the command line,but is useful for those situations where you don't have the necessarybits to make automatic dependency tracking work(see Dependencies). In this case the effect is to effectivelydisable automatic dependency tracking.
no-dist
Don't emit any code related to dist target. This is usefulwhen a package has its own method for making distributions.
no-dist-gzip
Do not hook dist-gzip to dist.
no-exeext
If your Makefile.am defines a rule for target foo, itwill override a rule for a target named ‘ foo$(EXEEXT)’. This isnecessary when EXEEXT is found to be empty. However, bydefault automake will generate an error for this use. The no-exeext option will disable this error. This is intended foruse only where it is known in advance that the package will not beported to Windows, or any other operating system using extensions onexecutables.
no-installinfo
The generated Makefile.in will not cause info pages to be builtor installed by default. However, info and install-infotargets will still be available. This option is disallowed at gnu strictness and above.
no-installman
The generated Makefile.in will not cause man pages to beinstalled by default. However, an install-man target will stillbe available for optional installation. This option is disallowed at gnu strictness and above.
nostdinc
This option can be used to disable the standard -I options thatare ordinarily automatically provided by Automake.
no-texinfo.tex
Don't require texinfo.tex, even if there are texinfo files inthis directory.
parallel-tests
Enable test suite driver for TESTS that can run tests in parallel(see Simple Tests using parallel-tests, for more information).
readme-alpha
If this release is an alpha release, and the file README-alphaexists, then it will be added to the distribution. If this option isgiven, version numbers are expected to follow one of two forms. Thefirst form is ‘ major.minor.alpha’, where eachelement is a number; the final period and number should be left off fornon-alpha releases. The second form is‘ major.minoralpha’, where alpha is aletter; it should be omitted for non-alpha releases.
silent-rules
Enable less verbose build rules. This can be used to let build rulesoutput status lines of the form: 
          GEN output-file
           CC object-file

instead of printing the command that will be executed to updateoutput-file or to compileobject-file. It can alsosilence libtool output.

For more information about how to use, enable, or disable silentrules, see Automake silent-rules Option.

std-options
Make the installcheck rule check that installed scripts andprograms support the --help and --version options. This also provides a basic check that the program'srun-time dependencies are satisfied after installation.

In a few situations, programs (or scripts) have to be exempted from thistest. For instance,false (from GNU coreutils) is neversuccessful, even for--help or --version. You can listsuch programs in the variableAM_INSTALLCHECK_STD_OPTIONS_EXEMPT. Programs (not scripts) listed in this variable should be suffixed by‘$(EXEEXT)’ for the sake of Win32 or OS/2. For instance, suppose webuildfalse as a program but true.sh as a script, and thatneither of them support--help or --version:

          AUTOMAKE_OPTIONS = std-options
          bin_PROGRAMS = false ...
          bin_SCRIPTS = true.sh ...
          AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh

subdir-objects
If this option is specified, then objects are placed into thesubdirectory of the build directory corresponding to the subdirectory ofthe source file. For instance, if the source file is subdir/file.cxx, then the output file would be subdir/file.o.

In order to use this option with C sources, you should addAM_PROG_CC_C_O toconfigure.ac.


tar-v7 tar-ustar tar-pax
These three mutually exclusive options select the tar format to usewhen generating tarballs with ‘ make dist’. (The tar file createdis then compressed according to the set of no-dist-gzip, dist-bzip2, dist-xz and dist-tarZ options in use.)

These options must be passed as arguments to AM_INIT_AUTOMAKE(seeMacros) because they can require additional configure checks. Automake will complain if it sees such options in anAUTOMAKE_OPTIONS variable.

tar-v7 selects the old V7 tar format. This is the historicaldefault. This antiquated format is understood by all tarimplementations and supports file names with up to 99 characters. Whengiven longer file names some tar implementations will diagnose theproblem while other will generate broken tarballs or use non-portableextensions. Furthermore, the V7 format cannot store emptydirectories. When using this format, consider using thefilename-length-max=99 option to catch file names too long.

tar-ustar selects the ustar format defined by POSIX1003.1-1988. This format is believed to be old enough to be portable. It fully supports empty directories. It can store file names with upto 256 characters, provided that the file name can be split atdirectory separator in two parts, first of them being at most 155bytes long. So, in most cases the maximum file name length will beshorter than 256 characters. However you may run against broken tarimplementations that incorrectly handle file names longer than 99characters (please report them to bug-automake@gnu.org so wecan document this accurately).

tar-pax selects the new pax interchange format defined by POSIX1003.1-2001. It does not limit the length of file names. However,this format is very young and should probably be restricted topackages that target only very modern platforms. There are moves tochange the pax format in an upward-compatible way, so this option mayrefer to a more recent version in the future.

See Controlling the Archive Format, forfurther discussion about tar formats.

configure knows several ways to construct these formats. Itwill not abort if it cannot find a tool up to the task (so that thepackage can still be built), but ‘make dist’ will fail.

version
A version number (e.g., ‘ 0.30’) can be specified. If Automake is notnewer than the version specified, creation of the Makefile.inwill be suppressed.
-Wcategory or --warnings=category
These options behave exactly like their command-line counterpart(see Invoking Automake). This allows you to enable or disable somewarning categories on a per-file basis. You can also setup some warningsfor your entire project; for instance, try ‘ AM_INIT_AUTOMAKE([-Wall])’in your configure.ac.

Unrecognized options are diagnosed by automake.

If you want an option to apply to all the files in the tree, you can usethe AM_INIT_AUTOMAKE macro in configure.ac. SeeMacros.

Next:  ,Previous:  Options,Up:  Top

18 Miscellaneous Rules

There are a few rules and variables that didn't fit anywhere else.

  • Tags: Interfacing to etags and mkid
  • Suffixes: Handling new file extensions
  • Multilibs: Support for multilibs.

Next:  ,Up:  Miscellaneous

18.1 Interfacing to etags

Automake will generate rules to generateTAGS files for use withGNU Emacs under some circumstances.

If any C, C++ or Fortran 77 source code or headers are present, thentags andTAGS rules will be generated for the directory. All files listed using the_SOURCES, _HEADERS, and_LISP primaries will be used to generate tags. Note thatgenerated source files that are not distributed must be declared invariables likenodist_noinst_HEADERS ornodist_prog_SOURCES or they will be ignored.

A tags rule will be output at the topmost directory of amulti-directory package. When run from this topmost directory,‘make tags’ will generate aTAGS file that includes byreference all TAGS files from subdirectories.

The tags rule will also be generated if the variableETAGS_ARGS is defined. This variable is intended for use indirectories that contain taggable source thatetags doesnot understand. The user can use theETAGSFLAGS to passadditional flags to etags;AM_ETAGSFLAGS is alsoavailable for use in Makefile.am.Here is how Automake generates tags for its source, and for nodes in itsTexinfo file:

     ETAGS_ARGS = automake.in --lang=none \
      --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi

If you add file names to ETAGS_ARGS, you will probably alsowant to defineTAGS_DEPENDENCIES. The contents of this variableare added directly to the dependencies for thetags rule. Automake also generates actags rule that can be used tobuild vi-styletags files. The variable CTAGSis the name of the program to invoke (by defaultctags);CTAGSFLAGS can be used by the user to pass additional flags,andAM_CTAGSFLAGS can be used by the Makefile.am.

Automake will also generate an ID rule that will runmkid on the source. This is only supported on adirectory-by-directory basis.Finally, Automake also emits rules to support theGNU Global Tags program. TheGTAGS rule runs Global Tags and puts theresult in the top build directory. The variableGTAGS_ARGSholds arguments that are passed to gtags.

Next:  ,Previous:  Tags,Up:  Miscellaneous

18.2 Handling new file extensions

It is sometimes useful to introduce a new implicit rule to handle a filetype that Automake does not know about.

For instance, suppose you had a compiler that could compile .foofiles to.o files. You would simply define a suffix rule foryour language:

     .foo.o:
             foocc -c -o $@ $<

Then you could directly use a .foo file in a_SOURCESvariable and expect the correct results:

     bin_PROGRAMS = doit
     doit_SOURCES = doit.foo

This was the simpler and more common case. In other cases, you willhave to help Automake to figure out which extensions you are defining yoursuffix rule for. This usually happens when your extension does notstart with a dot. Then, all you have to do is to put a list of newsuffixes in the SUFFIXES variable before you define yourimplicit rule.

For instance, the following definition prevents Automake from misinterpretingthe ‘.idlC.cpp:’ rule as an attempt to transform.idlC files into.cpp files.

     SUFFIXES = .idl C.cpp
     .idlC.cpp:
             # whatever

As you may have noted, the SUFFIXES variable behaves like the.SUFFIXES special target ofmake. You should not touch.SUFFIXES yourself, but useSUFFIXES instead and letAutomake generate the suffix list for .SUFFIXES. Any givenSUFFIXES go at the start of the generated suffixes list, followedby Automake generated suffixes not already in the list.

Previous:  Suffixes,Up:  Miscellaneous

18.3 Support for Multilibs

Automake has support for an obscure feature called multilibs. Amultilib is a library that is built for multiple different ABIsat a single time; each time the library is built with a different targetflag combination. This is only useful when the library is intended tobe cross-compiled, and it is almost exclusively used for compilersupport libraries.

The multilib support is still experimental. Only use it if you arefamiliar with multilibs and can debug problems you might encounter.

Next:  ,Previous:  Miscellaneous,Up:  Top

19 Include

Automake supports aninclude directive that can be used toinclude other Makefile fragments whenautomake is run. Note that these fragments are read and interpreted byautomake,not by make. As with conditionals,make has no idea thatinclude is in use.

There are two forms of include:

include $(srcdir)/file
Include a fragment that is found relative to the current sourcedirectory.
include $(top_srcdir)/file
Include a fragment that is found relative to the top source directory.

Note that if a fragment is included inside a conditional, then thecondition applies to the entire contents of that fragment.

Makefile fragments included this way are always distributed becausethey are needed to rebuildMakefile.in.

Next:  ,Previous:  Include,Up:  Top

20 Conditionals

Automake supports a simple type of conditionals.

These conditionals are not the same as conditionals inGNU Make. Automake conditionals are checked at configure time by theconfigure script, and affect the translation fromMakefile.in to Makefile. They are based on options passedtoconfigure and on results that configure has discoveredabout the host system. GNU Make conditionals are checked atmaketime, and are based on variables passed to the make program or definedin theMakefile.

Automake conditionals will work with any make program.

Next:  ,Up:  Conditionals

20.1 Usage of Conditionals

Before using a conditional, you must define it by usingAM_CONDITIONAL in theconfigure.ac file (see Macros).

— Macro: AM_CONDITIONAL ( conditional, condition)

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

The shell condition (suitable for use in a shell ifstatement) is evaluated whenconfigure is run. Note that youmust arrange forevery AM_CONDITIONAL to be invoked everytime configure is run. IfAM_CONDITIONAL is runconditionally (e.g., in a shell if statement), then the resultwill confuseautomake.

Conditionals typically depend upon options that the user provides tothe configure script. Here is an example of how to write aconditional that is true if the user uses the--enable-debugoption.

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

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

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

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

You may only test a single variable in an if statement, possiblynegated using ‘!’. Theelse statement may be omitted. Conditionals may be nested to any depth. You may specify an argument toelse in which case it must be the negation of the condition usedfor the currentif. Similarly you may specify the conditionthat is closed on the endif line:

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

Unbalanced conditions are errors. The if, else, andendif statements should not be indented, i.e., start on columnone.

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

In order to allow access to the condition registered byAM_CONDITIONAL insideconfigure.ac, and to allowconditional AC_CONFIG_FILES, AM_COND_IF may be used:

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

If conditional is fulfilled, execute if-true, otherwiseexecuteif-false. If either branch contains AC_CONFIG_FILES,it will causeautomake to output the rules for the respectivefiles only for the given condition.

AM_COND_IF macros may be nested when m4 quotation is usedproperly (seeM4 Quotation).

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

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

Previous:  Usage of Conditionals,Up:  Conditionals

20.2 Limits of Conditionals

Conditionals should enclose complete statements like variables orrules definitions. Automake cannot deal with conditionals used insidea variable definition, for instance, and is not even able to diagnosethis situation. The following example would not work:

     # This syntax is not understood by Automake
     AM_CPPFLAGS = \
       -DFEATURE_A \
     if WANT_DEBUG
       -DDEBUG \
     endif
       -DFEATURE_B

However the intended definition of AM_CPPFLAGS can be achievedwith

     if WANT_DEBUG
       DEBUGFLAGS = -DDEBUG
     endif
     AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B

or

     AM_CPPFLAGS = -DFEATURE_A
     if WANT_DEBUG
     AM_CPPFLAGS += -DDEBUG
     endif
     AM_CPPFLAGS += -DFEATURE_B

More details and examples of conditionals are described alongsidevarious Automake features in this manual (seeConditional Subdirectories, see Conditional Sources, see Conditional Programs, seeConditional Libtool Libraries, see Conditional Libtool Sources).

Next:  ,Previous:  Conditionals,Up:  Top

21 Silencing make

Next:  ,Up:  Silencing Make

21.1 Make is verbose by default

Normally, when executing the set of rules associated with a target,make prints each rule before it is executed. This behaviour,while having been in place for a long time, and being even mandated bythe POSIX standard, starkly violates the “silence is golden” UNIXprinciple8:

When a program has nothing interesting or surprising to say, it shouldsay nothing. Well-behaved Unix programs do their jobs unobtrusively,with a minimum of fuss and bother. Silence is golden.

In fact, while such verbosity of make can theoretically beuseful to track bugs and understand reasons of failures right away, itcan also hide warning and error messages frommake-invokedtools, drowning them in a flood of uninteresting and seldom usefulmessages, and thus allowing them to go easily undetected.

This problem can be very annoying, especially for developers, who usuallyknow quite well what's going on behind the scenes, and for whom theverbose output frommake ends up being mostly noise that hampersthe easy detection of potentially important warning messages.

Next:  ,Previous:  Make verbosity,Up:  Silencing Make

21.2 Standard and generic ways to silence make

Here we describe some common idioms/tricks to obtain a quieter makeoutput, with their relative advantages and drawbacks. In the nextsection (Automake silent-rules Option) we'll see how Automakecan help in this respect.

  • make -s

    This simply causes make not to printany rule beforeexecuting it.

    The -s flag is mandated by POSIX, universally supported, andits purpose and function are easy to understand.

    But it also has its serious limitations too. First of all, it embodiesan “all or nothing” strategy, i.e., either everything is silenced, ornothing is; this lack of granularity can sometimes be a fatal flaw. Moreover, when the-s flag is used, the make outputmight turn out to be too much terse; in case of errors, the user won'tbe able to easily see what rule or command have caused them, or even,in case of tools with poor error reporting, what the errors were!

  • make >/dev/null || make

    Apparently, this perfectly obeys the “silence is golden” rule: warningsfrom stderr are passed through, output reporting is done only in case oferror, and in that case it should provide a verbose-enough report to allowan easy determination of the error location and causes.

    However, calling make two times in a row might hide errors(especially intermittent ones), or subtly change the expected semanticof themake calls — things these which can clearly makedebugging and error assessment very difficult.

  • make --no-print-directory

    This is GNU make specific. When called with the--no-print-directory option, GNUmake will disableprinting of the working directory by invoked sub-makes (thewell-known “Entering/Leaving directory ...” messages). This helpsto decrease the verbosity of the output, but experience has shown thatit can also often render debugging considerably harder in projects usingdeeply-nestedmake recursion.

    As an aside, notice that the --no-print-directory option isautomatically activated if the-s flag is used.

Previous:  Tricks For Silencing Make,Up:  Silencing Make

21.3 How Automake can help in silencing make

The tricks and idioms for silencing make described in theprevious section can be useful from time to time, but we've seen thatthey all have their serious drawbacks and limitations. That's whyautomake provides support for a more advanced and flexible way ofobtaining quieter output from make: thesilent-rulesmode.

To give the gist of what silent-rules can do, here is a simplecomparison between a typicalmake output (where silent rulesare disabled) and one with silent rules enabled:

     % cat Makefile.am
     bin_PROGRAMS = foo
     foo_SOURCES = main.c func.c
     % cat main.c
     int main (void) { return func (); }  /* func used undeclared */
     % cat func.c
     int func (void) { int i; return i; } /* i used uninitialized */
     
     The make output is by default very verbose.  This causes warnings
     from the compiler to be somewhat hidden, and not immediate to spot.
     % make CFLAGS=-Wall
     gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
     -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
     -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
     -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
     main.c: In function ‘main’:
     main.c:3:3: warning: implicit declaration of function ‘func’
     mv -f .deps/main.Tpo .deps/main.Po
     gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
     -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
     -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
     -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
     func.c: In function ‘func’:
     func.c:4:3: warning: ‘i’ used uninitialized in this function
     mv -f .deps/func.Tpo .deps/func.Po
     gcc -Wall -o foo main.o func.o
     
     Clean up, so that we we can rebuild everything from scratch.
     % make clean
     test -z "foo" || rm -f foo
     rm -f *.o
     
     Silent rules enabled: the output is minimal but informative.  In
     particular, the warnings from the compiler stick out very clearly.
     % make V=0 CFLAGS=-Wall
       CC     main.o
     main.c: In function ‘main’:
     main.c:3:3: warning: implicit declaration of function ‘func’
       CC     func.o
     func.c: In function ‘func’:
     func.c:4:3: warning: ‘i’ used uninitialized in this function
       CCLD   foo

Also, in projects using libtool, the use of silent rules canautomatically enable thelibtool's --silent option:

     % cat Makefile.am
     lib_LTLIBRARIES = libx.la
     
     % make # Both make and libtool are verbose by default.
     ...
     libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
       -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
       -DPIC -o .libs/libx.o
     mv -f .deps/libx.Tpo .deps/libx.Plo
     /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
       /usr/local/lib libx.lo
     libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
       -o .libs/libx.so.0.0.0
     libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
     ...
     
     % make V=0
       CC     libx.lo
       CCLD   libx.la

Let's now see how the silent-rules mode interfaces with thepackage developer and the package user.

To enable the use of silent-rules in his package, a developerneeds to do either of the following:

  • Add the silent-rules option as argument toAM_INIT_AUTOMAKE.
  • Call the AM_SILENT_RULES macro from within the configure.acfile.

It is not possible to instead specify silent-rules in aMakefile.am file.

If the developer has done either of the above, then the user of thepackage may influence the verbosity atconfigure run time aswell as at make run time:

  • Passing--enable-silent-rules to configure will causebuild rules to be less verbose; the option--disable-silent-ruleswill cause normal verbose output.
  • At make run time, the default chosen atconfiguretime may be overridden: make V=1 will produce verbose output,make V=0 less verbose output.

Note that silent rules aredisabled by default; the user mustenable them explicitly at either configure run time or atmake run time. We think that this is a good policy, sinceit provides the casual user with enough information to prepare a goodbug report in case anything breaks.

Still, notwithstanding the rationales above, a developer who wants tomake silent rules enabled by default in his own package can do so byadding a ‘yes’ argument to theAM_SILENT_RULES call inconfigure.ac. We advise against this approach, though.

Users who prefer to have silent rules enabled by default can edit theirconfig.site file to make the variableenable_silent_rulesdefault to ‘yes’. This should still allow disabling silent rulesatconfigure time and at make time.

For portability to different make implementations, package authorsare advised to not set the variableV inside the Makefile.amfile, to allow the user to override the value for subdirectories as well.

The current implementation of this feature relies on a non-POSIX, but inpractice rather widely supportedMakefile construct of nestedvariable expansion ‘$(var1$(V))’. Do not use thesilent-rules option if your package needs to build withmake implementations that do not support it. Thesilent-rules option turns off warnings about recursive variableexpansion, which are in turn enabled by -Wportability(see Invoking Automake).

To extend the silent mode to your own rules, you have two choices:

  • You can use the predefined variable AM_V_GEN as a prefix tocommands that should output a status line in silent mode, andAM_V_at as a prefix to commands that should not output anythingin silent mode. When output is to be verbose, both of these variableswill expand to the empty string.
  • You can add your own variables, so strings of your own choice are shown. The following snippet shows how you would define your own equivalent ofAM_V_GEN: 
              pkg_verbose = $(pkg_verbose_$(V))
          pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
          pkg_verbose_0 = @echo PKG-GEN $@;
          
          foo: foo.in
                  $(pkg_verbose)cp $(srcdir)/foo.in $@

As a final note, observe that, even when silent rules are enabled,the --no-print-directory option is still required with GNUmake if the “Entering/Leaving directory ...” messagesare to be disabled.

Next:  ,Previous:  Silencing Make,Up:  Top

22 The effect of --gnu and--gnits

The--gnu option (or gnu in theAUTOMAKE_OPTIONS variable) causesautomake to checkthe following:

  • The files INSTALL, NEWS,README, AUTHORS,andChangeLog, plus one of COPYING.LIB,COPYING.LESSERor COPYING, are required at the topmost directory of the package.

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

  • The options no-installman and no-installinfo areprohibited.

Note that this option will be extended in the future to do even morechecking; it is advisable to be familiar with the precise requirementsof the GNU standards. Also,--gnu can require certainnon-standard GNU programs to exist for use by various maintainer-onlyrules; for instance, in the futurepathchk might be required for‘make dist’.

The--gnits option does everything that --gnu does, andchecks the following as well:

  • ‘make installcheck’ will check to make sure that the--helpand --version really print a usage message and a version string,respectively. This is thestd-options option (see Options).
  • ‘make dist’ will check to make sure theNEWS file has beenupdated to the current version.
  • VERSION is checked to make sure its format complies with Gnitsstandards.
  • If VERSION indicates that this is an alpha release, and the fileREADME-alpha appears in the topmost directory of a package, thenit is included in the distribution. This is done in --gnitsmode, and no other, because this mode is the only one where versionnumber formats are constrained, and hence the only mode where Automakecan automatically determine whetherREADME-alpha should beincluded.
  • The file THANKS is required.

Next:  ,Previous:  Gnits,Up:  Top

23 The effect of --cygnus

Some packages, notably GNU GCC and GNU gdb, have a build environmentoriginally written at Cygnus Support (subsequently renamed CygnusSolutions, and then later purchased by Red Hat). Packages with thisancestry are sometimes referred to as “Cygnus” trees.

A Cygnus tree has slightly different rules for how aMakefile.in is to be constructed. Passing--cygnus toautomake will cause any generatedMakefile.in tocomply with Cygnus rules.

Here are the precise effects of --cygnus:

  • Info files are always created in the build directory, and not in thesource directory.
  • texinfo.tex is not required if a Texinfo source file isspecified. The assumption is that the file will be supplied, but in aplace that Automake cannot find. This assumption is an artifact of howCygnus packages are typically bundled.
  • ‘make dist’ is not supported, and the rules for it are notgenerated. Cygnus-style trees use their own distribution mechanism.
  • Certain tools will be searched for in the build tree as well as in theuser's PATH. These tools are runtest,expect,makeinfo andtexi2dvi.
  • --foreign is implied.
  • The options no-installinfo and no-dependencies areimplied.
  • The macro AM_MAINTAINER_MODE is required.
  • The check target doesn't depend on all.

GNU maintainers are advised to use gnu strictness in preferenceto the special Cygnus mode. Some day, perhaps, the differences betweenCygnus trees and GNU trees will disappear (for instance, as GCC is mademore standards compliant). At that time the special Cygnus mode will beremoved.

Next:  ,Previous:  Cygnus,Up:  Top

24 When Automake Isn't Enough

In some situations, where Automake is not up to one task, one has toresort to handwritten rules or even handwrittenMakefiles.

Next:  ,Up:  Not Enough

24.1 Extending Automake Rules

With some minor exceptions (for example _PROGRAMS variables,TESTS, orXFAIL_TESTS) being rewritten to append‘$(EXEEXT)’), the contents of aMakefile.am is copied toMakefile.in verbatim.

These copying semantics mean that many problems can be worked aroundby simply adding somemake variables and rules toMakefile.am. Automake will ignore these additions.

Since aMakefile.in is built from data gathered from threedifferent places (Makefile.am,configure.ac, andautomake itself), it is possible to have conflictingdefinitions of rules or variables. When buildingMakefile.inthe following priorities are respected byautomake to ensurethe user always has the last word:

  • User defined variables in Makefile.am have priority overvariablesAC_SUBSTed from configure.ac, andAC_SUBSTed variables have priority overautomake-defined variables.
  • As far as rules are concerned, a user-defined rule overrides anyautomake-defined rule for the same target.

These overriding semantics make it possible to fine tune some defaultsettings of Automake, or replace some of its rules. OverridingAutomake rules is often inadvisable, particularly in the topmostdirectory of a package with subdirectories. The-Woverrideoption (see Invoking Automake) comes in handy to catch overriddendefinitions.

Note that Automake does not make any distinction between rules withcommands and rules that only specify dependencies. So it is notpossible to append new dependencies to anautomake-definedtarget without redefining the entire rule.

However, various useful targets have a ‘-local’ version you canspecify in yourMakefile.am. Automake will supplement thestandard target with these user-supplied targets.

The targets that support a local version are all, info,dvi,ps, pdf, html, check,install-data,install-dvi, install-exec,install-html, install-info, install-pdf,install-ps, uninstall,installdirs,installcheck and the various clean targets(mostlyclean,clean, distclean, andmaintainer-clean).

Note that there are no uninstall-exec-local oruninstall-data-local targets; just useuninstall-local. It doesn't make sense to uninstall just data or just executables.

For instance, here is one way to erase a subdirectory during‘make clean’ (seeClean).

     clean-local:
             -rm -rf testSubDir

You may be tempted to use install-data-local to install a fileto some hard-coded location, but you should avoid this(seeHard-Coded Install Paths).

With the -local targets, there is no particular guarantee ofexecution order; typically, they are run early, but with parallelmake, there is no way to be sure of that.

In contrast, some rules also have a way to run another rule, called ahook; hooks are always executed after the main rule's work is done. The hook is named after the principal target, with ‘-hook’ appended. The targets allowing hooks are install-data,install-exec, uninstall, dist, anddistcheck.

For instance, here is how to create a hard link to an installed program:

     install-exec-hook:
             ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
                $(DESTDIR)$(bindir)/proglink$(EXEEXT)

Although cheaper and more portable than symbolic links, hard linkswill not work everywhere (for instance, OS/2 does not haveln). Ideally you should fall back to ‘cp -p’ whenln does not work. An easy way, if symbolic links areacceptable to you, is to add AC_PROG_LN_S toconfigure.ac (see Particular Program Checks) and use ‘$(LN_S)’ inMakefile.am.

For instance, here is how you could install a versioned copy of aprogram using ‘$(LN_S)’:

     install-exec-hook:
             cd $(DESTDIR)$(bindir) && \
               mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
               $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)

Note that we rename the program so that a new version will erase thesymbolic link, not the real binary. Also wecd into thedestination directory in order to create relative links.

When writing install-exec-hook or install-data-hook,please bear in mind that the exec/data distinction is based on theinstallation directory, not on the primary used (seeThe Two Parts of Install). So a foo_SCRIPTS will be installed byinstall-data, and abarexec_SCRIPTS will be installed byinstall-exec. You should define your hooks consequently.

Previous:  Extending,Up:  Not Enough

24.2 Third-Party Makefiles

In most projects allMakefiles are generated by Automake. Insome cases, however, projects need to embed subdirectories withhandwrittenMakefiles. For instance, one subdirectory could bea third-party project with its own build system, not using Automake.

It is possible to list arbitrary directories in SUBDIRS orDIST_SUBDIRS provided each of these directories has aMakefile that recognizes all the following recursive targets.

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

all
Compile the entire package. This is the default target inAutomake-generated Makefiles, but it does not need to be thedefault in third-party Makefiles.
distdir
Copy files to distribute into ‘ $(distdir)’, before a tarball isconstructed. Of course this target is not required if the no-dist option (see Options) is used.

The variables ‘$(top_distdir)’ and ‘$(distdir)’(seeThe dist Hook) will be passed from the outer package to the subpackagewhen thedistdir target is invoked. These two variables havebeen adjusted for the directory that is being recursed into, so theyare ready to use.

install install-data install-exec uninstall
Install or uninstall files (see Install).
install-dvi install-html install-info install-ps install-pdf
Install only some specific documentation format (see Texinfo).
installdirs
Create install directories, but do not install any files.
check installcheck
Check the package (see Tests).
mostlyclean clean distclean maintainer-clean
Cleaning rules (see Clean).
dvi pdf ps info html
Build the documentation in various formats (see Texinfo).
tags ctags
Build TAGS and CTAGS (see Tags).

If you have ever used Gettext in a project, this is a good example ofhow third-partyMakefiles can be used with Automake. TheMakefilesgettextize puts in the po/ andintl/ directories are handwrittenMakefiles thatimplement all these targets. That way they can be added toSUBDIRS in Automake packages.

Directories that are only listed in DIST_SUBDIRS but not inSUBDIRS need only thedistclean,maintainer-clean, and distdir rules (seeConditional Subdirectories).

Usually, many of these rules are irrelevant to the third-partysubproject, but they are required for the whole package to work. It'sOK to have a rule that does nothing, so if you are integrating athird-party project with no documentation or tag support, you couldsimply augment its Makefile as follows:

     EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
     .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
     $(EMPTY_AUTOMAKE_TARGETS):

Another aspect of integrating third-party build systems is whetherthey support VPATH builds (seeVPATH Builds). Obviously if thesubpackage does not support VPATH builds the whole package will notsupport VPATH builds. This in turns means that ‘make distcheck’will not work, because it relies on VPATH builds. Some people canlive without this (actually, many Automake users have never heard of‘make distcheck’). Other people may prefer to revamp theexistingMakefiles to support VPATH. Doing so does notnecessarily require Automake, only Autoconf is needed (seeBuild Directories). The necessary substitutions: ‘@srcdir@’, ‘@top_srcdir@’,and ‘@top_builddir@’ are defined by configure when itprocesses aMakefile (see Preset Output Variables), they are notcomputed by the Makefile like the aforementioned ‘$(distdir)’ and‘$(top_distdir)’ variables.

It is sometimes inconvenient to modify a third-party Makefileto introduce the above required targets. For instance, one may want tokeep the third-party sources untouched to ease upgrades to newversions.

Here are two other ideas. If GNU make is assumed, one possibility isto add to that subdirectory aGNUmakefile that defines therequired targets and includes the third-partyMakefile. Forthis to work in VPATH builds,GNUmakefile must lie in the builddirectory; the easiest way to do this is to write aGNUmakefile.in instead, and have it processed withAC_CONFIG_FILES from the outer package. For example if weassume Makefile defines all targets except the documentationtargets, and that thecheck target is actually calledtest, we could write GNUmakefile (orGNUmakefile.in) like this:

     # First, include the real Makefile
     include Makefile
     # Then, define the other targets needed by Automake Makefiles.
     .PHONY: dvi pdf ps info html check
     dvi pdf ps info html:
     check: test

A similar idea that does not useinclude is to write a proxyMakefile that dispatches rules to the realMakefile,either with ‘$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target’ (ifit's OK to rename the originalMakefile) or with ‘cdsubdir && $(MAKE) $(AM_MAKEFLAGS) target’ (if it's OK to store thesubdirectory project one directory deeper). The good news is thatthis proxyMakefile can be generated with Automake. All weneed are-local targets (see Extending) that perform thedispatch. Of course the other Automake features are available, so youcould decide to let Automake perform distribution or installation. Here is a possibleMakefile.am:

     all-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
     check-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
     clean-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
     
     # Assuming the package knows how to install itself
     install-data-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
     install-exec-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
     uninstall-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
     
     # Distribute files from here.
     EXTRA_DIST = subdir/Makefile subdir/program.c ...

Pushing this idea to the extreme, it is also possible to ignore thesubproject build system and build everything from this proxyMakefile.am. This might sound very sensible if you need VPATHbuilds but the subproject does not support them.

Next:  ,Previous:  Not Enough,Up:  Top

25 Distributing Makefile.ins

Automake places no restrictions on the distribution of the resultingMakefile.ins. We still encourage software authors todistribute their work under terms like those of the GPL, but doing sois not required to use Automake.

Some of the files that can be automatically installed via the--add-missing switch do fall under the GPL. However, these alsohave a special exception allowing you to distribute them with yourpackage, regardless of the licensing you choose.

Next:  ,Previous:  Distributing,Up:  Top

26 Automake API Versioning

New Automake releases usually include bug fixes and new features. Unfortunately they may also introduce new bugs and incompatibilities. This makes four reasons why a package may require a particular Automakeversion.

Things get worse when maintaining a large tree of packages, each onerequiring a different version of Automake. In the past, this meant thatany developer (and sometimes users) had to install several versions ofAutomake in different places, and switch ‘$PATH’ appropriately foreach package.

Starting with version 1.6, Automake installs versioned binaries. Thismeans you can install several versions of Automake in the same‘$prefix’, and can select an arbitrary Automake version by runningautomake-1.6 or automake-1.7 without juggling with‘$PATH’. Furthermore,Makefile's generated by Automake 1.6will useautomake-1.6 explicitly in their rebuild rules.

The number ‘1.6’ in automake-1.6 is Automake's API version,not Automake's version. If a bug fix release is made, for instanceAutomake 1.6.1, the API version will remain 1.6. This means that apackage that works with Automake 1.6 should also work with 1.6.1; afterall, this is what people expect from bug fix releases.

If your package relies on a feature or a bug fix introduced ina release, you can pass this version as an option to Automake to ensureolder releases will not be used. For instance, use this in yourconfigure.ac:

       AM_INIT_AUTOMAKE([1.6.1])    dnl Require Automake 1.6.1 or better.

or, in a particular Makefile.am:

       AUTOMAKE_OPTIONS = 1.6.1   # Require Automake 1.6.1 or better.

Automake will print an error message if its version isolder than the requested version.

What is in the API

Automake's programming interface is not easy to define. Basically itshould include at least alldocumented variables and targetsthat a Makefile.am author can use, any behavior associated withthem (e.g., the places where ‘-hook’'s are run), the command lineinterface of automake and aclocal,...

What is not in the API

Every undocumented variable, target, or command line option, is not partof the API. You should avoid using them, as they could change from oneversion to the other (even in bug fix releases, if this helps to fix abug).

If it turns out you need to use such an undocumented feature, contactautomake@gnu.org and try to get it documented and exercised bythe test-suite.

Next:  ,Previous:  API Versioning,Up:  Top

27 Upgrading a Package to a Newer Automake Version

Automake maintains three kind of files in a package.

  • aclocal.m4
  • Makefile.ins
  • auxiliary tools like install-sh or py-compile

aclocal.m4 is generated by aclocal and contains someAutomake-supplied M4 macros. Auxiliary tools are installed by‘automake --add-missing’ when needed. Makefile.ins arebuilt from Makefile.am by automake, and rely on thedefinitions of the M4 macros put inaclocal.m4 as well as thebehavior of the auxiliary tools installed.

Because all these files are closely related, it is important toregenerate all of them when upgrading to a newer Automake release. The usual way to do that is

     aclocal # with any option needed (such a -I m4)
     autoconf
     automake --add-missing --force-missing

or more conveniently:

     autoreconf -vfi

The use of --force-missing ensures that auxiliary tools will beoverridden by new versions (seeInvoking Automake).

It is important to regenerate all these files each time Automake isupgraded, even between bug fixes releases. For instance, it is notunusual for a bug fix to involve changes to both the rules generatedinMakefile.in and the supporting M4 macros copied toaclocal.m4.

Presently automake is able to diagnose situations whereaclocal.m4 has been generated with another version ofaclocal. However it never checks whether auxiliary scriptsare up-to-date. In other words, automake will tell you whenaclocal needs to be rerun, but it will never diagnose amissing--force-missing.

Before upgrading to a new major release, it is a good idea to read thefile NEWS. This file lists all changes between releases: newfeatures, obsolete constructs, known incompatibilities, andworkarounds.

Next:  ,Previous:  Upgrading,Up:  Top

28 Frequently Asked Questions about Automake

This chapter covers some questions that often come up on the mailinglists.

Next:  ,Up:  FAQ

28.1 CVS and generated files

Background: distributed generated Files

Packages made with Autoconf and Automake ship with some generatedfiles likeconfigure or Makefile.in. These files weregenerated on the developer's host and are distributed so thatend-users do not have to install the maintainer tools required torebuild them. Other generated files like Lex scanners, Yacc parsers,or Info documentation, are usually distributed on similar grounds.

Automake outputs rules in Makefiles to rebuild these files. Forinstance,make will run autoconf to rebuildconfigure wheneverconfigure.ac is changed. This makesdevelopment safer by ensuring aconfigure is never out-of-datewith respect toconfigure.ac.

As generated files shipped in packages are up-to-date, and becausetar preserves times-tamps, these rebuild rules are nottriggered when a user unpacks and builds a package.

Background: CVS and Timestamps

Unless you use CVS keywords (in which case files must be updated atcommit time), CVS preserves timestamp during ‘cvs commit’ and‘cvs import -d’ operations.

When you check out a file using ‘cvs checkout’ its timestamp isset to that of the revision that is being checked out.

However, during cvs update, files will have the date of theupdate, not the original timestamp of this revision. This is meant tomake sure thatmake notices sources files have been updated.

This timestamp shift is troublesome when both sources and generatedfiles are kept under CVS. Because CVS processes files in lexicalorder,configure.ac will appear newer than configureafter a cvs update that updates both files, even ifconfigure was newer thanconfigure.ac when it waschecked in. Callingmake will then trigger a spurious rebuildofconfigure.

Living with CVS in Autoconfiscated Projects

There are basically two clans amongst maintainers: those who keep alldistributed files under CVS, including generated files, and those whokeep generated filesout of CVS.

All Files in CVS
  • The CVS repository contains all distributed files so you know exactlywhat is distributed, and you can checkout any prior version entirely.
  • Maintainers can see how generated files evolve (for instance, you cansee what happens to yourMakefile.ins when you upgrade Automakeand make sure they look OK).
  • Users do not need the autotools to build a checkout of the project, itworks just like a released tarball.
  • If users use cvs update to update their copy, instead ofcvs checkout to fetch a fresh one, timestamps will beinaccurate. Some rebuild rules will be triggered and attempt torun developer tools such as autoconf orautomake.

    Actually, calls to such tools are all wrapped into a call to themissing script discussed later (seemaintainer-mode). missing will take care of fixing the timestamps when thesetools are not installed, so that the build can continue.

  • In distributed development, developers are likely to have differentversion of the maintainer tools installed. In this case rebuildstriggered by timestamp lossage will lead to spurious changesto generated files. There are several solutions to this:
    • All developers should use the same versions, so that the rebuilt filesare identical to files in CVS. (This starts to be difficult when eachproject you work on uses different versions.)
    • Or people use a script to fix the timestamp after a checkout (the GCCfolks have such a script).
    • Or configure.ac uses AM_MAINTAINER_MODE, which willdisable all these rebuild rules by default. This is further discussedinmaintainer-mode.
  • Although we focused on spurious rebuilds, the converse can alsohappen. CVS's timestamp handling can also let you think anout-of-date file is up-to-date.

    For instance, suppose a developer has modified Makefile.am andhas rebuiltMakefile.in, and then decides to do a last-minutechange toMakefile.am right before checking in both files(without rebuildingMakefile.in to account for the change).

    This last change to Makefile.am makes the copy ofMakefile.in out-of-date. Since CVS processes filesalphabetically, when another developer ‘cvs update’s his or hertree, Makefile.in will happen to be newer thanMakefile.am. This other developer will not see thatMakefile.in is out-of-date.

Generated Files out of CVS

One way to get CVS and make working peacefully is to neverstore generated files in CVS, i.e., do not CVS-control files thatareMakefile targets (also called derived files).

This way developers are not annoyed by changes to generated files. Itdoes not matter if they all have different versions (assuming they arecompatible, of course). And finally, timestamps are not lost, changesto sources files can't be missed as in theMakefile.am/Makefile.in example discussed earlier.

The drawback is that the CVS repository is not an exact copy of whatis distributed and that users now need to install various developmenttools (maybe even specific versions) before they can build a checkout. But, after all, CVS's job is versioning, not distribution.

Allowing developers to use different versions of their tools can alsohide bugs during distributed development. Indeed, developers will beusing (hence testing) their own generated files, instead of thegenerated files that will be released actually. The developer whoprepares the tarball might be using a version of the tool thatproduces bogus output (for instance a non-portable C file), somethingother developers could have noticed if they weren't using their ownversions of this tool.

Third-party Files

Another class of files not discussed here (because they do not causetimestamp issues) are files that are shipped with a package, butmaintained elsewhere. For instance, tools like gettextizeandautopoint (from Gettext) or libtoolize (fromLibtool), will install or update files in your package.

These files, whether they are kept under CVS or not, raise similarconcerns about version mismatch between developers' tools. TheGettext manual has a section about this, seeCVS Issues.

Next:  ,Previous:  CVS,Up:  FAQ

28.2 missing and AM_MAINTAINER_MODE

missing

The missing script is a wrapper around several maintainertools, designed to warn users if a maintainer tool is required butmissing. Typical maintainer tools areautoconf,automake,bison, etc. Because file generated bythese tools are shipped with the other sources of a package, thesetools shouldn't be required during a user build and they are notchecked for inconfigure.

However, if for some reason a rebuild rule is triggered and involves amissing tool,missing will notice it and warn the user. Besides the warning, when a tool is missing,missing willattempt to fix timestamps in a way that allows the build to continue. For instance,missing will touch configure ifautoconf is not installed. When all distributed files arekept under version control, this feature ofmissing allows auser with no maintainer tools to build a package off its versioncontrol repository, bypassing any timestamp inconsistency (implied bye.g. ‘cvs update’ or ‘git clone’).

If the required tool is installed, missing will run it andwon't attempt to continue after failures. This is correct duringdevelopment: developers love fixing failures. However, users withwrong versions of maintainer tools may get an error when the rebuildrule is spuriously triggered, halting the build. This failure to letthe build continue is one of the arguments of theAM_MAINTAINER_MODE advocates.

AM_MAINTAINER_MODE

AM_MAINTAINER_MODE allows you to choose whether the so called"rebuild rules" should be enabled or disabled. WithAM_MAINTAINER_MODE([enable]), they are enabled by default,otherwise they are disabled by default. In the latter case, ifyou haveAM_MAINTAINER_MODE in configure.ac, and run‘./configure && make’, thenmake will *never* attempt torebuild configure, Makefile.ins, Lex or Yacc outputs, etc. I.e., this disables build rules for files that are usually distributedand that users should normally not have to update.

The user can override the default setting by passing either‘--enable-maintainer-mode’ or ‘--disable-maintainer-mode’toconfigure.

People use AM_MAINTAINER_MODE either because they do not want theirusers (or themselves) annoyed by timestamps lossage (seeCVS), orbecause they simply can't stand the rebuild rules and prefer runningmaintainer tools explicitly.

AM_MAINTAINER_MODE also allows you to disable some custom buildrules conditionally. Some developers use this feature to disablerules that need exotic tools that users may not have available.

Several years ago François Pinard pointed out several argumentsagainst this AM_MAINTAINER_MODE macro. Most of them relate toinsecurity. By removing dependencies you get non-dependable builds:changes to sources files can have no effect on generated files and thiscan be very confusing when unnoticed. He adds that security shouldn'tbe reserved to maintainers (what --enable-maintainer-modesuggests), on the contrary. If one user has to modify aMakefile.am, then eitherMakefile.in should be updatedor a warning should be output (this is what Automake usesmissing for) but the last thing you want is that nothinghappens and the user doesn't notice it (this is what happens whenrebuild rules are disabled by AM_MAINTAINER_MODE).

Jim Meyering, the inventor of the AM_MAINTAINER_MODE macro wasswayed by François's arguments, and got rid ofAM_MAINTAINER_MODE in all of his packages.

Still many people continue to use AM_MAINTAINER_MODE, becauseit helps them working on projects where all files are kept under versioncontrol, and becausemissing isn't enough if you have thewrong version of the tools.

Next:  ,Previous:  maintainer-mode,Up:  FAQ

28.3 Why doesn't Automake support wildcards?

Developers are lazy. They would often like to use wildcards inMakefile.ams, so that they would not need to remember toupdateMakefile.ams every time they add, delete, or renamea file.

There are several objections to this:

  • When using CVS (or similar) developers need to remember they have torun ‘cvs add’ or ‘cvs rm’ anyway. UpdatingMakefile.am accordingly quickly becomes a reflex.

    Conversely, if your application doesn't compilebecause you forgot to add a file inMakefile.am, it will helpyou remember to ‘cvs add’ it.

  • Using wildcards makes it easy to distribute files by mistake. Forinstance, some code a developer is experimenting with (a test case,say) that should not be part of the distribution.
  • Using wildcards it's easy to omit some files by mistake. Forinstance, one developer creates a new file, uses it in many places,but forgets to commit it. Another developer then checks out theincomplete project and is able to run ‘make dist’ successfully,even though a file is missing. By listing files, ‘make dist’will complain.
  • Wildcards are not portable to some non-GNU make implementations,e.g., NetBSDmake will not expand globs such as ‘*’ inprerequisites of a target.
  • Finally, it's really hard to forget to add a file toMakefile.am: files that are not listed inMakefile.am arenot compiled or installed, so you can't even test them.

Still, these are philosophical objections, and as such you may disagree,or find enough value in wildcards to dismiss all of them. Before youstart writing a patch against Automake to teach it about wildcards,let's see the main technical issue: portability.

Although ‘$(wildcard ...)’ works with GNUmake, it isnot portable to other make implementations.

The only way Automake could support $(wildcard ...) is byexpending$(wildcard ...) when automake is run. The resultingMakefile.ins would be portable since they wouldlist all files and not use ‘$(wildcard ...)’. However thatmeans developers would need to remember to runautomake eachtime they add, delete, or rename files.

Compared to editing Makefile.am, this is a very small gain. Sure,it's easier and faster to type ‘automake; make’ than to type‘emacs Makefile.am; make’. But nobody bothered enough to write apatch to add support for this syntax. Some people use scripts togenerate file lists inMakefile.am or in separateMakefile fragments.

Even if you don't care about portability, and are tempted to use‘$(wildcard ...)’ anyway because you target only GNU Make, youshould know there are many places where Automake needs to know exactlywhich files should be processed. As Automake doesn't know how toexpand ‘$(wildcard ...)’, you cannot use it in these places. ‘$(wildcard ...)’ is a black box comparable toAC_SUBSTedvariables as far Automake is concerned.

You can get warnings about ‘$(wildcard ...’) constructs using the-Wportability flag.

Next:  ,Previous:  Wildcards,Up:  FAQ

28.4 Limitations on File Names

Automake attempts to support all kinds of file names, even those thatcontain unusual characters or are unusually long. However, somelimitations are imposed by the underlying operating system and tools.

Most operating systems prohibit the use of the null byte in filenames, and reserve ‘/’ as a directory separator. Also, theyrequire that file names are properly encoded for the user's locale. Automake is subject to these limits.

Portable packages should limit themselves to POSIX filenames. These can contain ASCII letters and digits,‘_’, ‘.’, and ‘-’. File names consist of componentsseparated by ‘/’. File name components cannot begin with‘-’.

Portable POSIX file names cannot contain components that exceed a14-byte limit, but nowadays it's normally safe to assume themore-generous XOPEN limit of 255 bytes. POSIXlimits file names to 255 bytes (XOPEN allows 1023 bytes),but you may want to limit a source tarball to file names of 99 bytesto avoid interoperability problems with old versions oftar.

If you depart from these rules (e.g., by using non-ASCIIcharacters in file names, or by using lengthy file names), yourinstallers may have problems for reasons unrelated to Automake. However, if this does not concern you, you should know about thelimitations imposed by Automake itself. These limitations areundesirable, but some of them seem to be inherent to underlying toolslike Autoconf, Make, M4, and the shell. They fall into threecategories: install directories, build directories, and file names.

The following characters:

     newline " # $ ' `

should not appear in the names of install directories. For example,the operand ofconfigure's --prefix option shouldnot contain these characters.

Build directories suffer the same limitations as install directories,and in addition should not contain the following characters:

     & @ \

For example, the full name of the directory containing the sourcefiles should not contain these characters.

Source and installation file names like main.c are limited evenfurther: they should conform to the POSIX/XOPENrules described above. In addition, if you plan to port tonon-POSIX environments, you should avoid file names thatdiffer only in case (e.g., makefile andMakefile). Nowadays it is no longer worth worrying about the 8.3 limits ofDOS file systems.

Next:  ,Previous:  Limitations on File Names,Up:  FAQ

28.5 Files left in build directory after distclean

This is a diagnostic you might encounter while running ‘makedistcheck’.

As explained in Checking the Distribution, ‘make distcheck’attempts to build and check your package for errors like this one.

‘make distcheck’ will perform a VPATH build of yourpackage (seeVPATH Builds), and then call ‘make distclean’. Files left in the build directory after ‘make distclean’ has runare listed after this error.

This diagnostic really covers two kinds of errors:

  • files that are forgotten by distclean;
  • distributed files that are erroneously rebuilt.

The former left-over files are not distributed, so the fix is to markthem for cleaning (seeClean), this is obvious and doesn't deservemore explanations.

The latter bug is not always easy to understand and fix, so let'sproceed with an example. Suppose our package contains a program forwhich we want to build a man page usinghelp2man. GNUhelp2man produces simple manual pages from the--helpand --version output of other commands (seeOverview). Because we don't want to force ourusers to installhelp2man, we decide to distribute thegenerated man page using the following setup.

     # This Makefile.am is bogus.
     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     dist_man_MANS = foo.1
     
     foo.1: foo$(EXEEXT)
             help2man --output=foo.1 ./foo$(EXEEXT)

This will effectively distribute the man page. However,‘make distcheck’ will fail with:

     ERROR: files left in build directory after distclean:
     ./foo.1

Why was foo.1 rebuilt? Because although distributed,foo.1 depends on a non-distributed built file:foo$(EXEEXT).foo$(EXEEXT) is built by the user, so itwill always appear to be newer than the distributedfoo.1.

‘make distcheck’ caught an inconsistency in our package. Ourintent was to distributefoo.1 so users do not need to installhelp2man, however since this rule causes this file to bealways rebuilt, usersdo need help2man. Either weshould ensure thatfoo.1 is not rebuilt by users, or there isno point in distributingfoo.1.

More generally, the rule is that distributed files should never dependon non-distributed built files. If you distribute somethinggenerated, distribute its sources.

One way to fix the above example, while still distributingfoo.1 is to not depend onfoo$(EXEEXT). For instance,assuming foo --version and foo --help do notchange unlessfoo.c or configure.ac change, we couldwrite the followingMakefile.am:

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     dist_man_MANS = foo.1
     
     foo.1: foo.c $(top_srcdir)/configure.ac
             $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
             help2man --output=foo.1 ./foo$(EXEEXT)

This way, foo.1 will not get rebuilt every timefoo$(EXEEXT) changes. Themake call makes surefoo$(EXEEXT) is up-to-date beforehelp2man. Anotherway to ensure this would be to use separate directories for binariesand man pages, and setSUBDIRS so that binaries are builtbefore man pages.

We could also decide not to distribute foo.1. Inthis case it's fine to havefoo.1 dependent uponfoo$(EXEEXT), since both will have to be rebuilt. However it would be impossible to build the package in across-compilation, because buildingfoo.1 involvesan execution of foo$(EXEEXT).

Another context where such errors are common is when distributed filesare built by tools that are built by the package. The pattern issimilar:

     distributed-file: built-tools distributed-sources
             build-command

should be changed to

     distributed-file: distributed-sources
             $(MAKE) $(AM_MAKEFLAGS) built-tools
             build-command

or you could choose not to distribute distributed-file, ifcross-compilation does not matter.

The points made through these examples are worth a summary:

  • Distributed files should never depend upon non-distributed builtfiles.
  • Distributed files should be distributed with all their dependencies.
  • If a file is intended to be rebuilt by users, then there is no pointin distributing it.

For desperate cases, it's always possible to disable this check bysettingdistcleancheck_listfiles as documented in Checking the Distribution. Make sure you do understand the reason why ‘make distcheck’complains before you do this.distcleancheck_listfiles is away to hide errors, not to fix them. You can always do better.

Next:  ,Previous:  distcleancheck,Up:  FAQ

28.6 Flag Variables Ordering

     What is the difference between AM_CFLAGS, CFLAGS, and
     mumble_CFLAGS?

     Why does automake output CPPFLAGS after
     AM_CPPFLAGS on compile lines?  Shouldn't it be the converse?

     My configure adds some warning flags into CXXFLAGS.  In
     one Makefile.am I would like to append a new flag, however if I
     put the flag into AM_CXXFLAGS it is prepended to the other
     flags, not appended.
Compile Flag Variables

This section attempts to answer all the above questions. We willmostly discuss CPPFLAGS in our examples, but actually theanswer holds for all the compile flags used in Automake:CCASFLAGS,CFLAGS, CPPFLAGS, CXXFLAGS,FCFLAGS,FFLAGS, GCJFLAGS, LDFLAGS,LFLAGS,LIBTOOLFLAGS, OBJCFLAGS, RFLAGS,UPCFLAGS, andYFLAGS.

CPPFLAGS, AM_CPPFLAGS, and mumble_CPPFLAGS arethree variables that can be used to pass flags to the C preprocessor(actually these variables are also used for other languages like C++or preprocessed Fortran).CPPFLAGS is the user variable(see User Variables),AM_CPPFLAGS is the Automake variable,and mumble_CPPFLAGS is the variable specific to themumble target (we call this a per-target variable,seeProgram and Library Variables).

Automake always uses two of these variables when compiling C sourcesfiles. When compiling an object file for themumble target,the first variable will be mumble_CPPFLAGS if it is defined, orAM_CPPFLAGS otherwise. The second variable is alwaysCPPFLAGS.

In the following example,

     bin_PROGRAMS = foo bar
     foo_SOURCES = xyz.c
     bar_SOURCES = main.c
     foo_CPPFLAGS = -DFOO
     AM_CPPFLAGS = -DBAZ

xyz.o will be compiled with ‘$(foo_CPPFLAGS) $(CPPFLAGS)’,(becausexyz.o is part of the foo target), whilemain.o will be compiled with ‘$(AM_CPPFLAGS) $(CPPFLAGS)’(because there is no per-target variable for target bar).

The difference between mumble_CPPFLAGS and AM_CPPFLAGSbeing clear enough, let's focus onCPPFLAGS. CPPFLAGSis a user variable, i.e., a variable that users are entitled to modifyin order to compile the package. This variable, like many others,is documented at the end of the output of ‘configure --help’.

For instance, someone who needs to add /home/my/usr/include tothe C compiler's search path would configure a package with

     ./configure CPPFLAGS='-I /home/my/usr/include'

and this flag would be propagated to the compile rules of allMakefiles.

It is also not uncommon to override a user variable atmake-time. Many installers do this withprefix, butthis can be useful with compiler flags too. For instance, if, whiledebugging a C++ project, you need to disable optimization in onespecific object file, you can run something like

     rm file.o
     make CXXFLAGS=-O0 file.o
     make

The reason ‘$(CPPFLAGS)’ appears after ‘$(AM_CPPFLAGS)’ or‘$(mumble_CPPFLAGS)’ in the compile command is that usersshould always have the last say. It probably makes more sense if youthink about it while looking at the ‘CXXFLAGS=-O0’ above, whichshould supersede any other switch fromAM_CXXFLAGS ormumble_CXXFLAGS (and this of course replaces the previous valueofCXXFLAGS).

You should never redefine a user variable such as CPPFLAGS inMakefile.am. Use ‘automake -Woverride’ to diagnose suchmistakes. Even something like

     CPPFLAGS = -DDATADIR=\"$(datadir)\" @CPPFLAGS@

is erroneous. Although this preserves configure's value ofCPPFLAGS, the definition ofDATADIR will disappear if auser attempts to override CPPFLAGS from themakecommand line.

     AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"

is all that is needed here if no per-target flags are used.

You should not add options to these user variables withinconfigure either, for the same reason. Occasionally you needto modify these variables to perform a test, but you should resettheir values afterwards. In contrast, it is OK to modify the‘AM_’ variables withinconfigure if you AC_SUBSTthem, but it is rather rare that you need to do this, unless youreally want to change the default definitions of the ‘AM_’variables in allMakefiles.

What we recommend is that you define extra flags in separatevariables. For instance, you may write an Autoconf macro that computesa set of warning options for the C compiler, andAC_SUBST themin WARNINGCFLAGS; you may also have an Autoconf macro thatdetermines which compiler and which linker flags should be used tolink with librarylibfoo, and AC_SUBST these inLIBFOOCFLAGS andLIBFOOLDFLAGS. Then, aMakefile.am could use these variables as follows:

     AM_CFLAGS = $(WARNINGCFLAGS)
     bin_PROGRAMS = prog1 prog2
     prog1_SOURCES = ...
     prog2_SOURCES = ...
     prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
     prog2_LDFLAGS = $(LIBFOOLDFLAGS)

In this example both programs will be compiled with the flagssubstituted into ‘$(WARNINGCFLAGS)’, andprog2 willadditionally be compiled with the flags required to link withlibfoo.

Note that listing AM_CFLAGS in a per-target CFLAGSvariable is a common idiom to ensure thatAM_CFLAGS applies toevery target in a Makefile.in.

Using variables like this gives you full control over the ordering ofthe flags. For instance, if there is a flag in $(WARNINGCFLAGS) thatyou want to negate for a particular target, you can use something like‘prog1_CFLAGS = $(AM_CFLAGS) -no-flag’. If all these flags hadbeen forcefully appended to CFLAGS, there would be no way todisable one flag. Yet another reason to leave user variables tousers.

Finally, we have avoided naming the variable of the exampleLIBFOO_LDFLAGS (with an underscore) because that would causeAutomake to think that this is actually a per-target variable (likemumble_LDFLAGS) for some non-declaredLIBFOO target.

Other Variables

There are other variables in Automake that follow similar principlesto allow user options. For instance, Texinfo rules (seeTexinfo)use MAKEINFOFLAGS and AM_MAKEINFOFLAGS. Similarly,DejaGnu tests (seeDejaGnu Tests) use RUNTESTDEFAULTFLAGS andAM_RUNTESTDEFAULTFLAGS. The tags and ctags rules(seeTags) use ETAGSFLAGS, AM_ETAGSFLAGS,CTAGSFLAGS, andAM_CTAGSFLAGS. Java rules(see Java) use JAVACFLAGS andAM_JAVACFLAGS. Noneof these rules support per-target flags (yet).

To some extent, even AM_MAKEFLAGS (see Subdirectories)obeys this naming scheme. The slight difference is thatMAKEFLAGS is passed to sub-makes implicitly bymake itself.

However you should not think that all variables ending withFLAGS follow this convention. For instance,DISTCHECK_CONFIGURE_FLAGS (seeChecking the Distribution) andACLOCAL_AMFLAGS (seeRebuilding and Local Macros),are two variables that are only useful to the maintainer and have nouser counterpart.

ARFLAGS (see A Library) is usually defined by Automake andhas neitherAM_ nor per-target cousin.

Finally you should not think that the existence of a per-targetvariable implies the existance of anAM_ variable or of a uservariable. For instance, the mumble_LDADD per-target variableoverrides the makefile-wideLDADD variable (which is not a uservariable), and mumble_LIBADD exists only as a per-targetvariable. SeeProgram and Library Variables.

Next:  ,Previous:  Flag Variables Ordering,Up:  FAQ

28.7 Why are object files sometimes renamed?

This happens when per-target compilation flags are used. Objectfiles need to be renamed just in case they would clash with objectfiles compiled from the same sources, but with different flags. Consider the following example.

     bin_PROGRAMS = true false
     true_SOURCES = generic.c
     true_CPPFLAGS = -DEXIT_CODE=0
     false_SOURCES = generic.c
     false_CPPFLAGS = -DEXIT_CODE=1

Obviously the two programs are built from the same source, but itwould be bad if they shared the same object, becausegeneric.ocannot be built with both ‘-DEXIT_CODE=0’and‘-DEXIT_CODE=1’. Therefore automake outputs rules tobuild two different objects:true-generic.o andfalse-generic.o.

automake doesn't actually look whether source files areshared to decide if it must rename objects. It will just rename allobjects of a target as soon as it sees per-target compilation flagsused.

It's OK to share object files when per-target compilation flags are notused. For instance,true and false will both useversion.o in the following example.

     AM_CPPFLAGS = -DVERSION=1.0
     bin_PROGRAMS = true false
     true_SOURCES = true.c version.c
     false_SOURCES = false.c version.c

Note that the renaming of objects is also affected by the_SHORTNAME variable (seeProgram and Library Variables).

Next:  ,Previous:  Renamed Objects,Up:  FAQ

28.8 Per-Object Flags Emulation

     One of my source files needs to be compiled with different flags.  How
     do I do?

Automake supports per-program and per-library compilation flags (seeProgram and Library Variables andFlag Variables Ordering). With this you can define compilation flags that apply toall files compiled for a target. For instance, in

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c foo.h bar.c bar.h main.c
     foo_CFLAGS = -some -flags

foo-foo.o, foo-bar.o, andfoo-main.o will all becompiled with ‘-some -flags’. (If you wonder about the names ofthese object files, seeRenamed Objects.) Note thatfoo_CFLAGS gives the flags to use when compiling all the Csources of theprogram foo, it has nothing to do withfoo.c orfoo-foo.o specifically.

What if foo.c needs to be compiled intofoo.o using somespecific flags, that none of the other files requires? Obviouslyper-program flags are not directly applicable here. Something likeper-object flags are expected, i.e., flags that would be used onlywhen creatingfoo-foo.o. Automake does not support that,however this is easy to simulate using a library that contains onlythat object, and compiling this library with per-library flags.

     bin_PROGRAMS = foo
     foo_SOURCES = bar.c bar.h main.c
     foo_CFLAGS = -some -flags
     foo_LDADD = libfoo.a
     noinst_LIBRARIES = libfoo.a
     libfoo_a_SOURCES = foo.c foo.h
     libfoo_a_CFLAGS = -some -other -flags

Here foo-bar.o and foo-main.o will all becompiled with ‘-some -flags’, whilelibfoo_a-foo.o willbe compiled using ‘-some -other -flags’. Eventually, allthree objects will be linked to formfoo.

This trick can also be achieved using Libtool convenience libraries,for instance ‘noinst_LTLIBRARIES = libfoo.la’ (seeLibtool Convenience Libraries).

Another tempting idea to implement per-object flags is to override thecompile rulesautomake would output for these files. Automake will not define a rule for a target you have defined, so youcould think about defining the ‘foo-foo.o: foo.c’ rule yourself. We recommend against this, because this is error prone. For instance,if you add such a rule to the first example, it will break the day youdecide to removefoo_CFLAGS (because foo.c will then becompiled asfoo.o instead of foo-foo.o, seeRenamed Objects). Also in order to support dependency tracking, the two.o/.obj extensions, and all the other flags variablesinvolved in a compilation, you will end up modifying a copy of therule previously output by automake for this file. If a newrelease of Automake generates a different rule, your copy will need tobe updated by hand.

Next:  ,Previous:  Per-Object Flags,Up:  FAQ

28.9 Handling Tools that Produce Many Outputs

This section describes amake idiom that can be used when atool produces multiple output files. It is not specific to Automakeand can be used in ordinaryMakefiles.

Suppose we have a program called foo that will read one filecalleddata.foo and produce two files named data.c anddata.h. We want to write aMakefile rule that capturesthis one-to-two dependency.

The naive rule is incorrect:

     # This is incorrect.
     data.c data.h: data.foo
             foo data.foo

What the above rule really says is that data.c anddata.h each depend ondata.foo, and can each be built byrunning ‘foo data.foo’. In other words it is equivalent to:

     # We do not want this.
     data.c: data.foo
             foo data.foo
     data.h: data.foo
             foo data.foo

which means that foo can be run twice. Usually it will notbe run twice, becausemake implementations are smart enoughto check for the existence of the second file after the first one hasbeen built; they will therefore detect that it already exists. However there are a few situations where it can run twice anyway:

  • The most worrying case is when running a parallel make. Ifdata.c anddata.h are built in parallel, two ‘foodata.foo’ commands will run concurrently. This is harmful.
  • Another case is when the dependency (here data.foo) is(or depends upon) a phony target.

A solution that works with parallel make but not withphony dependencies is the following:

     data.c data.h: data.foo
             foo data.foo
     data.h: data.c

The above rules are equivalent to

     data.c: data.foo
             foo data.foo
     data.h: data.foo data.c
             foo data.foo

therefore a parallel make will have to serialize the buildsofdata.c and data.h, and will detect that the second isno longer needed once the first is over.

Using this pattern is probably enough for most cases. However it doesnot scale easily to more output files (in this scheme all output filesmust be totally ordered by the dependency relation), so we willexplore a more complicated solution.

Another idea is to write the following:

     # There is still a problem with this one.
     data.c: data.foo
             foo data.foo
     data.h: data.c

The idea is that ‘foo data.foo’ is run only whendata.cneeds to be updated, but we further state thatdata.h dependsupon data.c. That way, ifdata.h is required anddata.foo is out of date, the dependency ondata.c willtrigger the build.

This is almost perfect, but suppose we have built data.h anddata.c, and then we erasedata.h. Then, running‘make data.h’ will not rebuilddata.h. The above rulesjust state that data.c must be up-to-date with respect todata.foo, and this is already the case.

What we need is a rule that forces a rebuild when data.h ismissing. Here it is:

     data.c: data.foo
             foo data.foo
     data.h: data.c
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               rm -f data.c; \
               $(MAKE) $(AM_MAKEFLAGS) data.c; \
             fi

The above scheme can be extended to handle more outputs and moreinputs. One of the outputs is selected to serve as a witness to thesuccessful completion of the command, it depends upon all inputs, andall other outputs depend upon it. For instance, iffooshould additionally read data.bar and also producedata.w anddata.x, we would write:

     data.c: data.foo data.bar
             foo data.foo data.bar
     data.h data.w data.x: data.c
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               rm -f data.c; \
               $(MAKE) $(AM_MAKEFLAGS) data.c; \
             fi

However there are now three minor problems in this setup. One is relatedto the timestamp ordering ofdata.h, data.w,data.x, anddata.c. Another one is a race conditionif a parallelmake attempts to run multiple instances of therecover block at once. Finally, the recursive rule breaks ‘make -n’when run with GNUmake (as well as some other makeimplementations), as it may removedata.h even when it should not(see How the MAKE Variable Works).

Let us deal with the first problem. foo outputs four files,but we do not know in which order these files are created. Supposethatdata.h is created before data.c. Then we have aweird situation. The next timemake is run, data.hwill appear older thandata.c, the second rule will betriggered, a shell will be started to execute the ‘if...fi’command, but actually it will just execute thethen branch,that is: nothing. In other words, because the witness we selected isnot the first file created byfoo, make will starta shell to do nothing each time it is run.

A simple riposte is to fix the timestamps when this happens.

     data.c: data.foo data.bar
             foo data.foo data.bar
     data.h data.w data.x: data.c
             @if test -f $@; then \
               touch $@; \
             else \
     ## Recover from the removal of $@
               rm -f data.c; \
               $(MAKE) $(AM_MAKEFLAGS) data.c; \
             fi

Another solution is to use a different and dedicated file as witness,rather than using any offoo's outputs.

     data.stamp: data.foo data.bar
             @rm -f data.tmp
             @touch data.tmp
             foo data.foo data.bar
             @mv -f data.tmp $@
     data.c data.h data.w data.x: data.stamp
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               rm -f data.stamp; \
               $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
             fi

data.tmp is created before foo is run, so it has atimestamp older than output files output byfoo. It is thenrenamed to data.stamp afterfoo has run, because wedo not want to updatedata.stamp if foo fails.

This solution still suffers from the second problem: the racecondition in the recover rule. If, after a successful build, a usererasesdata.c and data.h, and runs ‘make -j’, thenmake may start both recover rules in parallel. If the twoinstances of the rule execute ‘$(MAKE) $(AM_MAKEFLAGS)data.stamp’ concurrently the build is likely to fail (for instance, thetwo rules will createdata.tmp, but only one can rename it).

Admittedly, such a weird situation does not arise during ordinarybuilds. It occurs only when the build tree is mutilated. Heredata.c anddata.h have been explicitly removed withoutalso removingdata.stamp and the other output files. make clean; make will always recover from these situations evenwith parallel makes, so you may decide that the recover rule is solelyto help non-parallel make users and leave things as-is. Fixing thisrequires some locking mechanism to ensure only one instance of therecover rule rebuilds data.stamp. One could imagine somethingalong the following lines.

     data.c data.h data.w data.x: data.stamp
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
     ## mkdir is a portable test-and-set
               if mkdir data.lock 2>/dev/null; then \
     ## This code is being executed by the first process.
                 rm -f data.stamp; \
                 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
                 result=$$?; rm -rf data.lock; exit $$result; \
               else \
     ## This code is being executed by the follower processes.
     ## Wait until the first process is done.
                 while test -d data.lock; do sleep 1; done; \
     ## Succeed if and only if the first process succeeded.
                 test -f data.stamp; \
               fi; \
             fi

Using a dedicated witness, like data.stamp, is very handy whenthe list of output files is not known beforehand. As an illustration,consider the following rules to compile many*.el files into*.elc files in a single command. It does not matter howELFILES is defined (as long as it is not empty: empty targetsare not accepted by POSIX).

     ELFILES = one.el two.el three.el ...
     ELCFILES = $(ELFILES:=c)
     
     elc-stamp: $(ELFILES)
             @rm -f elc-temp
             @touch elc-temp
             $(elisp_comp) $(ELFILES)
             @mv -f elc-temp $@
     
     $(ELCFILES): elc-stamp
             @if test -f $@; then :; else \
     ## Recover from the removal of $@
               trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
               if mkdir elc-lock 2>/dev/null; then \
     ## This code is being executed by the first process.
                 rm -f elc-stamp; \
                 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
                 rmdir elc-lock; \
               else \
     ## This code is being executed by the follower processes.
     ## Wait until the first process is done.
                 while test -d elc-lock; do sleep 1; done; \
     ## Succeed if and only if the first process succeeded.
                 test -f elc-stamp; exit $$?; \
     
               fi; \
             fi

These solutions all still suffer from the third problem, namely thatthey break the promise that ‘make -n’ should not cause any actualchanges to the tree. For those solutions that do not create lock files,it is possible to split the recover rules into two separate recipecommands, one of which does all work but the recursion, and theother invokes the recursive ‘$(MAKE)’. The solutions involvinglocking could act upon the contents of the ‘MAKEFLAGS’ variable,but parsing that portably is not easy (seeThe Make Macro MAKEFLAGS). Here is an example:

     ELFILES = one.el two.el three.el ...
     ELCFILES = $(ELFILES:=c)
     
     elc-stamp: $(ELFILES)
             @rm -f elc-temp
             @touch elc-temp
             $(elisp_comp) $(ELFILES)
             @mv -f elc-temp $@
     
     $(ELCFILES): elc-stamp
     ## Recover from the removal of $@
             @dry=; for f in x $$MAKEFLAGS; do \
               case $$f in \
                 *=*|--*);; \
                 *n*) dry=:;; \
               esac; \
             done; \
             if test -f $@; then :; else \
               $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
               if $$dry mkdir elc-lock 2>/dev/null; then \
     ## This code is being executed by the first process.
                 $$dry rm -f elc-stamp; \
                 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
                 $$dry rmdir elc-lock; \
               else \
     ## This code is being executed by the follower processes.
     ## Wait until the first process is done.
                 while test -d elc-lock && test -z "$$dry"; do \
     
                   sleep 1; \
                 done; \
     ## Succeed if and only if the first process succeeded.
                 $$dry test -f elc-stamp; exit $$?; \
               fi; \
             fi

For completeness it should be noted that GNU make is able toexpress rules with multiple output files using pattern rules(seePattern Rule Examples). We do not discuss pattern rules here because they are notportable, but they can be convenient in packages that assume GNUmake.

Next:  ,Previous:  Multiple Outputs,Up:  FAQ

28.10 Installing to Hard-Coded Locations

     My package needs to install some configuration file.  I tried to use
     the following rule, but ‘make distcheck’ fails.  Why?
     
          # Do not do this.
          install-data-local:
                  $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile

     My package needs to populate the installation directory of another
     package at install-time.  I can easily compute that installation
     directory in configure, but if I install files therein,
     ‘make distcheck’ fails.  How else should I do?

These two setups share their symptoms: ‘make distcheck’ failsbecause they are installing files to hard-coded paths. In the latercase the path is not really hard-coded in the package, but we canconsider it to be hard-coded in the system (or in whichever tool thatsupplies the path). As long as the path does not use any of thestandard directory variables (‘$(prefix)’, ‘$(bindir)’,‘$(datadir)’, etc.), the effect will be the same:user-installations are impossible.

As a (non-root) user who wants to install a package, you usually have noright to install anything in/usr or /usr/local. So youdo something like ‘./configure --prefix ~/usr’ to install apackage in your own~/usr tree.

If a package attempts to install something to some hard-coded path(e.g., /etc/afile), regardless of this --prefix setting,then the installation will fail. ‘make distcheck’ performs sucha--prefix installation, hence it will fail too.

Now, there are some easy solutions.

The above install-data-local example for installing/etc/afile would be better replaced by

     sysconf_DATA = afile

by default sysconfdir will be ‘$(prefix)/etc’, becausethis is what the GNU Standards require. When such a package isinstalled on an FHS compliant system, the installer will have to set‘--sysconfdir=/etc’. As the maintainer of the package youshould not be concerned by such site policies: use the appropriatestandard directory variable to install your files so that the installercan easily redefine these variables to match their site conventions.

Installing files that should be used by another package is slightlymore involved. Let's take an example and assume you want to installa shared library that is a Python extension module. If you ask Pythonwhere to install the library, it will answer something like this:

     % python -c 'from distutils import sysconfig;
                  print sysconfig.get_python_lib(1,0)'
     /usr/lib/python2.5/site-packages

If you indeed use this absolute path to install your shared library,non-root users will not be able to install the package, hencedistcheck fails.

Let's do better. The ‘sysconfig.get_python_lib()’ functionactually accepts a third argument that will replace Python'sinstallation prefix.

     % python -c 'from distutils import sysconfig;
                  print sysconfig.get_python_lib(1,0,"${exec_prefix}")'
     ${exec_prefix}/lib/python2.5/site-packages

You can also use this new path. If you do

  • root users can install your package with the same --prefixas Python (you get the behavior of the previous attempt)
  • non-root users can install your package too, they will have theextension module in a place that is not searched by Python but theycan work around this using environment variables (and if you installedscripts that use this shared library, it's easy to tell Python were tolook in the beginning of your script, so the script works in bothcases).

The AM_PATH_PYTHON macro uses similar commands to define‘$(pythondir)’ and ‘$(pyexecdir)’ (seePython).

Of course not all tools are as advanced as Python regarding thatsubstitution ofprefix. So another strategy is to figure thepart of the installation directory that must be preserved. Forinstance, here is howAM_PATH_LISPDIR (see Emacs Lisp)computes ‘$(lispdir)’:

     $EMACS -batch -q -eval '(while load-path
       (princ (concat (car load-path) "\n"))
       (setq load-path (cdr load-path)))' >conftest.out
     lispdir=`sed -n
       -e 's,/$,,'
       -e '/.*\/lib\/x*emacs\/site-lisp$/{
             s,.*/lib/\(x*emacs/site-lisp\)$,${libdir}/\1,;p;q;
           }'
       -e '/.*\/share\/x*emacs\/site-lisp$/{
             s,.*/share/\(x*emacs/site-lisp\),${datarootdir}/\1,;p;q;
           }'
       conftest.out`

I.e., it just picks the first directory that looks like*/lib/*emacs/site-lisp or*/share/*emacs/site-lisp inthe search path of emacs, and then substitutes ‘${libdir}’ or‘${datadir}’ appropriately.

The emacs case looks complicated because it processes a list andexpects two possible layouts, otherwise it's easy, and the benefits fornon-root users are really worth the extrased invocation.

Next:  ,Previous:  Hard-Coded Install Paths,Up:  FAQ

28.11 Debugging Make Rules

The rules and dependency trees generated byautomake can getrather complex, and leave the developer head-scratching when thingsdon't work as expected. Besides the debug options provided by themake command (seeOptions Summary), here's a couple of further hints for debugging makefilesgenerated byautomake effectively:

  • If less verbose output has been enabled in the package with the‘silent-rules’ option (seeOptions), you can usemake V=1 to see the commands being executed.
  • make -n can help show what would be done without actually doingit. Note however, that this willstill execute commands prefixedwith ‘+’, and, when using GNUmake, commands that containthe strings ‘$(MAKE)’ or ‘${MAKE}’ (seeInstead of Execution). Typically, this is helpful to show what recursive rules would do, but itmeans that, in your own rules, you should not mix such recursion withactions that change any files.9 Furthermore, note that GNU make will updateprerequisites for theMakefile file itself even with -n(seeRemaking Makefiles).
  • make SHELL="/bin/bash -vx" can help debug complex rules. See The Make Macro SHELL, for someportability quirks associated with this construct.
  • echo 'print: ; @echo "$(VAR)"' | make -f Makefile -f - printcan be handy to examine the expanded value of variables. You may needto use a target other than ‘print’ if that is already used or afile with that name exists.
  • http://bashdb.sourceforge.net/remake/ provides a modifiedGNUmake command called remake that copes withcomplex GNUmake-specific Makefiles and allows to traceexecution, examine variables, and call rules interactively, much likea debugger.

Previous:  Debugging Make Rules,Up:  FAQ

28.12 Reporting Bugs

Most nontrivial software has bugs. Automake is no exception. Althoughwe cannot promise we can or will fix a bug, and we might not even agreethat it is a bug, we want to hear about problems you encounter. Often weagree they are bugs and want to fix them.

To make it possible for us to fix a bug, please report it. In order todo so effectively, it helps to know when and how to do it.

Before reporting a bug, it is a good idea to see if it is already known. You can look at theGNU Bug Trackerand the bug-automake mailing list archives for previous bug reports. Wepreviously used aGnats database for bug tracking, so some bugs might have been reportedthere already. Please do not use it for new bug reports, however.

If the bug is not already known, it should be reported. It is veryimportant to report bugs in a way that is useful and efficient. Forthis, please familiarize yourself withHow to Report Bugs Effectively andHow to Ask Questions the Smart Way. This helps you and developers to save timewhich can then be spent on fixing more bugs and implementing morefeatures.

For a bug report, a feature request or other suggestions, please sendemail to bug-automake@gnu.org. This will then open a newbug in the bug tracker. Besure to include the versions of Autoconf and Automake that you use. Ideally, post a minimalMakefile.am and configure.ac thatreproduces the problem you encounter. If you have encountered testsuite failures, please attach thetests/test-suite.log file.

Next:  ,Previous:  FAQ,Up:  Top

29 History of Automake

This chapter presents various aspects of the history of Automake. Theexhausted reader can safely skip it; this will be more of interest tonostalgic people, or to those curious to learn about the evolution ofAutomake.

Next:  ,Up:  History

29.1 Timeline

1994-09-19 First CVS commit.
If we can trust the CVS repository, David J. MacKenzie (djm) startedworking on Automake (or AutoMake, as it was spelt then) this Monday.

The first version of the automake script looks as follows.

          #!/bin/sh
          
          status=0
          
          for makefile
          do
            if test ! -f ${makefile}.am; then
              echo "automake: ${makefile}.am: No such honkin' file"
              status=1
              continue
            fi
          
            exec 4> ${makefile}.in
          
          done

From this you can already see that Automake will be about reading*.am file and producing*.in files. You cannot seeanything else, but if you also know that David is the one who createdAutoconf two years before you can guess the rest.

Several commits follow, and by the end of the day Automake isreported to work for GNU fileutils and GNU m4.

The modus operandi is the one that is still used today: variableassignments inMakefile.am files trigger injections ofprecannedMakefile fragments into the generatedMakefile.in. The use ofMakefile fragments was inspiredby the 4.4BSDmake and include files, however Automake aimsto be portable and to conform to the GNU standards forMakefilevariables and targets.

At this point, the most recent release of Autoconf is version 1.11,and David is preparing to release Autoconf 2.0 in late October. As amatter of fact, he will barely touch Automake after September.

1994-11-05 David MacKenzie's last commit.
At this point Automake is a 200 line portable shell script, plus 332lines of Makefile fragments. In the README, Davidstates his ambivalence between “portable shell” and “moreappropriate language”:
I wrote it keeping in mind the possibility of it becoming an Autoconfmacro, so it would run at configure-time. That would slowconfiguration down a bit, but allow users to modify the Makefile.amwithout needing to fetch the AutoMake package. And, the Makefile.infiles wouldn't need to be distributed. But all of AutoMake would. SoI might reimplement AutoMake in Perl, m4, or some other moreappropriate language.

Automake is described as “an experimental Makefile generator”. There is no documentation. Adventurous users are referred to theexamples and patches needed to use Automake with GNU m4 1.3, fileutils3.9, time 1.6, and development versions of find and indent.

These examples seem to have been lost. However at the time of writing(10 years later in September, 2004) the FSF still distributes apackage that uses this version of Automake: check out GNU termutils2.0.

1995-11-12 Tom Tromey's first commit.
After one year of inactivity, Tom Tromey takes over the package. Tom was working on GNU cpio back then, and doing this just for fun,having trouble finding a project to contribute to. So while hackinghe wanted to bring the Makefile.in up to GNU standards. Thiswas hard, and one day he saw Automake on ftp://alpha.gnu.org/,grabbed it and tried it out.

Tom didn't talk to djm about it until later, just to make sure hedidn't mind if he made a release. He did a bunch of early releases tothe Gnits folks.

Gnits was (and still is) totally informal, just a few GNU friends whoFrançois Pinard knew, who were all interested in making a commoninfrastructure for GNU projects, and shared a similar outlook on howto do it. So they were able to make some progress. It came alongwith Autoconf and extensions thereof, and then Automake from David andTom (who were both gnitsians). One of their ideas was to write adocument paralleling the GNU standards, that was more strict in someways and more detailed. They never finished the GNITS standards, butthe ideas mostly made their way into Automake.

1995-11-23 Automake 0.20
Besides introducing automatic dependency tracking (see Dependency Tracking Evolution), this version also supplies a 9-page manual.

At this time aclocal and AM_INIT_AUTOMAKE did notexist, so many things had to be done by hand. For instance, here iswhat a configure.in (this is the former name of theconfigure.ac we use today) must contain in order to useAutomake 0.20: 

          PACKAGE=cpio
          VERSION=2.3.911
          AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
          AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
          AC_SUBST(PACKAGE)
          AC_SUBST(VERSION)
          AC_ARG_PROGRAM
          AC_PROG_INSTALL

(Today all of the above is achieved by AC_INIT andAM_INIT_AUTOMAKE.)

Here is how programs are specified in Makefile.am:

          PROGRAMS = hello
          hello_SOURCES = hello.c

This looks pretty much like what we do today, except thePROGRAMS variable has no directory prefix specifying wherehello should be installed: all programs are installed in‘$(bindir)’.LIBPROGRAMS can be used to specify programsthat must be built but not installed (it is callednoinst_PROGRAMS nowadays).

Programs can be built conditionally using AC_SUBSTitutions: 

          PROGRAMS = @progs@
          AM_PROGRAMS = foo bar baz

(AM_PROGRAMS has since then been renamed toEXTRA_PROGRAMS.)

Similarly scripts, static libraries, and data can be built and installedusing theLIBRARIES, SCRIPTS, and DATA variables. HoweverLIBRARIES were treated a bit specially in that Automakedid automatically supply thelib and .a prefixes. Therefore to buildlibcpio.a, one had to write 

          LIBRARIES = cpio
          cpio_SOURCES = ...

Extra files to distribute must be listed in DIST_OTHER (theancestor ofEXTRA_DIST). Also extra directories that are to bedistributed should appear inDIST_SUBDIRS, but the manualdescribes this as a temporary ugly hack (today extra directories shouldalso be listed inEXTRA_DIST, and DIST_SUBDIRS is usedfor another purpose, seeConditional Subdirectories).

1995-11-26 Automake 0.21
In less time than it takes to cook a frozen pizza, Tom rewritesAutomake using Perl. At this time Perl 5 is only one year old, andPerl 4.036 is in use at many sites. Supporting several Perl versionshas been a source of problems through the whole history of Automake.

If you never used Perl 4, imagine Perl 5 without objects, without‘my’ variables (only dynamically scoped ‘local’ variables),without function prototypes, with function calls that needs to beprefixed with ‘&’, etc. Traces of this old style can still befound in today'sautomake.

1995-11-28 Automake 0.22 1995-11-29 Automake 0.23
Bug fixes.
1995-12-08 Automake 0.24 1995-12-10 Automake 0.25
Releases are raining. 0.24 introduces the uniform naming scheme weuse today, i.e., bin_PROGRAMS instead of PROGRAMS, noinst_LIBRARIES instead of LIBLIBRARIES, etc. (However EXTRA_PROGRAMS does not exist yet, AM_PROGRAMS is stillin use; and TEXINFOS and MANS still have no directoryprefixes.) Adding support for prefixes like that was one of the majorideas in automake; it has lasted pretty well.

AutoMake is renamed to Automake (Tom seems to recall it was FrançoisPinard's doing).

0.25 fixes a Perl 4 portability bug.

1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
1995-12-31 François Pinard starts using Automake in GNU tar.
1996-01-03 Automake 0.26 1996-01-03 Automake 0.27
Of the many changes and suggestions sent by François Pinard andincluded in 0.26, perhaps the most important is the advice that toease customization a user rule or variable definition should alwaysoverride an Automake rule or definition.

Gordon Matzigkeit and Jim Meyering are two other early contributorsthat have been sending fixes.

0.27 fixes yet another Perl 4 portability bug.

1996-01-13 Automake 0.28
Automake starts scanning configure.in for LIBOBJSsupport. This is an important step because until this versionAutomake only knew about the Makefile.ams it processed. configure.in was Autoconf's world and the link between Autoconfand Automake had to be done by the Makefile.am author. Forinstance, if config.h was generated by configure, it was thepackage maintainer's responsibility to define the CONFIG_HEADERvariable in each Makefile.am.

Succeeding releases will rely more and more on scanningconfigure.in to better automate the Autoconf integration.

0.28 also introduces the AUTOMAKE_OPTIONS variable and the--gnu and--gnits options, the latter being stricter.

1996-02-07 Automake 0.29
Thanks to configure.in scanning, CONFIG_HEADER is gone,and rebuild rules for configure-generated file areautomatically output.

TEXINFOS and MANS converted to the uniform namingscheme.

1996-02-24 Automake 0.30
The test suite is born. It contains 9 tests. From now on test caseswill be added pretty regularly (see Releases), and this proved tobe really helpful later on.

EXTRA_PROGRAMS finally replaces AM_PROGRAMS.

All the third-party Autoconf macros, written mostly by FrançoisPinard (and later Jim Meyering), are distributed in Automake'shand-writtenaclocal.m4 file. Package maintainers are expectedto extract the necessary macros from this file. (In previous versionsyou had to copy and paste them from the manual...)

1996-03-11 Automake 0.31
The test suite in 0.30 was run via a long check-local rule. UponUlrich Drepper's suggestion, 0.31 makes it an Automake rule outputwhenever the TESTS variable is defined.

DIST_OTHER is renamed to EXTRA_DIST, and the check_prefix is introduced. The syntax is now the same as today.

1996-03-15 Gordon Matzigkeit starts writing libtool.
1996-04-27 Automake 0.32
-hook targets are introduced; an idea from Dieter Baron.

*.info files, which were output in the build directory arenow built in the source directory, because they are distributed. Itseems these files like to move back and forth as that will happenagain in future versions.

1996-05-18 Automake 0.33
Gord Matzigkeit's main two contributions:
  • very preliminary libtool support
  • the distcheck rule

Although they were very basic at this point, these are probablyamong the top features for Automake today.

Jim Meyering also provides the infamous jm_MAINTAINER_MODE,since then renamed toAM_MAINTAINER_MODE and abandoned by itsauthor (see maintainer-mode).

1996-05-28 Automake 1.0
After only six months of heavy development, the automake script is3134 lines long, plus 973 lines of Makefile fragments. Thepackage has 30 pages of documentation, and 38 test cases. aclocal.m4 contains 4 macros.

From now on and until version 1.4, new releases will occur at a rateof about one a year. 1.1 did not exist, actually 1.1b to 1.1p havebeen the name of beta releases for 1.2. This is the first timeAutomake uses suffix letters to designate beta releases, a habit thatlasts.

1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
1996-11-26 David J. MacKenzie releases Autoconf 2.12.
Between June and October, the Autoconf development is almost stalled. Roland McGrath has been working at the beginning of the year. Davidcomes back in November to release 2.12, but he won't touch Autoconfanymore after this year, and Autoconf then really stagnates. Thedesolate Autoconf ChangeLog for 1997 lists only 7 commits.
1997-02-28 automake@gnu.ai.mit.edu list alive
The mailing list is announced as follows: 
          I've created the "automake" mailing list.  It is
          "automake@gnu.ai.mit.edu".  Administrivia, as always, to
          automake-request@gnu.ai.mit.edu.
          
          The charter of this list is discussion of automake, autoconf, and
          other configuration/portability tools (e.g., libtool).  It is expected
          that discussion will range from pleas for help all the way up to
          patches.
          
          This list is archived on the FSF machines.  Offhand I don't know if
          you can get the archive without an account there.
          
          This list is open to anybody who wants to join.  Tell all your
          friends!
          -- Tom Tromey

Before that people were discussing Automake privately, on the Gnitsmailing list (which is not public either), and less frequently ongnu.misc.discuss.

gnu.ai.mit.edu is now gnu.org, in case you nevernoticed. The archives of the early years of theautomake@gnu.org list have been lost, so today it is almostimpossible to find traces of discussions that occurred before 1999. This has been annoying more than once, as such discussions can beuseful to understand the rationale behind a piece of uncommented codethat was introduced back then.

1997-06-22 Automake 1.2
Automake developments continues, and more and more new Autoconf macrosare required. Distributing them in aclocal.m4 and requiringpeople to browse this file to extract the relevant macros becomesuncomfortable. Ideally, some of them should be contributed toAutoconf so that they can be used directly, however Autoconf iscurrently inactive. Automake 1.2 consequently introduces aclocal ( aclocal was actually started on1996-07-28), a tool that automatically constructs an aclocal.m4file from a repository of third-party macros. Because Autoconf hasstalled, Automake also becomes a kind of repository for suchthird-party macros, even macros completely unrelated to Automake (forinstance macros that fix broken Autoconf macros).

The 1.2 release contains 20 macros, including theAM_INIT_AUTOMAKE macro that simplifies the creation ofconfigure.in.

Libtool is fully supported using *_LTLIBRARIES.

The missing script is introduced by François Pinard; it is meant to bea better solution thanAM_MAINTAINER_MODE(see maintainer-mode).

Conditionals support was implemented by Ian Lance Taylor. At thetime, Tom and Ian were working on an internal project at Cygnus. Theywere using ILU, which is pretty similar to CORBA. They wanted tointegrate ILU into their build, which was allconfigure-based,and Ian thought that adding conditionals toautomake wassimpler than doing all the work inconfigure (which was thestandard at the time). So this was actually funded by Cygnus.

This very useful but tricky feature will take a lot of time tostabilize. (At the time this text is written, there are stillprimaries that have not been updated to support conditionaldefinitions in Automake 1.9.)

The automake script has almost doubled: 6089 lines of Perl,plus 1294 lines ofMakefile fragments.

1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
1998-04-05 Automake 1.3
This is a small advance compared to 1.2. It adds support for assembly, and preliminary support for Java.

Perl 5.004_04 is out, but fixes to support Perl 4 are stillregularly submitted whenever Automake breaks it.

1998-09-06 sourceware.cygnus.com is on-line.
Sourceware was setup by Jason Molenda to host open source projects.
1998-09-19 Automake CVS repository moved to sourceware.cygnus.com 1998-10-26 sourceware.cygnus.com announces it hosts Automake:
Automake is now hosted on sourceware.cygnus.com. It has apublicly accessible CVS repository. This CVS repository is a copy ofthe one Tom was using on his machine, which in turn is based ona copy of the CVS repository of David MacKenzie. This is why we stillhave to full source history. (Automake was on Sourceware until 2007-10-29,when it moved to a git repository on savannah.gnu.org,but the Sourceware host had been renamed to sources.redhat.com.)

The oldest file in the administrative directory of the CVS repositorythat was created on Sourceware is dated 1998-09-19, while theannouncement thatautomake and autoconf had joinedsourceware was made on 1998-10-26. They were among thefirst projects to be hosted there.

The heedful reader will have noticed Automake was exactly 4 years oldon 1998-09-19.

1999-01-05 Ben Elliston releases Autoconf 2.13.
1999-01-14 Automake 1.4
This release adds support for Fortran 77 and for the includestatement. Also, ‘ +=’ assignments are introduced, but it isstill quite easy to fool Automake when mixing this with conditionals.

These two releases, Automake 1.4 and Autoconf 2.13 make a duo thatwill be used together for years.

automake is 7228 lines, plus 1591 lines of Makefilefragment, 20 macros (some 1.3 macros were finally contributed back toAutoconf), 197 test cases, and 51 pages of documentation.

1999-03-27 The user-dep-branch is created on the CVS repository.
This implements a new dependency tracking schemed that should beable to handle automatic dependency tracking using any compiler (notjust gcc) and any make (not just GNU make). In addition,the new scheme should be more reliable than the old one, asdependencies are generated on the end user's machine. Alexandre Olivacreates depcomp for this purpose.

See Dependency Tracking Evolution, for more details about theevolution of automatic dependency tracking in Automake.

1999-11-21 The user-dep-branch is merged into the main trunk.
This was a huge problem since we also had patches going in on thetrunk. The merge took a long time and was very painful.
2000-05-10
Since September 1999 and until 2003, Akim Demaille will be zealouslyrevamping Autoconf.
I think the next release should be called "3.0".
Let's face it: you've basically rewritten autoconf.
Every weekend there are 30 new patches.
I don't see how we could call this "2.15" with a straight face.
– Tom Tromey on autoconf@gnu.org

Actually Akim works like a submarine: he will pile up patches while heworks off-line during the weekend, and flush them in batch when heresurfaces on Monday.

2001-01-24
On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50is out, and Akim has to find something to do during his week-end :)
2001-01-28
Akim sends a batch of 14 patches to automake@gnu.org.
Aiieeee! I was dreading the day that the Demaillator turned hissights on automake ... and now it has arrived! – Tom Tromey

It's only the beginning: in two months he will send 192 patches. Thenhe would slow down so Tom can catch up and review all this. InitiallyTom actually read all these patches, then he probably trustinglyanswered OK to most of them, and finally gave up and let Akim applywhatever he wanted. There was no way to keep up with that patch rate.

Anyway the patch below won't apply since it predates Akim'ssourcequake; I have yet to figure where the relevant passage hasbeen moved :) – Alexandre Duret-Lutz

All these patches were sent to and discussed onautomake@gnu.org, so subscribed users were literally drowning intechnical mails. Eventually, theautomake-patches@gnu.orgmailing list was created in May.

Year after year, Automake had drifted away from its initial design:construct Makefile.in by assembling various Makefilefragments. In 1.4, lots ofMakefile rules are being emitted atvarious places in theautomake script itself; this does nothelp ensuring a consistent treatment of these rules (for instancemaking sure that user-defined rules override Automake's own rules). One of Akim's goal was moving all these hard-coded rules to separateMakefile fragments, so the logic could be centralized in aMakefile fragment processor.

Another significant contribution of Akim is the interface with the“trace” feature of Autoconf. The way to scanconfigure.in atthis time was to read the file and grep the various macro of interestto Automake. Doing so could break in many unexpected ways;automakecould miss some definition (for instance ‘AC_SUBST([$1], [$2])’where the arguments are known only when M4 is run), or conversely itcould detect some macro that was not expanded (because it is calledconditionally). In the CVS version of Autoconf, Akim had implementedthe--trace option, which provides accurate information aboutwhere macros are actually called and with what arguments. Akim willequip Automake with a secondconfigure.in scanner that usesthis --trace interface. Since it was not sensible to drop theAutoconf 2.13 compatibility yet, this experimental scanner was onlyused when an environment variable was set, the traditionalgrep-scanner being still the default.

2001-04-25 Gary V. Vaughan releases Libtool 1.4
It has been more than two years since Automake 1.4, CVS Automake hassuffered lot's of heavy changes and still is not ready for release. Libtool 1.4 had to be distributed with a patch against Automake 1.4.
2001-05-08 Automake 1.4-p1 2001-05-24 Automake 1.4-p2
Gary V. Vaughan, the principal Libtool maintainer, makes a “patchrelease” of Automake:
The main purpose of this release is to have a stable automakewhich is compatible with the latest stable libtool.

The release also contains obvious fixes for bugs in Automake 1.4,some of which were reported almost monthly.

2001-05-21 Akim Demaille releases Autoconf 2.50
2001-06-07 Automake 1.4-p3 2001-06-10 Automake 1.4-p4 2001-07-15 Automake 1.4-p5
Gary continues his patch-release series. These also add support forsome new Autoconf 2.50 idioms. Essentially, Autoconf now advocates configure.ac over configure.in, and it introduces a newsyntax for AC_OUTPUTing files.
2001-08-23 Automake 1.5
A major and long-awaited release, that comes more than two years after1.4. It brings many changes, among which:
  • The new dependency tracking scheme that uses depcomp. Aside from the improvement on the dependency tracking itself(seeDependency Tracking Evolution), this also streamlines the useofautomake-generated Makefile.ins as theMakefile.insused during development are now the same as those used indistributions. Before that theMakefile.ins generated formaintainers required GNUmake and GCC, they were differentfrom the portableMakefile generated for distribution; this wascausing some confusion.
  • Support for per-target compilation flags.
  • Support for reference to files in subdirectories in mostMakefile.am variables.
  • Introduction of the dist_, nodist_, and nobase_prefixes.
  • Perl 4 support is finally dropped.

1.5 did break several packages that worked with 1.4. Enough so thatLinux distributions could not easily install the new Automake versionwithout breaking many of the packages for which they had to runautomake.

Some of these breakages were effectively bugs that would eventually befixed in the next release. However, a lot of damage was caused bysome changes made deliberately to render Automake stricter on somesetup we did consider bogus. For instance, ‘make distcheck’ wasimproved to check that ‘make uninstall’ did remove all the files‘make install’ installed, that ‘make distclean’ did not omitsome file, and that a VPATH build would work even if the sourcedirectory was read-only. Similarly, Automake now rejects multipledefinitions of the same variable (because that would mix very badlywith conditionals), and ‘+=’ assignments with no previousdefinition. Because these changes all occurred suddenly after 1.4 hadbeen established for more than two years, it hurt users.

To make matter worse, meanwhile Autoconf (now at version 2.52) wasfacing similar troubles, for similar reasons.

2002-03-05 Automake 1.6
This release introduced versioned installation (see API Versioning). This was mainly pushed by Havoc Pennington, taking theGNOME source tree as motive: due to incompatibilities between theautotools it's impossible for the GNOME packages to switch to Autoconf2.53 and Automake 1.5 all at once, so they are currently stuck withAutoconf 2.13 and Automake 1.4.

The idea was to call this version automake-1.6, call all itsbug-fix versions identically, and switch toautomake-1.7 forthe next release that adds new features or changes some rules. Thisscheme implies maintaining a bug-fix branch in addition to thedevelopment trunk, which means more work from the maintainer, butproviding regular bug-fix releases proved to be really worthwhile.

Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional ornot. Perhaps the more annoying was the dependence on the newlyreleased Autoconf 2.53. Autoconf seemed to have stabilized enoughsince its explosive 2.50 release and included changes required to fixsome bugs in Automake. In order to upgrade to Automake 1.6, peoplenow had to upgrade Autoconf too; for some packages it was no picnic.

While versioned installation helped people to upgrade, it alsounfortunately allowed people not to upgrade. At the time of writing,some Linux distributions are shipping packages for Automake 1.4, 1.5,1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default. Some distribution also call 1.4 the “stable” version, and present“1.9” as the development version; this does not really makes sensesince 1.9 is way more solid than 1.4. All this does not help thenewcomer.

2002-04-11 Automake 1.6.1
1.6, and the upcoming 1.4-p6 release were the last release by Tom. This one and those following will be handled by AlexandreDuret-Lutz. Tom is still around, and will be there until about 1.7,but his interest into Automake is drifting away towards projects like gcj.

Alexandre has been using Automake since 2000, and started tocontribute mostly on Akim's incitement (Akim and Alexandre have beenworking in the same room from 1999 to 2002). In 2001 and 2002 he hada lot of free time to enjoy hacking Automake.

2002-06-14 Automake 1.6.2
2002-07-28 Automake 1.6.3 2002-07-28 Automake 1.4-p6
Two releases on the same day. 1.6.3 is a bug-fix release.

Tom Tromey backported the versioned installation mechanism on the 1.4branch, so that Automake 1.6.x and Automake 1.4-p6 could be installedside by side. Another request from the GNOME folks.

2002-09-25 Automake 1.7
This release switches to the new configure.ac scanner Akimwas experimenting in 1.5.
2002-10-16 Automake 1.7.1 2002-12-06 Automake 1.7.2 2003-02-20 Automake 1.7.3 2003-04-23 Automake 1.7.4 2003-05-18 Automake 1.7.5 2003-07-10 Automake 1.7.6 2003-09-07 Automake 1.7.7 2003-10-07 Automake 1.7.8
Many bug-fix releases. 1.7 lasted because the development version(upcoming 1.8) was suffering some major internal revamping.
2003-10-26 Automake on screen
Episode 49, `Repercussions', in the third season of the `Alias' TVshow is first aired.

Marshall, one of the characters, is working on a computer virus that hehas to modify before it gets into the wrong hands or something likethat. The screenshots you see do not show any program code, they showaMakefile.in generated by automake...

2003-11-09 Automake 1.7.9
2003-12-10 Automake 1.8
The most striking update is probably that of aclocal.

aclocal now uses m4_include in the producedaclocal.m4 when the included macros are already distributedwith the package (an idiom used in many packages), which reduces codeduplication. Many people liked that, but in fact this change wasreally introduced to fix a bug in rebuild rules:Makefile.inmust be rebuilt whenever a dependency ofconfigure changes, butall the m4 files included inaclocal.m4 where unknownfrom automake. Nowautomake can just trace them4_includes to discover the dependencies.

aclocal also starts using the --trace Autoconf optionin order to discover used macros more accurately. This will turn outto be very tricky (later releases will improve this) as people haddevised many ways to cope with the limitation of previousaclocal versions, notably using handwrittenm4_includes: aclocal must make sure not to redefine arule that is already included by such statement.

Automake also has seen its guts rewritten. Although this rewritingtook a lot of efforts, it is only apparent to the users in that someconstructions previously disallowed by the implementation now worknicely. Conditionals, Locations, Variable and Rule definitions,Options: these items on which Automake works have been rewritten asseparate Perl modules, and documented.

2004-01-11 Automake 1.8.1 2004-01-12 Automake 1.8.2 2004-03-07 Automake 1.8.3 2004-04-25 Automake 1.8.4 2004-05-16 Automake 1.8.5
2004-07-28 Automake 1.9
This release tries to simplify the compilation rules it outputs toreduce the size of the Makefile. The complaint initially come fromthe libgcj developers. Their Makefile.in generated withAutomake 1.4 and custom build rules (1.4 did not support compiledJava) is 250KB. The one generated by 1.8 was over 9MB! 1.9 gets itdown to 1.2MB.

Aside from this it contains mainly minor changes and bug-fixes.

2004-08-11 Automake 1.9.1 2004-09-19 Automake 1.9.2
Automake has ten years. This chapter of the manual was initiallywritten for this occasion.
2007-10-29 Automake repository moves to savannah.gnu.org and uses
git as primary repository.

Next:  ,Previous:  Timeline,Up:  History

29.2 Dependency Tracking in Automake

Over the years Automake has deployed three different dependencytracking methods. Each method, including the current one, has hadflaws of various sorts. Here we lay out the different dependencytracking methods, their flaws, and their fixes. We conclude withrecommendations for tool writers, and by indicating future directionsfor dependency tracking work in Automake.

Next:  ,Up:  Dependency Tracking Evolution

29.2.1 First Take on Dependency Tracking
Description

Our first attempt at automatic dependency tracking was based on themethod recommended by GNUmake. (see Generating Prerequisites Automatically)

This version worked by precomputing dependencies ahead of time. Foreach source file, it had a special.P file that held thedependencies. There was a rule to generate a.P file byinvoking the compiler appropriately. All such.P files wereincluded by the Makefile, thus implicitly becoming dependenciesofMakefile.

Bugs

This approach had several critical bugs.

  • The code to generate the .P file relied ongcc. (A limitation, not technically a bug.)
  • The dependency tracking mechanism itself relied on GNU make. (A limitation, not technically a bug.)
  • Because each .P file was a dependency ofMakefile, thismeant that dependency tracking was done eagerly bymake. For instance, ‘make clean’ would cause all the dependency filesto be updated, and then immediately removed. This eagerness alsocaused problems with some configurations; if a certain source filecould not be compiled on a given architecture for some reason,dependency tracking would fail, aborting the entire build.
  • As dependency tracking was done as a pre-pass, compile times weredoubled–the compiler had to be run twice per source file.
  • ‘make dist’ re-ran automake to generate aMakefile that did not have automatic dependency tracking (andthat was thus portable to any version of make). In order todo this portably, Automake had to scan the dependency files and removeany reference that was to a source file not in the distribution. This process was error-prone. Also, if ‘make dist’ was run in anenvironment where some object file had a dependency on a source filethat was only conditionally created, Automake would generate aMakefile that referred to a file that might not appear in theend user's build. A special, hacky mechanism was required to workaround this.
Historical Note

The code generated by Automake is often inspired by theMakefile style of a particular author. In the case of the firstimplementation of dependency tracking, I believe the impetus andinspiration was Jim Meyering. (I could be mistaken. If you knowotherwise feel free to correct me.)

Next:  ,Previous:  First Take on Dependencies,Up:  Dependency Tracking Evolution

29.2.2 Dependencies As Side Effects
Description

The next refinement of Automake's automatic dependency tracking schemewas to implement dependencies as side effects of the compilation. This was aimed at solving the most commonly reported problems with thefirst approach. In particular we were most concerned with eliminatingthe weird rebuilding effect associated with make clean.

In this approach, the .P files were included using the-include command, which let us create these files lazily. Thisavoided the ‘make clean’ problem.

We only computed dependencies when a file was actually compiled. Thisavoided the performance penalty associated with scanning each filetwice. It also let us avoid the other problems associated with thefirst, eager, implementation. For instance, dependencies would neverbe generated for a source file that was not compilable on a givenarchitecture (because it in fact would never be compiled).

Bugs
  • This approach also relied on the existence of gcc and GNUmake. (A limitation, not technically a bug.)
  • Dependency tracking was still done by the developer, so the problemsfrom the first implementation relating to massaging of dependencies by‘make dist’ were still in effect.
  • This implementation suffered from the “deleted header file” problem. Suppose a lazily-created.P file includes a dependency on agiven header file, like this: 
              maude.o: maude.c something.h

    Now suppose that you remove something.h and updatemaude.cso that this include is no longer needed. If you runmake,you will get an error because there is no way to createsomething.h.

    We fixed this problem in a later release by further massaging theoutput of gcc to include a dummy dependency for each headerfile.

Next:  ,Previous:  Dependencies As Side Effects,Up:  Dependency Tracking Evolution

29.2.3 Dependencies for the User
Description

The bugs associated with ‘make dist’, over time, became a realproblem. Packages using Automake were being built on a large numberof platforms, and were becoming increasingly complex. Brokendependencies were distributed in “portable” Makefile.ins,leading to user complaints. Also, the requirement forgccand GNU make was a constant source of bug reports. The nextimplementation of dependency tracking aimed to remove these problems.

We realized that the only truly reliable way to automatically trackdependencies was to do it when the package itself was built. Thismeant discovering a method portable to any version of make and anycompiler. Also, we wanted to preserve what we saw as the best pointof the second implementation: dependency computation as a side effectof compilation.

In the end we found that most modern make implementations support someform of include directive. Also, we wrote a wrapper script that letus abstract away differences between dependency tracking methods forcompilers. For instance, some compilers cannot generate dependenciesas a side effect of compilation. In this case we simply have thescript run the compiler twice. Currently our wrapper script(depcomp) knows about twelve different compilers (includinga "compiler" that simply invokes makedepend and then thereal compiler, which is assumed to be a standard Unix-like C compilerwith no way to do dependency tracking).

Bugs
  • Running a wrapper script for each compilation slows down the build.
  • Many users don't really care about precise dependencies.
  • This implementation, like every other automatic dependency trackingscheme in common use today (indeed, every one we've ever heard of),suffers from the “duplicated new header” bug.

    This bug occurs because dependency tracking tools, such as thecompiler, only generate dependencies on the successful opening of afile, and not on every probe.

    Suppose for instance that the compiler searches three directories fora given header, and that the header is found in the third directory. If the programmer erroneously adds a header file with the same name tothe first directory, then a clean rebuild from scratch could fail(suppose the new header file is buggy), whereas an incremental rebuildwill succeed.

    What has happened here is that people have a misunderstanding of whata dependency is. Tool writers think a dependency encodes informationabout which files were read by the compiler. However, a dependencymust actually encode information about what the compiler tried to do.

    This problem is not serious in practice. Programmers typically do notuse the same name for a header file twice in a given project. (Atleast, not in C or C++. This problem may be more troublesome inJava.) This problem is easy to fix, by modifying dependencygenerators to record every probe, instead of every successful open.

  • Since Automake generates dependencies as a side effect of compilation,there is a bootstrapping problem when header files are generated byrunning a program. The problem is that, the first time the build isdone, there is no way by default to know that the headers arerequired, so make might try to run a compilation for which the headershave not yet been built.

    This was also a problem in the previous dependency tracking implementation.

    The current fix is to use BUILT_SOURCES to list built headers(seeSources). This causes them to be built before any otherbuild rules are run. This is unsatisfactory as a general solution,however in practice it seems sufficient for most actual programs.

This code is used since Automake 1.5.

In GCC 3.0, we managed to convince the maintainers to add specialcommand-line options to help Automake more efficiently do its job. Wehoped this would let us avoid the use of a wrapper script whenAutomake's automatic dependency tracking was used withgcc.

Unfortunately, this code doesn't quite do what we want. Inparticular, it removes the dependency file if the compilation fails;we'd prefer that it instead only touch the file in any way if thecompilation succeeds.

Nevertheless, since Automake 1.7, when a recent gcc isdetected atconfigure time, we inline thedependency-generation code and do not use thedepcompwrapper script. This makes compilations faster for those using thiscompiler (probably our primary user base). The counterpart is thatbecause we have to encode two compilation rules inMakefile(with or without depcomp), the producedMakefiles arelarger.

Next:  ,Previous:  Dependencies for the User,Up:  Dependency Tracking Evolution

29.2.4 Techniques for Computing Dependencies

There are actually several ways for a build tool like Automake tocause tools to generate dependencies.

makedepend
This was a commonly-used method in the past. The idea is to run aspecial program over the source and have it generate dependencyinformation. Traditional implementations of makedepend arenot completely precise; ordinarily they were conservative anddiscovered too many dependencies.
The tool
An obvious way to generate dependencies is to simply write the tool sothat it can generate the information needed by the build tool. This isalso the most portable method. Many compilers have an option togenerate dependencies. Unfortunately, not all tools provide such anoption.
The file system
It is possible to write a special file system that tracks opens,reads, writes, etc, and then feed this information back to the buildtool. clearmake does this. This is a very powerfultechnique, as it doesn't require cooperation from thetool. Unfortunately it is also very difficult to implement and alsonot practical in the general case.
LD_PRELOAD
Rather than use the file system, one could write a special library tointercept open and other syscalls. This technique is also quitepowerful, but unfortunately it is not portable enough for use in automake.

Next:  ,Previous:  Techniques for Dependencies,Up:  Dependency Tracking Evolution

29.2.5 Recommendations for Tool Writers

We think that every compilation tool ought to be able to generatedependencies as a side effect of compilation. Furthermore, at leastwhilemake-based tools are nearly universally in use (atleast in the free software community), the tool itself should generatedummy dependencies for header files, to avoid the deleted header filebug. Finally, the tool should generate a dependency for each probe,instead of each successful file open, in order to avoid the duplicatednew header bug.

Previous:  Recommendations for Tool Writers,Up:  Dependency Tracking Evolution

29.2.6 Future Directions for Dependencies

Currently, only languages and compilers understood by Automake canhave dependency tracking enabled. We would like to see if it ispractical (and worthwhile) to let this support be extended by the userto languages unknown to Automake.

Previous:  Dependency Tracking Evolution,Up:  History

29.3 Release Statistics

The following table (inspired by ‘perlhist(1)’) quantifies theevolution of Automake using these metrics:

Date, Rel
The date and version of the release.
am
The number of lines of the automake script.
acl
The number of lines of the aclocal script.
pm
The number of lines of the Perl supporting modules.
*.am
The number of lines of the Makefile fragments. The number inparentheses is the number of files.
m4
The number of lines (and files) of Autoconf macros.
doc
The number of pages of the documentation (the Postscript version).
t
The number of test cases in the test suite. Of those, the number inparentheses is the number of generated test cases.

DateRelamaclpm*.amm4doct
1994-09-19CVS141  299 (24)   
1994-11-05CVS208  332 (28)   
1995-11-230.20533  458 (35) 9 
1995-11-260.21613  480 (36) 11 
1995-11-280.221116  539 (38) 12 
1995-11-290.231240  541 (38) 12 
1995-12-080.241462  504 (33) 14 
1995-12-100.251513  511 (37) 15 
1996-01-030.261706  438 (36) 16 
1996-01-030.271706  438 (36) 16 
1996-01-130.281964  934 (33) 16 
1996-02-070.292299  936 (33) 17 
1996-02-240.302544  919 (32)85 (1)209
1996-03-110.312877  919 (32)85 (1)2917
1996-04-270.323058  921 (31)85 (1)3026
1996-05-180.333110  926 (31)105 (1)3035
1996-05-281.03134  973 (32)105 (1)3038
1997-06-221.26089385 1294 (36)592 (20)37126
1998-04-051.36415422 1470 (39)741 (23)39156
1999-01-141.47240426 1591 (40)734 (20)51197
2001-05-081.4-p17251426 1591 (40)734 (20)51197
2001-05-241.4-p27268439 1591 (40)734 (20)49197
2001-06-071.4-p37312439 1591 (40)734 (20)49197
2001-06-101.4-p47321439 1591 (40)734 (20)49198
2001-07-151.4-p57228426 1596 (40)734 (20)51198
2001-08-231.580164756002654 (39)1166 (29)63327
2002-03-051.6846547511362732 (39)1603 (27)66365
2002-04-111.6.1854447511362741 (39)1603 (27)66372
2002-06-141.6.2857547511362800 (39)1609 (27)67386
2002-07-281.6.3860047511532809 (39)1609 (27)67391
2002-07-281.4-p67332455 1596 (40)735 (20)49197
2002-09-251.7918947117902965 (39)1606 (28)73430
2002-10-161.7.1922947517902977 (39)1606 (28)73437
2002-12-061.7.2933447517902988 (39)1606 (28)77445
2003-02-201.7.3938947517903023 (39)1651 (29)84448
2003-04-231.7.4942947517903031 (39)1644 (29)85458
2003-05-181.7.5942947517903033 (39)1645 (29)85459
2003-07-101.7.6944247517903033 (39)1660 (29)85461
2003-09-071.7.7944347517903041 (39)1660 (29)90467
2003-10-071.7.8944447517903041 (39)1660 (29)90468
2003-11-091.7.9944447517903048 (39)1660 (29)90468
2003-12-101.8717158577303236 (39)1666 (31)104521
2004-01-111.8.1721766377263287 (39)1686 (31)104525
2004-01-121.8.2721766377263288 (39)1686 (31)104526
2004-03-071.8.3721468677353303 (39)1695 (31)111530
2004-04-251.8.4721468677363310 (39)1701 (31)112531
2004-05-161.8.5724068677363299 (39)1701 (31)112533
2004-07-281.9750871577943352 (40)1812 (32)115551
2004-08-111.9.1751271577943354 (40)1812 (32)115552
2004-09-191.9.2751271577943354 (40)1812 (32)132554
2004-11-011.9.3750771878043354 (40)1812 (32)134556
2004-12-181.9.4750871878563361 (40)1811 (32)140560
2005-02-131.9.5752371978593373 (40)1453 (32)142562
2005-07-101.9.6753969978673400 (40)1453 (32)144570
2006-10-151.107859107280243512 (40)1496 (34)172604
2008-01-191.10.17870108980253520 (40)1499 (34)173617
2008-11-231.10.27882108980273540 (40)1509 (34)176628
2009-05-171.118721109282894164 (42)1714 (37)181732 (20)
2009-12-071.10.37892108980273566 (40)1535 (34)174636
2009-12-071.11.18722109282924162 (42)1730 (37)181739 (20)
2011-12-211.11.28822111283304223 (42)1821 (38)189915 (22)

Next:  ,Previous:  History,Up:  Top

Appendix A Copying This Manual

Up:  Copying This Manual

A.1 GNU Free Documentation License

Version 1.3, 3 November 2008 
     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     http://fsf.org/
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or otherfunctional and useful documentfree in the sense of freedom: toassure everyone the effective freedom to copy and redistribute it,with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a wayto get credit for their work, while not being considered responsiblefor modifications made by others.

    This License is a kind of “copyleft”, which means that derivativeworks of the document must themselves be free in the same sense. Itcomplements the GNU General Public License, which is a copyleftlicense designed for free software.

    We have designed this License in order to use it for manuals for freesoftware, because free software needs free documentation: a freeprogram should come with manuals providing the same freedoms that thesoftware does. But this License is not limited to software manuals;it can be used for any textual work, regardless of subject matter orwhether it is published as a printed book. We recommend this Licenseprincipally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, thatcontains a notice placed by the copyright holder saying it can bedistributed under the terms of this License. Such a notice grants aworld-wide, royalty-free license, unlimited in duration, to use thatwork under the conditions stated herein. The “Document”, below,refers to any such manual or work. Any member of the public is alicensee, and is addressed as “you”. You accept the license if youcopy, modify or distribute the work in a way requiring permissionunder copyright law.

    A “Modified Version” of the Document means any work containing theDocument or a portion of it, either copied verbatim, or withmodifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter sectionof the Document that deals exclusively with the relationship of thepublishers or authors of the Document to the Document's overallsubject (or to related matters) and contains nothing that could falldirectly within that overall subject. (Thus, if the Document is inpart a textbook of mathematics, a Secondary Section may not explainany mathematics.) The relationship could be a matter of historicalconnection with the subject or with related matters, or of legal,commercial, philosophical, ethical or political position regardingthem.

    The “Invariant Sections” are certain Secondary Sections whose titlesare designated, as being those of Invariant Sections, in the noticethat says that the Document is released under this License. If asection does not fit the above definition of Secondary then it is notallowed to be designated as Invariant. The Document may contain zeroInvariant Sections. If the Document does not identify any InvariantSections then there are none.

    The “Cover Texts” are certain short passages of text that are listed,as Front-Cover Texts or Back-Cover Texts, in the notice that says thatthe Document is released under this License. A Front-Cover Text maybe at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy,represented in a format whose specification is available to thegeneral public, that is suitable for revising the documentstraightforwardly with generic text editors or (for images composed ofpixels) generic paint programs or (for drawings) some widely availabledrawing editor, and that is suitable for input to text formatters orfor automatic translation to a variety of formats suitable for inputto text formatters. A copy made in an otherwise Transparent fileformat whose markup, or absence of markup, has been arranged to thwartor discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amountof text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plainascii without markup, Texinfo input format, LaTeX inputformat,SGML or XML using a publicly availableDTD, and standard-conforming simpleHTML,PostScript or PDF designed for human modification. Examplesof transparent image formats includePNG, XCF andJPG. Opaque formats include proprietary formats that can beread and edited only by proprietary word processors,SGML orXML for which the DTD and/or processing tools arenot generally available, and the machine-generatedHTML,PostScript or PDF produced by some word processors foroutput purposes only.

    The “Title Page” means, for a printed book, the title page itself,plus such following pages as are needed to hold, legibly, the materialthis License requires to appear in the title page. For works informats which do not have any title page as such, “Title Page” meansthe text near the most prominent appearance of the work's title,preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes copiesof the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Document whosetitle either is precisely XYZ or contains XYZ in parentheses followingtext that translates XYZ in another language. (Here XYZ stands for aspecific section name mentioned below, such as “Acknowledgements”,“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title”of such a section when you modify the Document means that it remains asection “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice whichstates that this License applies to the Document. These WarrantyDisclaimers are considered to be included by reference in thisLicense, but only as regards disclaiming warranties: any otherimplication that these Warranty Disclaimers may have is void and hasno effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, eithercommercially or noncommercially, provided that this License, thecopyright notices, and the license notice saying this License appliesto the Document are reproduced in all copies, and that you add no otherconditions whatsoever to those of this License. You may not usetechnical measures to obstruct or control the reading or furthercopying of the copies you make or distribute. However, you may acceptcompensation in exchange for copies. If you distribute a large enoughnumber of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, andyou may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly haveprinted covers) of the Document, numbering more than 100, and theDocument's license notice requires Cover Texts, you must enclose thecopies in covers that carry, clearly and legibly, all these CoverTexts: Front-Cover Texts on the front cover, and Back-Cover Texts onthe back cover. Both covers must also clearly and legibly identifyyou as the publisher of these copies. The front cover must presentthe full title with all words of the title equally prominent andvisible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preservethe title of the Document and satisfy these conditions, can be treatedas verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fitlegibly, you should put the first ones listed (as many as fitreasonably) on the actual cover, and continue the rest onto adjacentpages.

    If you publish or distribute Opaque copies of the Document numberingmore than 100, you must either include a machine-readable Transparentcopy along with each Opaque copy, or state in or with each Opaque copya computer-network location from which the general network-usingpublic has access to download using public-standard network protocolsa complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps,when you begin distribution of Opaque copies in quantity, to ensurethat this Transparent copy will remain thus accessible at the statedlocation until at least one year after the last time you distribute anOpaque copy (directly or through your agents or retailers) of thatedition to the public.

    It is requested, but not required, that you contact the authors of theDocument well before redistributing any large number of copies, to givethem a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document underthe conditions of sections 2 and 3 above, provided that you releasethe Modified Version under precisely this License, with the ModifiedVersion filling the role of the Document, thus licensing distributionand modification of the Modified Version to whoever possesses a copyof it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinctfrom that of the Document, and from those of previous versions(which should, if there were any, be listed in the History sectionof the Document). You may use the same title as a previous versionif the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entitiesresponsible for authorship of the modifications in the ModifiedVersion, together with at least five of the principal authors of theDocument (all of its principal authors, if it has fewer than five),unless they release you from this requirement.
    3. State on the Title page the name of the publisher of theModified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modificationsadjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license noticegiving the public permission to use the Modified Version under theterms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sectionsand required Cover Texts given in the Document's license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and addto it an item stating at least the title, year, new authors, andpublisher of the Modified Version as given on the Title Page. Ifthere is no section Entitled “History” in the Document, create onestating the title, year, authors, and publisher of the Document asgiven on its Title Page, then add an item describing the ModifiedVersion as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document forpublic access to a Transparent copy of the Document, and likewisethe network locations given in the Document for previous versionsit was based on. These may be placed in the “History” section. You may omit a network location for a work that was published atleast four years before the Document itself, or if the originalpublisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preservethe Title of the section, and preserve in the section all thesubstance and tone of each of the contributor acknowledgements and/ordedications given therein.
    12. Preserve all the Invariant Sections of the Document,unaltered in their text and in their titles. Section numbersor the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a sectionmay not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” orto conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections orappendices that qualify as Secondary Sections and contain no materialcopied from the Document, you may at your option designate some or allof these sections as invariant. To do this, add their titles to thelist of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it containsnothing but endorsements of your Modified Version by variousparties—for example, statements of peer review or that the text hasbeen approved by an organization as the authoritative definition of astandard.

    You may add a passage of up to five words as a Front-Cover Text, and apassage of up to 25 words as a Back-Cover Text, to the end of the listof Cover Texts in the Modified Version. Only one passage ofFront-Cover Text and one of Back-Cover Text may be added by (orthrough arrangements made by) any one entity. If the Document alreadyincludes a cover text for the same cover, previously added by you orby arrangement made by the same entity you are acting on behalf of,you may not add another; but you may replace the old one, on explicitpermission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this Licensegive permission to use their names for publicity for or to assert orimply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under thisLicense, under the terms defined in section 4 above for modifiedversions, provided that you include in the combination all of theInvariant Sections of all of the original documents, unmodified, andlist them all as Invariant Sections of your combined work in itslicense notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, andmultiple identical Invariant Sections may be replaced with a singlecopy. If there are multiple Invariant Sections with the same name butdifferent contents, make the title of each such section unique byadding at the end of it, in parentheses, the name of the originalauthor or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list ofInvariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History”in the various original documents, forming one section Entitled“History”; likewise combine any sections Entitled “Acknowledgements”,and any sections Entitled “Dedications”. You must delete allsections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documentsreleased under this License, and replace the individual copies of thisLicense in the various documents with a single copy that is included inthe collection, provided that you follow the rules of this License forverbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distributeit individually under this License, provided you insert a copy of thisLicense into the extracted document, and follow this License in allother respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separateand independent documents or works, in or on a volume of a storage ordistribution medium, is called an “aggregate” if the copyrightresulting from the compilation is not used to limit the legal rightsof the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does notapply to the other works in the aggregate which are not themselvesderivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to thesecopies of the Document, then if the Document is less than one half ofthe entire aggregate, the Document's Cover Texts may be placed oncovers that bracket the Document within the aggregate, or theelectronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the wholeaggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you maydistribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires specialpermission from their copyright holders, but you may includetranslations of some or all Invariant Sections in addition to theoriginal versions of these Invariant Sections. You may include atranslation of this License, and all the license notices in theDocument, and any Warranty Disclaimers, provided that you also includethe original English version of this License and the original versionsof those notices and disclaimers. In case of a disagreement betweenthe translation and the original version of this License or a noticeor disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”,“Dedications”, or “History”, the requirement (section 4) to Preserveits Title (section 1) will typically require changing the actualtitle.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Documentexcept as expressly provided under this License. Any attemptotherwise to copy, modify, sublicense, or distribute it is void, andwill automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your licensefrom a particular copyright holder is reinstated (a) provisionally,unless and until the copyright holder explicitly and finallyterminates your license, and (b) permanently, if the copyright holderfails to notify you of the violation by some reasonable means prior to60 days after the cessation.

    Moreover, your license from a particular copyright holder isreinstated permanently if the copyright holder notifies you of theviolation by some reasonable means, this is the first time you havereceived notice of violation of this License (for any work) from thatcopyright holder, and you cure the violation prior to 30 days afteryour receipt of the notice.

    Termination of your rights under this section does not terminate thelicenses of parties who have received copies or rights from you underthis License. If your rights have been terminated and not permanentlyreinstated, receipt of a copy of some or all of the same material doesnot give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versionsof the GNU Free Documentation License from time to time. Such newversions will be similar in spirit to the present version, but maydiffer in detail to address new problems or concerns. Seehttp://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of thisLicense “or any later version” applies to it, you have the option offollowing the terms and conditions either of that specified version orof any later version that has been published (not as a draft) by theFree Software Foundation. If the Document does not specify a versionnumber of this License, you may choose any version ever published (notas a draft) by the Free Software Foundation. If the Documentspecifies that a proxy can decide which future versions of thisLicense can be used, that proxy's public statement of acceptance of aversion permanently authorizes you to choose that version for theDocument.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means anyWorld Wide Web server that publishes copyrightable works and alsoprovides prominent facilities for anybody to edit those works. Apublic wiki that anybody can edit is an example of such a server. A“Massive Multiauthor Collaboration” (or “MMC”) contained in thesite means any set of copyrightable works thus published on the MMCsite.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0license published by Creative Commons Corporation, a not-for-profitcorporation with a principal place of business in San Francisco,California, as well as future copyleft versions of that licensepublished by that same organization.

    “Incorporate” means to publish or republish a Document, in whole orin part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under thisLicense, and if all works that were first published under this Licensesomewhere other than this MMC, and subsequently incorporated in wholeor in part into the MMC, (1) had no cover texts or invariant sections,and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the siteunder CC-BY-SA on the same site at any time before August 1, 2009,provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy ofthe License in the document and put the following copyright andlicense notices just after the title page:

       Copyright (C)  year  your name.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.3
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,replace the “with...Texts.” line with this:

         with the Invariant Sections being list their titles, with
         the Front-Cover Texts being list, and with the Back-Cover Texts
         being list.

If you have Invariant Sections without Cover Texts, or some othercombination of the three, merge those two alternatives to suit thesituation.

If your document contains nontrivial examples of program code, werecommend releasing these examples in parallel under your choice offree software license, such as the GNU General Public License,to permit their use in free software.

Previous:  Copying This Manual,Up:  Top

Appendix B Indices

Next:  ,Up:  Indices

B.1 Macro Index

Next:  ,Previous:  Macro Index,Up:  Indices

B.2 Variable Index

Previous:  Variable Index,Up:  Indices

B.3 General Index

Footnotes

[1] These variables are also calledmake macrosin Make terminology, however in this manual we reserve the termmacro for Autoconf's macros.

[2] Older Autoconf versions usedconfigure.in. Autoconf 2.50 and greater promotesconfigure.ac overconfigure.in. The rest of thisdocumentation will refer toconfigure.ac, but Automake alsosupports configure.in for backward compatibility.

[3] Webelieve. This work is new and there are probably warts. SeeIntroduction, for information on reporting bugs.

[4] There are other, more obscure reasons forthis limitation as well.

[5] Please note thatautomake recognizes-d inAM_YFLAGS only if it is not clustered with otheroptions; for example, it won't be recognized ifAM_YFLAGS is-dt, but it will be ifAM_YFLAGS is -d -t or-d -t

[6] Much, if not most, of theinformation in the following sections pertaining to preprocessingFortran 77 programs was taken almost verbatim fromCatalogue of Rules.

[7] For example,the cfortran packageaddresses all of these inter-language issues, and runs under nearly allFortran 77, C and C++ compilers on nearly all platforms. However,cfortran is not yet Free Software, but it will be in the nextmajor release.

[8] See alsohttp://catb.org/~esr/writings/taoup/html/ch11s09.html.

[9] Automake's ‘dist’ and‘distcheck’ rules had a bug in this regard in that they createddirectories even with-n, but this has been fixed in Automake1.11.

perry_peng
关注
  • 0
    点赞
  • 踩
  • 4
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
wget
perry_peng的专栏
01-07 1万+
<!-- pre.display {font-family:inherit} pre.format {font-family:inherit} pre.smalldisplay {font-family:inherit; font-size:smaller} pre.smallformat {font-family:inherit; font-size:smalle
wget使用 （代理，header，referer 超时限制,次数限制）
guoguo1980的专栏
02-21 1万+
wget -Y on -e "http_proxy=http://[User]:[Password]@ProxyServer:Port/""http://www.jukuu.com"-O a.html -t 2 --timeout=40 --header="User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; zh-CN; rv:1
编译打包linux内核为iso
最新发布
CHNIM的博客
05-11 998
是一个强大的命令行工具，主要用于创建、修改和操作 ISO 9660 文件系统映像，这是光盘上使用的标准文件系统格式。它超越了基本的 ISO 创建功能，还支持更高级的光盘映像操作，如多-session光盘、混合模式（ISO 9660 + HFS 或 UDF）光盘以及Rock Ridge扩展，后者用于在ISO映像中保持Unix/Linux文件属性，如符号链接、所有权和权限。编译Linux内核时，配置是关键的一步，它决定了内核将包含哪些功能以及这些功能是以何种形式存在（例如，是否编译为模块）。
wget命令详解_Linux命令详解（一）
weixin_39681644的博客
12-12 97
Linux命令详解(一)今日详解 ❍locate▶locate 命令可以快速的定位文件，特别是在用户完全不知道文件放在哪里的时候，locate命令是个不错的选择，如下：[WWW@log01 ~]$ locate *exe/usr/bin/gzexe/usr/lib64/python2.6/distutils/command/wininst-6.0.exe/usr/lib64/python...
automake使用说明
weixin_33757609的博客
08-15 296
automake Automake is a tool for automatically generating Makefile.in files compliant with the GNU Coding Standards. Automake requires the use of Autoconf. 复制代码 目前automake支持三种目录层次：flat、shallow和deep。 ...
man gzip
weixin_30508241的博客
05-09 253
GZIP(1) GZIP(1) NAME/名称 gzip, gunzip, zcat - compress or expand files/压缩或展开文件 SYNOPSIS/简介 gzip [ -acdfhlLnNrtvV19 ] [...
ubuntu20.04离线dpkg安装automake
08-23
ubuntu20.04离线dpkg安装automake
automake-1.15.1.tar.gz
09-08
《automake-1.15.1：构建自动化工具在hi3861开发环境中的应用》 在软件开发过程中，构建自动化工具扮演着至关重要的角色，它们能够简化编译、链接和其他构建过程，提高效率并减少人为错误。automake便是这样一款...
automake-1.16.1.tar.xz
06-04
`automake-1.16.1.tar.xz` 是一个包含 `automake-1.16.1` 版本源代码的压缩文件。`automake` 是一个自动化工具，广泛用于开源软件项目，尤其是那些遵循 GNU 编译器集合（GCC）和GNU 编译系统（GNU Build System）...
automake-1.16.tar.gz
03-03
`automake-1.16.tar.gz` 是一个包含了 `automake` 工具的源代码包，主要用于自动化构建过程中的Makefile生成。在Linux和类Unix系统中，`automake` 是一个不可或缺的工具，它与`autoconf`、`libtool`等一起工作，帮助...
automake autotools autoconf
07-18
`autotools`可以理解为一个流程，包括编写`configure.ac`（`autoconf`的输入）、运行`autoconf`生成`configure`脚本，然后编写`Makefile.am`（`automake`的输入），运行`automake`和`autoheader`生成`Makefile.in`和...
GZIP(1)
weixin_34029680的博客
05-29 183
为什么80%的码农都做不了架构师？>>> ...
linux如何压缩为gz文件,将一个.gz文件拆分为多个1GB压缩（.gz）文件
weixin_31702225的博客
04-28 3279
我在Linux上有一个250GB的压缩文件，我想将它拆分为250个1GB文件，并在运行时压缩生成的部分文件(只要一个文件被生成，它应该被压缩)。 我试图用这个 -将一个.gz文件拆分为多个1GB压缩(.gz)文件zcat file.gz | split -b 1G – file.gz.part但这产生未压缩的文件有很强的针对性。我修改它看起来像这样，但得到了一个错误：zcat file.gz | ...
grep命令
行者的博客
01-09 3万+
grep 命令 简介 　　grep (global search regular expression(RE) and print out the line,全面搜索正则表达式并把行打印出来)是一种强大的文本搜索工具，它能使用正则表达式搜索文本，并把匹配的行打印出来。 　　Unix的grep家族包括grep、egrep和fgrep。egrep和fgrep的命令只跟grep有很小不同。egre...
grep常用方法
热门推荐
识途老码
09-21 5万+
grep匹配多个关键字 1、 grep ‘字符串’ 2、 反向匹配grep -v ‘字符串’ 3、 grep -E 同时匹配多个关键字–或关系 4、 同时匹配多个关键字–与关系 5、显示前几行和后几行 通配符(匹配文件名) 常用正则表达式(匹配文件内容) grep常用语法...
Linux命令-grep
喜欢前端的后端 MelodyJerry
02-06 2546
grep 强大的文本搜索工具 补充说明 grep （global search regular expression(RE) and print out the line 全面搜索正则表达式并把行打印出来）是一种强大的文本搜索工具，它能使用正则表达式搜索文本，并把匹配的行打印出来。 用于过滤/搜索的特定字符。 可使用正则表达式能多种命令配合使用，使用上十分灵活。 选项 -a --text # 不要忽略二进制数据。 -A <显示行数> --after-context=<显示行数
用命令:tar -zxvf，解压tar.gz包失败的问题解决。
liuzhongye博客
05-14 1万+
问题描述： 主机上，使用tar -zxvf 解压tar.gz包的时候，出现以下错误： gzip: stdin: not in gzip format tar: Child returned status 1 tar: Error is not recoverable: exiting now 问题办法： 开门见山，先给出解决我这问题的办法。我的错误原因很简单：就是要解压的tar.gz包格式有错误。 用file FILE_NAME 命令，发现是data。 正确的格式应该是：gzip com
grep命令的用法详解
qq_51372804的博客
07-04 1612
其中，`选项`用于指定grep的不同行为，`模式`是要搜索的字符串或正则表达式，`文件`是要在其中搜索模式的文件名。是一个在Linux和Unix系统中使用的强大的搜索工具。它用于在文本文件中查找指定的模式，并打印匹配的行。grep还支持更多的选项和高级的正则表达式搜索功能。-r：递归地搜索目录及其子目录中的文件。-c：统计匹配的行数而非显示匹配行。-v：反转匹配，只输出不匹配的行。-l：只输出包含匹配项的文件名。-i：忽略大小写进行匹配。-n：显示匹配行的行号。-w：仅匹配完整单词。
GNU Automake 1.11.2 官方手册
"automake 手册" GNU Automake 是一个自动化工具，用于根据模板文件生成遵循GNU标准的Makefiles。这个手册是针对Automake版本1.11.2的，由David MacKenzie、Tom Tromey和Alexandre Duret-Lutz等人编写的，旨在帮助...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值