blob: ace21c5e09375176d0deaa1b7b3f667f1a0f1a2c [file] [log] [blame]
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename automake-ng.info
@settitle automake-ng
@setchapternewpage off
@c %**end of header
@include version.texi
@c @ovar(ARG, DEFAULT)
@c -------------------
@c The ARG is an optional argument. To be used for macro arguments in
@c their documentation (@defmac).
@macro ovar{varname}
@r{[}@var{\varname\}@r{]}
@end macro
@set PACKAGE_BUGREPORT automake-ng@@gnu.org
@copying
This manual is for GNU Automake-NG (version @value{VERSION},
@value{UPDATED}), a program that creates GNU standards-compliant
Makefiles from template files.
Copyright @copyright{} 1995-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover texts,
and with no Back-Cover Texts. A copy of the license is included in the
section entitled ``GNU Free Documentation License.''
@end quotation
@end copying
@dircategory Software development
@direntry
* Automake-NG: (automake-ng). Making GNU standards-compliant Makefiles.
@end direntry
@dircategory Individual utilities
@direntry
* aclocal-invocation: (automake-ng)aclocal Invocation. Generating aclocal.m4.
* automake-invocation: (automake-ng)automake Invocation. Generating Makefile.in.
@end direntry
@titlepage
@title GNU Automake-NG
@subtitle For version @value{VERSION}, @value{UPDATED}
@author David MacKenzie
@author Tom Tromey
@author Alexandre Duret-Lutz
@author Ralf Wildenhues
@author Stefano Lattarini
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@c We use the following macros to define indices:
@c @cindex concepts, and anything that does not fit elsewhere
@c @vindex Makefile variables
@c @trindex targets
@c @acindex Autoconf/Automake/Libtool/M4/... macros
@c @opindex tool options
@c Define an index of configure macros.
@defcodeindex ac
@c Define an index of options.
@defcodeindex op
@c Define an index of targets.
@defcodeindex tr
@c Define an index of commands.
@defcodeindex cm
@c Put the macros in the function index.
@syncodeindex ac fn
@c Put everything else into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@syncodeindex tr cp
@syncodeindex cm cp
@ifnottex
@node Top
@comment node-name, next, previous, up
@top GNU Automake-NG
@insertcopying
@menu
* Introduction:: Automake-NG's purpose
* Autotools Introduction:: An Introduction to the Autotools
* Generalities:: General ideas
* Examples:: Some example packages
* automake Invocation:: Creating a Makefile.in
* configure:: Scanning configure.ac, using aclocal
* Directories:: Declaring subdirectories
* Programs:: Building programs and libraries
* Other Objects:: Other derived objects
* Other GNU Tools:: Other GNU Tools
* Documentation:: Building documentation
* Install:: What gets installed
* Clean:: What gets cleaned
* Dist:: What goes in a distribution
* Tests:: Support for test suites
* Rebuilding:: Automatic rebuilding of Makefile
* Options:: Changing Automake's behavior
* Miscellaneous:: Miscellaneous rules
* Include:: Including extra files in an Automake template
* Conditionals:: Conditionals
* Silencing Make:: Obtain less verbose output from @command{make}
* Gnits:: The effect of @option{--gnu} and @option{--gnits}
* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in
* API Versioning:: About compatibility between Automake versions
* Upgrading:: Upgrading to a Newer Automake Version
* FAQ:: Frequently Asked Questions
* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of variables, macros, and concepts
@detailmenu
--- The Detailed Node Listing ---
An Introduction to the Autotools
* GNU Build System:: Introducing the GNU Build System
* Use Cases:: Use Cases for the GNU Build System
* Why Autotools:: How Autotools Help
* Hello World:: A Small Hello World Package
Use Cases for the GNU Build System
* Basic Installation:: Common installation procedure
* Standard Targets:: A list of standard Makefile targets
* Standard Directory Variables:: A list of standard directory variables
* Standard Configuration Variables:: Using configuration variables
* config.site:: Using a config.site file
* VPATH Builds:: Parallel build trees
* Two-Part Install:: Installing data and programs separately
* Cross-Compilation:: Building for other architectures
* Renaming:: Renaming programs at install time
* DESTDIR:: Building binary packages with DESTDIR
* Preparing Distributions:: Rolling out tarballs
* Dependency Tracking:: Automatic dependency tracking
* Nested Packages:: The GNU Build Systems can be nested
A Small Hello World
* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
* amhello's configure.ac Setup Explained::
* amhello's Makefile.am Setup Explained::
General ideas
* General Operation:: General operation of Automake
* Strictness:: Standards conformance checking
* Uniform:: The Uniform Naming Scheme
* Length Limitations:: Staying below the command line length limit
* Canonicalization:: How derived variables are named
* User Variables:: Variables reserved for the user
* Auxiliary Programs:: Programs automake might require
Some example packages
* Complete:: A simple example, start to finish
* true:: Building true and false
Scanning @file{configure.ac}, using @command{aclocal}
* Requirements:: Configuration requirements
* Optional:: Other things Automake recognizes
* aclocal Invocation:: Auto-generating aclocal.m4
* Macros:: Autoconf macros supplied with Automake
Auto-generating aclocal.m4
* aclocal Options:: Options supported by aclocal
* Macro Search Path:: How aclocal finds .m4 files
* Extending aclocal:: Writing your own aclocal macros
* Local Macros:: Organizing local macros
* Serials:: Serial lines in Autoconf macros
* Future of aclocal:: aclocal's scheduled death
Autoconf macros supplied with Automake
* Public Macros:: Macros that you can use.
* Private Macros:: Macros that you should not use.
Directories
* Subdirectories:: Building subdirectories recursively
* Conditional Subdirectories:: Conditionally not building directories
* Alternative:: Subdirectories without recursion
* Subpackages:: Nesting packages
Conditional Subdirectories
* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
* Subdirectories with AC_SUBST:: Another way for conditional recursion
* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
Building Programs and Libraries
* A Program:: Building a program
* A Library:: Building a library
* A Shared Library:: Building a Libtool library
* Program and Library Variables:: Variables controlling program and
library builds
* Default _SOURCES:: Default source files
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
* Program Variables:: Variables used when building a program
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
* Objective C++ Support:: Compiling Objective C++ sources
* Unified Parallel C Support:: Compiling Unified Parallel C sources
* Assembly Support:: Compiling assembly sources
* Fortran 77 Support:: Compiling Fortran 77 sources
* Fortran 9x Support:: Compiling Fortran 9x sources
* Java Support with gcj:: Compiling Java sources using gcj
* Vala Support:: Compiling Vala sources
* Support for Other Languages:: Compiling other languages
* Dependencies:: Automatic dependency tracking
* EXEEXT:: Support for executable extensions
Building a program
* Program Sources:: Defining program sources
* Linking:: Linking with libraries or extra objects
* Conditional Sources:: Handling conditional sources
* Conditional Programs:: Building a program conditionally
Building a Shared Library
* Libtool Concept:: Introducing Libtool
* Libtool Libraries:: Declaring Libtool Libraries
* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
* Conditional Libtool Sources:: Choosing Library Sources Conditionally
* Libtool Convenience Libraries:: Building Convenience Libtool Libraries
* Libtool Modules:: Building Libtool Modules
* Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
* Libtool Issues:: Common Issues Related to Libtool's Use
Common Issues Related to Libtool's Use
* Error required file ltmain.sh not found:: The need to run libtoolize
* Objects created both with libtool and without:: Avoid a specific build race
Fortran 77 Support
* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
* Compiling Fortran 77 Files:: Compiling Fortran 77 sources
* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
Mixing Fortran 77 With C and C++
* How the Linker is Chosen:: Automatic linker selection
Fortran 9x Support
* Compiling Fortran 9x Files:: Compiling Fortran 9x sources
Other Derived Objects
* Scripts:: Executable scripts
* Headers:: Header files
* Data:: Architecture-independent data files
* Sources:: Derived sources
Built Sources
* Built Sources Example:: Several ways to handle built sources.
Other GNU Tools
* Emacs Lisp:: Emacs Lisp
* gettext:: Gettext
* Libtool:: Libtool
* Java:: Java bytecode compilation (deprecated)
* Python:: Python
Building documentation
* Texinfo:: Texinfo
* Man Pages:: Man pages
What Gets Installed
* Basics of Installation:: What gets installed where
* The Two Parts of Install:: Installing data and programs separately
* Extending Installation:: Adding your own rules for installation
* Staged Installs:: Installation in a temporary location
* Install Rules for the User:: Useful additional rules
What Goes in a Distribution
* Basics of Distribution:: Files distributed by default
* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
* The dist Hook:: A target for last-minute distribution changes
* Checking the Distribution:: @samp{make distcheck} explained
* The Types of Distributions:: A variety of formats and compression methods
Support for test suites
* Generalities about Testing:: Generic concepts and terminology about testing
* Simple Tests:: Listing test scripts in @code{TESTS}
* Custom Test Drivers:: Writing and using custom test drivers
* Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
* DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
* Install Tests:: Running tests on installed packages
Simple Tests
* Scripts-based Testsuites:: Automake-specific concepts and terminology
* Serial Test Harness:: Older (and obsolescent) serial test harness
* Parallel Test Harness:: Generic concurrent test harness
Using the TAP test protocol
* Introduction to TAP::
* Use TAP with the Automake test harness::
* Incompatibilities with other TAP parsers and drivers::
* Links and external resources on TAP::
Custom Test Drivers
* Overview of Custom Test Drivers Support::
* Declaring Custom Test Drivers::
* API for Custom Test Drivers::
API for Custom Test Drivers
* Command-line arguments for test drivers::
* Log files generation and test results recording::
* Testsuite progress output::
Changing Automake's Behavior
* Options generalities:: Semantics of Automake option
* List of Automake options:: A comprehensive list of Automake options
Miscellaneous Rules
* Tags:: Interfacing to cscope, etags and mkid
* Suffixes:: Handling new file extensions
Conditionals
* Usage of Conditionals:: Declaring conditional content
* Limits of Conditionals:: Enclosing complete statements
Silencing Make
* Make verbosity:: Make is verbose by default
* Tricks For Silencing Make:: Standard and generic ways to silence make
* Automake Silent Rules:: How Automake can help in silencing make
When Automake Isn't Enough
* Extending:: Adding new rules or overriding existing ones.
* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
Frequently Asked Questions about Automake
* CVS:: CVS and generated files
* maintainer tools:: The missing script and maintainer tools
* Wildcards:: Why doesn't Automake support wildcards?
* Limitations on File Names:: Limitations on source and installed file names
* Errors with distclean:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
* Renamed Objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
* Multiple Outputs:: Writing rules for tools with many output files
* Hard-Coded Install Paths:: Installing to hard-coded locations
* Debugging Make Rules:: Strategies when things don't work as expected
* Reporting Bugs:: Feedback on bugs and feature requests
Copying This Manual
* GNU Free Documentation License:: License for copying this manual
Indices
* Macro Index:: Index of Autoconf macros
* Variable Index:: Index of Makefile variables
* General Index:: General index
@end detailmenu
@end menu
@end ifnottex
@node Introduction
@chapter Introduction
Automake-NG is a tool for automatically generating @file{Makefile.in}s
from files called @file{Makefile.am}. Each @file{Makefile.am} is
basically a series of @command{make} variable
definitions@footnote{These variables are also called @dfn{make macros}
in Make terminology, however in this manual we reserve the term
@dfn{macro} for Autoconf's macros.}, with rules being thrown in
occasionally. The generated @file{Makefile.in}s are compliant with
the GNU Makefile standards.
@cindex GNU Makefile standards
The GNU Makefile Standards Document
(@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
is long, complicated, and subject to change. The goal of Automake-NG
is to remove the burden of Makefile maintenance from the back of the
individual GNU maintainer (and put it on the back of the Automake-NG
maintainers).
The typical Automake-NG input file is simply a series of variable
definitions. Each such file is processed to create a @file{Makefile.in}.
There should generally be one @file{Makefile.am} per directory of a
project.
@cindex Constraints of Automake-NG
@cindex Automake-NG constraints
@cindex Constraints of Automake
@cindex Automake constraints
Automake-NG does constrain a project in certain ways; for instance, it
assumes that the project uses Autoconf (@pxref{Top, , Introduction,
autoconf, The Autoconf Manual}), and enforces certain restrictions on
the @file{configure.ac} contents.
@cindex Automake-NG requirements
@cindex Requirements, Automake-NG
@cindex Automake requirements
@cindex Requirements, Automake
Automake-NG requires @command{perl} in order to generate the
@file{Makefile.in}s. However, the distributions created by Automake-NG
are fully GNU standards-compliant, and do not require @command{perl} in
order to be built.
@cindex Bugs, reporting
@cindex Reporting bugs
@cindex E-mail, bug reports
For more information on bug reports, @xref{Reporting Bugs}.
@node Autotools Introduction
@chapter An Introduction to the Autotools
If you are new to Automake-NG, maybe you know that it is part of a set of
tools called @emph{The Autotools}. Maybe you've already delved into a
package full of files named @file{configure}, @file{configure.ac},
@file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
some of them claiming to be @emph{generated by} Autoconf or Automake-NG.
But the exact purpose of these files and their relations is probably
fuzzy. The goal of this chapter is to introduce you to this machinery,
to show you how it works and how powerful it is. If you've never
installed or seen such a package, do not worry: this chapter will walk
you through it.
If you need some teaching material, more illustrations, or a less
@command{automake}-centered continuation, some slides for this
introduction are available in Alexandre Duret-Lutz's
@uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
Autotools Tutorial}.
This chapter is the written version of the first part of his tutorial.
@menu
* GNU Build System:: Introducing the GNU Build System
* Use Cases:: Use Cases for the GNU Build System
* Why Autotools:: How Autotools Help
* Hello World:: A Small Hello World Package
@end menu
@node GNU Build System
@section Introducing the GNU Build System
@cindex GNU Build System, introduction
It is a truth universally acknowledged, that as a developer in
possession of a new package, you must be in want of a build system.
In the Unix world, such a build system is traditionally achieved using
the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
Manual}). You express the recipe to build your package in a
@file{Makefile}. This file is a set of rules to build the files in
the package. For instance the program @file{prog} may be built by
running the linker on the files @file{main.o}, @file{foo.o}, and
@file{bar.o}; the file @file{main.o} may be built by running the
compiler on @file{main.c}; etc. Each time @command{make} is run, it
reads @file{Makefile}, checks the existence and modification time of
the files mentioned, decides what files need to be built (or rebuilt),
and runs the associated commands.
When a package needs to be built on a different platform than the one
it was developed on, its @file{Makefile} usually needs to be adjusted.
For instance the compiler may have another name or require more
options. In 1991, David J. MacKenzie got tired of customizing
@file{Makefile} for the 20 platforms he had to deal with. Instead, he
handcrafted a little shell script called @file{configure} to
automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
autoconf, The Autoconf Manual}). Compiling his package was now
as simple as running @code{./configure && make}.
@cindex GNU Coding Standards
Today this process has been standardized in the GNU project. The GNU
Coding Standards (@pxref{Managing Releases, The Release Process, ,
standards, The GNU Coding Standards}) explains how each package of the
GNU project should have a @file{configure} script, and the minimal
interface it should have. The @file{Makefile} too should follow some
established conventions. The result? A unified build system that
makes all packages almost indistinguishable by the installer. In its
simplest scenario, all the installer has to do is to unpack the
package, run @code{./configure && make && make install}, and repeat
with the next package to install.
We call this build system the @dfn{GNU Build System}, since it was
grown out of the GNU project. However it is used by a vast number of
other packages: following any existing convention has its advantages.
@cindex Autotools, introduction
The Autotools are tools that will create a GNU Build System for your
package. Autoconf mostly focuses on @file{configure} and Automake-NG
on @file{Makefile}s. It is entirely possible to create a GNU Build
System without the help of these tools. However it is rather
burdensome and error-prone. We will discuss this again after some
illustration of the GNU Build System in action.
@node Use Cases
@section Use Cases for the GNU Build System
@cindex GNU Build System, use cases
@cindex GNU Build System, features
@cindex Features of the GNU Build System
@cindex Use Cases for the GNU Build System
@cindex @file{amhello-1.0.tar.gz}, location
@cindex @file{amhello-1.0.tar.gz}, use cases
In this section we explore several use cases for the GNU Build System.
You can replay all of these examples on the @file{amhello-1.0.tar.gz}
package distributed with Automake-NG. If Automake-NG is installed on
your system, you should find a copy of this file in
@file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
@var{prefix} is the installation prefix specified during configuration
(@var{prefix} defaults to @file{/usr/local}, however if Automake-NG was
installed by some GNU/Linux distribution it most likely has been set
to @file{/usr}). If you do not have a copy of Automake-NG installed,
you can find a copy of this file inside the @file{doc/} directory of
the Automake-NG package.
Some of the following use cases present features that are in fact
extensions to the GNU Build System. Read: they are not specified by
the GNU Coding Standards, but they are nonetheless part of the build
system created by the Autotools. To keep things simple, we do not
point out the difference. Our objective is to show you many of the
features that the build system created by the Autotools will offer to
you.
@menu
* Basic Installation:: Common installation procedure
* Standard Targets:: A list of standard Makefile targets
* Standard Directory Variables:: A list of standard directory variables
* Standard Configuration Variables:: Using configuration variables
* config.site:: Using a config.site file
* VPATH Builds:: Parallel build trees
* Two-Part Install:: Installing data and programs separately
* Cross-Compilation:: Building for other architectures
* Renaming:: Renaming programs at install time
* DESTDIR:: Building binary packages with DESTDIR
* Preparing Distributions:: Rolling out tarballs
* Dependency Tracking:: Automatic dependency tracking
* Nested Packages:: The GNU Build Systems can be nested
@end menu
@node Basic Installation
@subsection Basic Installation
@cindex Configuration, basics
@cindex Installation, basics
@cindex GNU Build System, basics
The most common installation procedure looks as follows.
@example
~ % @kbd{tar zxf amhello-1.0.tar.gz}
~ % @kbd{cd amhello-1.0}
~/amhello-1.0 % @kbd{./configure}
@dots{}
config.status: creating Makefile
config.status: creating src/Makefile
@dots{}
~/amhello-1.0 % @kbd{make}
@dots{}
~/amhello-1.0 % @kbd{make check}
@dots{}
~/amhello-1.0 % @kbd{su}
Password:
/home/adl/amhello-1.0 # @kbd{make install}
@dots{}
/home/adl/amhello-1.0 # @kbd{exit}
~/amhello-1.0 % @kbd{make installcheck}
@dots{}
@end example
@cindex Unpacking
The user first unpacks the package. Here, and in the following
examples, we will use the non-portable @code{tar zxf} command for
simplicity. On a system without GNU @command{tar} installed, this
command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
The user then enters the newly created directory to run the
@file{configure} script. This script probes the system for various
features, and finally creates the @file{Makefile}s. In this toy
example there are only two @file{Makefile}s, but in real-world projects,
there may be many more, usually one @file{Makefile} per directory.
It is now possible to run @code{make}. This will construct all the
programs, libraries, and scripts that need to be constructed for the
package. In our example, this compiles the @file{hello} program.
All files are constructed in place, in the source tree; we will see
later how this can be changed.
@code{make check} causes the package's tests to be run. This step is
not mandatory, but it is often good to make sure the programs that
have been built behave as they should, before you decide to install
them. Our example does not contain any tests, so running @code{make
check} is a no-op.
@cindex su, before @code{make install}
After everything has been built, and maybe tested, it is time to
install it on the system. That means copying the programs,
libraries, header files, scripts, and other data files from the
source directory to their final destination on the system. The
command @code{make install} will do that. However, by default
everything will be installed in subdirectories of @file{/usr/local}:
binaries will go into @file{/usr/local/bin}, libraries will end up in
@file{/usr/local/lib}, etc. This destination is usually not writable
by any user, so we assume that we have to become root before we can
run @code{make install}. In our example, running @code{make install}
will copy the program @file{hello} into @file{/usr/local/bin}
and @file{README} into @file{/usr/local/share/doc/amhello}.
A last and optional step is to run @code{make installcheck}. This
command may run tests on the installed files. @code{make check} tests
the files in the source tree, while @code{make installcheck} tests
their installed copies. The tests run by the latter can be different
from those run by the former. For instance, there are tests that
cannot be run in the source tree. Conversely, some packages are set
up so that @code{make installcheck} will run the very same tests as
@code{make check}, only on different files (non-installed
vs.@: installed). It can make a difference, for instance when the
source tree's layout is different from that of the installation.
Furthermore it may help to diagnose an incomplete installation.
Presently most packages do not have any @code{installcheck} tests
because the existence of @code{installcheck} is little known, and its
usefulness is neglected. Our little toy package is no better: @code{make
installcheck} does nothing.
@node Standard Targets
@subsection Standard @file{Makefile} Targets
So far we have come across four ways to run @command{make} in the GNU
Build System: @code{make}, @code{make check}, @code{make install}, and
@code{make installcheck}. The words @code{check}, @code{install}, and
@code{installcheck}, passed as arguments to @command{make}, are called
@dfn{targets}. @code{make} is a shorthand for @code{make all},
@code{all} being the default target in the GNU Build System.
Here is a list of the most useful targets that the GNU Coding Standards
specify.
@table @code
@item make all
@trindex all
Build programs, libraries, documentation, etc.@: (same as @code{make}).
@item make install
@trindex install
Install what needs to be installed, copying the files from the
package's tree to system-wide directories.
@item make install-strip
@trindex install-strip
Same as @code{make install}, then strip debugging symbols. Some
users like to trade space for useful bug reports@enddots{}
@item make uninstall
@trindex uninstall
The opposite of @code{make install}: erase the installed files.
(This needs to be run from the same build tree that was installed.)
@item make clean
@trindex clean
Erase from the build tree the files built by @code{make all}.
@item make distclean
@trindex distclean
Additionally erase anything @code{./configure} created.
@item make check
@trindex check
Run the test suite, if any.
@item make installcheck
@trindex installcheck
Check the installed programs or libraries, if supported.
@item make dist
@trindex dist
Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
files.
@end table
@node Standard Directory Variables
@subsection Standard Directory Variables
@cindex directory variables
The GNU Coding Standards also specify a hierarchy of variables to
denote installation directories. Some of these are:
@multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
@headitem Directory variable @tab Default value
@item @code{prefix} @tab @code{/usr/local}
@item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
@item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
@item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
@item @w{@ @ @ @ @dots{}}
@item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
@item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
@item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
@item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
@item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
@item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
@item @w{@ @ @dots{}}
@end multitable
@c We should provide a complete table somewhere, but not here. The
@c complete list of directory variables it too confusing as-is. It
@c requires some explanations that are too complicated for this
@c introduction. Besides listing directories like localstatedir
@c would make the explanations in ``Two-Part Install'' harder.
Each of these directories has a role which is often obvious from its
name. In a package, any installable file will be installed in one of
these directories. For instance in @code{amhello-1.0}, the program
@file{hello} is to be installed in @var{bindir}, the directory for
binaries. The default value for this directory is
@file{/usr/local/bin}, but the user can supply a different value when
calling @command{configure}. Also the file @file{README} will be
installed into @var{docdir}, which defaults to
@file{/usr/local/share/doc/amhello}.
@opindex --prefix
As a user, if you wish to install a package on your own account, you
could proceed as follows:
@example
~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
@dots{}
~/amhello-1.0 % @kbd{make}
@dots{}
~/amhello-1.0 % @kbd{make install}
@dots{}
@end example
This would install @file{~/usr/bin/hello} and
@file{~/usr/share/doc/amhello/README}.
The list of all such directory options is shown by
@code{./configure --help}.
@node Standard Configuration Variables
@subsection Standard Configuration Variables
@cindex configuration variables, overriding
The GNU Coding Standards also define a set of standard configuration
variables used during the build. Here are some:
@table @asis
@item @code{CC}
C compiler command
@item @code{CFLAGS}
C compiler flags
@item @code{CXX}
C++ compiler command
@item @code{CXXFLAGS}
C++ compiler flags
@item @code{LDFLAGS}
linker flags
@item @code{CPPFLAGS}
C/C++ preprocessor flags
@item @dots{}
@end table
@command{configure} usually does a good job at setting appropriate
values for these variables, but there are cases where you may want to
override them. For instance you may have several versions of a
compiler installed and would like to use another one, you may have
header files installed outside the default search path of the
compiler, or even libraries out of the way of the linker.
Here is how one would call @command{configure} to force it to use
@command{gcc-3} as C compiler, use header files from
@file{~/usr/include} when compiling, and libraries from
@file{~/usr/lib} when linking.
@example
~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
@end example
Again, a full list of these variables appears in the output of
@code{./configure --help}.
@node config.site
@subsection Overriding Default Configuration Setting with @file{config.site}
@cindex @file{config.site} example
When installing several packages using the same setup, it can be
convenient to create a file to capture common settings.
If a file named @file{@var{prefix}/share/config.site} exists,
@command{configure} will source it at the beginning of its execution.
Recall the command from the previous section:
@example
~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
@end example
Assuming we are installing many package in @file{~/usr}, and will
always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
@code{LDFLAGS}, we can automate this by creating the following
@file{~/usr/share/config.site} file:
@example
test -z "$CC" && CC=gcc-3
test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
@end example
Now, any time a @file{configure} script is using the @file{~/usr}
prefix, it will execute the above @file{config.site} and define
these three variables.
@example
~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
configure: loading site script /home/adl/usr/share/config.site
@dots{}
@end example
@xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
Manual}, for more information about this feature.
@node VPATH Builds
@subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
@cindex Parallel build trees
@cindex VPATH builds
@cindex source tree and build tree
@cindex build tree and source tree
@cindex trees, source vs.@: build
The GNU Build System distinguishes two trees: the source tree, and
the build tree.
The source tree is rooted in the directory containing
@file{configure}. It contains all the sources files (those that are
distributed), and may be arranged using several subdirectories.
The build tree is rooted in the directory in which @file{configure}
was run, and is populated with all object files, programs, libraries,
and other derived files built from the sources (and hence not
distributed). The build tree usually has the same subdirectory layout
as the source tree; its subdirectories are created automatically by
the build system.
If @file{configure} is executed in its own directory, the source and
build trees are combined: derived files are constructed in the same
directories as their sources. This was the case in our first
installation example (@pxref{Basic Installation}).
A common request from users is that they want to confine all derived
files to a single directory, to keep their source directories
uncluttered. Here is how we could run @file{configure} to build
everything in a subdirectory called @file{build/}.
@example
~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
~ % @kbd{cd amhello-1.0}
~/amhello-1.0 % @kbd{mkdir build && cd build}
~/amhello-1.0/build % @kbd{../configure}
@dots{}
~/amhello-1.0/build % @kbd{make}
@dots{}
@end example
These setups, where source and build trees are different, are often
called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
@emph{parallel build} is misleading: the word @emph{parallel} is a
reference to the way the build tree shadows the source tree, it is not
about some concurrency in the way build commands are run. For this
reason we refer to such setups using the name @emph{VPATH builds} in
the following. @emph{VPATH} is the name of the @command{make} feature
used by the @file{Makefile}s to allow these builds (@pxref{General
Search, , @code{VPATH} Search Path for All Prerequisites, make, The
GNU Make Manual}).
@cindex multiple configurations, example
@cindex debug build, example
@cindex optimized build, example
VPATH builds have other interesting uses. One is to build the same
sources with multiple configurations. For instance:
@c Keep in sync with amhello-cflags.sh
@example
~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
~ % @kbd{cd amhello-1.0}
~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
@dots{}
~/amhello-1.0/debug % @kbd{make}
@dots{}
~/amhello-1.0/debug % cd ../optim
~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
@dots{}
~/amhello-1.0/optim % @kbd{make}
@dots{}
@end example
With network file systems, a similar approach can be used to build the
same sources on different machines. For instance, suppose that the
sources are installed on a directory shared by two hosts: @code{HOST1}
and @code{HOST2}, which may be different platforms.
@example
~ % @kbd{cd /nfs/src}
/nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
@end example
On the first host, you could create a local build directory:
@example
[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
...
[HOST1] /tmp/amh % @kbd{make && sudo make install}
...
@end example
@noindent
(Here we assume that the installer has configured @command{sudo} so it
can execute @code{make install} with root privileges; it is more convenient
than using @command{su} like in @ref{Basic Installation}).
On the second host, you would do exactly the same, possibly at
the same time:
@example
[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
...
[HOST2] /tmp/amh % @kbd{make && sudo make install}
...
@end example
@cindex read-only source tree
@cindex source tree, read-only
In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
directory from being read-only. In fact VPATH builds are also a means
of building packages from a read-only medium such as a CD-ROM. (The
FSF used to sell CD-ROM with unpacked source code, before the GNU
project grew so big.)
@node Two-Part Install
@subsection Two-Part Installation
In our last example (@pxref{VPATH Builds}), a source tree was shared
by two hosts, but compilation and installation were done separately on
each host.
The GNU Build System also supports networked setups where part of the
installed files should be shared amongst multiple hosts. It does so
by distinguishing architecture-dependent files from
architecture-independent files, and providing two @file{Makefile}
targets to install each of these classes of files.
@trindex install-exec
@trindex install-data
These targets are @code{install-exec} for architecture-dependent files
and @code{install-data} for architecture-independent files.
The command we used up to now, @code{make install}, can be thought of
as a shorthand for @code{make install-exec install-data}.
From the GNU Build System point of view, the distinction between
architecture-dependent files and architecture-independent files is
based exclusively on the directory variable used to specify their
installation destination. In the list of directory variables we
provided earlier (@pxref{Standard Directory Variables}), all the
variables based on @var{exec-prefix} designate architecture-dependent
directories whose files will be installed by @code{make install-exec}.
The others designate architecture-independent directories and will
serve files installed by @code{make install-data}. @xref{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
@file{/usr}, and (2) the directory @file{/usr/share} is shared by the
two hosts.
On the first host we would run
@example
[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
...
[HOST1] /tmp/amh % @kbd{make && sudo make install}
...
@end example
On the second host, however, we need only install the
architecture-specific files.
@example
[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
...
[HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
...
@end example
In packages that have installation checks, it would make sense to run
@code{make installcheck} (@pxref{Basic Installation}) to verify that
the package works correctly despite the apparent partial installation.
@node Cross-Compilation
@subsection Cross-Compilation
@cindex cross-compilation
To @dfn{cross-compile} is to build on one platform a binary that will
run on another platform. When speaking of cross-compilation, it is
important to distinguish between the @dfn{build platform} on which
the compilation is performed, and the @dfn{host platform} on which the
resulting executable is expected to run. The following
@command{configure} options are used to specify each of them:
@table @option
@item --build=@var{build}
@opindex --build=@var{build}
The system on which the package is built.
@item --host=@var{host}
@opindex --host=@var{host}
The system where built programs and libraries will run.
@end table
When the @option{--host} is used, @command{configure} will search for
the cross-compiling suite for this platform. Cross-compilation tools
commonly have their target architecture as prefix of their name. For
instance my cross-compiler for MinGW32 has its binaries called
@code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
@code{i586-mingw32msvc-as}, etc.
@cindex MinGW cross-compilation example
@cindex cross-compilation example
Here is how we could build @code{amhello-1.0} for
@code{i586-mingw32msvc} on a GNU/Linux PC.
@c Keep in sync with amhello-cross-compile.sh
@smallexample
~/amhello-1.0 % @kbd{./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...
@dots{}
~/amhello-1.0 % @kbd{make}
@dots{}
~/amhello-1.0 % @kbd{cd src; file hello.exe}
hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
@end smallexample
The @option{--host} and @option{--build} options are usually all we
need for cross-compiling. The only exception is if the package being
built is itself a cross-compiler: we need a third option to specify
its target architecture.
@table @option
@item --target=@var{target}
@opindex --target=@var{target}
When building compiler tools: the system for which the tools will
create output.
@end table
For instance when installing GCC, the GNU Compiler Collection, we can
use @option{--target=@/@var{target}} to specify that we want to build
GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
@option{--target}, we can actually cross-compile a cross-compiler;
such a three-way cross-compilation is known as a @dfn{Canadian cross}.
@xref{Specifying Names, , Specifying the System Type, autoconf, The
Autoconf Manual}, for more information about these @command{configure}
options.
@node Renaming
@subsection Renaming Programs at Install Time
@cindex Renaming programs
@cindex Transforming program names
@cindex Programs, renaming during installation
The GNU Build System provides means to automatically rename
executables and manpages before they are installed (@pxref{Man Pages}).
This is especially convenient
when installing a GNU package on a system that already has a
proprietary implementation you do not want to overwrite. For instance,
you may want to install GNU @command{tar} as @command{gtar} so you can
distinguish it from your vendor's @command{tar}.
This can be done using one of these three @command{configure} options.
@table @option
@item --program-prefix=@var{prefix}
@opindex --program-prefix=@var{prefix}
Prepend @var{prefix} to installed program names.
@item --program-suffix=@var{suffix}
@opindex --program-suffix=@var{suffix}
Append @var{suffix} to installed program names.
@item --program-transform-name=@var{program}
@opindex --program-transform-name=@var{program}
Run @code{sed @var{program}} on installed program names.
@end table
The following commands would install @file{hello}
as @file{/usr/local/bin/test-hello}, for instance.
@example
~/amhello-1.0 % @kbd{./configure --program-prefix test-}
@dots{}
~/amhello-1.0 % @kbd{make}
@dots{}
~/amhello-1.0 % @kbd{sudo make install}
@dots{}
@end example
@node DESTDIR
@subsection Building Binary Packages Using DESTDIR
@vindex DESTDIR
The GNU Build System's @code{make install} and @code{make uninstall}
interface does not exactly fit the needs of a system administrator
who has to deploy and upgrade packages on lots of hosts. In other
words, the GNU Build System does not replace a package manager.
Such package managers usually need to know which files have been
installed by a package, so a mere @code{make install} is
inappropriate.
@cindex Staged installation
The @code{DESTDIR} variable can be used to perform a staged
installation. The package should be configured as if it was going to
be installed in its final location (e.g., @code{--prefix /usr}), but
when running @code{make install}, the @code{DESTDIR} should be set to
the absolute name of a directory into which the installation will be
diverted. From this directory it is easy to review which files are
being installed where, and finally copy them to their final location
by some means.
@cindex Binary package
For instance here is how we could create a binary package containing a
snapshot of all the files to be installed.
@c Keep in sync with amhello-binpkg.sh
@example
~/amhello-1.0 % @kbd{./configure --prefix /usr}
@dots{}
~/amhello-1.0 % @kbd{make}
@dots{}
~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
@dots{}
~/amhello-1.0 % @kbd{cd ~/inst}
~/inst % @kbd{find . -type f -print > ../files.lst}
~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
./usr/bin/hello
./usr/share/doc/amhello/README
@end example
After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
instead of @samp{.} as argument for @command{tar} avoids entries for
each subdirectory in the archive: we would not like @command{tar} to
restore the modification time of @file{/}, @file{/usr/}, etc.)
Note that when building packages for several architectures, it might
be convenient to use @code{make install-data} and @code{make
install-exec} (@pxref{Two-Part Install}) to gather
architecture-independent files in a single package.
@xref{Install}, for more information.
@c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
@c UNINSTALL counterparts.
@node Preparing Distributions
@subsection Preparing Distributions
@cindex Preparing distributions
@cindex Packages, preparation
@cindex Distributions, preparation
We have already mentioned @code{make dist}. This target collects all
your source files and the necessary parts of the build system to
create a tarball named @file{@var{package}-@var{version}.tar.gz}.
@cindex @code{distcheck} better than @code{dist}
Another, more useful command is @code{make distcheck}. The
@code{distcheck} target constructs
@file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
but it additionally ensures most of the use cases presented so far
work:
@itemize @bullet
@item
It attempts a full compilation of the package (@pxref{Basic
Installation}), unpacking the newly constructed tarball, running
@code{make}, @code{make check}, @code{make install}, as well as
@code{make installcheck}, and even @code{make dist},
@item
it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
@item
it makes sure @code{make clean}, @code{make distclean}, and @code{make
uninstall} do not omit any file (@pxref{Standard Targets}),
@item
and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
@end itemize
All of these actions are performed in a temporary subdirectory, so
that no root privileges are required.
Releasing a package that fails @code{make distcheck} means that one of
the scenarios we presented will not work and some users will be
disappointed. Therefore it is a good practice to release a package
only after a successful @code{make distcheck}. This of course does
not imply that the package will be flawless, but at least it will
prevent some of the embarrassing errors you may find in packages
released by people who have never heard about @code{distcheck} (like
@code{DESTDIR} not working because of a typo, or a distributed file
being erased by @code{make clean}, or even @code{VPATH} builds not
working).
@xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
@code{make distcheck}. @xref{Checking the Distribution}, for more
information about @code{distcheck}.
@node Dependency Tracking
@subsection Automatic Dependency Tracking
@cindex Dependency tracking
Dependency tracking is performed as a side-effect of compilation.
Each time the build system compiles a source file, it computes its
list of dependencies (in C these are the header files included by the
source being compiled). Later, any time @command{make} is run and a
dependency appears to have changed, the dependent files will be
rebuilt.
Automake generates code for automatic dependency tracking by default,
unless the developer chooses to override it; for more information,
@pxref{Dependencies}.
When @command{configure} is executed, you can see it probing each
compiler for the dependency mechanism it supports (several mechanisms
can be used):
@example
~/amhello-1.0 % @kbd{./configure --prefix /usr}
@dots{}
checking dependency style of gcc... gcc3
@dots{}
@end example
Because dependencies are only computed as a side-effect of the
compilation, no dependency information exists the first time a package
is built. This is OK because all the files need to be built anyway:
@code{make} does not have to decide which files need to be rebuilt.
In fact, dependency tracking is completely useless for one-time builds
and there is a @command{configure} option to disable this:
@table @option
@item --disable-dependency-tracking
@opindex --disable-dependency-tracking
Speed up one-time builds.
@end table
Some compilers do not offer any practical way to derive the list of
dependencies as a side-effect of the compilation, requiring a separate
run (maybe of another tool) to compute these dependencies. The
performance penalty implied by these methods is important enough to
disable them by default. The option @option{--enable-dependency-tracking}
must be passed to @command{configure} to activate them.
@table @option
@item --enable-dependency-tracking
@opindex --enable-dependency-tracking
Do not reject slow dependency extractors.
@end table
@xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
automake-history, Brief History of Automake}, for some discussion about
the different dependency tracking schemes used by Automake over the years.
@node Nested Packages
@subsection Nested Packages
@cindex Nested packages
@cindex Packages, nested
@cindex Subpackages
Although nesting packages isn't something we would recommend to
someone who is discovering the Autotools, it is a nice feature worthy
of mention in this small advertising tour.
Autoconfiscated packages (that means packages whose build system have
been created by Autoconf and friends) can be nested to arbitrary
depth.
A typical setup is that package A will distribute one of the libraries
it needs in a subdirectory. This library B is a complete package with
its own GNU Build System. The @command{configure} script of A will
run the @command{configure} script of B as part of its execution,
building and installing A will also build and install B. Generating a
distribution for A will also include B.
It is possible to gather several packages like this. GCC is a heavy
user of this feature. This gives installers a single package to
configure, build and install, while it allows developers to work on
subpackages independently.
When configuring nested packages, the @command{configure} options
given to the top-level @command{configure} are passed recursively to
nested @command{configure}s. A package that does not understand an
option will ignore it, assuming it is meaningful to some other
package.
@opindex --help=recursive
The command @code{configure --help=recursive} can be used to display
the options supported by all the included packages.
@xref{Subpackages}, for an example setup.
@node Why Autotools
@section How Autotools Help
@cindex Autotools, purpose
There are several reasons why you may not want to implement the GNU
Build System yourself (read: write a @file{configure} script and
@file{Makefile}s yourself).
@itemize @bullet
@item
As we have seen, the GNU Build System has a lot of
features (@pxref{Use Cases}).
Some users may expect features you have not implemented because
you did not need them.
@item
Implementing these features portably is difficult and exhausting.
Think of writing portable shell scripts, and portable
@file{Makefile}s, for systems you may not have handy. @xref{Portable
Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
convince yourself.
@item
You will have to upgrade your setup to follow changes to the GNU
Coding Standards.
@end itemize
The GNU Autotools take all this burden off your back and provide:
@itemize @bullet
@item
Tools to create a portable, complete, and self-contained GNU Build
System, from simple instructions.
@emph{Self-contained} meaning the resulting build system does not
require the GNU Autotools.
@item
A central place where fixes and improvements are made:
a bug-fix for a portability issue will benefit every package.
@end itemize
Yet there also exist reasons why you may want NOT to use the
Autotools@enddots{} For instance you may be already using (or used to)
another incompatible build system. Autotools will only be useful if
you do accept the concepts of the GNU Build System. People who have their
own idea of how a build system should work will feel frustrated by the
Autotools.
@node Hello World
@section A Small Hello World
@cindex Example Hello World
@cindex Hello World example
@cindex @file{amhello-1.0.tar.gz}, creation
In this section we recreate the @file{amhello-1.0} package from
scratch. The first subsection shows how to call the Autotools to
instantiate the GNU Build System, while the second explains the
meaning of the @file{configure.ac} and @file{Makefile.am} files read
by the Autotools.
@anchor{amhello Explained}
@menu
* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
* amhello's configure.ac Setup Explained::
* amhello's Makefile.am Setup Explained::
@end menu
@node Creating amhello
@subsection Creating @file{amhello-1.0.tar.gz}
Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
The package is simple enough so that we will only need to write 5
files. (You may copy them from the final @file{amhello-1.0.tar.gz}
that is distributed with Automake if you do not want to write them.)
Create the following files in an empty directory.
@itemize @bullet
@item
@file{src/main.c} is the source file for the @file{hello} program. We
store it in the @file{src/} subdirectory, because later, when the package
evolves, it will ease the addition of a @file{man/} directory for man
pages, a @file{data/} directory for data files, etc.
@example
~/amhello % @kbd{cat src/main.c}
#include <config.h>
#include <stdio.h>
int
main (void)
@{
puts ("Hello World!");
puts ("This is " PACKAGE_STRING ".");
return 0;
@}
@end example
@item
@file{README} contains some very limited documentation for our little
package.
@example
~/amhello % @kbd{cat README}
This is a demonstration package for GNU Automake-NG.
Type 'info Automake-NG' to read its manual.
@end example
@item
@file{Makefile.am} and @file{src/Makefile.am} contain Automake-NG
instructions for these two directories.
@example
~/amhello % @kbd{cat src/Makefile.am}
bin_PROGRAMS = hello
hello_SOURCES = main.c
~/amhello % @kbd{cat Makefile.am}
SUBDIRS = src
dist_doc_DATA = README
@end example
@item
Finally, @file{configure.ac} contains Autoconf instructions to
create the @command{configure} script.
@example
~/amhello % @kbd{cat configure.ac}
AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
AM_INIT_AUTOMAKE([-Wall -Werror foreign])
AC_PROG_CC
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_FILES([
Makefile
src/Makefile
])
AC_OUTPUT
@end example
@end itemize
@cindex @command{autoreconf}, example
Once you have these five files, it is time to run the Autotools to
instantiate the build system. Do this using the @command{autoreconf}
command as follows:
@example
~/amhello % @kbd{autoreconf --install}
configure.ac: installing './install-sh'
configure.ac: installing './missing'
src/Makefile.am: installing './depcomp'
@end example
At this point the build system is complete.
In addition to the three scripts mentioned in its output, you can see
that @command{autoreconf} created four other files: @file{configure},
@file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
The latter three files are templates that will be adapted to the
system by @command{configure} under the names @file{config.h},
@file{Makefile}, and @file{src/Makefile}. Let's do this:
@example
~/amhello % @kbd{./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
@end example
@trindex distcheck
@cindex @code{distcheck} example
You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
being created at the end after @command{configure} has probed the
system. It is now possible to run all the targets we wish
(@pxref{Standard Targets}). For instance:
@example
~/amhello % @kbd{make}
@dots{}
~/amhello % @kbd{src/hello}
Hello World!
This is amhello 1.0.
~/amhello % @kbd{make distcheck}
@dots{}
=============================================
amhello-1.0 archives ready for distribution:
amhello-1.0.tar.gz
=============================================
@end example
Note that running @command{autoreconf} is only needed initially when
the GNU Build System does not exist. When you later change some
instructions in a @file{Makefile.am} or @file{configure.ac}, the
relevant part of the build system will be regenerated automatically
when you execute @command{make}.
@command{autoreconf} is a script that calls @command{autoconf},
@command{automake}, and a bunch of other commands in the right order.
If you are beginning with these tools, it is not important to figure
out in which order all of these tools should be invoked and why. However,
because Autoconf and Automake-NG have separate manuals, the important
point to understand is that @command{autoconf} is in charge of
creating @file{configure} from @file{configure.ac}, while
@command{automake} is in charge of creating @file{Makefile.in}s from
@file{Makefile.am}s and @file{configure.ac}. This should at least
direct you to the right manual when seeking answers.
@node amhello's configure.ac Setup Explained
@subsection @code{amhello}'s @file{configure.ac} Setup Explained
@cindex @file{configure.ac}, Hello World
Let us begin with the contents of @file{configure.ac}.
@example
AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
AM_INIT_AUTOMAKE([-Wall -Werror foreign])
AC_PROG_CC
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_FILES([
Makefile
src/Makefile
])
AC_OUTPUT
@end example
This file is read by both @command{autoconf} (to create
@file{configure}) and @command{automake} (to create the various
@file{Makefile.in}s). It contains a series of M4 macros that will be
expanded as shell code to finally form the @file{configure} script.
We will not elaborate on the syntax of this file, because the Autoconf
manual has a whole section about it (@pxref{Writing Autoconf Input, ,
Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
The macros prefixed with @code{AC_} are Autoconf macros, documented
in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
Index, autoconf, The Autoconf Manual}). The macros that start with
@code{AM_} are Automake macros, documented later in this manual
(@pxref{Macro Index}).
The first two lines of @file{configure.ac} initialize Autoconf and
Automake. @code{AC_INIT} takes in as parameters the name of the package,
its version number, and a contact address for bug-reports about the
package (this address is output at the end of @code{./configure
--help}, for instance). When adapting this setup to your own package,
by all means please do not blindly copy Automake's address: use the
mailing list of your package, or your own mail address.
@opindex -Wall
@opindex -Werror
@opindex foreign
The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
@command{automake} (@pxref{Options}). @option{-Wall} and
@option{-Werror} ask @command{automake} to turn on all warnings and
report them as errors. We are speaking of @strong{Automake} warnings
here, such as dubious instructions in @file{Makefile.am}. This has
absolutely nothing to do with how the compiler will be called, even
though it may support options with similar names. Using @option{-Wall
-Werror} is a safe setting when starting to work on a package: you do
not want to miss any issues. Later you may decide to relax things a
bit. The @option{foreign} option tells Automake that this package
will not follow the GNU Standards. GNU packages should always
distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
etc. We do not want @command{automake} to complain about these
missing files in our small example.
The @code{AC_PROG_CC} line causes the @command{configure} script to
search for a C compiler and define the variable @code{CC} with its
name. The @file{src/Makefile.in} file generated by Automake uses the
variable @code{CC} to build @file{hello}, so when @command{configure}
creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
@code{CC} with the value it has found. If Automake is asked to create
a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
not define it, it will suggest you add a call to @code{AC_PROG_CC}.
The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
@command{configure} script to create a @file{config.h} file gathering
@samp{#define}s defined by other macros in @file{configure.ac}. In our
case, the @code{AC_INIT} macro already defined a few of them. Here
is an excerpt of @file{config.h} after @command{configure} has run:
@smallexample
@dots{}
/* Define to the address where bug reports for this package should be sent. */
#define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
/* Define to the full name and version of this package. */
#define PACKAGE_STRING "amhello 1.0"
@dots{}
@end smallexample
As you probably noticed, @file{src/main.c} includes @file{config.h} so
it can use @code{PACKAGE_STRING}. In a real-world project,
@file{config.h} can grow really big, with one @samp{#define} per
feature probed on the system.
The @code{AC_CONFIG_FILES} macro declares the list of files that
@command{configure} should create from their @file{*.in} templates.
Automake also scans this list to find the @file{Makefile.am} files it must
process. (This is important to remember: when adding a new directory
to your project, you should add its @file{Makefile} to this list,
otherwise Automake will never process the new @file{Makefile.am} you
wrote in that directory.)
Finally, the @code{AC_OUTPUT} line is a closing command that actually
produces the part of the script in charge of creating the files
registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
@cindex @command{autoscan}
When starting a new project, we suggest you start with such a simple
@file{configure.ac}, and gradually add the other tests it requires.
The command @command{autoscan} can also suggest a few of the tests
your package may need (@pxref{autoscan Invocation, , Using
@command{autoscan} to Create @file{configure.ac}, autoconf, The
Autoconf Manual}).
@node amhello's Makefile.am Setup Explained
@subsection @code{amhello}'s @file{Makefile.am} Setup Explained
@cindex @file{Makefile.am}, Hello World
We now turn to @file{src/Makefile.am}. This file contains
Automake instructions to build and install @file{hello}.
@example
bin_PROGRAMS = hello
hello_SOURCES = main.c
@end example
A @file{Makefile.am} has the same syntax as an ordinary
@file{Makefile}. When @command{automake} processes a
@file{Makefile.am} it copies the entire file into the output
@file{Makefile.in} (that will be later turned into @file{Makefile} by
@command{configure}) but will react to certain variable definitions
by generating some build rules and other variables.
Often @file{Makefile.am}s contain only a list of variable definitions as
above, but they can also contain other variable and rule definitions that
@command{automake} will pass along without interpretation.
Variables that end with @code{_PROGRAMS} are special variables
that list programs that the resulting @file{Makefile} should build.
In Automake speak, this @code{_PROGRAMS} suffix is called a
@dfn{primary}; Automake recognizes other primaries such as
@code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
to different types of files.
The @samp{bin} part of the @code{bin_PROGRAMS} tells
@command{automake} that the resulting programs should be installed in
@var{bindir}. Recall that the GNU Build System uses a set of variables
to denote destination directories and allow users to customize these
locations (@pxref{Standard Directory Variables}). Any such directory
variable can be put in front of a primary (omitting the @code{dir}
suffix) to tell @command{automake} where to install the listed files.
Programs need to be built from source files, so for each program
@code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
@command{automake} will look for another variable named
@code{@var{prog}_SOURCES} listing its source files. There may be more
than one source file: they will all be compiled and linked together.
Automake also knows that source files need to be distributed when
creating a tarball (unlike built programs). So a side-effect of this
@code{hello_SOURCES} declaration is that @file{main.c} will be
part of the tarball created by @code{make dist}.
Finally here are some explanations regarding the top-level
@file{Makefile.am}.
@example
SUBDIRS = src
dist_doc_DATA = README
@end example
@code{SUBDIRS} is a special variable listing all directories that
@command{make} should recurse into before processing the current
directory. So this line is responsible for @command{make} building
@file{src/hello} even though we run it from the top-level. This line
also causes @code{make install} to install @file{src/hello} before
installing @file{README} (not that this order matters).
The line @code{dist_doc_DATA = README} causes @file{README} to be
distributed and installed in @var{docdir}. Files listed with the
@code{_DATA} primary are not automatically part of the tarball built
with @code{make dist}, so we add the @code{dist_} prefix so they get
distributed. However, for @file{README} it would not have been
necessary: @command{automake} automatically distributes any
@file{README} file it encounters (the list of other files
automatically distributed is presented by @code{automake --help}).
The only important effect of this second line is therefore to install
@file{README} during @code{make install}.
One thing not covered in this example is accessing the installation
directory values (@pxref{Standard Directory Variables}) from your
program code, that is, converting them into defined macros. For this,
@pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
@node Generalities
@chapter General ideas
The following sections cover a few basic ideas that will help you
understand how Automake works.
@menu
* General Operation:: General operation of Automake
* Strictness:: Standards conformance checking
* Uniform:: The Uniform Naming Scheme
* Length Limitations:: Staying below the command line length limit
* Canonicalization:: How derived variables are named
* User Variables:: Variables reserved for the user
* Auxiliary Programs:: Programs automake might require
@end menu
@node General Operation
@section General Operation
Automake works by reading a @file{Makefile.am} and generating a
@file{Makefile.in}. Certain variables and rules defined in the
@file{Makefile.am} instruct Automake to generate more specialized code;
for instance, a @code{bin_PROGRAMS} variable definition will cause rules
for compiling and linking programs to be generated.
@cindex Non-standard targets
@cindex @code{git-dist}, non-standard example
@trindex git-dist
The variable definitions and rules in the @file{Makefile.am} are
copied mostly verbatim into the generated file, with all variable
definitions preceding all rules. This allows you to add almost
arbitrary code into the generated @file{Makefile.in}. For instance,
the Automake distribution includes a non-standard rule for the
@code{git-dist} target, which the Automake maintainer uses to make
distributions from the source control system.
@cindex GNU make extensions
Note that most GNU make extensions are sadly not yet recognized by
Automake. Using such extensions in a @file{Makefile.am} will likely
lead to errors or confusing behavior. We hope to improve this
situation over time.
@cindex Append operator
@cmindex +=
For historical reasons, the GNU make append operator @samp{+=} (which
appends its right hand argument to the variable specified on the left)
is supported and handled in a special way: Automake will translate the
operator into an ordinary @samp{=} operator @emph{at Automake (not make)
runtime}. This behaviour might change future versions.
Automake tries to keep comments grouped with any adjoining rules or
variable definitions.
@cindex Limitations of automake parser
@cindex Automake parser, limitations of
@cindex indentation in Makefile.am
Generally, Automake is not particularly smart in the parsing of unusual
Makefile constructs, so you're advised to avoid fancy constructs or
``creative'' use of whitespaces.
For example, @key{TAB} characters cannot be used between a target name
and the following ``@code{:}'' character, and variable assignments
shouldn't be indented with @key{TAB} characters.
@cindex Make targets, overriding
@cindex Make rules, overriding
@cindex Overriding make rules
@cindex Overriding make targets
A rule defined in @file{Makefile.am} generally overrides any such
rule of a similar name that would be automatically generated by
@command{automake}. Although this is a supported feature, it is generally
best to avoid making use of it, as sometimes the generated rules are
very particular.
@cindex Variables, overriding
@cindex Overriding make variables
Similarly, a variable defined in @file{Makefile.am} or
@code{AC_SUBST}ed from @file{configure.ac} will override any
definition of the variable that @command{automake} would ordinarily
create. This feature is more often useful than the ability to
override a rule. Be warned that many of the variables generated by
@command{automake} are considered to be for internal use only, and their
names might change in future releases.
@cindex Recursive operation of Automake
@cindex Automake, recursive operation
@cindex Example of recursive operation
When examining the definition of some ``special'' variables, Automake
might recursively examine variables referenced in the definition in order
to perform its magic. For example, if Automake is looking at the content
of @code{foo_SOURCES} in this snippet
@c Keep in sync with interp.sh
@example
xs = a.c b.c
foo_SOURCES = c.c $(xs)
@end example
it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
contents of @code{foo_SOURCES}.
Unfortunately, for historical reasons, this interpolation processes
has the effect of currently making it impossible to use more advanced
GNU make features in the definitions of special variables like
@code{foo_SOURCES}; for example, Automake will generate a broken
@file{Makefile.in} on this input:
@c Keep in sync with interp3.test.
@example
bin_PROGRAMS = foo
xs = one two
foo_SOURCES = main.c $(foreach base, $(xs), $(base).c $(base).h)
@end example
@cindex @code{##} (special Automake comment)
@cindex Special Automake comment
@cindex Comment, special to Automake
Automake also allows a form of comment that is @emph{not} copied into
the output; all lines beginning with @samp{##} (leading spaces allowed)
are completely ignored by Automake.
It is customary to make the first line of @file{Makefile.am} read:
@cindex Makefile.am, first line
@cindex First line of Makefile.am
@example
## Process this file with automake to produce Makefile.in
@end example
@c FIXME discuss putting a copyright into Makefile.am here? I would but
@c I don't know quite what to say.
@c FIXME document customary ordering of Makefile.am here!
@node Strictness
@section Strictness
@cindex Non-GNU packages
While Automake is intended to be used by maintainers of GNU packages, it
does make some effort to accommodate those who wish to use it, but do
not want to use all the GNU conventions.
@cindex Strictness, defined
@cindex Strictness, @option{foreign}
@cindex @option{foreign} strictness
@cindex Strictness, @option{gnu}
@cindex @option{gnu} strictness
@cindex Strictness, @option{gnits}
@cindex @option{gnits} strictness
To this end, Automake supports three levels of @dfn{strictness}---the
strictness indicating how stringently Automake should check standards
conformance.
The valid strictness levels are:
@table @option
@item foreign
Automake will check for only those things that are absolutely
required for proper operations. For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in
this mode. This strictness will also turn off some warnings by default
(among them, portability warnings).
The name comes from the fact that Automake is intended to be
used for GNU programs; these relaxed rules are not the standard mode of
operation.
@item gnu
Automake will check---as much as possible---for compliance to the GNU
standards for packages. This is the default.
@item gnits
Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
standards}. These are based on the GNU standards, but are even more
detailed. Unless you are a Gnits standards contributor, it is
recommended that you avoid this option until such time as the Gnits
standard is actually published (which may never happen).
@end table
@xref{Gnits}, for more information on the precise implications of the
strictness level.
@node Uniform
@section The Uniform Naming Scheme
@cindex Uniform naming scheme
Automake variables generally follow a @dfn{uniform naming scheme} that
makes it easy to decide how programs (and other derived objects) are
built, and how they are installed. This scheme also supports
@command{configure} time determination of what should be built.
@cindex @code{_PROGRAMS} primary variable
@cindex @code{PROGRAMS} primary variable
@cindex Primary variable, @code{PROGRAMS}
@cindex Primary variable, defined
@vindex _PROGRAMS
At @command{make} time, certain variables are used to determine which
objects are to be built. The variable names are made of several pieces
that are concatenated together.
The piece that tells @command{automake} what is being built is commonly called
the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
list of programs that are to be compiled and linked.
@vindex PROGRAMS
@cindex @code{pkgdatadir}, defined
@cindex @code{pkgincludedir}, defined
@cindex @code{pkglibdir}, defined
@cindex @code{pkglibexecdir}, defined
@vindex pkgdatadir
@vindex pkgincludedir
@vindex pkglibdir
@vindex pkglibexecdir
@cindex @code{PACKAGE}, directory
A different set of names is used to decide where the built objects
should be installed. These names are prefixes to the primary, and they
indicate which standard directory should be used as the installation
directory. The standard directory names are given in the GNU standards
(@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
@code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
@code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
@cindex @code{EXTRA_}, prepending
For each primary, there is one additional variable named by prepending
@samp{EXTRA_} to the primary name. This variable is used to list
objects that may or may not be built, depending on what
@command{configure} decides. This variable is required because Automake
must statically know the entire list of objects that may be built in
order to generate a @file{Makefile.in} that will work in all cases.
@cindex @code{EXTRA_PROGRAMS}, defined
@cindex Example, @code{EXTRA_PROGRAMS}
@cindex @command{cpio} example
For instance, @command{cpio} decides at configure time which programs
should be built. Some of the programs are installed in @code{bindir},
and some are installed in @code{sbindir}:
@example
EXTRA_PROGRAMS = mt rmt
bin_PROGRAMS = cpio pax
sbin_PROGRAMS = $(MORE_PROGRAMS)
@end example
Defining a primary without a prefix as a variable, e.g.,
@samp{PROGRAMS}, is an error.
Note that the common @samp{dir} suffix is left off when constructing the
variable names; thus one writes @samp{bin_PROGRAMS} and not
@samp{bindir_PROGRAMS}.
Not every sort of object can be installed in every directory. Automake
will flag those attempts it finds in error (but see below how to override
the check if you really need to).
Automake will also diagnose obvious misspellings in directory names.
@cindex Extending list of installation directories
@cindex Installation directories, extending list
Sometimes the standard directories---even as augmented by
Automake---are not enough. In particular it is sometimes useful, for
clarity, to install objects in a subdirectory of some predefined
directory. To this end, Automake allows you to extend the list of
possible installation directories. A given prefix (e.g., @samp{zar})
is valid if a variable of the same name with @samp{dir} appended is
defined (e.g., @samp{zardir}).
For instance, the following snippet will install @file{file.xml} into
@samp{$(datadir)/xml}.
@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
xmldir = $(datadir)/xml
xml_DATA = file.xml
@end example
This feature can also be used to override the sanity checks Automake
performs to diagnose suspicious directory/primary couples (in the
unlikely case these checks are undesirable, and you really know what
you're doing). For example, Automake would error out on this input:
@c Should be tested in primary-prefix-invalid-couples.sh
@example
# Forbidden directory combinations, automake will error out on this.
pkglib_PROGRAMS = foo
doc_LIBRARIES = libquux.a
@end example
@noindent
but it will succeed with this:
@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
# 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
@end example
The @samp{exec} substring of the @samp{my_execbindir} variable lets
the files be installed at the right time (@pxref{The Two Parts of
Install}).
@cindex @samp{noinst_} primary prefix, definition
@vindex noinst_
The special prefix @samp{noinst_} indicates that the objects in question
should be built but not installed at all. This is usually used for
objects required to build the rest of your package, for instance static
libraries (@pxref{A Library}), or helper scripts.
@cindex @samp{check_} primary prefix, definition
@vindex check_
The special prefix @samp{check_} indicates that the objects in question
should not be built until the @samp{make check} command is run. Those
objects are not installed either.
The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
@samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
@samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
@samp{TEXINFOS}.
@vindex PROGRAMS
@vindex LIBRARIES
@vindex LTLIBRARIES
@vindex LISP
@vindex PYTHON
@vindex JAVA
@vindex SCRIPTS
@vindex DATA
@vindex HEADERS
@vindex MANS
@vindex TEXINFOS
Some primaries also allow additional prefixes that control other
aspects of @command{automake}'s behavior. The currently defined prefixes
are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
These prefixes are explained later (@pxref{Program and Library Variables})
(@pxref{Man Pages}).
@node Length Limitations
@section Staying below the command line length limit
@cindex command line length limit
@cindex ARG_MAX
Traditionally, most unix-like systems have a length limitation for the
command line arguments and environment contents when creating new
processes (see for example
@uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
overview on this issue),
which of course also applies to commands spawned by @command{make}.
POSIX requires this limit to be at least 4096 bytes, and most modern
systems have quite high limits (or are unlimited).
In order to create portable Makefiles that do not trip over these
limits, it is necessary to keep the length of file lists bounded.
Unfortunately, it is not possible to do so fully transparently within
Automake, so your help may be needed. Typically, you can split long
file lists manually and use different installation directory names for
each list. For example,
@example
data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
@end example
@noindent
may also be written as
@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
data_DATA = file1 @dots{} file@var{N}
data2dir = $(datadir)
data2_DATA = file@var{N+1} @dots{} file@var{2N}
@end example
@noindent
and will cause Automake to treat the two lists separately during
@code{make install}. See @ref{The Two Parts of Install} for choosing
directory names that will keep the ordering of the two parts of
installation Note that @code{make dist} may still only work on a host
with a higher length limit in this example.
Automake itself employs a couple of strategies to avoid long command
lines. For example, when @samp{$@{srcdir@}/} is prepended to file
names, as can happen with above @code{$(data_DATA)} lists, it limits
the amount of arguments passed to external commands.
Unfortunately, some system's @command{make} commands may prepend
@code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
may have to switch to use GNU Make, or refrain from using VPATH builds,
in order to stay below the length limit.
For libraries and programs built from many sources, convenience archives
may be used as intermediates in order to limit the object list length
(@pxref{Libtool Convenience Libraries}).
@node Canonicalization
@section How derived variables are named
@cindex canonicalizing Automake variables
Sometimes a Makefile variable name is derived from some text the
maintainer supplies. For instance, a program name listed in
@samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
variable. In cases like this, Automake canonicalizes the text, so that
program names and the like do not have to follow Makefile variable naming
rules. All characters in the name except for letters, numbers, the
strudel (@@), and the underscore are turned into underscores when making
variable references.
For example, if your program is named @file{sniff-glue}, the derived
variable name would be @samp{sniff_glue_SOURCES}, not
@samp{sniff-glue_SOURCES}. Similarly the sources for a library named
@file{libmumble++.a} should be listed in the
@samp{libmumble___a_SOURCES} variable.
The strudel is an addition, to make the use of Autoconf substitutions in
variable names less obfuscating.
@node User Variables
@section Variables reserved for the user
@cindex variables, reserved for the user
@cindex user variables
Some @file{Makefile} variables are reserved by the GNU Coding Standards
for the use of the ``user''---the person building the package. For
instance, @code{CFLAGS} is one such variable.
Sometimes package developers are tempted to set user variables such as
@code{CFLAGS} because it appears to make their job easier. However,
the package itself should never set a user variable, particularly not
to include switches that are required for proper compilation of the
package. Since these variables are documented as being for the
package builder, that person rightfully expects to be able to override
any of these variables at build time.
To get around this problem, Automake introduces an automake-specific
shadow variable for each user flag variable. (Shadow variables are
not introduced for variables like @code{CC}, where they would make no
sense.) The shadow variable is named by prepending @samp{AM_} to the
user variable's name. For instance, the shadow variable for
@code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
the author(s) of the @file{Makefile.am} and @file{configure.ac}
files---may adjust these shadow variables however necessary.
@xref{Flag Variables Ordering}, for more discussion about these
variables and how they interact with per-target variables.
@node Auxiliary Programs
@section Programs automake might require
@cindex Programs, auxiliary
@cindex Auxiliary programs
Automake sometimes requires helper programs so that the generated
@file{Makefile} can do its work properly. There are a fairly large
number of them, and we list them here.
Although all of these files are distributed and installed with
Automake, a couple of them are maintained separately. The Automake
copies are updated before each release, but we mention the original
source in case you need more recent versions.
@table @code
@item ar-lib
This is a wrapper primarily for the Microsoft lib archiver, to make
it more POSIX-like.
@item compile
This is a wrapper for compilers that do not accept options @option{-c}
and @option{-o} at the same time. It is only used when absolutely
required. Such compilers are rare, with the Microsoft C/C++ Compiler
as the most notable exception. This wrapper also makes the following
common options available for that compiler, while performing file name
translation where needed: @option{-I}, @option{-L}, @option{-l},
@option{-Wl,} and @option{-Xlinker}.
@item config.guess
@itemx config.sub
These two programs compute the canonical triplets for the given build,
host, or target architecture. These programs are updated regularly to
support new architectures and fix probes broken by changes in new
kernel versions. Each new release of Automake comes with up-to-date
copies of these programs. If your copy of Automake is getting old,
you are encouraged to fetch the latest versions of these files from
@url{http://savannah.gnu.org/git/?group=config} before making a
release.
@item depcomp
This program understands how to run a compiler so that it will
generate not only the desired output but also dependency information
that is then used by the automatic dependency tracking feature
(@pxref{Dependencies}).
@item install-sh
This is a replacement for the @command{install} program that works on
platforms where @command{install} is unavailable or unusable.
@item mdate-sh
This script is used to generate a @file{version.texi} file. It examines
a file and prints some date information about it.
@item missing
This wraps a number of programs that are typically only required by
maintainers. If the program in question doesn't exist, or seems to old,
@command{missing} will print an informative warning before failing out,
to provide the user with more context and information.
@item py-compile
This is used to byte-compile Python scripts.
@item test-driver
This implements the default test driver offered by the parallel
testsuite harness.
@item texinfo.tex
Not a program, this file is required for @samp{make dvi}, @samp{make
ps} and @samp{make pdf} to work when Texinfo sources are in the
package. The latest version can be downloaded from
@url{http://www.gnu.org/software/texinfo/}.
@item ylwrap
This program wraps @command{lex} and @command{yacc} to rename their
output files. It also ensures that, for instance, multiple
@command{yacc} instances can be invoked in a single directory in
parallel.
@end table
@node Examples
@chapter Some example packages
This section contains two small examples.
The first example (@pxref{Complete}) assumes you have an existing
project already using Autoconf, with handcrafted @file{Makefile}s, and
that you want to convert it to using Automake. If you are discovering
both tools, it is probably better that you look at the Hello World
example presented earlier (@pxref{Hello World}).
The second example (@pxref{true}) shows how two programs can be built
from the same file, using different compilation parameters. It
contains some technical digressions that are probably best skipped on
first read.
@menu
* Complete:: A simple example, start to finish
* true:: Building true and false
@end menu
@node Complete
@section A simple example, start to finish
@cindex Complete example
Let's suppose you just finished writing @code{zardoz}, a program to make
your head float from vortex to vortex. You've been using Autoconf to
provide a portability framework, but your @file{Makefile.in}s have been
ad-hoc. You want to make them bulletproof, so you turn to Automake.
@cindex @code{AM_INIT_AUTOMAKE}, example use
The first step is to update your @file{configure.ac} to include the
commands that @command{automake} needs. The way to do this is to add an
@code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
@example
AC_INIT([zardoz], [1.0])
AM_INIT_AUTOMAKE
@dots{}
@end example
Since your program doesn't have any complicating factors (e.g., it
doesn't use @code{gettext}, it doesn't want to build a shared library),
you're done with this part. That was easy!
@cindex @command{aclocal} program, introduction
@cindex @file{aclocal.m4}, preexisting
@cindex @file{acinclude.m4}, defined
Now you must regenerate @file{configure}. But to do that, you'll need
to tell @command{autoconf} how to find the new macro you've used. The
easiest way to do this is to use the @command{aclocal} program to
generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
already have an @file{aclocal.m4}, because you had to write some hairy
macros for your program. The @command{aclocal} program lets you put
your own macros into @file{acinclude.m4}, so simply rename and then
run:
@example
mv aclocal.m4 acinclude.m4
aclocal
autoconf
@end example
@cindex @command{zardoz} example
Now it is time to write your @file{Makefile.am} for @code{zardoz}.
Since @code{zardoz} is a user program, you want to install it where the
rest of the user programs go: @code{bindir}. Additionally,
@code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
script uses @code{AC_REPLACE_FUNCS}, so you need to link against
@samp{$(LIBOBJS)}. So here's what you'd write:
@example
bin_PROGRAMS = zardoz
zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
zardoz_LDADD = $(LIBOBJS)
info_TEXINFOS = zardoz.texi
@end example
Now you can run @samp{automake --add-missing} to generate your
@file{Makefile.in} and grab any auxiliary files you might need, and
you're done!
@node true
@section Building true and false
@cindex Example, @command{false} and @command{true}
@cindex @command{false} Example
@cindex @command{true} Example
Here is another, trickier example. It shows how to generate two
programs (@code{true} and @code{false}) from the same source file
(@file{true.c}). The difficult part is that each compilation of
@file{true.c} requires different @code{cpp} flags.
@example
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
@end example
Note that there is no @code{true_SOURCES} definition. Automake will
implicitly assume that there is a source file named @file{true.c}
(@pxref{Default _SOURCES}), and
define rules to compile @file{true.o} and link @file{true}. The
@samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
will override the Automake generated rule to build @file{true.o}.
@code{false_SOURCES} is defined to be empty---that way no implicit value
is substituted. Because we have not listed the source of
@file{false}, we have to tell Automake how to link the program. This is
the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
variable, holding the dependencies of the @file{false} target will be
automatically generated by Automake from the content of
@code{false_LDADD}.
The above rules won't work if your compiler doesn't accept both
@option{-c} and @option{-o}. The simplest fix for this is to introduce a
bogus dependency (to avoid problems with a parallel @command{make}):
@example
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
@end example
As it turns out, there is also a much easier way to do this same task.
Some of the above technique is useful enough that we've kept the
example in the manual. However if you were to build @code{true} and
@code{false} in real life, you would probably use per-program
compilation flags, like so:
@c Keep in sync with specflg7.sh and specflg8.sh
@example
bin_PROGRAMS = false true
false_SOURCES = true.c
false_CPPFLAGS = -DEXIT_CODE=1
true_SOURCES = true.c
true_CPPFLAGS = -DEXIT_CODE=0
@end example
In this case Automake will cause @file{true.c} to be compiled twice,
with different flags. In this instance, the names of the object files
would be chosen by automake; they would be @file{false-true.o} and
@file{true-true.o}. (The name of the object files rarely matters.)
@node automake Invocation
@chapter Creating a @file{Makefile.in}
@c This node used to be named "Invoking automake". This @anchor
@c allows old links to still work.
@anchor{Invoking automake}
@cindex Multiple @file{configure.ac} files
@cindex Invoking @command{automake}
@cindex @command{automake}, invoking
@cindex Invocation of @command{automake}
@cindex @command{automake}, invocation
To create all the @file{Makefile.in}s for a package, run the
@command{automake} program in the top level directory, with no
arguments. @command{automake} will automatically find each
appropriate @file{Makefile.am} (by scanning @file{configure.ac};
@pxref{configure}) and generate the corresponding @file{Makefile.in}.
Note that @command{automake} has a rather simplistic view of what
constitutes a package; it assumes that a package has only one
@file{configure.ac}, at the top. If your package has multiple
@file{configure.ac}s, then you must run @command{automake} in each
directory holding a @file{configure.ac}. (Alternatively, you may rely
on Autoconf's @command{autoreconf}, which is able to recurse your
package tree and run @command{automake} where appropriate.)
You can optionally give @command{automake} an argument; @file{.am} is
appended to the argument and the result is used as the name of the
input file. This feature is generally only used to automatically
rebuild an out-of-date @file{Makefile.in}. Note that
@command{automake} must always be run from the topmost directory of a
project, even if being used to regenerate the @file{Makefile.in} in
some subdirectory. This is necessary because @command{automake} must
scan @file{configure.ac}, and because @command{automake} uses the
knowledge that a @file{Makefile.in} is in a subdirectory to change its
behavior in some cases.
@vindex AUTOCONF
Automake will run @command{autoconf} to scan @file{configure.ac} and
its dependencies (i.e., @file{aclocal.m4} and any included file),
therefore @command{autoconf} must be in your @env{PATH}. If there is
an @env{AUTOCONF} variable in your environment it will be used
instead of @command{autoconf}, this allows you to select a particular
version of Autoconf. By the way, don't misunderstand this paragraph:
@command{automake} runs @command{autoconf} to @strong{scan} your
@file{configure.ac}, this won't build @file{configure} and you still
have to run @command{autoconf} yourself for this purpose.
@cindex @command{automake} options
@cindex Options, @command{automake}
@cindex Strictness, command line
@command{automake} accepts the following options:
@cindex Extra files distributed with Automake
@cindex Files distributed with Automake
@cindex @file{config.guess}
@table @code
@item -a
@itemx --add-missing
@opindex -a
@opindex --add-missing
Automake requires certain common files to exist in certain situations;
for instance, @file{config.guess} is required if @file{configure.ac} invokes
@code{AC_CANONICAL_HOST}. Automake is distributed with several of these
files (@pxref{Auxiliary Programs}); this option will cause the missing
ones to be automatically added to the package, whenever possible. In
general if Automake tells you a file is missing, try using this option.
By default Automake tries to make a symbolic link pointing to its own
copy of the missing file; this can be changed with @option{--copy}.
Many of the potentially-missing files are common scripts whose
location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
file is considered missing, and where the missing file is added
(@pxref{Optional}).
In some strictness modes, additional files are installed, see @ref{Gnits}
for more information.
@item --libdir=@var{dir}
@opindex --libdir
Look for Automake data files in directory @var{dir} instead of in the
installation directory. This is typically used for debugging.
@item --print-libdir
@opindex --print-libdir
Print the path of the installation directory containing Automake-provided
scripts and data files (like e.g., @file{texinfo.texi} and
@file{install-sh}).
@item -c
@opindex -c
@itemx --copy
@opindex --copy
When used with @option{--add-missing}, causes installed files to be
copied. The default is to make a symbolic link.
@item -f
@opindex -f
@itemx --force-missing
@opindex --force-missing
When used with @option{--add-missing}, causes standard files to be reinstalled
even if they already exist in the source tree. This involves removing
the file from the source tree before creating the new symlink (or, with
@option{--copy}, copying the new file).
@item --foreign
@opindex --foreign
Set the global strictness to @option{foreign}. For more information, see
@ref{Strictness}.
@item --gnits
@opindex --gnits
Set the global strictness to @option{gnits}. For more information, see
@ref{Gnits}.
@item --gnu
@opindex --gnu
Set the global strictness to @option{gnu}. For more information, see
@ref{Gnits}. This is the default strictness.
@item --help
@opindex --help
Print a summary of the command line options and exit.
@item -i
@itemx --ignore-deps
@opindex -i
This disables the dependency tracking feature in generated
@file{Makefile}s; see @ref{Dependencies}.
@item --include-deps
@opindex --include-deps
This enables the dependency tracking feature. This feature is enabled
by default. This option is provided for historical reasons only and
probably should not be used.
@item --no-force
@opindex --no-force
Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
@file{configure.ac}. This option causes it to only update those
@file{Makefile.in}s that are out of date with respect to one of their
dependents.
@item -o @var{dir}
@itemx --output-dir=@var{dir}
@opindex -o
@opindex --output-dir
Put the generated @file{Makefile.in} in the directory @var{dir}.
Ordinarily each @file{Makefile.in} is created in the directory of the
corresponding @file{Makefile.am}. This option is deprecated and will be
removed in a future release.
@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Cause Automake to print information about which files are being read or
created.
@item --version
@opindex --version
Print the version number of Automake and exit.
@item -W CATEGORY
@itemx --warnings=@var{category}
@opindex -W
@opindex --warnings
Output warnings falling in @var{category}. @var{category} can be
one of:
@table @code
@item gnu
warnings related to the GNU Coding Standards
(@pxref{Top, , , standards, The GNU Coding Standards}).
@item obsolete
obsolete features or constructions
@item override
user redefinitions of Automake rules or variables
@item portability
portability issues; e.g., use of file names like @file{aux} that are
reserved on some systems (like Windows), or use of Automake features
that require support from the target C compiler, support that is
known not be present on all the mainstream C compilers.
@item extra-portability
extra portability issues related to obscure tools. One example of such
a tool is the Microsoft @command{lib} archiver.
@item syntax
weird syntax, unused variables, typos
@item unsupported
unsupported or incomplete features
@item all
all the warnings
@item none
turn off all the warnings
@item error
treat warnings as errors
@end table
A category can be turned off by prefixing its name with @samp{no-}. For
instance, @option{-Wno-syntax} will hide the warnings about unused
variables.
The categories output by default are @samp{syntax} and
@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
are enabled in @option{--gnu} and @option{--gnits} strictness.
@c Checked by extra-portability.sh
Turning off @samp{portability} will also turn off @samp{extra-portability},
and similarly turning on @samp{extra-portability} will also turn on
@samp{portability}. However, turning on @samp{portability} or turning
off @samp{extra-portability} will not affect the other category.
@vindex WARNINGS
The environment variable @env{WARNINGS} can contain a comma separated
list of categories to enable. It will be taken into account before the
command-line switches, this way @option{-Wnone} will also ignore any
warning category enabled by @env{WARNINGS}. This variable is also used
by other tools like @command{autoconf}; unknown categories are ignored
for this reason.
@end table
@node configure
@chapter Scanning @file{configure.ac}, using @command{aclocal}
@cindex @file{configure.ac}, scanning
@cindex Scanning @file{configure.ac}
@cindex Using @command{aclocal}
@cindex @command{aclocal}, using
Automake scans the package's @file{configure.ac} to determine certain
information about the package. Some @command{autoconf} macros are required
and some variables must be defined in @file{configure.ac}. Automake
will also use information from @file{configure.ac} to further tailor its
output.
Automake also supplies some Autoconf macros to make the maintenance
easier. These macros can automatically be put into your
@file{aclocal.m4} using the @command{aclocal} program.
@menu
* Requirements:: Configuration requirements
* Optional:: Other things Automake recognizes
* aclocal Invocation:: Auto-generating aclocal.m4
* Macros:: Autoconf macros supplied with Automake
@end menu
@node Requirements
@section Configuration requirements
@cindex Automake requirements
@cindex Requirements of Automake
@acindex AM_INIT_AUTOMAKE
The one real requirement of Automake is that your @file{configure.ac}
call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
required for proper Automake operation (@pxref{Macros}).
Here are the other macros that Automake requires but which are not run
by @code{AM_INIT_AUTOMAKE}:
@table @code
@item AC_CONFIG_FILES
@itemx AC_OUTPUT
@acindex AC_CONFIG_FILES
@acindex AC_OUTPUT
These two macros are usually invoked as follows near the end of
@file{configure.ac}.
@example
@dots{}
AC_CONFIG_FILES([
Makefile
doc/Makefile
src/Makefile
src/lib/Makefile
@dots{}
])
AC_OUTPUT
@end example
Automake uses these to determine which files to create (@pxref{Output, ,
Creating Output Files, autoconf, The Autoconf Manual}). A listed file
is considered to be an Automake generated @file{Makefile} if there
exists a file with the same name and the @file{.am} extension appended.
Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
When using @code{AC_CONFIG_FILES} with multiple input files, as in
@example
AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
@end example
@noindent
@command{automake} will generate the first @file{.in} input file for
which a @file{.am} file exists. If no such file exists the output
file is not considered to be generated by Automake.
Files created by @code{AC_CONFIG_FILES}, be they Automake
@file{Makefile}s or not, are all removed by @samp{make distclean}.
Their inputs are automatically distributed, unless they
are the output of prior @code{AC_CONFIG_FILES} commands.
Finally, rebuild rules are generated in the Automake @file{Makefile}
existing in the subdirectory of the output file, if there is one, or
in the top-level @file{Makefile} otherwise.
The above machinery (cleaning, distributing, and rebuilding) works
fine if the @code{AC_CONFIG_FILES} specifications contain only
literals. If part of the specification uses shell variables,
@command{automake} will not be able to fulfill this setup, and you will
have to complete the missing bits by hand. For instance, on
@c Keep in sync with output11.sh
@example
file=input
@dots{}
AC_CONFIG_FILES([output:$file],, [file=$file])
@end example
@noindent
@command{automake} will output rules to clean @file{output}, and
rebuild it. However the rebuild rule will not depend on @file{input},
and this file will not be distributed either. (You must add
@samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
source file.)
Similarly
@c Keep in sync with output11.sh
@example
file=output
file2=out:in
@dots{}
AC_CONFIG_FILES([$file:input],, [file=$file])
AC_CONFIG_FILES([$file2],, [file2=$file2])
@end example
@noindent
will only cause @file{input} to be distributed. No file will be
cleaned automatically (add @samp{DISTCLEANFILES = output out}
yourself), and no rebuild rule will be output.
Obviously @command{automake} cannot guess what value @samp{$file} is
going to hold later when @file{configure} is run, and it cannot use
the shell variable @samp{$file} in a @file{Makefile}. However, if you
make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
that is compatible with @command{make}'s syntax) and furthermore use
@code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
@file{Makefile}, then @command{automake} will be able to use
@samp{$@{file@}} to generate all of these rules. For instance, here is
how the Automake package itself generates versioned scripts for its
test suite:
@example
AC_SUBST([APIVERSION], @dots{})
@dots{}
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@}])
@end example
@noindent
Here cleaning, distributing, and rebuilding are done automatically,
because @samp{$@{APIVERSION@}} is known at @command{make}-time.
Note that you should not use shell variables to declare
@file{Makefile} files for which @command{automake} must create
@file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
@command{automake} needs to know the file name when it runs in order
to check whether @file{Makefile.am} exists. (In the very hairy case
that your setup requires such use of variables, you will have to tell
Automake which @file{Makefile.in}s to generate on the command-line.)
It is possible to let @command{automake} emit conditional rules for
@code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
(@pxref{Optional}).
To summarize:
@itemize @bullet
@item
Use literals for @file{Makefile}s, and for other files whenever possible.
@item
Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
for files that @command{automake} should ignore.
@item
Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
that @command{automake} should not ignore.
@end itemize
@end table
@node Optional
@section Other things Automake recognizes
@cindex Macros Automake recognizes
@cindex Recognized macros by Automake
Every time Automake is run it calls Autoconf to trace
@file{configure.ac}. This way it can recognize the use of certain
macros and tailor the generated @file{Makefile.in} appropriately.
Currently recognized macros and their effects are:
@ftable @code
@item AC_CANONICAL_BUILD
@itemx AC_CANONICAL_HOST
@itemx AC_CANONICAL_TARGET
@vindex build
@vindex host
@vindex target
Automake will ensure that @file{config.guess} and @file{config.sub}
exist. Also, the @file{Makefile} variables @code{build}, @code{host}
and @code{target} are introduced. See @ref{Canonicalizing, ,
Getting the Canonical System Type, autoconf, The Autoconf Manual}.
@item AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as
@file{install-sh}, in the directory named in this macro invocation.
@c This list is accurate relative to version 1.11
(The full list of scripts is:
@file{ar-lib},
@file{config.guess},
@file{config.sub},
@file{depcomp},
@file{compile},
@file{install-sh},
@file{ltmain.sh},
@file{mdate-sh},
@file{missing},
@file{py-compile},
@file{test-driver},
@file{texinfo.tex},
@file{ylwrap}.)
Not all scripts are always searched for; some scripts
will only be sought if the generated @file{Makefile.in} requires them.
If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
their standard locations. For @file{mdate-sh},
@file{texinfo.tex}, and @file{ylwrap}, the standard location is the
source directory corresponding to the current @file{Makefile.am}. For
the rest, the standard location is the first one of @file{.}, @file{..},
or @file{../..} (relative to the top source directory) that provides any
one of the helper scripts. @xref{Input, , Finding `configure' Input,
autoconf, The Autoconf Manual}.
Required files from @code{AC_CONFIG_AUX_DIR} are automatically
distributed, even if there is no @file{Makefile.am} in this directory.
@item AC_CONFIG_LIBOBJ_DIR
Automake will require the sources file declared with
@code{AC_LIBSOURCE} (see below) in the directory specified by this
macro.
@item AC_CONFIG_HEADERS
Automake will generate rules to rebuild these headers. Older versions
of Automake required the use of @code{AM_CONFIG_HEADER}; this is no
longer the case, and that macro has indeed been removed.
As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
specification using shell variables will be ignored as far as
cleaning, distributing, and rebuilding is concerned.
@item AC_CONFIG_LINKS
Automake will generate rules to remove @file{configure} generated
links on @samp{make distclean} and to distribute named source files as
part of @samp{make dist}.
As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
specification using shell variables will be ignored as far as cleaning
and distributing is concerned. (There are no rebuild rules for links.)
@item AC_LIBOBJ
@itemx AC_LIBSOURCE
@itemx AC_LIBSOURCES
@vindex LIBOBJS
Automake will automatically distribute any file listed in
@code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
@file{file.c} will be distributed automatically by Automake. This
encompasses many macros like @code{AC_FUNC_ALLOCA},
@code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
By the way, direct assignments to @code{LIBOBJS} are no longer
supported. You should always use @code{AC_LIBOBJ} for this purpose.
@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
autoconf, The Autoconf Manual}.
@item AC_PROG_RANLIB
This is required if any libraries are built in the package.
@xref{Particular Programs, , Particular Program Checks, autoconf, The
Autoconf Manual}.
@item AC_PROG_CXX
This is required if any C++ source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@item AC_PROG_OBJC
This is required if any Objective C source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@item AC_PROG_OBJCXX
This is required if any Objective C++ source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@item AC_PROG_F77
This is required if any Fortran 77 source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@item AC_F77_LIBRARY_LDFLAGS
This is required for programs and shared libraries that are a mixture of
languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
@item AC_FC_SRCEXT
Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
of files with the respective source extension (@pxref{Fortran Compiler, ,
Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
@item AC_PROG_FC
This is required if any Fortran 90/95 source is included. This macro is
distributed with Autoconf version 2.58 and later. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@item AC_PROG_LIBTOOL
Automake will turn on processing for @command{libtool} (@pxref{Top, ,
Introduction, libtool, The Libtool Manual}).
@item AC_PROG_YACC
@vindex YACC
If a Yacc source file is seen, then you must either use this macro or
define the variable @code{YACC} in @file{configure.ac}. The former is
preferred (@pxref{Particular Programs, , Particular Program Checks,
autoconf, The Autoconf Manual}).
@item AC_PROG_LEX
If a Lex source file is seen, then this macro must be used.
@xref{Particular Programs, , Particular Program Checks, autoconf, The
Autoconf Manual}.
@item AC_REQUIRE_AUX_FILE
For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
@command{automake} will ensure that @file{@var{file}} exists in the
aux directory, and will complain otherwise. It
will also automatically distribute the file. This macro should be
used by third-party Autoconf macros that require some supporting
files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
above. @xref{Input, , Finding @command{configure} Input, autoconf,
The Autoconf Manual}.
@item AC_SUBST
The first argument is automatically defined as a variable in each
generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
used for this variable. @xref{Setting Output Variables, , Setting
Output Variables, autoconf, The Autoconf Manual}.
For every substituted variable @var{var}, @command{automake} will add
a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
Many Autoconf macros invoke @code{AC_SUBST} to set output variables
this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
@code{X_LIBS}. Thus, you can access these variables as
@code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
if @code{AC_PATH_XTRA} is called.
@item AM_CONDITIONAL
This introduces an Automake conditional (@pxref{Conditionals}).
@item AM_COND_IF
This macro allows @code{automake} to detect subsequent access within
@file{configure.ac} to a conditional previously introduced with
@code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
(@pxref{Usage of Conditionals}).
@item AM_GNU_GETTEXT
This macro is required for packages that use GNU gettext
(@pxref{gettext}). It is distributed with gettext. If Automake sees
this macro it ensures that the package meets some of gettext's
requirements.
@item AM_GNU_GETTEXT_INTL_SUBDIR
This macro specifies that the @file{intl/} subdirectory is to be built,
even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
of @samp{external}.
@item AM_SUBST_NOTMAKE(@var{var})
Prevent Automake from defining a variable @var{var}, even if it is
substituted by @command{config.status}. Normally, Automake defines a
@command{make} variable for each @command{configure} substitution,
i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
definition from Automake. If @code{AC_SUBST} has not been called
for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
Preventing variable definitions may be useful for substitution of
multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
unintended results.
@item m4_include
Files included by @file{configure.ac} using this macro will be
detected by Automake and automatically distributed. They will also
appear as dependencies in @file{Makefile} rules.
@code{m4_include} is seldom used by @file{configure.ac} authors, but
can appear in @file{aclocal.m4} when @command{aclocal} detects that
some required macros come from files local to your package (as opposed to
macros installed in a system-wide directory, @pxref{aclocal Invocation}).
@end ftable
@node aclocal Invocation
@section Auto-generating aclocal.m4
@c This node used to be named "Invoking automake". This @anchor
@c allows old links to still work.
@anchor{Invoking aclocal}
@cindex Invocation of @command{aclocal}
@cindex @command{aclocal}, Invocation
@cindex Invoking @command{aclocal}
@cindex @command{aclocal}, Invoking
Automake includes a number of Autoconf macros that can be used in
your package (@pxref{Macros}); some of them are actually required by
Automake in certain situations. These macros must be defined in your
@file{aclocal.m4}; otherwise they will not be seen by
@command{autoconf}.
The @command{aclocal} program will automatically generate
@file{aclocal.m4} files based on the contents of @file{configure.ac}.
This provides a convenient way to get Automake-provided macros,
without having to search around. The @command{aclocal} mechanism
allows other packages to supply their own macros (@pxref{Extending
aclocal}). You can also use it to maintain your own set of custom
macros (@pxref{Local Macros}).
At startup, @command{aclocal} scans all the @file{.m4} files it can
find, looking for macro definitions (@pxref{Macro Search Path}). Then
it scans @file{configure.ac}. Any mention of one of the macros found
in the first step causes that macro, and any macros it in turn
requires, to be put into @file{aclocal.m4}.
@emph{Putting} the file that contains the macro definition into
@file{aclocal.m4} is usually done by copying the entire text of this
file, including unused macro definitions as well as both @samp{#} and
@samp{dnl} comments. If you want to make a comment that will be
completely ignored by @command{aclocal}, use @samp{##} as the comment
leader.
When a file selected by @command{aclocal} is located in a subdirectory
specified as a relative search path with @command{aclocal}'s @option{-I}
argument, @command{aclocal} assumes the file belongs to the package
and uses @code{m4_include} instead of copying it into
@file{aclocal.m4}. This makes the package smaller, eases dependency
tracking, and cause the file to be distributed automatically.
(@xref{Local Macros}, for an example.) Any macro that is found in a
system-wide directory, or via an absolute search path will be copied.
So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
some relative directory should be considered outside the package.
The contents of @file{acinclude.m4}, if this file exists, are also
automatically included in @file{aclocal.m4}. We recommend against
using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
@vindex AUTOM4TE
@cindex autom4te
While computing @file{aclocal.m4}, @command{aclocal} runs
@command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
autoconf, The Autoconf Manual}) in order to trace the macros that are
really used, and omit from @file{aclocal.m4} all macros that are
mentioned but otherwise unexpanded (this can happen when a macro is
called conditionally). @command{autom4te} is expected to be in the
@env{PATH}, just as @command{autoconf}. Its location can be
overridden using the @env{AUTOM4TE} environment variable.
@menu
* aclocal Options:: Options supported by aclocal
* Macro Search Path:: How aclocal finds .m4 files
* Extending aclocal:: Writing your own aclocal macros
* Local Macros:: Organizing local macros
* Serials:: Serial lines in Autoconf macros
* Future of aclocal:: aclocal's scheduled death
@end menu
@node aclocal Options
@subsection aclocal Options
@cindex @command{aclocal}, Options
@cindex Options, @command{aclocal}
@command{aclocal} accepts the following options:
@table @code
@item --automake-acdir=@var{dir}
@opindex --automake-acdir
Look for the automake-provided macro files in @var{dir} instead of
in the installation directory. This is typically used for debugging.
@item --system-acdir=@var{dir}
@opindex --system-acdir
Look for the system-wide third-party macro files (and the special
@file{dirlist} file) in @var{dir} instead of in the installation
directory. This is typically used for debugging.
@item --diff[=@var{command}]
@opindex --diff
Run @var{command} on M4 file that would be installed or overwritten
by @option{--install}. The default @var{command} is @samp{diff -u}.
This option implies @option{--install} and @option{--dry-run}.
@item --dry-run
@opindex --dry-run
Do not actually overwrite (or create) @file{aclocal.m4} and M4
files installed by @option{--install}.
@item --help
@opindex --help
Print a summary of the command line options and exit.
@item -I @var{dir}
@opindex -I
Add the directory @var{dir} to the list of directories searched for
@file{.m4} files.
@item --install
@opindex --install
Install system-wide third-party macros into the first directory
specified with @samp{-I @var{dir}} instead of copying them in the
output file.
@c Keep in sync with aclocal-install-absdir.sh
Note that this will happen also if @var{dir} is an absolute path.
@cindex serial number and @option{--install}
When this option is used, and only when this option is used,
@command{aclocal} will also honor @samp{#serial @var{number}} lines
that appear in macros: an M4 file is ignored if there exists another
M4 file with the same basename and a greater serial number in the
search path (@pxref{Serials}).
@item --force
@opindex --force
Always overwrite the output file. The default is to overwrite the output
file only when really needed, i.e., when its contents changes or if one
of its dependencies is younger.
This option forces the update of @file{aclocal.m4} (or the file
specified with @file{--output} below) and only this file, it has
absolutely no influence on files that may need to be installed by
@option{--install}.
@item --output=@var{file}
@opindex --output
Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
@item --print-ac-dir
@opindex --print-ac-dir
Prints the name of the directory that @command{aclocal} will search to
find third-party @file{.m4} files. When this option is given, normal
processing is suppressed. This option was used @emph{in the past} by
third-party packages to determine where to install @file{.m4} macro
files, but @emph{this usage is today discouraged}, since it causes
@samp{$(prefix)} not to be thoroughly honoured (which violates the
GNU Coding Standards), and a similar semantics can be better obtained
with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
@item --verbose
@opindex --verbose
Print the names of the files it examines.
@item --version
@opindex --version
Print the version number of Automake and exit.
@item -W CATEGORY
@item --warnings=@var{category}
@opindex -W
@opindex --warnings
Output warnings falling in @var{category}. @var{category} can be
one of:
@table @code
@item syntax
dubious syntactic constructs, underquoted macros, unused macros, etc.
@item unsupported
unknown macros
@item all
all the warnings, this is the default
@item none
turn off all the warnings
@item error
treat warnings as errors
@end table
All warnings are output by default.
@vindex WARNINGS
The environment variable @env{WARNINGS} is honored in the same
way as it is for @command{automake} (@pxref{automake Invocation}).
@end table
@node Macro Search Path
@subsection Macro Search Path
@cindex Macro search path
@cindex @command{aclocal} search path
By default, @command{aclocal} searches for @file{.m4} files in the following
directories, in this order:
@table @code
@item @var{acdir-APIVERSION}
This is where the @file{.m4} macros distributed with Automake itself
are stored. @var{APIVERSION} depends on the Automake release used;
for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
@item @var{acdir}
This directory is intended for third party @file{.m4} files, and is
configured when @command{automake} itself is built. This is
@file{@@datadir@@/aclocal/}, which typically
expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
value of @var{acdir}, use the @option{--print-ac-dir} option
(@pxref{aclocal Options}).
@end table
As an example, suppose that @command{automake-1.11.2} was configured with
@option{--prefix=@-/usr/local}. Then, the search path would be:
@enumerate
@item @file{/usr/local/share/aclocal-1.11.2/}
@item @file{/usr/local/share/aclocal/}
@end enumerate
The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
be changed respectively through aclocal options @option{--system-acdir}
and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
that these options are only intended for use by the internal Automake
test suite, or for debugging under highly unusual situations; they are
not ordinarily needed by end-users.
As explained in (@pxref{aclocal Options}), there are several options that
can be used to change or extend this search path.
@subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
Any extra directories specified using @option{-I} options
(@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
@samp{aclocal -I /foo -I /bar} results in the following search path:
@enumerate
@item @file{/foo}
@item @file{/bar}
@item @var{acdir}-@var{APIVERSION}
@item @var{acdir}
@end enumerate
@subsubheading Modifying the Macro Search Path: @file{dirlist}
@cindex @file{dirlist}
There is a third mechanism for customizing the search path. If a
@file{dirlist} file exists in @var{acdir}, then that file is assumed to
contain a list of directory patterns, one per line. @command{aclocal}
expands these patterns to directory names, and adds them to the search
list @emph{after} all other directories. @file{dirlist} entries may
use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
For example, suppose
@file{@var{acdir}/dirlist} contains the following:
@example
/test1
/test2
/test3*
@end example
@noindent
and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
Then, the search path would be
@c @code looks better than @file here
@enumerate
@item @code{/foo}
@item @code{/bar}
@item @var{acdir}-@var{APIVERSION}
@item @var{acdir}
@item @code{/test1}
@item @code{/test2}
@end enumerate
@noindent
and all directories with path names starting with @code{/test3}.
If the @option{--system-acdir=@var{dir}} option is used, then
@command{aclocal} will search for the @file{dirlist} file in
@var{dir}; but remember the warnings above against the use of
@option{--system-acdir}.
@file{dirlist} is useful in the following situation: suppose that
@command{automake} version @code{1.11.2} is installed with
@samp{--prefix=/usr} by the system vendor. Thus, the default search
directories are
@c @code looks better than @file here
@enumerate
@item @code{/usr/share/aclocal-1.11/}
@item @code{/usr/share/aclocal/}
@end enumerate
However, suppose further that many packages have been manually
installed on the system, with $prefix=/usr/local, as is typical. In
that case, many of these ``extra'' @file{.m4} files are in
@file{/usr/local/share/aclocal}. The only way to force
@file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
always call @samp{aclocal -I /usr/local/share/aclocal}. This is
inconvenient. With @file{dirlist}, one may create a file
@file{/usr/share/aclocal/dirlist} containing only the single line
@example
/usr/local/share/aclocal
@end example
Now, the ``default'' search path on the affected system is
@c @code looks better than @file here
@enumerate
@item @code{/usr/share/aclocal-1.11/}
@item @code{/usr/share/aclocal/}
@item @code{/usr/local/share/aclocal/}
@end enumerate
without the need for @option{-I} options; @option{-I} options can be reserved
for project-specific needs (@file{my-source-dir/m4/}), rather than
using it to work around local system-dependent tool installation
directories.
Similarly, @file{dirlist} can be handy if you have installed a local
copy of Automake in your account and want @command{aclocal} to look for
macros installed at other places on the system.
@anchor{ACLOCAL_PATH}
@subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
@cindex @env{ACLOCAL_PATH}
The fourth and last mechanism to customize the macro search path is
also the simplest. Any directory included in the colon-separated
environment variable @env{ACLOCAL_PATH} is added to the search path
@c Keep in sync with aclocal-path-precedence.sh
and takes precedence over system directories (including those found via
@file{dirlist}), with the exception of the versioned directory
@var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
passed via @option{-I} will take precedence over directories in
@env{ACLOCAL_PATH}.
@c Keep in sync with aclocal-path-installed.sh
Also note that, if the @option{--install} option is used, any @file{.m4}
file containing a required macro that is found in a directory listed in
@env{ACLOCAL_PATH} will be installed locally.
@c Keep in sync with aclocal-path-installed-serial.sh
In this case, serial numbers in @file{.m4} are honoured too,
@pxref{Serials}.
Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
using a global copy of Automake and want @command{aclocal} to look for
macros somewhere under your home directory.
@subsubheading Planned future incompatibilities
The order in which the directories in the macro search path are currently
looked up is confusing and/or suboptimal in various aspects, and is
probably going to be changed in the future Automake release. In
particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
directories in @file{@var{acdir}/dirlist} might end up taking precedence
over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
@node Extending aclocal
@subsection Writing your own aclocal macros
@cindex @command{aclocal}, extending
@cindex Extending @command{aclocal}
The @command{aclocal} program doesn't have any built-in knowledge of any
macros, so it is easy to extend it with your own macros.
This can be used by libraries that want to supply their own Autoconf
macros for use by other programs. For instance, the @command{gettext}
library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
any package using @command{gettext}. When the library is installed, it
installs this macro so that @command{aclocal} will find it.
A macro file's name should end in @file{.m4}. Such files should be
installed in @file{$(datadir)/aclocal}. This is as simple as writing:
@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
aclocaldir = $(datadir)/aclocal
aclocal_DATA = mymacro.m4 myothermacro.m4
@end example
@noindent
Please do use @file{$(datadir)/aclocal}, and not something based on
the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
Paths}, for arguments). It might also be helpful to suggest to
the user to add the @file{$(datadir)/aclocal} directory to his
@env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
@command{aclocal} will find the @file{.m4} files installed by your
package automatically.
A file of macros should be a series of properly quoted
@code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
Autoconf Manual}). The @command{aclocal} programs also understands
@code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
Autoconf Manual}), so it is safe to put each macro in a separate file.
Each file should have no side effects but macro definitions.
Especially, any call to @code{AC_PREREQ} should be done inside the
defined macro, not at the beginning of the file.
@cindex underquoted @code{AC_DEFUN}
@acindex AC_DEFUN
@acindex AC_PREREQ
Starting with Automake 1.8, @command{aclocal} will warn about all
underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
lot of people, because @command{aclocal} was not so strict in the past
and many third party macros are underquoted; and we have to apologize
for this temporary inconvenience. The reason we have to be stricter
is that a future implementation of @command{aclocal} (@pxref{Future of
aclocal}) will have to temporarily include all of these third party
@file{.m4} files, maybe several times, including even files that are
not actually needed. Doing so should alleviate many problems of the
current implementation, however it requires a stricter style from the
macro authors. Hopefully it is easy to revise the existing macros.
For instance,
@example
# bad style
AC_PREREQ(2.68)
AC_DEFUN(AX_FOOBAR,
[AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
])
@end example
@noindent
should be rewritten as
@example
AC_DEFUN([AX_FOOBAR],
[AC_PREREQ([2.68])dnl
AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
])
@end example
Wrapping the @code{AC_PREREQ} call inside the macro ensures that
Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
used. Most importantly, quoting the first argument of @code{AC_DEFUN}
allows the macro to be redefined or included twice (otherwise this
first argument would be expanded during the second definition). For
consistency we like to quote even arguments such as @code{2.68} that
do not require it.
If you have been directed here by the @command{aclocal} diagnostic but
are not the maintainer of the implicated macro, you will want to
contact the maintainer of that macro. Please make sure you have the
latest version of the macro and that the problem hasn't already been
reported before doing so: people tend to work faster when they aren't
flooded by mails.
Another situation where @command{aclocal} is commonly used is to
manage macros that are used locally by the package, @ref{Local
Macros}.
@node Local Macros
@subsection Handling Local Macros
Feature tests offered by Autoconf do not cover all needs. People
often have to supplement existing tests with their own macros, or
with third-party macros.
There are two ways to organize custom macros in a package.
The first possibility (the historical practice) is to list all your
macros in @file{acinclude.m4}. This file will be included in
@file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
henceforth be visible to @command{autoconf}. However if it contains
numerous macros, it will rapidly become difficult to maintain, and it
will be almost impossible to share macros between packages.
The second possibility, which we do recommend, is to write each macro
in its own file and gather all these files in a directory. This
directory is usually called @file{m4/}. Then it's enough to update
@file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIR}:
@example
AC_CONFIG_MACRO_DIR([m4])
@end example
@command{aclocal} will then take care of automatically adding @file{m4/}
to its search path for m4 files.
When @samp{aclocal} is run, it will build an @file{aclocal.m4}
that @code{m4_include}s any file from @file{m4/} that defines a
required macro. Macros not found locally will still be searched in
system-wide directories, as explained in @ref{Macro Search Path}.
Custom macros should be distributed for the same reason that
@file{configure.ac} is: so that other people have all the sources of
your package if they want to work on it. Actually, this distribution
happens automatically because all @code{m4_include}d files are
distributed.
However there is no consensus on the distribution of third-party
macros that your package may use. Many libraries install their own
macro in the system-wide @command{aclocal} directory (@pxref{Extending
aclocal}). For instance, Guile ships with a file called
@file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
be used to define setup compiler and linker flags appropriate for
using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
cause @command{aclocal} to copy @file{guile.m4} into
@file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
it will not be distributed. Technically, that means a user who
needs to rebuild @file{aclocal.m4} will have to install Guile first.
This is probably OK, if Guile already is a requirement to build the
package. However, if Guile is only an optional feature, or if your
package might run on architectures where Guile cannot be installed,
this requirement will hinder development. An easy solution is to copy
such third-party macros in your local @file{m4/} directory so they get
distributed.
Since Automake 1.10, @command{aclocal} offers the option @code{--install}
to copy these system-wide third-party macros in your local macro directory,
helping to solve the above problem.
With this setup, system-wide macros will be copied to @file{m4/}
the first time you run @command{aclocal}. Then the locally installed
macros will have precedence over the system-wide installed macros
each time @command{aclocal} is run again.
One reason why you should keep @option{--install} in the flags even
after the first run is that when you later edit @file{configure.ac}
and depend on a new macro, this macro will be installed in your
@file{m4/} automatically. Another one is that serial numbers
(@pxref{Serials}) can be used to update the macros in your source tree
automatically when new system-wide versions are installed. A serial
number should be a single line of the form
@example
#serial @var{nnn}
@end example
@noindent
where @var{nnn} contains only digits and dots. It should appear in
the M4 file before any macro definition. It is a good practice to
maintain a serial number for each macro you distribute, even if you do
not use the @option{--install} option of @command{aclocal}: this allows
other people to use it.
@node Serials
@subsection Serial Numbers
@cindex serial numbers in macros
@cindex macro serial numbers
@cindex @code{#serial} syntax
@cindex @command{aclocal} and serial numbers
Because third-party macros defined in @file{*.m4} files are naturally
shared between multiple projects, some people like to version them.
This makes it easier to tell which of two M4 files is newer. Since at
least 1996, the tradition is to use a @samp{#serial} line for this.
A serial number should be a single line of the form
@example
# serial @var{version}
@end example
@noindent
where @var{version} is a version number containing only digits and
dots. Usually people use a single integer, and they increment it each
time they change the macro (hence the name of ``serial''). Such a
line should appear in the M4 file before any macro definition.
The @samp{#} must be the first character on the line,
and it is OK to have extra words after the version, as in
@example
#serial @var{version} @var{garbage}
@end example
Normally these serial numbers are completely ignored by
@command{aclocal} and @command{autoconf}, like any genuine comment.
However when using @command{aclocal}'s @option{--install} feature, these
serial numbers will modify the way @command{aclocal} selects the
macros to install in the package: if two files with the same basename
exist in your search path, and if at least one of them uses a
@samp{#serial} line, @command{aclocal} will ignore the file that has
the older @samp{#serial} line (or the file that has none).
Note that a serial number applies to a whole M4 file, not to any macro
it contains. A file can contains multiple macros, but only one
serial.
Here is a use case that illustrates the use of @option{--install} and
its interaction with serial numbers. Let's assume we maintain a
package called MyPackage, the @file{configure.ac} of which requires a
third-party macro @code{AX_THIRD_PARTY} defined in
@file{/usr/share/aclocal/thirdparty.m4} as follows:
@example
# serial 1
AC_DEFUN([AX_THIRD_PARTY], [...])
@end example
MyPackage uses an @file{m4/} directory to store local macros as
explained in @ref{Local Macros}, and has
@example
AC_CONFIG_MACRO_DIR([m4])
@end example
@noindent
in its @file{configure.ac}.
Initially the @file{m4/} directory is empty. The first time we run
@command{aclocal --install}, it will notice that
@itemize @bullet
@item
@file{configure.ac} uses @code{AX_THIRD_PARTY}
@item
No local macros define @code{AX_THIRD_PARTY}
@item
@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
with serial 1.
@end itemize
@noindent
Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
and @command{aclocal} was given the @option{--install} option, it will
copy this file in @file{m4/thirdparty.m4}, and output an
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
The next time @samp{aclocal --install} is run, something different
happens. @command{aclocal} notices that
@itemize @bullet
@item
@file{configure.ac} uses @code{AX_THIRD_PARTY}
@item
@file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
with serial 1.
@item
@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
with serial 1.
@end itemize
@noindent
Because both files have the same serial number, @command{aclocal} uses
the first it found in its search path order (@pxref{Macro Search
Path}). @command{aclocal} therefore ignores
@file{/usr/share/aclocal/thirdparty.m4} and outputs an
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
Local directories specified with @option{-I} are always searched before
system-wide directories, so a local file will always be preferred to
the system-wide file in case of equal serial numbers.
Now suppose the system-wide third-party macro is changed. This can
happen if the package installing this macro is updated. Let's suppose
the new macro has serial number 2. The next time @samp{aclocal --install}
is run the situation is the following:
@itemize @bullet
@item
@file{configure.ac} uses @code{AX_THIRD_PARTY}
@item
@file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
with serial 1.
@item
@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
with serial 2.
@end itemize
@noindent
When @command{aclocal} sees a greater serial number, it immediately
forgets anything it knows from files that have the same basename and a
smaller serial number. So after it has found
@file{/usr/share/aclocal/thirdparty.m4} with serial 2,
@command{aclocal} will proceed as if it had never seen
@file{m4/thirdparty.m4}. This brings us back to a situation similar
to that at the beginning of our example, where no local file defined
the macro. @command{aclocal} will install the new version of the
macro in @file{m4/thirdparty.m4}, in this case overriding the old
version. MyPackage just had its macro updated as a side effect of
running @command{aclocal}.
If you are leery of letting @command{aclocal} update your local
macro, you can run @samp{aclocal --diff} to review the changes
@samp{aclocal --install} would perform on these macros.
Finally, note that the @option{--force} option of @command{aclocal} has
absolutely no effect on the files installed by @option{--install}. For
instance, if you have modified your local macros, do not expect
@option{--install --force} to replace the local macros by their
system-wide versions. If you want to do so, simply erase the local
macros you want to revert, and run @samp{aclocal --install}.
@node Future of aclocal
@subsection The Future of @command{aclocal}
@cindex @command{aclocal}'s scheduled death
@command{aclocal} is expected to disappear. This feature really
should not be offered by Automake. Automake should focus on
generating @file{Makefile}s; dealing with M4 macros really is
Autoconf's job. The fact that some people install Automake just to use
@command{aclocal}, but do not use @command{automake} otherwise is an
indication of how that feature is misplaced.
The new implementation will probably be done slightly differently.
For instance, it could enforce the @file{m4/}-style layout discussed in
@ref{Local Macros}.
We have no idea when and how this will happen. This has been
discussed several times in the past, but someone still has to commit
to that non-trivial task.
From the user point of view, @command{aclocal}'s removal might turn
out to be painful. There is a simple precaution that you may take to
make that switch more seamless: never call @command{aclocal} yourself.
Keep this guy under the exclusive control of @command{autoreconf} and
Automake's rebuild rules. Hopefully you won't need to worry about
things breaking, when @command{aclocal} disappears, because everything
will have been taken care of. If otherwise you used to call
@command{aclocal} directly yourself or from some script, you will
quickly notice the change.
Many packages come with a script called @file{bootstrap.sh} or
@file{autogen.sh}, that will just call @command{aclocal},
@command{libtoolize}, @command{gettextize} or @command{autopoint},
@command{autoconf}, @command{autoheader}, and @command{automake} in
the right order. Actually this is precisely what @command{autoreconf}
can do for you. If your package has such a @file{bootstrap.sh} or
@file{autogen.sh} script, consider using @command{autoreconf}. That
should simplify its logic a lot (less things to maintain, yum!), it's
even likely you will not need the script anymore, and more to the point
you will not call @command{aclocal} directly anymore.
For the time being, third-party packages should continue to install
public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
is replaced by another tool it might make sense to rename the
directory, but supporting @file{/usr/share/aclocal/} for backward
compatibility should be really easy provided all macros are properly
written (@pxref{Extending aclocal}).
@node Macros
@section Autoconf macros supplied with Automake
Automake ships with several Autoconf macros that you can use from your
@file{configure.ac}. When you use one of them it will be included by
@command{aclocal} in @file{aclocal.m4}.
@menu
* Public Macros:: Macros that you can use.
* Private Macros:: Macros that you should not use.
@end menu
@c consider generating the following subsections automatically from m4 files.
@node Public Macros
@subsection Public Macros
@table @code
@item AM_INIT_AUTOMAKE([OPTIONS])
@acindex AM_INIT_AUTOMAKE
Runs many macros required for proper operation of the generated Makefiles.
@vindex AUTOMAKE_OPTIONS
@code{AM_INIT_AUTOMAKE} is called with a single argument: a space-separated
list of Automake options that should be applied to every @file{Makefile.am}
in the tree. The effect is as if each option were listed in
@code{AUTOMAKE_OPTIONS} (@pxref{Options}).
@c FIXME: Remove this "modernization advice" in Automake 1.14 (and adjust
@c FIXME: the error message in m4/init.m4:AM_INIT_AUTOMAKE accordingly).
@acindex AC_INIT
This macro could once (before Automake 1.13) also be called in the
@emph{now obsolete and completely unsupported} form
@code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
there were two required arguments: the package and the version number.
@anchor{Modernize AM_INIT_AUTOMAKE invocation}
If your @file{configure.ac} has:
@example
AC_INIT([src/foo.c])
AM_INIT_AUTOMAKE([mumble], [1.5])
@end example
@noindent
you must modernize it as follows in order to make it work with Automake
1.13 or later:
@example
AC_INIT([mumble], [1.5])
AC_CONFIG_SRCDIR([src/foo.c])
AM_INIT_AUTOMAKE
@end example
Note that if you're upgrading your @file{configure.ac} from an earlier
version of Automake, it is not always correct to simply move the
package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
@code{AC_INIT}, as in the example above. The first argument to
@code{AC_INIT} should be the name of your package (e.g., @samp{GNU
Automake}), not the tarball name (e.g., @samp{automake}) that you used
to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
tarball name from the package name, which should work for most but not
all package names. (If it doesn't work for yours, you can use the
four-argument form of @code{AC_INIT} to provide the tarball name
explicitly).
@cindex @code{PACKAGE}, prevent definition
@cindex @code{VERSION}, prevent definition
@opindex no-define
By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
@code{VERSION}. This can be avoided by passing the @option{no-define}
option:
@example
AM_INIT_AUTOMAKE([gnits 1.11.6 no-define parallel-tests])
@end example
@item AM_PATH_LISPDIR
@acindex AM_PATH_LISPDIR
@vindex EMACS
@vindex lispdir
Searches for the program @command{emacs}, and, if found, sets the
output variable @code{lispdir} to the full path to Emacs' site-lisp
directory.
Note that this test assumes the @command{emacs} found to be a version
that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
emacsen can cause this test to hang (some, like old versions of
MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
exit, which is hardly obvious for a non-emacs user). In most cases,
however, you should be able to use @kbd{C-c} to kill the test. In
order to avoid problems, you can set @env{EMACS} to ``no'' in the
environment, or use the @option{--with-lispdir} option to
@command{configure} to explicitly set the correct path (if you're sure
you have an @command{emacs} that supports Emacs Lisp).
@item AM_PROG_AR(@ovar{act-if-fail})
@acindex AM_PROG_AR
@vindex AR
You must use this macro when you use the archiver in your project, if
you want support for unusual archivers such as Microsoft @command{lib}.
The content of the optional argument is executed if the archiver
interface is not recognized; the default action is to abort configure
with an error message.
@item AM_PROG_AS
@acindex AM_PROG_AS
@vindex CCAS
@vindex CCASFLAGS
Use this macro when you have assembly code in your project. This will
choose the assembler for you (by default the C compiler) and set
@code{CCAS}, and will also set @code{CCASFLAGS} if required.
@item AM_PROG_CC_C_O
@acindex AM_PROG_CC_C_O
@acindex AC_PROG_CC_C_O
This is like @code{AC_PROG_CC_C_O}, but it generates its results in
the manner required by Automake. You must use this instead of
@code{AC_PROG_CC_C_O} when you need this functionality, that is, when
using per-target flags or subdir objects with C sources.
@item AM_PROG_LEX
@acindex AM_PROG_LEX
@acindex AC_PROG_LEX
@cindex HP-UX 10, @command{lex} problems
@cindex @command{lex} problems with HP-UX 10
Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}), but uses the
@command{missing} script on systems that do not have @command{lex}.
HP-UX 10 is one such system.
@item AM_PROG_GCJ
@acindex AM_PROG_GCJ
@vindex GCJ
@vindex GCJFLAGS
This macro finds the @command{gcj} program or causes an error. It sets
@code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
GNU Compiler Collection.
@item AM_PROG_UPC([@var{compiler-search-list}])
@acindex AM_PROG_UPC
@vindex UPC
Find a compiler for Unified Parallel C and define the @code{UPC}
variable. The default @var{compiler-search-list} is @samp{upcc upc}.
This macro will abort @command{configure} if no Unified Parallel C
compiler is found.
@item AM_MISSING_PROG(@var{name}, @var{program})
@acindex AM_MISSING_PROG
@vindex MISSING
Find a maintainer tool @var{program} and define the @var{name}
environment variable with its location. If @var{program} is not
detected, then @var{name} will instead invoke the @command{missing}
script, in order to give useful advice to the user about the missing
maintainer tool. @xref{maintainer tools}, for more information on
when the @command{missing} script is appropriate.
@item AM_SILENT_RULES
@acindex AM_SILENT_RULES
Control the machinery for less verbose build output
(@pxref{Automake Silent Rules}).
@item AM_WITH_DMALLOC
@acindex AM_WITH_DMALLOC
@cindex @command{dmalloc}, support for
@vindex WITH_DMALLOC
@opindex --with-dmalloc
Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
the user runs @command{configure} with @option{--with-dmalloc}, then
define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
@end table
@node Private Macros
@subsection Private Macros
The following macros are private macros you should not call directly.
They are called by the other public macros when appropriate. Do not
rely on them, as they might be changed in a future version. Consider
them as implementation details; or better, do not consider them at all:
skip this section!
@ftable @code
@item _AM_DEPENDENCIES
@itemx AM_SET_DEPDIR
@itemx AM_DEP_TRACK
These macros are used to implement Automake's automatic dependency
tracking scheme. They are called automatically by Automake when
required, and there should be no need to invoke them manually.
@item AM_PROG_INSTALL_STRIP
This is used to find a version of @code{install} that can be used to
strip a program at installation time. This macro is automatically
included when required.
@item AM_SANITY_CHECK
This checks to make sure that a file created in the build directory is
newer than a file in the source directory. This can fail on systems
where the clock is set incorrectly. This macro is automatically run
from @code{AM_INIT_AUTOMAKE}.
@end ftable
@node Directories
@chapter Directories
For simple projects that distribute all files in the same directory
it is enough to have a single @file{Makefile.am} that builds
everything in place.
In larger projects, it is common to organize files in different
directories, in a tree. For example, there could be a directory
for the program's source, one for the testsuite, and one for the
documentation; or, for very large projects, there could be one
directory per program, per library or per module.
The traditional approach is to build these subdirectories recursively,
employing @emph{make recursion}: each directory contains its
own @file{Makefile}, and when @command{make} is run from the top-level
directory, it enters each subdirectory in turn, and invokes there a
new @command{make} instance to build the directory's contents.
Because this approach is very widespread, Automake offers built-in
support for it. However, it is worth nothing that the use of make
recursion has its own serious issues and drawbacks, and that it's
well possible to have packages with a multi directory layout that
make little or no use of such recursion (examples of such packages
are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
section below.
@menu
* Subdirectories:: Building subdirectories recursively
* Conditional Subdirectories:: Conditionally not building directories
* Alternative:: Subdirectories without recursion
* Subpackages:: Nesting packages
@end menu
@node Subdirectories
@section Recursing subdirectories
@cindex @code{SUBDIRS}, explained
In packages using make recursion, the top level @file{Makefile.am} must
tell Automake which subdirectories are to be built. This is done via
the @code{SUBDIRS} variable.
@vindex SUBDIRS
The @code{SUBDIRS} variable holds a list of subdirectories in which
building of various sorts can occur. The rules for many targets
(e.g., @code{all}) in the generated @file{Makefile} will run commands
both locally and in all specified subdirectories. Note that the
directories listed in @code{SUBDIRS} are not required to contain
@file{Makefile.am}s; only @file{Makefile}s (after configuration).
This allows inclusion of libraries from packages that do not use
Automake (such as @code{gettext}; see also @ref{Third-Party
Makefiles}).
In packages that use subdirectories, the top-level @file{Makefile.am} is
often very short. For instance, here is the @file{Makefile.am} from the
GNU Hello distribution:
@example
EXTRA_DIST = BUGS ChangeLog.O README-alpha
SUBDIRS = doc intl po src tests
@end example
When Automake invokes @command{make} in a subdirectory, it uses the value
of the @code{MAKE} variable.
@vindex MAKE
The directories mentioned in @code{SUBDIRS} are usually direct
children of the current directory, each subdirectory containing its
own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
subdirectories. Automake can be used to construct packages of
arbitrary depth this way.
By default, Automake generates @file{Makefiles} that work depth-first
in postfix order: the subdirectories are built before the current
directory. However, it is possible to change this ordering. You can
do this by putting @samp{.} into @code{SUBDIRS}. For instance,
putting @samp{.} first will cause a prefix ordering of
directories.
Using
@example
SUBDIRS = lib src . test
@end example
@noindent
will cause @file{lib/} to be built before @file{src/}, then the
current directory will be built, finally the @file{test/} directory
will be built. It is customary to arrange test directories to be
built after everything else since they are meant to test what has
been constructed.
In addition to the built-in recursive targets defined by Automake
(@code{all}, @code{check}, etc.), the developer can also define his
own recursive targets. That is done by passing the names of such
targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS}
in @file{configure.ac}. Automake generates rules to handle the
recursion for such targets; and the developer can define real actions
for them by defining corresponding @code{-local} targets.
@example
% @kbd{cat configure.ac}
AC_INIT([pkg-name], [1.0]
AM_INIT_AUTOMAKE
AM_EXTRA_RECURSIVE_TARGETS([foo])
AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
AC_OUTPUT
% @kbd{cat Makefile.am}
SUBDIRS = sub
foo-local:
@@echo This will be run by "make foo".
% @kbd{cat sub/Makefile.am}
SUBDIRS = src
% @kbd{cat sub/src/Makefile.am}
foo-local:
@@echo This too will be run by a "make foo" issued either in
@@echo the 'sub/src/' directory, the 'sub/' directory, or the
@@echo top-level directory.
@end example
@node Conditional Subdirectories
@section Conditional Subdirectories
@cindex Subdirectories, building conditionally
@cindex Conditional subdirectories
@cindex @code{SUBDIRS}, conditional
@cindex Conditional @code{SUBDIRS}
It is possible to define the @code{SUBDIRS} variable conditionally if,
like in the case of GNU Inetutils, you want to only build a subset of
the entire package.
To illustrate how this works, let's assume we have two directories
@file{src/} and @file{opt/}. @file{src/} should always be built, but we
want to decide in @command{configure} whether @file{opt/} will be built
or not. (For this example we will assume that @file{opt/} should be
built when the variable @samp{$want_opt} was set to @samp{yes}.)
Running @command{make} should thus recurse into @file{src/} always, and
then maybe in @file{opt/}.
However @samp{make dist} should always recurse into both @file{src/}
and @file{opt/}. Because @file{opt/} should be distributed even if it
is not needed in the current configuration. This means
@file{opt/Makefile} should be created @emph{unconditionally}.
There are two ways to setup a project like this. You can use Automake
conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
variables (@pxref{Setting Output Variables, , Setting Output
Variables, autoconf, The Autoconf Manual}). Using Automake
conditionals is the preferred solution. Before we illustrate these
two possibilities, let's introduce @code{DIST_SUBDIRS}.
@menu
* SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
* Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
* Subdirectories with AC_SUBST:: Another way for conditional recursion
* Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
@end menu
@node SUBDIRS vs DIST_SUBDIRS
@subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
@cindex @code{DIST_SUBDIRS}, explained
Automake considers two sets of directories, defined by the variables
@code{SUBDIRS} and @code{DIST_SUBDIRS}.
@code{SUBDIRS} contains the subdirectories of the current directory
that must be built (@pxref{Subdirectories}). It must be defined
manually; Automake will never guess a directory is to be built. As we
will see in the next two sections, it is possible to define it
conditionally so that some directory will be omitted from the build.
@code{DIST_SUBDIRS} is used in rules that need to recurse in all
directories, even those that have been conditionally left out of the
build. Recall our example where we may not want to build subdirectory
@file{opt/}, but yet we want to distribute it? This is where
@code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in