[eclipse-cdt] 04/04: Updated autotools documentation sources
Jakub Adam
xhaakon-guest at alioth.debian.org
Thu Oct 3 19:10:13 UTC 2013
This is an automated email from the git hooks/post-receive script.
xhaakon-guest pushed a commit to branch master
in repository eclipse-cdt.
commit f3f08f51b9193a5b3aacec7bdac5a72d95c3ad34
Author: Jakub Adam <jakub.adam at ktknet.cz>
Date: Thu Oct 3 20:33:24 2013 +0200
Updated autotools documentation sources
---
debian/changelog | 1 +
debian/docs/src/autoconf/2.69/autoconf.texi | 24 +-
.../docs/src/automake/1.14/automake-history.texi | 1214 ++
debian/docs/src/automake/1.14/automake.texi |13204 ++++++++++++++++++++
debian/docs/src/automake/1.14/fdl.texi | 506 +
debian/docs/src/automake/1.14/version.texi | 4 +
.../autotools-add-distro-version-to-list.patch | 4 +-
7 files changed, 14943 insertions(+), 14 deletions(-)
diff --git a/debian/changelog b/debian/changelog
index f2c775a..f79a99b 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,7 @@
eclipse-cdt (8.2.1-1) UNRELEASED; urgency=low
* New upstream release.
+ * Updated autotools documentation sources.
-- Jakub Adam <jakub.adam at ktknet.cz> Thu, 03 Oct 2013 20:30:16 +0200
diff --git a/debian/docs/src/autoconf/2.69/autoconf.texi b/debian/docs/src/autoconf/2.69/autoconf.texi
index 34ca213..3873114 100644
--- a/debian/docs/src/autoconf/2.69/autoconf.texi
+++ b/debian/docs/src/autoconf/2.69/autoconf.texi
@@ -15,7 +15,7 @@
@c The ARG is an optional argument. To be used for macro arguments in
@c their documentation (@defmac).
@macro ovar{varname}
- at r{[}@var{\varname\}@r{]}@c
+ at r{[}@var{\varname\}@r{]}
@end macro
@c @dvar(ARG, DEFAULT)
@@ -23,7 +23,7 @@
@c The ARG is an optional argument, defaulting to DEFAULT. To be used
@c for macro arguments in their documentation (@defmac).
@macro dvar{varname, default}
- at r{[}@var{\varname\} = @samp{\default\}@r{]}@c
+ at r{[}@var{\varname\} = @samp{\default\}@r{]}
@end macro
@c Handling the indexes with Texinfo yields several different problems.
@@ -8013,10 +8013,10 @@ variables, respectively. The computed linker flags are cached in
@code{ac_cv_f77_libs} or @code{ac_cv_fc_libs}, respectively.
@end defmac
- at defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
- AC_MSG_FAILURE})
- at defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @dvar{action-if-not-found, @
- AC_MSG_FAILURE})
+ at defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @
+ @dvar{action-if-not-found, AC_MSG_FAILURE})
+ at defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @
+ @dvar{action-if-not-found, AC_MSG_FAILURE})
@acindex{F77_DUMMY_MAIN}
@cvindex F77_DUMMY_MAIN
@acindex{FC_DUMMY_MAIN}
@@ -8267,8 +8267,8 @@ results in @code{ac_cv_fc_srcext_ at var{ext}} and
@code{ac_cv_fc_pp_srcext_ at var{ext}} variables, respectively.
@end defmac
- at defmac AC_FC_PP_DEFINE (@ovar{action-if-success}, @dvar{action-if-failure, @
- AC_MSG_FAILURE})
+ at defmac AC_FC_PP_DEFINE (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_PP_DEFINE}
@caindex fc_pp_define
@@ -8286,8 +8286,8 @@ The result of this test is cached in the @code{ac_cv_fc_pp_define}
variable.
@end defmac
- at defmac AC_FC_FREEFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
- AC_MSG_FAILURE})
+ at defmac AC_FC_FREEFORM (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_FREEFORM}
@caindex fc_freeform
@@ -8313,8 +8313,8 @@ The result of this test, or @samp{none} or @samp{unknown}, is cached in
the @code{ac_cv_fc_freeform} variable.
@end defmac
- at defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @dvar{action-if-failure, @
- AC_MSG_FAILURE})
+ at defmac AC_FC_FIXEDFORM (@ovar{action-if-success}, @
+ @dvar{action-if-failure, AC_MSG_FAILURE})
@acindex{FC_FIXEDFORM}
@caindex fc_fixedform
diff --git a/debian/docs/src/automake/1.14/automake-history.texi b/debian/docs/src/automake/1.14/automake-history.texi
new file mode 100644
index 0000000..5089f59
--- /dev/null
+++ b/debian/docs/src/automake/1.14/automake-history.texi
@@ -0,0 +1,1214 @@
+\input texinfo @c -*-texinfo-*-
+ at c %**start of header
+ at setfilename automake-history.info
+ at settitle automake-history
+ at setchapternewpage on
+ at c %**end of header
+
+ at copying
+
+This manual describes (part of) the history of GNU Automake, a program
+that creates GNU standards-compliant Makefiles from template files.
+
+Copyright @copyright{} 1995-2013 Free Software Foundation, Inc.
+
+ at 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.''
+
+ at end quotation
+ at end copying
+
+ at titlepage
+ at title Brief History of Automake
+ at author David MacKenzie
+ at author Tom Tromey
+ at author Alexandre Duret-Lutz
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+ at ifnottex
+ at node Top
+ at comment node-name, next, previous, up
+ at top Brief History of Automake
+
+ at insertcopying
+
+ at menu
+* Timeline:: The Automake story.
+* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
+* Releases:: Release statistics
+* Copying This Manual:: How to make copies of this manual
+
+ at detailmenu
+ --- The Detailed Node Listing ---
+
+Evolution of Automatic Dependency Tracking
+
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+
+Techniques for Computing Dependencies
+
+* Recommendations for Tool Writers::
+* Future Directions for Dependencies::
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
+ at end detailmenu
+ at end menu
+
+ at end ifnottex
+
+ at node Timeline
+ at chapter Timeline
+
+ at table @asis
+ at item 1994-09-19 First CVS commit.
+
+If we can trust the CVS repository, David J. at tie{}MacKenzie (djm) started
+working on Automake (or AutoMake, as it was spelt then) this Monday.
+
+The first version of the @command{automake} script looks as follows.
+
+ at example
+#!/bin/sh
+
+status=0
+
+for makefile
+do
+ if test ! -f $@{makefile@}.am; then
+ echo "automake: $@{makefile@}.am: No such honkin' file"
+ status=1
+ continue
+ fi
+
+ exec 4> $@{makefile@}.in
+
+done
+ at end example
+
+From this you can already see that Automake will be about reading
+ at file{*.am} file and producing @file{*.in} files. You cannot see
+anything else, but if you also know that David is the one who created
+Autoconf two years before you can guess the rest.
+
+Several commits follow, and by the end of the day Automake is
+reported to work for GNU fileutils and GNU m4.
+
+The modus operandi is the one that is still used today: variable
+assignments in @file{Makefile.am} files trigger injections of
+precanned @file{Makefile} fragments into the generated
+ at file{Makefile.in}. The use of @file{Makefile} fragments was inspired
+by the 4.4BSD @command{make} and include files, however Automake aims
+to be portable and to conform to the GNU standards for @file{Makefile}
+variables and targets.
+
+At this point, the most recent release of Autoconf is version 1.11,
+and David is preparing to release Autoconf 2.0 in late October. As a
+matter of fact, he will barely touch Automake after September.
+
+ at item 1994-11-05 David MacKenzie's last commit.
+
+At this point Automake is a 200 line portable shell script, plus 332
+lines of @file{Makefile} fragments. In the @file{README}, David
+states his ambivalence between ``portable shell'' and ``more
+appropriate language'':
+
+ at quotation
+I wrote it keeping in mind the possibility of it becoming an Autoconf
+macro, so it would run at configure-time. That would slow
+configuration down a bit, but allow users to modify the Makefile.am
+without needing to fetch the AutoMake package. And, the Makefile.in
+files wouldn't need to be distributed. But all of AutoMake would. So
+I might reimplement AutoMake in Perl, m4, or some other more
+appropriate language.
+ at end quotation
+
+Automake is described as ``an experimental Makefile generator''.
+There is no documentation. Adventurous users are referred to the
+examples and patches needed to use Automake with GNU m4 1.3, fileutils
+3.9, time 1.6, and development versions of find and indent.
+
+These examples seem to have been lost. However at the time of writing
+(10 years later in September, 2004) the FSF still distributes a
+package that uses this version of Automake: check out GNU termutils
+2.0.
+
+ at item 1995-11-12 Tom Tromey's first commit.
+
+After one year of inactivity, Tom Tromey takes over the package.
+Tom was working on GNU cpio back then, and doing this just for fun,
+having trouble finding a project to contribute to. So while hacking
+he wanted to bring the @file{Makefile.in} up to GNU standards. This
+was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
+grabbed it and tried it out.
+
+Tom didn't talk to djm about it until later, just to make sure he
+didn't mind if he made a release. He did a bunch of early releases to
+the Gnits folks.
+
+Gnits was (and still is) totally informal, just a few GNU friends who
+Fran@,cois Pinard knew, who were all interested in making a common
+infrastructure for GNU projects, and shared a similar outlook on how
+to do it. So they were able to make some progress. It came along
+with Autoconf and extensions thereof, and then Automake from David and
+Tom (who were both gnitsians). One of their ideas was to write a
+document paralleling the GNU standards, that was more strict in some
+ways and more detailed. They never finished the GNITS standards, but
+the ideas mostly made their way into Automake.
+
+ at item 1995-11-23 Automake 0.20
+
+Besides introducing automatic dependency tracking (@pxref{Dependency
+Tracking Evolution}), this version also supplies a 9-page manual.
+
+At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
+exist, so many things had to be done by hand. For instance, here is
+what a configure.in (this is the former name of the
+ at file{configure.ac} we use today) must contain in order to use
+Automake 0.20:
+
+ at example
+PACKAGE=cpio
+VERSION=2.3.911
+AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
+AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
+AC_SUBST(PACKAGE)
+AC_SUBST(VERSION)
+AC_ARG_PROGRAM
+AC_PROG_INSTALL
+ at end example
+
+(Today all of the above is achieved by @code{AC_INIT} and
+ at code{AM_INIT_AUTOMAKE}.)
+
+Here is how programs are specified in @file{Makefile.am}:
+
+ at example
+PROGRAMS = hello
+hello_SOURCES = hello.c
+ at end example
+
+This looks pretty much like what we do today, except the
+ at code{PROGRAMS} variable has no directory prefix specifying where
+ at file{hello} should be installed: all programs are installed in
+ at samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
+that must be built but not installed (it is called
+ at code{noinst_PROGRAMS} nowadays).
+
+Programs can be built conditionally using @code{AC_SUBST}itutions:
+
+ at example
+PROGRAMS = @@progs@@
+AM_PROGRAMS = foo bar baz
+ at end example
+
+(@code{AM_PROGRAMS} has since then been renamed to
+ at code{EXTRA_PROGRAMS}.)
+
+Similarly scripts, static libraries, and data can be built and installed
+using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
+However @code{LIBRARIES} were treated a bit specially in that Automake
+did automatically supply the @file{lib} and @file{.a} prefixes.
+Therefore to build @file{libcpio.a}, one had to write
+
+ at example
+LIBRARIES = cpio
+cpio_SOURCES = ...
+ at end example
+
+Extra files to distribute must be listed in @code{DIST_OTHER} (the
+ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
+distributed should appear in @code{DIST_SUBDIRS}, but the manual
+describes this as a temporary ugly hack (today extra directories should
+also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
+for another purpose, @pxref{Conditional Subdirectories, , Conditional
+Subdirectories, automake, GNU Automake}).
+
+ at item 1995-11-26 Automake 0.21
+
+In less time than it takes to cook a frozen pizza, Tom rewrites
+Automake using Perl. At this time Perl 5 is only one year old, and
+Perl 4.036 is in use at many sites. Supporting several Perl versions
+has been a source of problems through the whole history of Automake.
+
+If you never used Perl 4, imagine Perl 5 without objects, without
+ at samp{my} variables (only dynamically scoped @samp{local} variables),
+without function prototypes, with function calls that needs to be
+prefixed with @samp{&}, etc. Traces of this old style can still be
+found in today's @command{automake}.
+
+ at item 1995-11-28 Automake 0.22
+ at itemx 1995-11-29 Automake 0.23
+
+Bug fixes.
+
+ at item 1995-12-08 Automake 0.24
+ at itemx 1995-12-10 Automake 0.25
+
+Releases are raining. 0.24 introduces the uniform naming scheme we
+use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
+ at code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
+ at code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
+in use; and @code{TEXINFOS} and @code{MANS} still have no directory
+prefixes.) Adding support for prefixes like that was one of the major
+ideas in @command{automake}; it has lasted pretty well.
+
+AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
+Pinard's doing).
+
+0.25 fixes a Perl 4 portability bug.
+
+ at item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
+ at item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
+
+ at item 1996-01-03 Automake 0.26
+ at itemx 1996-01-03 Automake 0.27
+
+Of the many changes and suggestions sent by Fran@,cois Pinard and
+included in 0.26, perhaps the most important is the advice that to
+ease customization a user rule or variable definition should always
+override an Automake rule or definition.
+
+Gordon Matzigkeit and Jim Meyering are two other early contributors
+that have been sending fixes.
+
+0.27 fixes yet another Perl 4 portability bug.
+
+ at item 1996-01-13 Automake 0.28
+
+Automake starts scanning @file{configure.in} for @code{LIBOBJS}
+support. This is an important step because until this version
+Automake only knew about the @file{Makefile.am}s it processed.
+ at file{configure.in} was Autoconf's world and the link between Autoconf
+and Automake had to be done by the @file{Makefile.am} author. For
+instance, if @file{config.h} was generated by @file{configure}, it was the
+package maintainer's responsibility to define the @code{CONFIG_HEADER}
+variable in each @file{Makefile.am}.
+
+Succeeding releases will rely more and more on scanning
+ at file{configure.in} to better automate the Autoconf integration.
+
+0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
+ at option{--gnu} and @option{--gnits} options, the latter being stricter.
+
+ at item 1996-02-07 Automake 0.29
+
+Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
+and rebuild rules for @file{configure}-generated file are
+automatically output.
+
+ at code{TEXINFOS} and @code{MANS} converted to the uniform naming
+scheme.
+
+ at item 1996-02-24 Automake 0.30
+
+The test suite is born. It contains 9 tests. From now on test cases
+will be added pretty regularly (@pxref{Releases}), and this proved to
+be really helpful later on.
+
+ at code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
+
+All the third-party Autoconf macros, written mostly by Fran@,cois
+Pinard (and later Jim Meyering), are distributed in Automake's
+hand-written @file{aclocal.m4} file. Package maintainers are expected
+to extract the necessary macros from this file. (In previous versions
+you had to copy and paste them from the manual...)
+
+ at item 1996-03-11 Automake 0.31
+
+The test suite in 0.30 was run via a long @code{check-local} rule. Upon
+Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
+whenever the @code{TESTS} variable is defined.
+
+ at code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
+prefix is introduced. The syntax is now the same as today.
+
+ at item 1996-03-15 Gordon Matzigkeit starts writing libtool.
+
+ at item 1996-04-27 Automake 0.32
+
+ at code{-hook} targets are introduced; an idea from Dieter Baron.
+
+ at file{*.info} files, which were output in the build directory are
+now built in the source directory, because they are distributed. It
+seems these files like to move back and forth as that will happen
+again in future versions.
+
+ at item 1996-05-18 Automake 0.33
+
+Gord Matzigkeit's main two contributions:
+
+ at itemize
+ at item very preliminary libtool support
+ at item the distcheck rule
+ at end itemize
+
+Although they were very basic at this point, these are probably
+among the top features for Automake today.
+
+Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE}, since
+then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its author
+(@pxref{maintainer-mode, , maintainer-mode, automake, GNU Automake}).
+
+ at item 1996-05-28 Automake 1.0
+
+After only six months of heavy development, the @command{automake} script is
+3134 lines long, plus 973 lines of @file{Makefile} fragments. The
+package has 30 pages of documentation, and 38 test cases.
+ at file{aclocal.m4} contains 4 macros.
+
+From now on and until version 1.4, new releases will occur at a rate
+of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
+been the name of beta releases for 1.2. This is the first time
+Automake uses suffix letters to designate beta releases, a habit that
+lasts.
+
+ at item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
+
+ at item 1996-11-26 David J. at tie{}MacKenzie releases Autoconf 2.12.
+
+Between June and October, the Autoconf development is almost stalled.
+Roland McGrath has been working at the beginning of the year. David
+comes back in November to release 2.12, but he won't touch Autoconf
+anymore after this year, and Autoconf then really stagnates. The
+desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
+
+ at item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
+
+The mailing list is announced as follows:
+ at smallexample
+I've created the "automake" mailing list. It is
+"automake@@gnu.ai.mit.edu". Administrivia, as always, to
+automake-request@@gnu.ai.mit.edu.
+
+The charter of this list is discussion of automake, autoconf, and
+other configuration/portability tools (e.g., libtool). It is expected
+that discussion will range from pleas for help all the way up to
+patches.
+
+This list is archived on the FSF machines. Offhand I don't know if
+you can get the archive without an account there.
+
+This list is open to anybody who wants to join. Tell all your
+friends!
+-- Tom Tromey
+ at end smallexample
+
+Before that people were discussing Automake privately, on the Gnits
+mailing list (which is not public either), and less frequently on
+ at code{gnu.misc.discuss}.
+
+ at code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
+noticed. The archives of the early years of the
+ at code{automake@@gnu.org} list have been lost, so today it is almost
+impossible to find traces of discussions that occurred before 1999.
+This has been annoying more than once, as such discussions can be
+useful to understand the rationale behind a piece of uncommented code
+that was introduced back then.
+
+ at item 1997-06-22 Automake 1.2
+
+Automake developments continues, and more and more new Autoconf macros
+are required. Distributing them in @file{aclocal.m4} and requiring
+people to browse this file to extract the relevant macros becomes
+uncomfortable. Ideally, some of them should be contributed to
+Autoconf so that they can be used directly, however Autoconf is
+currently inactive. Automake 1.2 consequently introduces
+ at command{aclocal} (@command{aclocal} was actually started on
+1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
+file from a repository of third-party macros. Because Autoconf has
+stalled, Automake also becomes a kind of repository for such
+third-party macros, even macros completely unrelated to Automake (for
+instance macros that fix broken Autoconf macros).
+
+The 1.2 release contains 20 macros, including the
+ at code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
+ at file{configure.in}.
+
+Libtool is fully supported using @code{*_LTLIBRARIES}.
+
+The missing script is introduced by Fran@,cois Pinard; it is meant
+to be a better solution than @code{AM_MAINTAINER_MODE}
+(@pxref{maintainer-mode, , maintainer-mode, automake, GNU Automake}).
+
+Conditionals support was implemented by Ian Lance Taylor. At the
+time, Tom and Ian were working on an internal project at Cygnus. They
+were using ILU, which is pretty similar to CORBA at . They wanted to
+integrate ILU into their build, which was all @file{configure}-based,
+and Ian thought that adding conditionals to @command{automake} was
+simpler than doing all the work in @file{configure} (which was the
+standard at the time). So this was actually funded by Cygnus.
+
+This very useful but tricky feature will take a lot of time to
+stabilize. (At the time this text is written, there are still
+primaries that have not been updated to support conditional
+definitions in Automake 1.9.)
+
+The @command{automake} script has almost doubled: 6089 lines of Perl,
+plus 1294 lines of @file{Makefile} fragments.
+
+ at item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
+
+ at item 1998-04-05 Automake 1.3
+
+This is a small advance compared to 1.2.
+It adds support for assembly, and preliminary support for Java.
+
+Perl 5.004_04 is out, but fixes to support Perl 4 are still
+regularly submitted whenever Automake breaks it.
+
+ at item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
+
+Sourceware was setup by Jason Molenda to host open source projects.
+
+ at item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
+ at itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake:
+Automake is now hosted on @code{sourceware.cygnus.com}. It has a
+publicly accessible CVS repository. This CVS repository is a copy of
+the one Tom was using on his machine, which in turn is based on
+a copy of the CVS repository of David MacKenzie. This is why we still
+have to full source history. (Automake was on Sourceware until 2007-10-29,
+when it moved to a git repository on @code{savannah.gnu.org},
+but the Sourceware host had been renamed to @code{sources.redhat.com}.)
+
+The oldest file in the administrative directory of the CVS repository
+that was created on Sourceware is dated 1998-09-19, while the
+announcement that @command{automake} and @command{autoconf} had joined
+ at command{sourceware} was made on 1998-10-26. They were among the
+first projects to be hosted there.
+
+The heedful reader will have noticed Automake was exactly 4 years old
+on 1998-09-19.
+
+ at item 1999-01-05 Ben Elliston releases Autoconf 2.13.
+
+ at item 1999-01-14 Automake 1.4
+
+This release adds support for Fortran 77 and for the @code{include}
+statement. Also, @samp{+=} assignments are introduced, but it is
+still quite easy to fool Automake when mixing this with conditionals.
+
+These two releases, Automake 1.4 and Autoconf 2.13 make a duo that
+will be used together for years.
+
+ at command{automake} is 7228 lines, plus 1591 lines of Makefile
+fragment, 20 macros (some 1.3 macros were finally contributed back to
+Autoconf), 197 test cases, and 51 pages of documentation.
+
+ at item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
+
+This implements a new dependency tracking schemed that should be
+able to handle automatic dependency tracking using any compiler (not
+just gcc) and any make (not just GNU @command{make}). In addition,
+the new scheme should be more reliable than the old one, as
+dependencies are generated on the end user's machine. Alexandre Oliva
+creates depcomp for this purpose.
+
+ at xref{Dependency Tracking Evolution}, for more details about the
+evolution of automatic dependency tracking in Automake.
+
+ at item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
+
+This was a huge problem since we also had patches going in on the
+trunk. The merge took a long time and was very painful.
+
+ at item 2000-05-10
+
+Since September 1999 and until 2003, Akim Demaille will be zealously
+revamping Autoconf.
+
+ at quotation
+I think the next release should be called "3.0".@*
+Let's face it: you've basically rewritten autoconf.@*
+Every weekend there are 30 new patches.@*
+I don't see how we could call this "2.15" with a straight face.@*
+-- Tom Tromey on @email{autoconf@@gnu.org}
+ at end quotation
+
+Actually Akim works like a submarine: he will pile up patches while he
+works off-line during the weekend, and flush them in batch when he
+resurfaces on Monday.
+
+ at item 2001-01-24
+
+On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
+is out, and Akim has to find something to do during his week-end :)
+
+ at item 2001-01-28
+
+Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
+
+ at quotation
+Aiieeee! I was dreading the day that the Demaillator turned his
+sights on automake at dots{} and now it has arrived! -- Tom Tromey
+ at end quotation
+
+It's only the beginning: in two months he will send 192 patches. Then
+he would slow down so Tom can catch up and review all this. Initially
+Tom actually read all of these patches, then he probably trustingly
+answered OK to most of them, and finally gave up and let Akim apply
+whatever he wanted. There was no way to keep up with that patch rate.
+
+ at quotation
+Anyway the patch below won't apply since it predates Akim's
+sourcequake; I have yet to figure where the relevant passage has
+been moved :) -- Alexandre Duret-Lutz
+ at end quotation
+
+All of these patches were sent to and discussed on
+ at email{automake@@gnu.org}, so subscribed users were literally drowning in
+technical mails. Eventually, the @email{automake-patches@@gnu.org}
+mailing list was created in May.
+
+Year after year, Automake had drifted away from its initial design:
+construct @file{Makefile.in} by assembling various @file{Makefile}
+fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
+various places in the @command{automake} script itself; this does not
+help ensuring a consistent treatment of these rules (for instance
+making sure that user-defined rules override Automake's own rules).
+One of Akim's goal was moving all of these hard-coded rules to separate
+ at file{Makefile} fragments, so the logic could be centralized in a
+ at file{Makefile} fragment processor.
+
+Another significant contribution of Akim is the interface with the
+``trace'' feature of Autoconf. The way to scan @file{configure.in} at
+this time was to read the file and grep the various macro of interest
+to Automake. Doing so could break in many unexpected ways; @command{automake}
+could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
+where the arguments are known only when M4 is run), or conversely it
+could detect some macro that was not expanded (because it is called
+conditionally). In the CVS version of Autoconf, Akim had implemented
+the @option{--trace} option, which provides accurate information about
+where macros are actually called and with what arguments. Akim will
+equip Automake with a second @file{configure.in} scanner that uses
+this @option{--trace} interface. Since it was not sensible to drop the
+Autoconf 2.13 compatibility yet, this experimental scanner was only
+used when an environment variable was set, the traditional
+grep-scanner being still the default.
+
+ at item 2001-04-25 Gary V. at tie{}Vaughan releases Libtool 1.4
+
+It has been more than two years since Automake 1.4, CVS Automake has
+suffered lot's of heavy changes and still is not ready for release.
+Libtool 1.4 had to be distributed with a patch against Automake 1.4.
+
+ at item 2001-05-08 Automake 1.4-p1
+ at itemx 2001-05-24 Automake 1.4-p2
+
+Gary V. at tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
+release'' of Automake:
+
+ at quotation
+The main purpose of this release is to have a stable automake
+which is compatible with the latest stable libtool.
+ at end quotation
+
+The release also contains obvious fixes for bugs in Automake 1.4,
+some of which were reported almost monthly.
+
+ at item 2001-05-21 Akim Demaille releases Autoconf 2.50
+
+ at item 2001-06-07 Automake 1.4-p3
+ at itemx 2001-06-10 Automake 1.4-p4
+ at itemx 2001-07-15 Automake 1.4-p5
+
+Gary continues his patch-release series. These also add support for
+some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
+ at file{configure.ac} over @file{configure.in}, and it introduces a new
+syntax for @code{AC_OUTPUT}ing files.
+
+ at item 2001-08-23 Automake 1.5
+
+A major and long-awaited release, that comes more than two years after
+1.4. It brings many changes, among which:
+ at itemize
+ at item The new dependency tracking scheme that uses @command{depcomp}.
+Aside from the improvement on the dependency tracking itself
+(@pxref{Dependency Tracking Evolution}), this also streamlines the use
+of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s
+used during development are now the same as those used in
+distributions. Before that the @file{Makefile.in}s generated for
+maintainers required GNU @command{make} and GCC, they were different
+from the portable @file{Makefile} generated for distribution; this was
+causing some confusion.
+
+ at item Support for per-target compilation flags.
+
+ at item Support for reference to files in subdirectories in most
+ at file{Makefile.am} variables.
+
+ at item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
+prefixes.
+ at item Perl 4 support is finally dropped.
+ at end itemize
+
+1.5 did break several packages that worked with 1.4. Enough so that
+Linux distributions could not easily install the new Automake version
+without breaking many of the packages for which they had to run
+ at command{automake}.
+
+Some of these breakages were effectively bugs that would eventually be
+fixed in the next release. However, a lot of damage was caused by
+some changes made deliberately to render Automake stricter on some
+setup we did consider bogus. For instance, @samp{make distcheck} was
+improved to check that @samp{make uninstall} did remove all the files
+ at samp{make install} installed, that @samp{make distclean} did not omit
+some file, and that a VPATH build would work even if the source
+directory was read-only. Similarly, Automake now rejects multiple
+definitions of the same variable (because that would mix very badly
+with conditionals), and @samp{+=} assignments with no previous
+definition. Because these changes all occurred suddenly after 1.4 had
+been established for more than two years, it hurt users.
+
+To make matter worse, meanwhile Autoconf (now at version 2.52) was
+facing similar troubles, for similar reasons.
+
+ at item 2002-03-05 Automake 1.6
+
+This release introduced versioned installation (@pxref{API Versioning, ,
+API Versioning, automake, GNU Automake}). This was mainly pushed by
+Havoc Pennington, taking the GNOME source tree as motive: due to
+incompatibilities between the autotools it's impossible for the GNOME
+packages to switch to Autoconf 2.53 and Automake 1.5 all at once, so
+they are currently stuck with Autoconf 2.13 and Automake 1.4.
+
+The idea was to call this version @file{automake-1.6}, call all its
+bug-fix versions identically, and switch to @file{automake-1.7} for
+the next release that adds new features or changes some rules. This
+scheme implies maintaining a bug-fix branch in addition to the
+development trunk, which means more work from the maintainer, but
+providing regular bug-fix releases proved to be really worthwhile.
+
+Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional or
+not. Perhaps the more annoying was the dependence on the newly
+released Autoconf 2.53. Autoconf seemed to have stabilized enough
+since its explosive 2.50 release and included changes required to fix
+some bugs in Automake. In order to upgrade to Automake 1.6, people
+now had to upgrade Autoconf too; for some packages it was no picnic.
+
+While versioned installation helped people to upgrade, it also
+unfortunately allowed people not to upgrade. At the time of writing,
+some Linux distributions are shipping packages for Automake 1.4, 1.5,
+1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
+Some distribution also call 1.4 the ``stable'' version, and present
+``1.9'' as the development version; this does not really makes sense
+since 1.9 is way more solid than 1.4. All this does not help the
+newcomer.
+
+ at item 2002-04-11 Automake 1.6.1
+
+1.6, and the upcoming 1.4-p6 release were the last release by Tom.
+This one and those following will be handled by Alexandre
+Duret-Lutz. Tom is still around, and will be there until about 1.7,
+but his interest into Automake is drifting away towards projects like
+ at command{gcj}.
+
+Alexandre has been using Automake since 2000, and started to
+contribute mostly on Akim's incitement (Akim and Alexandre have been
+working in the same room from 1999 to 2002). In 2001 and 2002 he had
+a lot of free time to enjoy hacking Automake.
+
+ at item 2002-06-14 Automake 1.6.2
+
+ at item 2002-07-28 Automake 1.6.3
+ at itemx 2002-07-28 Automake 1.4-p6
+
+Two releases on the same day. 1.6.3 is a bug-fix release.
+
+Tom Tromey backported the versioned installation mechanism on the 1.4
+branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
+side by side. Another request from the GNOME folks.
+
+ at item 2002-09-25 Automake 1.7
+
+This release switches to the new @file{configure.ac} scanner Akim
+was experimenting in 1.5.
+
+ at item 2002-10-16 Automake 1.7.1
+ at itemx 2002-12-06 Automake 1.7.2
+ at itemx 2003-02-20 Automake 1.7.3
+ at itemx 2003-04-23 Automake 1.7.4
+ at itemx 2003-05-18 Automake 1.7.5
+ at itemx 2003-07-10 Automake 1.7.6
+ at itemx 2003-09-07 Automake 1.7.7
+ at itemx 2003-10-07 Automake 1.7.8
+
+Many bug-fix releases. 1.7 lasted because the development version
+(upcoming 1.8) was suffering some major internal revamping.
+
+ at item 2003-10-26 Automake on screen
+
+Episode 49, `Repercussions', in the third season of the `Alias' TV
+show is first aired.
+
+Marshall, one of the characters, is working on a computer virus that he
+has to modify before it gets into the wrong hands or something like
+that. The screenshots you see do not show any program code, they show
+a @file{Makefile.in} generated by automake...
+
+ at item 2003-11-09 Automake 1.7.9
+
+ at item 2003-12-10 Automake 1.8
+
+The most striking update is probably that of @command{aclocal}.
+
+ at command{aclocal} now uses @code{m4_include} in the produced
+ at file{aclocal.m4} when the included macros are already distributed
+with the package (an idiom used in many packages), which reduces code
+duplication. Many people liked that, but in fact this change was
+really introduced to fix a bug in rebuild rules: @file{Makefile.in}
+must be rebuilt whenever a dependency of @file{configure} changes, but
+all the @file{m4} files included in @file{aclocal.m4} where unknown
+from @command{automake}. Now @command{automake} can just trace the
+ at code{m4_include}s to discover the dependencies.
+
+ at command{aclocal} also starts using the @option{--trace} Autoconf option
+in order to discover used macros more accurately. This will turn out
+to be very tricky (later releases will improve this) as people had
+devised many ways to cope with the limitation of previous
+ at command{aclocal} versions, notably using handwritten
+ at code{m4_include}s: @command{aclocal} must make sure not to redefine a
+rule that is already included by such statement.
+
+Automake also has seen its guts rewritten. Although this rewriting
+took a lot of efforts, it is only apparent to the users in that some
+constructions previously disallowed by the implementation now work
+nicely. Conditionals, Locations, Variable and Rule definitions,
+Options: these items on which Automake works have been rewritten as
+separate Perl modules, and documented.
+
+ at item 2004-01-11 Automake 1.8.1
+ at itemx 2004-01-12 Automake 1.8.2
+ at itemx 2004-03-07 Automake 1.8.3
+ at itemx 2004-04-25 Automake 1.8.4
+ at itemx 2004-05-16 Automake 1.8.5
+
+ at item 2004-07-28 Automake 1.9
+
+This release tries to simplify the compilation rules it outputs to
+reduce the size of the Makefile. The complaint initially come from
+the libgcj developers. Their @file{Makefile.in} generated with
+Automake 1.4 and custom build rules (1.4 did not support compiled
+Java) is 250KB at . The one generated by 1.8 was over 9MB@! 1.9 gets it
+down to 1.2MB at .
+
+Aside from this it contains mainly minor changes and bug-fixes.
+
+ at item 2004-08-11 Automake 1.9.1
+ at itemx 2004-09-19 Automake 1.9.2
+
+Automake has ten years. This chapter of the manual was initially
+written for this occasion.
+
+ at item 2007-10-29 Automake repository moves to @code{savannah.gnu.org}
+and uses git as primary repository.
+
+ at end table
+
+ at node Dependency Tracking Evolution
+ at chapter Evolution of Automatic Dependency Tracking
+
+Over the years Automake has deployed three different dependency
+tracking methods. Each method, including the current one, has had
+flaws of various sorts. Here we lay out the different dependency
+tracking methods, their flaws, and their fixes. We conclude with
+recommendations for tool writers, and by indicating future directions
+for dependency tracking work in Automake.
+
+ at menu
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+ at end menu
+
+ at node First Take on Dependencies
+ at section First Take on Dependency Tracking
+ at unnumberedsubsec Description
+
+Our first attempt at automatic dependency tracking was based on the
+method recommended by GNU @command{make}. (@pxref{Automatic
+Prerequisites, , Generating Prerequisites Automatically, make, The GNU
+make Manual})
+
+This version worked by precomputing dependencies ahead of time. For
+each source file, it had a special @file{.P} file that held the
+dependencies. There was a rule to generate a @file{.P} file by
+invoking the compiler appropriately. All such @file{.P} files were
+included by the @file{Makefile}, thus implicitly becoming dependencies
+of @file{Makefile}.
+
+ at unnumberedsubsec Bugs
+
+This approach had several critical bugs.
+
+ at itemize
+ at item
+The code to generate the @file{.P} file relied on @command{gcc}.
+(A limitation, not technically a bug.)
+ at item
+The dependency tracking mechanism itself relied on GNU @command{make}.
+(A limitation, not technically a bug.)
+ at item
+Because each @file{.P} file was a dependency of @file{Makefile}, this
+meant that dependency tracking was done eagerly by @command{make}.
+For instance, @samp{make clean} would cause all the dependency files
+to be updated, and then immediately removed. This eagerness also
+caused problems with some configurations; if a certain source file
+could not be compiled on a given architecture for some reason,
+dependency tracking would fail, aborting the entire build.
+ at item
+As dependency tracking was done as a pre-pass, compile times were
+doubled--the compiler had to be run twice per source file.
+ at item
+ at samp{make dist} re-ran @command{automake} to generate a
+ at file{Makefile} that did not have automatic dependency tracking (and
+that was thus portable to any version of @command{make}). In order to
+do this portably, Automake had to scan the dependency files and remove
+any reference that was to a source file not in the distribution.
+This process was error-prone. Also, if @samp{make dist} was run in an
+environment where some object file had a dependency on a source file
+that was only conditionally created, Automake would generate a
+ at file{Makefile} that referred to a file that might not appear in the
+end user's build. A special, hacky mechanism was required to work
+around this.
+ at end itemize
+
+ at unnumberedsubsec Historical Note
+
+The code generated by Automake is often inspired by the
+ at file{Makefile} style of a particular author. In the case of the first
+implementation of dependency tracking, I believe the impetus and
+inspiration was Jim Meyering. (I could be mistaken. If you know
+otherwise feel free to correct me.)
+
+ at node Dependencies As Side Effects
+ at section Dependencies As Side Effects
+ at unnumberedsubsec Description
+
+The next refinement of Automake's automatic dependency tracking scheme
+was to implement dependencies as side effects of the compilation.
+This was aimed at solving the most commonly reported problems with the
+first approach. In particular we were most concerned with eliminating
+the weird rebuilding effect associated with make clean.
+
+In this approach, the @file{.P} files were included using the
+ at code{-include} command, which let us create these files lazily. This
+avoided the @samp{make clean} problem.
+
+We only computed dependencies when a file was actually compiled. This
+avoided the performance penalty associated with scanning each file
+twice. It also let us avoid the other problems associated with the
+first, eager, implementation. For instance, dependencies would never
+be generated for a source file that was not compilable on a given
+architecture (because it in fact would never be compiled).
+
+ at unnumberedsubsec Bugs
+
+ at itemize
+ at item
+This approach also relied on the existence of @command{gcc} and GNU
+ at command{make}. (A limitation, not technically a bug.)
+ at item
+Dependency tracking was still done by the developer, so the problems
+from the first implementation relating to massaging of dependencies by
+ at samp{make dist} were still in effect.
+ at item
+This implementation suffered from the ``deleted header file'' problem.
+Suppose a lazily-created @file{.P} file includes a dependency on a
+given header file, like this:
+
+ at example
+maude.o: maude.c something.h
+ at end example
+
+Now suppose that you remove @file{something.h} and update @file{maude.c}
+so that this include is no longer needed. If you run @command{make},
+you will get an error because there is no way to create
+ at file{something.h}.
+
+We fixed this problem in a later release by further massaging the
+output of @command{gcc} to include a dummy dependency for each header
+file.
+ at end itemize
+
+ at node Dependencies for the User
+ at section Dependencies for the User
+ at unnumberedsubsec Description
+
+The bugs associated with @samp{make dist}, over time, became a real
+problem. Packages using Automake were being built on a large number
+of platforms, and were becoming increasingly complex. Broken
+dependencies were distributed in ``portable'' @file{Makefile.in}s,
+leading to user complaints. Also, the requirement for @command{gcc}
+and GNU @command{make} was a constant source of bug reports. The next
+implementation of dependency tracking aimed to remove these problems.
+
+We realized that the only truly reliable way to automatically track
+dependencies was to do it when the package itself was built. This
+meant discovering a method portable to any version of make and any
+compiler. Also, we wanted to preserve what we saw as the best point
+of the second implementation: dependency computation as a side effect
+of compilation.
+
+In the end we found that most modern make implementations support some
+form of include directive. Also, we wrote a wrapper script that let
+us abstract away differences between dependency tracking methods for
+compilers. For instance, some compilers cannot generate dependencies
+as a side effect of compilation. In this case we simply have the
+script run the compiler twice. Currently our wrapper script
+(@command{depcomp}) knows about twelve different compilers (including
+a "compiler" that simply invokes @command{makedepend} and then the
+real compiler, which is assumed to be a standard Unix-like C compiler
+with no way to do dependency tracking).
+
+ at unnumberedsubsec Bugs
+
+ at itemize
+ at item
+Running a wrapper script for each compilation slows down the build.
+ at item
+Many users don't really care about precise dependencies.
+ at item
+This implementation, like every other automatic dependency tracking
+scheme in common use today (indeed, every one we've ever heard of),
+suffers from the ``duplicated new header'' bug.
+
+This bug occurs because dependency tracking tools, such as the
+compiler, only generate dependencies on the successful opening of a
+file, and not on every probe.
+
+Suppose for instance that the compiler searches three directories for
+a given header, and that the header is found in the third directory.
+If the programmer erroneously adds a header file with the same name to
+the first directory, then a clean rebuild from scratch could fail
+(suppose the new header file is buggy), whereas an incremental rebuild
+will succeed.
+
+What has happened here is that people have a misunderstanding of what
+a dependency is. Tool writers think a dependency encodes information
+about which files were read by the compiler. However, a dependency
+must actually encode information about what the compiler tried to do.
+
+This problem is not serious in practice. Programmers typically do not
+use the same name for a header file twice in a given project. (At
+least, not in C or C++. This problem may be more troublesome in
+Java.) This problem is easy to fix, by modifying dependency
+generators to record every probe, instead of every successful open.
+
+ at item
+Since Automake generates dependencies as a side effect of compilation,
+there is a bootstrapping problem when header files are generated by
+running a program. The problem is that, the first time the build is
+done, there is no way by default to know that the headers are
+required, so make might try to run a compilation for which the headers
+have not yet been built.
+
+This was also a problem in the previous dependency tracking implementation.
+
+The current fix is to use @code{BUILT_SOURCES} to list built headers
+(@pxref{Sources, , Sources, automake, GNU Automake}). This causes them
+to be built before any other build rules are run. This is unsatisfactory
+as a general solution, however in practice it seems sufficient for most
+actual programs.
+ at end itemize
+
+This code is used since Automake 1.5.
+
+In GCC 3.0, we managed to convince the maintainers to add special
+command-line options to help Automake more efficiently do its job. We
+hoped this would let us avoid the use of a wrapper script when
+Automake's automatic dependency tracking was used with @command{gcc}.
+
+Unfortunately, this code doesn't quite do what we want. In
+particular, it removes the dependency file if the compilation fails;
+we'd prefer that it instead only touch the file in any way if the
+compilation succeeds.
+
+Nevertheless, since Automake 1.7, when a recent @command{gcc} is
+detected at @command{configure} time, we inline the
+dependency-generation code and do not use the @command{depcomp}
+wrapper script. This makes compilations faster for those using this
+compiler (probably our primary user base). The counterpart is that
+because we have to encode two compilation rules in @file{Makefile}
+(with or without @command{depcomp}), the produced @file{Makefile}s are
+larger.
+
+ at node Techniques for Dependencies
+ at section Techniques for Computing Dependencies
+
+There are actually several ways for a build tool like Automake to
+cause tools to generate dependencies.
+
+ at table @asis
+ at item @command{makedepend}
+This was a commonly-used method in the past. The idea is to run a
+special program over the source and have it generate dependency
+information. Traditional implementations of @command{makedepend} are
+not completely precise; ordinarily they were conservative and
+discovered too many dependencies.
+ at item The tool
+An obvious way to generate dependencies is to simply write the tool so
+that it can generate the information needed by the build tool. This is
+also the most portable method. Many compilers have an option to
+generate dependencies. Unfortunately, not all tools provide such an
+option.
+ at item The file system
+It is possible to write a special file system that tracks opens,
+reads, writes, etc, and then feed this information back to the build
+tool. @command{clearmake} does this. This is a very powerful
+technique, as it doesn't require cooperation from the
+tool. Unfortunately it is also very difficult to implement and also
+not practical in the general case.
+ at item @code{LD_PRELOAD}
+Rather than use the file system, one could write a special library to
+intercept @code{open} and other syscalls. This technique is also quite
+powerful, but unfortunately it is not portable enough for use in
+ at command{automake}.
+ at end table
+
+ at menu
+* Recommendations for Tool Writers::
+* Future Directions for Dependencies::
+ at end menu
+
+ at node Recommendations for Tool Writers
+ at subsection Recommendations for Tool Writers
+
+We think that every compilation tool ought to be able to generate
+dependencies as a side effect of compilation. Furthermore, at least
+while @command{make}-based tools are nearly universally in use (at
+least in the free software community), the tool itself should generate
+dummy dependencies for header files, to avoid the deleted header file
+bug. Finally, the tool should generate a dependency for each probe,
+instead of each successful file open, in order to avoid the duplicated
+new header bug.
+
+ at node Future Directions for Dependencies
+ at subsection Future Directions for Dependencies
+
+Currently, only languages and compilers understood by Automake can
+have dependency tracking enabled. We would like to see if it is
+practical (and worthwhile) to let this support be extended by the user
+to languages unknown to Automake.
+
+ at node Releases
+ at chapter Release Statistics
+
+The following table (inspired by @samp{perlhist(1)}) quantifies the
+evolution of Automake using these metrics:
+
+ at table @asis
+ at item Date, Rel
+The date and version of the release.
+ at item am
+The number of lines of the @command{automake} script.
+ at item acl
+The number of lines of the @command{aclocal} script.
+ at item pm
+The number of lines of the @command{Perl} supporting modules.
+ at item @file{*.am}
+The number of lines of the @file{Makefile} fragments. The number in
+parentheses is the number of files.
+ at item m4
+The number of lines (and files) of Autoconf macros.
+ at item doc
+The number of pages of the documentation (the Postscript version).
+ at item t
+The number of test cases in the test suite. Of those, the number in
+parentheses is the number of generated test cases.
+ at end table
+
+ at multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888 (88)}
+ at headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
+ at item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
+ at item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
+ at item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
+ at item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
+ at item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
+ at item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
+ at item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
+ at item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
+ at item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
+ at item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
+ at item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
+ at item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
+ at item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
+ at item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
+ at item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
+ at item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
+ at item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
+ at item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
+ at item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
+ at item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
+ at item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
+ at item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
+ at item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
+ at item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
+ at item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
+ at item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
+ at item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
+ at item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
+ at item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
+ at item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
+ at item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
+ at item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
+ at item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
+ at item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
+ at item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
+ at item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
+ at item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
+ at item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
+ at item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
+ at item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
+ at item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
+ at item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
+ at item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
+ at item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
+ at item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
+ at item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
+ at item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
+ at item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
+ at item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
+ at item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
+ at item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
+ at item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
+ at item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
+ at item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
+ at item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
+ at item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617
+ at item 2008-11-23 @tab 1.10.2 @tab 7882 @tab 1089 @tab 8027 @tab 3540 (40) @tab 1509 (34) @tab 176 @tab 628
+ at item 2009-05-17 @tab 1.11 @tab 8721 @tab 1092 @tab 8289 @tab 4164 (42) @tab 1714 (37) @tab 181 @tab 732 (20)
+ at end multitable
+
+
+ at c ========================================================== Appendices
+
+ at page
+ at node Copying This Manual
+ at appendix Copying This Manual
+
+ at menu
+* GNU Free Documentation License:: License for copying this manual
+ at end menu
+
+ at node GNU Free Documentation License
+ at appendixsec GNU Free Documentation License
+ at include fdl.texi
+
+ at bye
diff --git a/debian/docs/src/automake/1.14/automake.texi b/debian/docs/src/automake/1.14/automake.texi
new file mode 100644
index 0000000..e37741b
--- /dev/null
+++ b/debian/docs/src/automake/1.14/automake.texi
@@ -0,0 +1,13204 @@
+\input texinfo @c -*-texinfo-*-
+ at c %**start of header
+ at setfilename automake-1.14.info
+ at settitle automake-1.14
+ at setchapternewpage off
+ at c %**end of header
+
+ at include version.texi
+
+ at c @ovar(ARG, DEFAULT)
+ at c -------------------
+ at c The ARG is an optional argument. To be used for macro arguments in
+ at c their documentation (@defmac).
+ at macro ovar{varname}
+ at r{[}@var{\varname\}@r{]}
+ at end macro
+
+ at set PACKAGE_BUGREPORT bug-automake@@gnu.org
+
+ at copying
+
+This manual is for GNU Automake (version @value{VERSION},
+ at value{UPDATED}), a program that creates GNU standards-compliant
+Makefiles from template files.
+
+Copyright @copyright{} 1995-2013 Free Software Foundation, Inc.
+
+ at 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.''
+
+ at end quotation
+ at end copying
+
+ at dircategory Software development
+ at direntry
+* Automake: (automake-1.14). Making GNU standards-compliant Makefiles.
+ at end direntry
+
+ at dircategory Individual utilities
+ at direntry
+* aclocal-invocation: (automake-1.14)aclocal Invocation. Generating aclocal.m4.
+* automake-invocation: (automake-1.14)automake Invocation. Generating Makefile.in.
+ at end direntry
+
+ at titlepage
+ at title GNU Automake
+ at subtitle For version @value{VERSION}, @value{UPDATED}
+ at author David MacKenzie
+ at author Tom Tromey
+ at author Alexandre Duret-Lutz
+ at author Ralf Wildenhues
+ at author Stefano Lattarini
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+ at c We use the following macros to define indices:
+ at c @cindex concepts, and anything that does not fit elsewhere
+ at c @vindex Makefile variables
+ at c @trindex targets
+ at c @acindex Autoconf/Automake/Libtool/M4/... macros
+ at c @opindex tool options
+
+ at c Define an index of configure macros.
+ at defcodeindex ac
+ at c Define an index of options.
+ at defcodeindex op
+ at c Define an index of targets.
+ at defcodeindex tr
+ at c Define an index of commands.
+ at defcodeindex cm
+
+ at c Put the macros in the function index.
+ at syncodeindex ac fn
+
+ at c Put everything else into one index (arbitrarily chosen to be the
+ at c concept index).
+ at syncodeindex op cp
+ at syncodeindex tr cp
+ at syncodeindex cm cp
+
+ at ifnottex
+ at node Top
+ at comment node-name, next, previous, up
+ at top GNU Automake
+
+ at insertcopying
+
+ at menu
+* Introduction:: Automake'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
+
+ at 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 discouraged) 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-mode:: missing and AM_MAINTAINER_MODE
+* 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
+
+ at end detailmenu
+ at end menu
+
+ at end ifnottex
+
+
+ at node Introduction
+ at chapter Introduction
+
+Automake 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 at footnote{These variables are also called @dfn{make macros}
+in Make terminology, however in this manual we reserve the term
+ at 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.
+
+ at 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 is to
+remove the burden of Makefile maintenance from the back of the
+individual GNU maintainer (and put it on the back of the Automake
+maintainers).
+
+The typical Automake input file is simply a series of variable definitions.
+Each such file is processed to create a @file{Makefile.in}.
+
+ at cindex Constraints of Automake
+ at cindex Automake constraints
+
+Automake 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.
+
+ at cindex Automake requirements
+ at cindex Requirements, Automake
+
+Automake requires @command{perl} in order to generate the
+ at file{Makefile.in}s. However, the distributions created by Automake are
+fully GNU standards-compliant, and do not require @command{perl} in order
+to be built.
+
+ at cindex Bugs, reporting
+ at cindex Reporting bugs
+ at cindex E-mail, bug reports
+
+For more information on bug reports, @xref{Reporting Bugs}.
+
+ at node Autotools Introduction
+ at chapter An Introduction to the Autotools
+
+If you are new to Automake, 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},
+ at file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
+some of them claiming to be @emph{generated by} Autoconf or Automake.
+But the exact purpose of these files and their relations is probably
+fuzzy. The goal of this chapter is to introduce you to this machinery,
+to show you how it works and how powerful it is. If you've never
+installed or seen such a package, do not worry: this chapter will walk
+you through it.
+
+If you need some teaching material, more illustrations, or a less
+ at command{automake}-centered continuation, some slides for this
+introduction are available in Alexandre Duret-Lutz's
+ at uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
+Autotools Tutorial}.
+This chapter is the written version of the first part of his tutorial.
+
+ at 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
+ at end menu
+
+ at node GNU Build System
+ at section Introducing the GNU Build System
+ at 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
+ at 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
+ at 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
+ at 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}.
+
+ at 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.
+
+ at 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 on
+ at 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.
+
+ at node Use Cases
+ at section Use Cases for the GNU Build System
+ at cindex GNU Build System, use cases
+ at cindex GNU Build System, features
+ at cindex Features of the GNU Build System
+ at cindex Use Cases for the GNU Build System
+ at cindex @file{amhello-1.0.tar.gz}, location
+ at 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. If Automake is installed on your
+system, you should find a copy of this file in
+ at file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
+ at var{prefix} is the installation prefix specified during configuration
+(@var{prefix} defaults to @file{/usr/local}, however if Automake 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 installed,
+you can find a copy of this file inside the @file{doc/} directory of
+the Automake package.
+
+Some of the following use cases present features that are in fact
+extensions to the GNU Build System. Read: they are not specified by
+the GNU Coding Standards, but they are nonetheless part of the build
+system created by the Autotools. To keep things simple, we do not
+point out the difference. Our objective is to show you many of the
+features that the build system created by the Autotools will offer to
+you.
+
+ at 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
+ at end menu
+
+ at node Basic Installation
+ at subsection Basic Installation
+ at cindex Configuration, basics
+ at cindex Installation, basics
+ at cindex GNU Build System, basics
+
+The most common installation procedure looks as follows.
+
+ at example
+~ % @kbd{tar zxf amhello-1.0.tar.gz}
+~ % @kbd{cd amhello-1.0}
+~/amhello-1.0 % @kbd{./configure}
+ at dots{}
+config.status: creating Makefile
+config.status: creating src/Makefile
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{make check}
+ at dots{}
+~/amhello-1.0 % @kbd{su}
+Password:
+/home/adl/amhello-1.0 # @kbd{make install}
+ at dots{}
+/home/adl/amhello-1.0 # @kbd{exit}
+~/amhello-1.0 % @kbd{make installcheck}
+ at dots{}
+ at end example
+
+ at 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
+ at 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.
+
+ at 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.
+
+ at 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
+ at 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
+ at 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.
+
+ at node Standard Targets
+ at 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
+ at code{make installcheck}. The words @code{check}, @code{install}, and
+ at code{installcheck}, passed as arguments to @command{make}, are called
+ at dfn{targets}. @code{make} is a shorthand for @code{make all},
+ at 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.
+
+ at table @code
+ at item make all
+ at trindex all
+Build programs, libraries, documentation, etc.@: (same as @code{make}).
+ at item make install
+ at trindex install
+Install what needs to be installed, copying the files from the
+package's tree to system-wide directories.
+ at item make install-strip
+ at trindex install-strip
+Same as @code{make install}, then strip debugging symbols. Some
+users like to trade space for useful bug reports at enddots{}
+ at item make uninstall
+ at 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.)
+ at item make clean
+ at trindex clean
+Erase from the build tree the files built by @code{make all}.
+ at item make distclean
+ at trindex distclean
+Additionally erase anything @code{./configure} created.
+ at item make check
+ at trindex check
+Run the test suite, if any.
+ at item make installcheck
+ at trindex installcheck
+Check the installed programs or libraries, if supported.
+ at item make dist
+ at trindex dist
+Recreate @file{@var{package}- at var{version}.tar.gz} from all the source
+files.
+ at end table
+
+ at node Standard Directory Variables
+ at subsection Standard Directory Variables
+ at cindex directory variables
+
+The GNU Coding Standards also specify a hierarchy of variables to
+denote installation directories. Some of these are:
+
+ at multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
+ at headitem Directory variable @tab Default value
+ at item @code{prefix} @tab @code{/usr/local}
+ at item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
+ at item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
+ at item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
+ at item @w{@ @ @ @ @dots{}}
+ at item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
+ at item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
+ at item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
+ at item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
+ at item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
+ at item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
+ at item @w{@ @ @dots{}}
+ at end multitable
+
+ at c We should provide a complete table somewhere, but not here. The
+ at c complete list of directory variables it too confusing as-is. It
+ at c requires some explanations that are too complicated for this
+ at c introduction. Besides listing directories like localstatedir
+ at 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
+ at file{hello} is to be installed in @var{bindir}, the directory for
+binaries. The default value for this directory is
+ at 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
+ at file{/usr/local/share/doc/amhello}.
+
+ at opindex --prefix
+
+As a user, if you wish to install a package on your own account, you
+could proceed as follows:
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{make install}
+ at dots{}
+ at end example
+
+This would install @file{~/usr/bin/hello} and
+ at file{~/usr/share/doc/amhello/README}.
+
+The list of all such directory options is shown by
+ at code{./configure --help}.
+
+ at node Standard Configuration Variables
+ at subsection Standard Configuration Variables
+ at cindex configuration variables, overriding
+
+The GNU Coding Standards also define a set of standard configuration
+variables used during the build. Here are some:
+
+ at table @asis
+ at item @code{CC}
+C compiler command
+ at item @code{CFLAGS}
+C compiler flags
+ at item @code{CXX}
+C++ compiler command
+ at item @code{CXXFLAGS}
+C++ compiler flags
+ at item @code{LDFLAGS}
+linker flags
+ at item @code{CPPFLAGS}
+C/C++ preprocessor flags
+ at item @dots{}
+ at end table
+
+ at 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
+ at command{gcc-3} as C compiler, use header files from
+ at file{~/usr/include} when compiling, and libraries from
+ at file{~/usr/lib} when linking.
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
+CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
+ at end example
+
+Again, a full list of these variables appears in the output of
+ at code{./configure --help}.
+
+ at node config.site
+ at subsection Overriding Default Configuration Setting with @file{config.site}
+ at 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,
+ at command{configure} will source it at the beginning of its execution.
+
+Recall the command from the previous section:
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
+CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
+ at 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
+ at code{LDFLAGS}, we can automate this by creating the following
+ at file{~/usr/share/config.site} file:
+
+ at example
+test -z "$CC" && CC=gcc-3
+test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
+test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
+ at 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.
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
+configure: loading site script /home/adl/usr/share/config.site
+ at dots{}
+ at end example
+
+ at xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
+Manual}, for more information about this feature.
+
+
+ at node VPATH Builds
+ at subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
+ at cindex Parallel build trees
+ at cindex VPATH builds
+ at cindex source tree and build tree
+ at cindex build tree and source tree
+ at 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
+ at 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/}.
+
+ at 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}
+ at dots{}
+~/amhello-1.0/build % @kbd{make}
+ at dots{}
+ at end example
+
+These setups, where source and build trees are different, are often
+called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
+ at 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}).
+
+ at cindex multiple configurations, example
+ at cindex debug build, example
+ at cindex optimized build, example
+
+VPATH builds have other interesting uses. One is to build the same
+sources with multiple configurations. For instance:
+
+ at c Keep in sync with amhello-cflags.sh
+ at 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'}
+ at dots{}
+~/amhello-1.0/debug % @kbd{make}
+ at dots{}
+~/amhello-1.0/debug % cd ../optim
+~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
+ at dots{}
+~/amhello-1.0/optim % @kbd{make}
+ at dots{}
+ at 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.
+
+ at example
+~ % @kbd{cd /nfs/src}
+/nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
+ at end example
+
+On the first host, you could create a local build directory:
+ at 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}
+...
+ at end example
+
+ at 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:
+ at 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}
+...
+ at end example
+
+ at cindex read-only source tree
+ at 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.)
+
+ at node Two-Part Install
+ at 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.
+
+ at trindex install-exec
+ at 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
+ at file{/usr}, and (2) the directory @file{/usr/share} is shared by the
+two hosts.
+
+On the first host we would run
+ at 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}
+...
+ at end example
+
+On the second host, however, we need only install the
+architecture-specific files.
+ at 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}
+...
+ at end example
+
+In packages that have installation checks, it would make sense to run
+ at code{make installcheck} (@pxref{Basic Installation}) to verify that
+the package works correctly despite the apparent partial installation.
+
+ at node Cross-Compilation
+ at subsection Cross-Compilation
+ at 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
+ at command{configure} options are used to specify each of them:
+
+ at table @option
+ at item --build=@var{build}
+ at opindex --build=@var{build}
+The system on which the package is built.
+ at item --host=@var{host}
+ at opindex --host=@var{host}
+The system where built programs and libraries will run.
+ at 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
+ at code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
+ at code{i586-mingw32msvc-as}, etc.
+
+ at cindex MinGW cross-compilation example
+ at cindex cross-compilation example
+
+Here is how we could build @code{amhello-1.0} for
+ at code{i586-mingw32msvc} on a GNU/Linux PC.
+
+ at c Keep in sync with amhello-cross-compile.sh
+ at 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...
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{cd src; file hello.exe}
+hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
+ at 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.
+
+ at table @option
+ at item --target=@var{target}
+ at opindex --target=@var{target}
+When building compiler tools: the system for which the tools will
+create output.
+ at 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
+ at option{--target}, we can actually cross-compile a cross-compiler;
+such a three-way cross-compilation is known as a @dfn{Canadian cross}.
+
+ at xref{Specifying Names, , Specifying the System Type, autoconf, The
+Autoconf Manual}, for more information about these @command{configure}
+options.
+
+ at node Renaming
+ at subsection Renaming Programs at Install Time
+ at cindex Renaming programs
+ at cindex Transforming program names
+ at 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.
+
+ at table @option
+ at item --program-prefix=@var{prefix}
+ at opindex --program-prefix=@var{prefix}
+Prepend @var{prefix} to installed program names.
+ at item --program-suffix=@var{suffix}
+ at opindex --program-suffix=@var{suffix}
+Append @var{suffix} to installed program names.
+ at item --program-transform-name=@var{program}
+ at opindex --program-transform-name=@var{program}
+Run @code{sed @var{program}} on installed program names.
+ at end table
+
+The following commands would install @file{hello}
+as @file{/usr/local/bin/test-hello}, for instance.
+
+ at example
+~/amhello-1.0 % @kbd{./configure --program-prefix test-}
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{sudo make install}
+ at dots{}
+ at end example
+
+ at node DESTDIR
+ at subsection Building Binary Packages Using DESTDIR
+ at 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.
+
+ at 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.
+
+ at cindex Binary package
+
+For instance here is how we could create a binary package containing a
+snapshot of all the files to be installed.
+
+ at c Keep in sync with amhello-binpkg.sh
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix /usr}
+ at dots{}
+~/amhello-1.0 % @kbd{make}
+ at dots{}
+~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
+ at 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
+ at 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.
+
+ at xref{Install}, for more information.
+
+ at c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
+ at c UNINSTALL counterparts.
+
+ at node Preparing Distributions
+ at subsection Preparing Distributions
+ at cindex Preparing distributions
+ at cindex Packages, preparation
+ at 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}- at var{version}.tar.gz}.
+
+ at cindex @code{distcheck} better than @code{dist}
+
+Another, more useful command is @code{make distcheck}. The
+ at code{distcheck} target constructs
+ at file{@var{package}- at var{version}.tar.gz} just as well as @code{dist},
+but it additionally ensures most of the use cases presented so far
+work:
+
+ at itemize @bullet
+ at item
+It attempts a full compilation of the package (@pxref{Basic
+Installation}), unpacking the newly constructed tarball, running
+ at code{make}, @code{make check}, @code{make install}, as well as
+ at code{make installcheck}, and even @code{make dist},
+ at item
+it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
+ at item
+it makes sure @code{make clean}, @code{make distclean}, and @code{make
+uninstall} do not omit any file (@pxref{Standard Targets}),
+ at item
+and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
+ at 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
+ at 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).
+
+ at xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
+ at code{make distcheck}. @xref{Checking the Distribution}, for more
+information about @code{distcheck}.
+
+ at node Dependency Tracking
+ at subsection Automatic Dependency Tracking
+ at 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,
+ at 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):
+
+ at example
+~/amhello-1.0 % @kbd{./configure --prefix /usr}
+ at dots{}
+checking dependency style of gcc... gcc3
+ at dots{}
+ at 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:
+ at 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:
+
+ at table @option
+ at item --disable-dependency-tracking
+ at opindex --disable-dependency-tracking
+Speed up one-time builds.
+ at 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.
+
+ at table @option
+ at item --enable-dependency-tracking
+ at opindex --enable-dependency-tracking
+Do not reject slow dependency extractors.
+ at end table
+
+ at 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.
+
+ at node Nested Packages
+ at subsection Nested Packages
+ at cindex Nested packages
+ at cindex Packages, nested
+ at 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.
+
+ at opindex --help=recursive
+
+The command @code{configure --help=recursive} can be used to display
+the options supported by all the included packages.
+
+ at xref{Subpackages}, for an example setup.
+
+ at node Why Autotools
+ at section How Autotools Help
+ at 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
+ at file{Makefile}s yourself).
+
+ at itemize @bullet
+ at 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.
+ at item
+Implementing these features portably is difficult and exhausting.
+Think of writing portable shell scripts, and portable
+ at file{Makefile}s, for systems you may not have handy. @xref{Portable
+Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
+convince yourself.
+ at item
+You will have to upgrade your setup to follow changes to the GNU
+Coding Standards.
+ at end itemize
+
+The GNU Autotools take all this burden off your back and provide:
+
+ at itemize @bullet
+ at item
+Tools to create a portable, complete, and self-contained GNU Build
+System, from simple instructions.
+ at emph{Self-contained} meaning the resulting build system does not
+require the GNU Autotools.
+ at item
+A central place where fixes and improvements are made:
+a bug-fix for a portability issue will benefit every package.
+ at end itemize
+
+Yet there also exist reasons why you may want NOT to use the
+Autotools at 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.
+
+ at node Hello World
+ at section A Small Hello World
+ at cindex Example Hello World
+ at cindex Hello World example
+ at 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.
+
+ at anchor{amhello Explained}
+ at menu
+* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
+* amhello's configure.ac Setup Explained::
+* amhello's Makefile.am Setup Explained::
+ at end menu
+
+ at node Creating amhello
+ at 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.
+
+ at itemize @bullet
+
+ at item
+ at 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.
+ at 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;
+@}
+ at end example
+
+ at item
+ at file{README} contains some very limited documentation for our little
+package.
+ at example
+~/amhello % @kbd{cat README}
+This is a demonstration package for GNU Automake.
+Type 'info Automake' to read the Automake manual.
+ at end example
+
+ at item
+ at file{Makefile.am} and @file{src/Makefile.am} contain Automake
+instructions for these two directories.
+
+ at 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
+ at end example
+
+ at item
+Finally, @file{configure.ac} contains Autoconf instructions to
+create the @command{configure} script.
+
+ at 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
+ at end example
+ at end itemize
+
+ at 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:
+
+ at example
+~/amhello % @kbd{autoreconf --install}
+configure.ac: installing './install-sh'
+configure.ac: installing './missing'
+configure.ac: installing './compile'
+src/Makefile.am: installing './depcomp'
+ at 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},
+ at 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},
+ at file{Makefile}, and @file{src/Makefile}. Let's do this:
+
+ at 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
+ at end example
+
+ at trindex distcheck
+ at 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:
+
+ at example
+~/amhello % @kbd{make}
+ at dots{}
+~/amhello % @kbd{src/hello}
+Hello World!
+This is amhello 1.0.
+~/amhello % @kbd{make distcheck}
+ at dots{}
+=============================================
+amhello-1.0 archives ready for distribution:
+amhello-1.0.tar.gz
+=============================================
+ at 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}.
+
+ at command{autoreconf} is a script that calls @command{autoconf},
+ at 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 have separate manuals, the important
+point to understand is that @command{autoconf} is in charge of
+creating @file{configure} from @file{configure.ac}, while
+ at command{automake} is in charge of creating @file{Makefile.in}s from
+ at file{Makefile.am}s and @file{configure.ac}. This should at least
+direct you to the right manual when seeking answers.
+
+
+ at node amhello's configure.ac Setup Explained
+ at subsection @code{amhello}'s @file{configure.ac} Setup Explained
+
+ at cindex @file{configure.ac}, Hello World
+
+Let us begin with the contents of @file{configure.ac}.
+
+ at 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
+ at end example
+
+This file is read by both @command{autoconf} (to create
+ at file{configure}) and @command{automake} (to create the various
+ at 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
+ at 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.
+
+ at opindex -Wall
+ at opindex -Werror
+ at opindex foreign
+
+The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
+ at command{automake} (@pxref{Options}). @option{-Wall} and
+ at 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
+ at 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
+ at command{configure} script to create a @file{config.h} file gathering
+ at 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:
+
+ at smallexample
+ at 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"
+ at dots{}
+ at 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,
+ at 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
+ at 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}.
+
+ at cindex @command{autoscan}
+
+When starting a new project, we suggest you start with such a simple
+ at 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
+ at command{autoscan} to Create @file{configure.ac}, autoconf, The
+Autoconf Manual}).
+
+
+ at node amhello's Makefile.am Setup Explained
+ at subsection @code{amhello}'s @file{Makefile.am} Setup Explained
+
+ at 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}.
+
+ at example
+bin_PROGRAMS = hello
+hello_SOURCES = main.c
+ at end example
+
+A @file{Makefile.am} has the same syntax as an ordinary
+ at file{Makefile}. When @command{automake} processes a
+ at file{Makefile.am} it copies the entire file into the output
+ at file{Makefile.in} (that will be later turned into @file{Makefile} by
+ at 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
+ at 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
+ at dfn{primary}; Automake recognizes other primaries such as
+ at code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
+to different types of files.
+
+The @samp{bin} part of the @code{bin_PROGRAMS} tells
+ at command{automake} that the resulting programs should be installed in
+ at 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
+ at code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
+ at command{automake} will look for another variable named
+ at 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
+ at 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
+ at file{Makefile.am}.
+
+ at example
+SUBDIRS = src
+dist_doc_DATA = README
+ at end example
+
+ at code{SUBDIRS} is a special variable listing all directories that
+ at command{make} should recurse into before processing the current
+directory. So this line is responsible for @command{make} building
+ at 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
+ at 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
+ at 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
+ at 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,
+ at pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
+
+
+ at node Generalities
+ at chapter General ideas
+
+The following sections cover a few basic ideas that will help you
+understand how Automake works.
+
+ at 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
+ at end menu
+
+
+ at node General Operation
+ at section General Operation
+
+Automake works by reading a @file{Makefile.am} and generating a
+ at file{Makefile.in}. Certain variables and rules defined in the
+ at 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.
+
+ at cindex Non-standard targets
+ at cindex @code{git-dist}, non-standard example
+ at 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
+ at code{git-dist} target, which the Automake maintainer uses to make
+distributions from the source control system.
+
+ at cindex GNU make extensions
+
+Note that most GNU make extensions are not recognized by Automake. Using
+such extensions in a @file{Makefile.am} will lead to errors or confusing
+behavior.
+
+ at cindex Append operator
+ at cmindex +=
+A special exception is that the GNU make append operator, @samp{+=}, is
+supported. This operator appends its right hand argument to the variable
+specified on the left. Automake will translate the operator into
+an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
+
+Automake tries to keep comments grouped with any adjoining rules or
+variable definitions.
+
+ at cindex Limitations of automake parser
+ at cindex Automake parser, limitations of
+ at 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.
+ at c Keep this in sync with doc-parsing-buglets-tabs.sh
+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.
+ at c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
+Also, using more complex macro in target names can cause trouble:
+
+ at example
+% @kbd{cat Makefile.am}
+$(FOO:=x): bar
+% @kbd{automake}
+Makefile.am:1: bad characters in variable name '$(FOO'
+Makefile.am:1: ':='-style assignments are not portable
+ at end example
+
+ at cindex Make targets, overriding
+ at cindex Make rules, overriding
+ at cindex Overriding make rules
+ at 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
+ at 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.
+
+ at cindex Variables, overriding
+ at cindex Overriding make variables
+
+Similarly, a variable defined in @file{Makefile.am} or
+ at 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
+ at command{automake} are considered to be for internal use only, and their
+names might change in future releases.
+
+ at cindex Recursive operation of Automake
+ at cindex Automake, recursive operation
+ at cindex Example of recursive operation
+
+When examining a variable definition, Automake will recursively examine
+variables referenced in the definition. For example, if Automake is
+looking at the content of @code{foo_SOURCES} in this snippet
+
+ at c Keep in sync with interp.sh
+ at example
+xs = a.c b.c
+foo_SOURCES = c.c $(xs)
+ at end example
+
+it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
+contents of @code{foo_SOURCES}.
+
+ at cindex @code{##} (special Automake comment)
+ at cindex Special Automake comment
+ at 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:
+
+ at cindex Makefile.am, first line
+ at cindex First line of Makefile.am
+
+ at example
+## Process this file with automake to produce Makefile.in
+ at end example
+
+ at c FIXME discuss putting a copyright into Makefile.am here? I would but
+ at c I don't know quite what to say.
+
+ at c FIXME document customary ordering of Makefile.am here!
+
+
+ at node Strictness
+ at section Strictness
+
+ at 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.
+
+ at cindex Strictness, defined
+ at cindex Strictness, @option{foreign}
+ at cindex @option{foreign} strictness
+ at cindex Strictness, @option{gnu}
+ at cindex @option{gnu} strictness
+ at cindex Strictness, @option{gnits}
+ at 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:
+
+ at table @option
+ at 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.
+
+ at item gnu
+Automake will check---as much as possible---for compliance to the GNU
+standards for packages. This is the default.
+
+ at 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).
+ at end table
+
+ at xref{Gnits}, for more information on the precise implications of the
+strictness level.
+
+
+ at node Uniform
+ at section The Uniform Naming Scheme
+
+ at 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
+ at command{configure} time determination of what should be built.
+
+ at cindex @code{_PROGRAMS} primary variable
+ at cindex @code{PROGRAMS} primary variable
+ at cindex Primary variable, @code{PROGRAMS}
+ at cindex Primary variable, defined
+ at 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.
+ at vindex PROGRAMS
+
+ at cindex @code{pkgdatadir}, defined
+ at cindex @code{pkgincludedir}, defined
+ at cindex @code{pkglibdir}, defined
+ at cindex @code{pkglibexecdir}, defined
+
+ at vindex pkgdatadir
+ at vindex pkgincludedir
+ at vindex pkglibdir
+ at vindex pkglibexecdir
+
+ at 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},
+ at code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
+non- at samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
+ at code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
+
+ at cindex @code{EXTRA_}, prepending
+For each primary, there is one additional variable named by prepending
+ at samp{EXTRA_} to the primary name. This variable is used to list
+objects that may or may not be built, depending on what
+ at 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.
+
+ at cindex @code{EXTRA_PROGRAMS}, defined
+ at cindex Example, @code{EXTRA_PROGRAMS}
+ at 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}:
+
+ at example
+EXTRA_PROGRAMS = mt rmt
+bin_PROGRAMS = cpio pax
+sbin_PROGRAMS = $(MORE_PROGRAMS)
+ at end example
+
+Defining a primary without a prefix as a variable, e.g.,
+ at 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
+ at 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.
+
+ at cindex Extending list of installation directories
+ at 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
+ at samp{$(datadir)/xml}.
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at example
+xmldir = $(datadir)/xml
+xml_DATA = file.xml
+ at 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:
+
+ at c Should be tested in primary-prefix-invalid-couples.sh
+ at example
+# Forbidden directory combinations, automake will error out on this.
+pkglib_PROGRAMS = foo
+doc_LIBRARIES = libquux.a
+ at end example
+
+ at noindent
+but it will succeed with this:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at 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
+ at 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}).
+
+ at cindex @samp{noinst_} primary prefix, definition
+ at 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.
+
+ at cindex @samp{check_} primary prefix, definition
+ at 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},
+ at samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
+ at samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
+ at samp{TEXINFOS}.
+ at vindex PROGRAMS
+ at vindex LIBRARIES
+ at vindex LTLIBRARIES
+ at vindex LISP
+ at vindex PYTHON
+ at vindex JAVA
+ at vindex SCRIPTS
+ at vindex DATA
+ at vindex HEADERS
+ at vindex MANS
+ at 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}).
+
+
+ at node Length Limitations
+ at section Staying below the command line length limit
+
+ at cindex command line length limit
+ at 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
+ at 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,
+
+ at example
+data_DATA = file1 @dots{} file at var{N} file at var{N+1} @dots{} file at var{2N}
+ at end example
+
+ at noindent
+may also be written as
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at example
+data_DATA = file1 @dots{} file at var{N}
+data2dir = $(datadir)
+data2_DATA = file at var{N+1} @dots{} file at var{2N}
+ at end example
+
+ at noindent
+and will cause Automake to treat the two lists separately during
+ at 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
+ at 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}).
+
+
+ at node Canonicalization
+ at section How derived variables are named
+
+ at cindex canonicalizing Automake variables
+
+Sometimes a Makefile variable name is derived from some text the
+maintainer supplies. For instance, a program name listed in
+ at 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
+ at samp{sniff-glue_SOURCES}. Similarly the sources for a library named
+ at file{libmumble++.a} should be listed in the
+ at samp{libmumble___a_SOURCES} variable.
+
+The strudel is an addition, to make the use of Autoconf substitutions in
+variable names less obfuscating.
+
+
+ at node User Variables
+ at section Variables reserved for the user
+
+ at cindex variables, reserved for the user
+ at 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
+ at 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
+ at 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.
+
+ at xref{Flag Variables Ordering}, for more discussion about these
+variables and how they interact with per-target variables.
+
+ at node Auxiliary Programs
+ at section Programs automake might require
+
+ at cindex Programs, auxiliary
+ at cindex Auxiliary programs
+
+Automake sometimes requires helper programs so that the generated
+ at 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.
+
+ at table @code
+ at item ar-lib
+This is a wrapper primarily for the Microsoft lib archiver, to make
+it more POSIX-like.
+
+ at 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},
+ at option{-Wl,} and @option{-Xlinker}.
+
+ at item config.guess
+ at 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
+ at url{http://savannah.gnu.org/git/?group=config} before making a
+release.
+
+ at 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}).
+
+ at item install-sh
+This is a replacement for the @command{install} program that works on
+platforms where @command{install} is unavailable or unusable.
+
+ at 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.
+
+ at 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,
+ at command{missing} will print an informative warning before failing out,
+to provide the user with more context and information.
+
+ at item mkinstalldirs
+This script used to be a wrapper around @samp{mkdir -p}, which is not
+portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
+finds that @samp{mkdir -p} does not work, this makes one less script to
+distribute.
+
+For backward compatibility @file{mkinstalldirs} is still used and
+distributed when @command{automake} finds it in a package. But it is no
+longer installed automatically, and it should be safe to remove it.
+
+ at item py-compile
+This is used to byte-compile Python scripts.
+
+ at item test-driver
+This implements the default test driver offered by the parallel
+testsuite harness.
+
+ at 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
+ at url{http://www.gnu.org/software/texinfo/}.
+
+ at item ylwrap
+This program wraps @command{lex} and @command{yacc} to rename their
+output files. It also ensures that, for instance, multiple
+ at command{yacc} instances can be invoked in a single directory in
+parallel.
+
+ at end table
+
+
+ at node Examples
+ at 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.
+
+ at menu
+* Complete:: A simple example, start to finish
+* true:: Building true and false
+ at end menu
+
+
+ at node Complete
+ at section A simple example, start to finish
+
+ at 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.
+
+ at 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
+ at code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
+
+ at example
+AC_INIT([zardoz], [1.0])
+AM_INIT_AUTOMAKE
+ at dots{}
+ at 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!
+
+ at cindex @command{aclocal} program, introduction
+ at cindex @file{aclocal.m4}, preexisting
+ at 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 at 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:
+
+ at example
+mv aclocal.m4 acinclude.m4
+aclocal
+autoconf
+ at end example
+
+ at 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,
+ at code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
+script uses @code{AC_REPLACE_FUNCS}, so you need to link against
+ at samp{$(LIBOBJS)}. So here's what you'd write:
+
+ at example
+bin_PROGRAMS = zardoz
+zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
+zardoz_LDADD = $(LIBOBJS)
+
+info_TEXINFOS = zardoz.texi
+ at end example
+
+Now you can run @samp{automake --add-missing} to generate your
+ at file{Makefile.in} and grab any auxiliary files you might need, and
+you're done!
+
+
+ at node true
+ at section Building true and false
+
+ at cindex Example, @command{false} and @command{true}
+ at cindex @command{false} Example
+ at 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
+ at file{true.c} requires different @code{cpp} flags.
+
+ at 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
+ at 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
+ at samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
+will override the Automake generated rule to build @file{true.o}.
+
+ at code{false_SOURCES} is defined to be empty---that way no implicit value
+is substituted. Because we have not listed the source of
+ at 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
+ at code{false_LDADD}.
+
+The above rules won't work if your compiler doesn't accept both
+ at option{-c} and @option{-o}. The simplest fix for this is to introduce a
+bogus dependency (to avoid problems with a parallel @command{make}):
+
+ at 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
+ at 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
+ at code{false} in real life, you would probably use per-program
+compilation flags, like so:
+
+ at c Keep in sync with specflg7.sh and specflg8.sh
+ at example
+bin_PROGRAMS = false true
+
+false_SOURCES = true.c
+false_CPPFLAGS = -DEXIT_CODE=1
+
+true_SOURCES = true.c
+true_CPPFLAGS = -DEXIT_CODE=0
+ at 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
+ at file{true-true.o}. (The name of the object files rarely matters.)
+
+ at node automake Invocation
+ at chapter Creating a @file{Makefile.in}
+ at c This node used to be named "Invoking automake". This @anchor
+ at c allows old links to still work.
+ at anchor{Invoking automake}
+
+ at cindex Multiple @file{configure.ac} files
+ at cindex Invoking @command{automake}
+ at cindex @command{automake}, invoking
+ at cindex Invocation of @command{automake}
+ at cindex @command{automake}, invocation
+
+To create all the @file{Makefile.in}s for a package, run the
+ at 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};
+ at 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
+ at file{configure.ac}, at the top. If your package has multiple
+ at 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
+ at 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.
+
+ at 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:
+ at command{automake} runs @command{autoconf} to @strong{scan} your
+ at file{configure.ac}, this won't build @file{configure} and you still
+have to run @command{autoconf} yourself for this purpose.
+
+ at cindex @command{automake} options
+ at cindex Options, @command{automake}
+ at cindex Strictness, command line
+
+ at command{automake} accepts the following options:
+
+ at cindex Extra files distributed with Automake
+ at cindex Files distributed with Automake
+ at cindex @file{config.guess}
+
+ at table @code
+ at item -a
+ at itemx --add-missing
+ at opindex -a
+ at 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
+ at 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.
+
+ at item --libdir=@var{dir}
+ at opindex --libdir
+Look for Automake data files in directory @var{dir} instead of in the
+installation directory. This is typically used for debugging.
+
+ at item --print-libdir
+ at opindex --print-libdir
+Print the path of the installation directory containing Automake-provided
+scripts and data files (like e.g., @file{texinfo.texi} and
+ at file{install-sh}).
+
+ at item -c
+ at opindex -c
+ at itemx --copy
+ at opindex --copy
+When used with @option{--add-missing}, causes installed files to be
+copied. The default is to make a symbolic link.
+
+ at item -f
+ at opindex -f
+ at itemx --force-missing
+ at 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
+ at option{--copy}, copying the new file).
+
+ at item --foreign
+ at opindex --foreign
+Set the global strictness to @option{foreign}. For more information, see
+ at ref{Strictness}.
+
+ at item --gnits
+ at opindex --gnits
+Set the global strictness to @option{gnits}. For more information, see
+ at ref{Gnits}.
+
+ at item --gnu
+ at opindex --gnu
+Set the global strictness to @option{gnu}. For more information, see
+ at ref{Gnits}. This is the default strictness.
+
+ at item --help
+ at opindex --help
+Print a summary of the command line options and exit.
+
+ at item -i
+ at itemx --ignore-deps
+ at opindex -i
+This disables the dependency tracking feature in generated
+ at file{Makefile}s; see @ref{Dependencies}.
+
+ at item --include-deps
+ at 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.
+
+ at item --no-force
+ at opindex --no-force
+Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
+ at file{configure.ac}. This option causes it to only update those
+ at file{Makefile.in}s that are out of date with respect to one of their
+dependents.
+
+ at item -o @var{dir}
+ at itemx --output-dir=@var{dir}
+ at opindex -o
+ at 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.
+
+ at item -v
+ at itemx --verbose
+ at opindex -v
+ at opindex --verbose
+Cause Automake to print information about which files are being read or
+created.
+
+ at item --version
+ at opindex --version
+Print the version number of Automake and exit.
+
+ at item -W CATEGORY
+ at itemx --warnings=@var{category}
+ at opindex -W
+ at opindex --warnings
+Output warnings falling in @var{category}. @var{category} can be
+one of:
+ at table @code
+ at item gnu
+warnings related to the GNU Coding Standards
+(@pxref{Top, , , standards, The GNU Coding Standards}).
+ at item obsolete
+obsolete features or constructions
+ at item override
+user redefinitions of Automake rules or variables
+ at item portability
+portability issues (e.g., use of @command{make} features that are
+known to be not portable)
+ at item extra-portability
+extra portability issues related to obscure tools. One example of such
+a tool is the Microsoft @command{lib} archiver.
+ at item syntax
+weird syntax, unused variables, typos
+ at item unsupported
+unsupported or incomplete features
+ at item all
+all the warnings
+ at item none
+turn off all the warnings
+ at item error
+treat warnings as errors
+ at 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{obsolete}, @samp{syntax} and
+ at samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
+are enabled in @option{--gnu} and @option{--gnits} strictness.
+
+ at 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
+ at samp{portability}. However, turning on @samp{portability} or turning
+off @samp{extra-portability} will not affect the other category.
+
+ at 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.
+
+ at end table
+
+ at vindex AUTOMAKE_JOBS
+If the environment variable @env{AUTOMAKE_JOBS} contains a positive
+number, it is taken as the maximum number of Perl threads to use in
+ at command{automake} for generating multiple @file{Makefile.in} files
+concurrently. This is an experimental feature.
+
+
+ at node configure
+ at chapter Scanning @file{configure.ac}, using @command{aclocal}
+
+ at cindex @file{configure.ac}, scanning
+ at cindex Scanning @file{configure.ac}
+ at cindex Using @command{aclocal}
+ at 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
+ at file{aclocal.m4} using the @command{aclocal} program.
+
+ at menu
+* Requirements:: Configuration requirements
+* Optional:: Other things Automake recognizes
+* aclocal Invocation:: Auto-generating aclocal.m4
+* Macros:: Autoconf macros supplied with Automake
+ at end menu
+
+
+ at node Requirements
+ at section Configuration requirements
+
+ at cindex Automake requirements
+ at cindex Requirements of Automake
+
+ at 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}:
+
+ at table @code
+ at item AC_CONFIG_FILES
+ at itemx AC_OUTPUT
+ at acindex AC_CONFIG_FILES
+ at acindex AC_OUTPUT
+These two macros are usually invoked as follows near the end of
+ at file{configure.ac}.
+
+ at example
+ at dots{}
+AC_CONFIG_FILES([
+ Makefile
+ doc/Makefile
+ src/Makefile
+ src/lib/Makefile
+ @dots{}
+])
+AC_OUTPUT
+ at 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
+
+ at example
+AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
+ at end example
+
+ at noindent
+ at 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
+ at 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,
+ at command{automake} will not be able to fulfill this setup, and you will
+have to complete the missing bits by hand. For instance, on
+
+ at c Keep in sync with output11.sh
+ at example
+file=input
+ at dots{}
+AC_CONFIG_FILES([output:$file],, [file=$file])
+ at end example
+
+ at noindent
+ at 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
+ at samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
+source file.)
+
+Similarly
+
+ at c Keep in sync with output11.sh
+ at example
+file=output
+file2=out:in
+ at dots{}
+AC_CONFIG_FILES([$file:input],, [file=$file])
+AC_CONFIG_FILES([$file2],, [file2=$file2])
+ at end example
+
+ at 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
+ at code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
+ at file{Makefile}, then @command{automake} will be able to use
+ at samp{$@{file@}} to generate all of these rules. For instance, here is
+how the Automake package itself generates versioned scripts for its
+test suite:
+
+ at example
+AC_SUBST([APIVERSION], @dots{})
+ at 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@}])
+ at end example
+
+ at 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
+ at file{Makefile} files for which @command{automake} must create
+ at file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
+ at 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
+ at code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
+(@pxref{Optional}).
+
+To summarize:
+ at itemize @bullet
+ at item
+Use literals for @file{Makefile}s, and for other files whenever possible.
+ at item
+Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
+for files that @command{automake} should ignore.
+ at item
+Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
+that @command{automake} should not ignore.
+ at end itemize
+
+ at end table
+
+
+ at node Optional
+ at section Other things Automake recognizes
+
+ at cindex Macros Automake recognizes
+ at cindex Recognized macros by Automake
+
+Every time Automake is run it calls Autoconf to trace
+ at 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:
+
+ at ftable @code
+ at item AC_CANONICAL_BUILD
+ at itemx AC_CANONICAL_HOST
+ at itemx AC_CANONICAL_TARGET
+ at vindex build_triplet
+ at vindex host_triplet
+ at vindex target_triplet
+Automake will ensure that @file{config.guess} and @file{config.sub}
+exist. Also, the @file{Makefile} variables @code{build_triplet},
+ at code{host_triplet} and @code{target_triplet} are introduced. See
+ at ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
+The Autoconf Manual}.
+
+ at item AC_CONFIG_AUX_DIR
+Automake will look for various helper scripts, such as
+ at file{install-sh}, in the directory named in this macro invocation.
+ at c This list is accurate relative to version 1.11
+(The full list of scripts is:
+ at file{ar-lib},
+ at file{config.guess},
+ at file{config.sub},
+ at file{depcomp},
+ at file{compile},
+ at file{install-sh},
+ at file{ltmain.sh},
+ at file{mdate-sh},
+ at file{missing},
+ at file{mkinstalldirs},
+ at file{py-compile},
+ at file{test-driver},
+ at file{texinfo.tex},
+ at 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},
+ at 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.
+
+ at item AC_CONFIG_LIBOBJ_DIR
+Automake will require the sources file declared with
+ at code{AC_LIBSOURCE} (see below) in the directory specified by this
+macro.
+
+ at item AC_CONFIG_HEADERS
+Automake will generate rules to rebuild these headers from the
+corresponding templates (usually, the template for a @file{foo.h}
+header being @file{foo.h.in}). 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.
+
+ at 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.)
+
+ at item AC_LIBOBJ
+ at itemx AC_LIBSOURCE
+ at itemx AC_LIBSOURCES
+ at vindex LIBOBJS
+Automake will automatically distribute any file listed in
+ at 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
+ at file{file.c} will be distributed automatically by Automake. This
+encompasses many macros like @code{AC_FUNC_ALLOCA},
+ at 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.
+ at xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
+autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_RANLIB
+This is required if any libraries are built in the package.
+ at xref{Particular Programs, , Particular Program Checks, autoconf, The
+Autoconf Manual}.
+
+ at item AC_PROG_CXX
+This is required if any C++ source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_OBJC
+This is required if any Objective C source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_OBJCXX
+This is required if any Objective C++ source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at item AC_PROG_F77
+This is required if any Fortran 77 source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
+ at 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}.
+
+ at 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}).
+
+ at 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}.
+
+ at item AC_PROG_LIBTOOL
+Automake will turn on processing for @command{libtool} (@pxref{Top, ,
+Introduction, libtool, The Libtool Manual}).
+
+ at item AC_PROG_YACC
+ at 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}).
+
+ at item AC_PROG_LEX
+If a Lex source file is seen, then this macro must be used.
+ at xref{Particular Programs, , Particular Program Checks, autoconf, The
+Autoconf Manual}.
+
+ at item AC_REQUIRE_AUX_FILE
+For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
+ at 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}.
+
+ at 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
+ at code{X_LIBS}. Thus, you can access these variables as
+ at code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
+if @code{AC_PATH_XTRA} is called.
+
+ at item AM_CONDITIONAL
+This introduces an Automake conditional (@pxref{Conditionals}).
+
+ at item AM_COND_IF
+This macro allows @code{automake} to detect subsequent access within
+ at file{configure.ac} to a conditional previously introduced with
+ at code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
+(@pxref{Usage of Conditionals}).
+
+ at 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.
+
+ at 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}.
+
+ at item AM_MAINTAINER_MODE(@ovar{default-mode})
+ at opindex --enable-maintainer-mode
+ at opindex --disable-maintainer-mode
+This macro adds an @option{--enable-maintainer-mode} option to
+ at command{configure}. If this is used, @command{automake} will cause
+``maintainer-only'' rules to be turned off by default in the
+generated @file{Makefile.in}s, unless @var{default-mode} is
+ at samp{enable}. This macro defines the @code{MAINTAINER_MODE}
+conditional, which you can use in your own @file{Makefile.am}.
+ at xref{maintainer-mode}.
+
+ at 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
+ at 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.
+
+ at 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.
+
+ at 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}).
+
+ at end ftable
+
+ at node aclocal Invocation
+ at section Auto-generating aclocal.m4
+ at c This node used to be named "Invoking automake". This @anchor
+ at c allows old links to still work.
+ at anchor{Invoking aclocal}
+
+ at cindex Invocation of @command{aclocal}
+ at cindex @command{aclocal}, Invocation
+ at cindex Invoking @command{aclocal}
+ at 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
+ at file{aclocal.m4}; otherwise they will not be seen by
+ at command{autoconf}.
+
+The @command{aclocal} program will automatically generate
+ at 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}.
+
+ at emph{Putting} the file that contains the macro definition into
+ at file{aclocal.m4} is usually done by copying the entire text of this
+file, including unused macro definitions as well as both @samp{#} and
+ at 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
+ at 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}).
+
+ at vindex AUTOM4TE
+ at cindex autom4te
+While computing @file{aclocal.m4}, @command{aclocal} runs
+ at 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
+ at env{PATH}, just as @command{autoconf}. Its location can be
+overridden using the @env{AUTOM4TE} environment variable.
+
+ at 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
+ at end menu
+
+ at node aclocal Options
+ at subsection aclocal Options
+
+ at cindex @command{aclocal}, Options
+ at cindex Options, @command{aclocal}
+
+ at command{aclocal} accepts the following options:
+
+ at table @code
+ at item --automake-acdir=@var{dir}
+ at 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.
+
+ at item --system-acdir=@var{dir}
+ at opindex --system-acdir
+Look for the system-wide third-party macro files (and the special
+ at file{dirlist} file) in @var{dir} instead of in the installation
+directory. This is typically used for debugging.
+
+ at item --diff[=@var{command}]
+ at 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}.
+
+ at item --dry-run
+ at opindex --dry-run
+Do not actually overwrite (or create) @file{aclocal.m4} and M4
+files installed by @option{--install}.
+
+ at item --help
+ at opindex --help
+Print a summary of the command line options and exit.
+
+ at item -I @var{dir}
+ at opindex -I
+Add the directory @var{dir} to the list of directories searched for
+ at file{.m4} files.
+
+ at item --install
+ at 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.
+ at c Keep in sync with aclocal-install-absdir.sh
+Note that this will happen also if @var{dir} is an absolute path.
+
+ at cindex serial number and @option{--install}
+When this option is used, and only when this option is used,
+ at 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}).
+
+ at item --force
+ at 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
+ at option{--install}.
+
+ at item --output=@var{file}
+ at opindex --output
+Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
+
+ at item --print-ac-dir
+ at 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
+ at 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}.
+
+ at item --verbose
+ at opindex --verbose
+Print the names of the files it examines.
+
+ at item --version
+ at opindex --version
+Print the version number of Automake and exit.
+
+ at item -W CATEGORY
+ at item --warnings=@var{category}
+ at opindex -W
+ at opindex --warnings
+Output warnings falling in @var{category}. @var{category} can be
+one of:
+ at table @code
+ at item syntax
+dubious syntactic constructs, underquoted macros, unused macros, etc.
+ at item unsupported
+unknown macros
+ at item all
+all the warnings, this is the default
+ at item none
+turn off all the warnings
+ at item error
+treat warnings as errors
+ at end table
+
+All warnings are output by default.
+
+ at vindex WARNINGS
+The environment variable @env{WARNINGS} is honored in the same
+way as it is for @command{automake} (@pxref{automake Invocation}).
+
+ at end table
+
+ at node Macro Search Path
+ at subsection Macro Search Path
+
+ at cindex Macro search path
+ at cindex @command{aclocal} search path
+
+By default, @command{aclocal} searches for @file{.m4} files in the following
+directories, in this order:
+
+ at table @code
+ at 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}.
+
+ at item @var{acdir}
+This directory is intended for third party @file{.m4} files, and is
+configured when @command{automake} itself is built. This is
+ at 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}).
+ at end table
+
+As an example, suppose that @command{automake-1.11.2} was configured with
+ at option{--prefix=@-/usr/local}. Then, the search path would be:
+
+ at enumerate
+ at item @file{/usr/local/share/aclocal-1.11.2/}
+ at item @file{/usr/local/share/aclocal/}
+ at 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.
+
+ at 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,
+ at samp{aclocal -I /foo -I /bar} results in the following search path:
+
+ at enumerate
+ at item @file{/foo}
+ at item @file{/bar}
+ at item @var{acdir}- at var{APIVERSION}
+ at item @var{acdir}
+ at end enumerate
+
+ at subsubheading Modifying the Macro Search Path: @file{dirlist}
+ at cindex @file{dirlist}
+
+There is a third mechanism for customizing the search path. If a
+ at 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
+ at file{@var{acdir}/dirlist} contains the following:
+
+ at example
+/test1
+/test2
+/test3*
+ at end example
+
+ at noindent
+and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
+Then, the search path would be
+
+ at c @code looks better than @file here
+ at enumerate
+ at item @code{/foo}
+ at item @code{/bar}
+ at item @var{acdir}- at var{APIVERSION}
+ at item @var{acdir}
+ at item @code{/test1}
+ at item @code{/test2}
+ at end enumerate
+
+ at noindent
+and all directories with path names starting with @code{/test3}.
+
+If the @option{--system-acdir=@var{dir}} option is used, then
+ at command{aclocal} will search for the @file{dirlist} file in
+ at var{dir}; but remember the warnings above against the use of
+ at option{--system-acdir}.
+
+ at file{dirlist} is useful in the following situation: suppose that
+ at command{automake} version @code{1.11.2} is installed with
+ at samp{--prefix=/usr} by the system vendor. Thus, the default search
+directories are
+
+ at c @code looks better than @file here
+ at enumerate
+ at item @code{/usr/share/aclocal-1.11/}
+ at item @code{/usr/share/aclocal/}
+ at 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
+ at file{/usr/local/share/aclocal}. The only way to force
+ at 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
+ at file{/usr/share/aclocal/dirlist} containing only the single line
+
+ at example
+/usr/local/share/aclocal
+ at end example
+
+Now, the ``default'' search path on the affected system is
+
+ at c @code looks better than @file here
+ at enumerate
+ at item @code{/usr/share/aclocal-1.11/}
+ at item @code{/usr/share/aclocal/}
+ at item @code{/usr/local/share/aclocal/}
+ at 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.
+
+ at anchor{ACLOCAL_PATH}
+ at subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
+ at 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
+ at c Keep in sync with aclocal-path-precedence.sh
+and takes precedence over system directories (including those found via
+ at file{dirlist}), with the exception of the versioned directory
+ at var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
+passed via @option{-I} will take precedence over directories in
+ at env{ACLOCAL_PATH}.
+
+ at 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
+ at env{ACLOCAL_PATH} will be installed locally.
+ at c Keep in sync with aclocal-path-installed-serial.sh
+In this case, serial numbers in @file{.m4} are honoured too,
+ at 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.
+
+ at 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!}
+
+ at node Extending aclocal
+ at subsection Writing your own aclocal macros
+
+ at cindex @command{aclocal}, extending
+ at 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:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at example
+aclocaldir = $(datadir)/aclocal
+aclocal_DATA = mymacro.m4 myothermacro.m4
+ at end example
+
+ at 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
+ at env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
+ at command{aclocal} will find the @file{.m4} files installed by your
+package automatically.
+
+A file of macros should be a series of properly quoted
+ at code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
+Autoconf Manual}). The @command{aclocal} programs also understands
+ at 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.
+
+ at cindex underquoted @code{AC_DEFUN}
+ at acindex AC_DEFUN
+ at 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
+ at 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,
+
+ at example
+# bad style
+AC_PREREQ(2.68)
+AC_DEFUN(AX_FOOBAR,
+[AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
+ at end example
+
+ at noindent
+should be rewritten as
+
+ at example
+AC_DEFUN([AX_FOOBAR],
+[AC_PREREQ([2.68])dnl
+AC_REQUIRE([AX_SOMETHING])dnl
+AX_FOO
+AX_BAR
+])
+ at 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}.
+
+ at node Local Macros
+ at 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
+ at 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
+ at file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIRS}:
+
+ at example
+AC_CONFIG_MACRO_DIRS([m4])
+ at end example
+
+ at 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
+ at 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
+ at 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
+ at 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
+ at 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
+
+ at example
+#serial @var{nnn}
+ at end example
+
+ at 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.
+
+
+ at node Serials
+ at subsection Serial Numbers
+ at cindex serial numbers in macros
+ at cindex macro serial numbers
+ at cindex @code{#serial} syntax
+ at 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
+
+ at example
+# serial @var{version}
+ at end example
+
+ at 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
+
+ at example
+#serial @var{version} @var{garbage}
+ at end example
+
+Normally these serial numbers are completely ignored by
+ at 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
+ at 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
+ at file{/usr/share/aclocal/thirdparty.m4} as follows:
+
+ at example
+# serial 1
+AC_DEFUN([AX_THIRD_PARTY], [...])
+ at end example
+
+MyPackage uses an @file{m4/} directory to store local macros as
+explained in @ref{Local Macros}, and has
+
+ at example
+AC_CONFIG_MACRO_DIRS([m4])
+ at end example
+
+ at noindent
+in its @file{configure.ac}.
+
+Initially the @file{m4/} directory is empty. The first time we run
+ at command{aclocal --install}, it will notice that
+
+ at itemize @bullet
+ at item
+ at file{configure.ac} uses @code{AX_THIRD_PARTY}
+ at item
+No local macros define @code{AX_THIRD_PARTY}
+ at item
+ at file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at end itemize
+
+ at 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
+ at 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
+
+ at itemize @bullet
+ at item
+ at file{configure.ac} uses @code{AX_THIRD_PARTY}
+ at item
+ at file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at item
+ at file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at end itemize
+
+ at 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
+ at file{/usr/share/aclocal/thirdparty.m4} and outputs an
+ at 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:
+
+ at itemize @bullet
+ at item
+ at file{configure.ac} uses @code{AX_THIRD_PARTY}
+ at item
+ at file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 1.
+ at item
+ at file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
+with serial 2.
+ at end itemize
+
+ at 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
+ at file{/usr/share/aclocal/thirdparty.m4} with serial 2,
+ at command{aclocal} will proceed as if it had never seen
+ at 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
+ at 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
+ at 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}.
+
+
+ at node Future of aclocal
+ at subsection The Future of @command{aclocal}
+ at cindex @command{aclocal}'s scheduled death
+
+ at 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
+ at 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
+ at 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
+ at 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
+ at file{autogen.sh}, that will just call @command{aclocal},
+ at command{libtoolize}, @command{gettextize} or @command{autopoint},
+ at 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
+ at 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}).
+
+
+
+ at node Macros
+ at section Autoconf macros supplied with Automake
+
+Automake ships with several Autoconf macros that you can use from your
+ at file{configure.ac}. When you use one of them it will be included by
+ at command{aclocal} in @file{aclocal.m4}.
+
+ at menu
+* Public Macros:: Macros that you can use.
+* Obsolete Macros:: Macros that will soon be removed.
+* Private Macros:: Macros that you should not use.
+ at end menu
+
+ at c consider generating the following subsections automatically from m4 files.
+
+ at node Public Macros
+ at subsection Public Macros
+
+ at table @code
+
+ at item AM_INIT_AUTOMAKE([OPTIONS])
+ at acindex AM_INIT_AUTOMAKE
+Runs many macros required for proper operation of the generated Makefiles.
+
+ at vindex AUTOMAKE_OPTIONS
+Today, @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}).
+
+ at acindex AC_INIT
+This macro can also be called in another, @emph{deprecated} form:
+ at code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
+there are two required arguments: the package and the version number.
+This usage is mostly obsolete because the @var{package} and @var{version}
+can be obtained from Autoconf's @code{AC_INIT} macro. However,
+differently from what happens for @code{AC_INIT} invocations, this
+ at code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions
+in the @code{PACKAGE} and @code{VERSION} arguments, and this can be
+still be useful in some selected situations. Our hope is that future
+Autoconf versions will improve their support for package versions
+defined dynamically at configure runtime; when (and if) this happens,
+support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely
+be removed from Automake.
+
+ at anchor{Modernize AM_INIT_AUTOMAKE invocation}
+If your @file{configure.ac} has:
+
+ at example
+AC_INIT([src/foo.c])
+AM_INIT_AUTOMAKE([mumble], [1.5])
+ at end example
+
+ at noindent
+you should modernize it as follows:
+
+ at example
+AC_INIT([mumble], [1.5])
+AC_CONFIG_SRCDIR([src/foo.c])
+AM_INIT_AUTOMAKE
+ at 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
+ at code{AC_INIT}, as in the example above. The first argument to
+ at 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).
+
+ at cindex @code{PACKAGE}, prevent definition
+ at cindex @code{VERSION}, prevent definition
+ at opindex no-define
+By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
+ at code{VERSION}. This can be avoided by passing the @option{no-define}
+option (@pxref{List of Automake options}):
+ at example
+AM_INIT_AUTOMAKE([no-define ...])
+ at end example
+
+ at item AM_PATH_LISPDIR
+ at acindex AM_PATH_LISPDIR
+ at vindex EMACS
+ at 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
+ at command{configure} to explicitly set the correct path (if you're sure
+you have an @command{emacs} that supports Emacs Lisp).
+
+ at item AM_PROG_AR(@ovar{act-if-fail})
+ at acindex AM_PROG_AR
+ at 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.
+
+ at item AM_PROG_AS
+ at acindex AM_PROG_AS
+ at vindex CCAS
+ at 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
+ at code{CCAS}, and will also set @code{CCASFLAGS} if required.
+
+ at item AM_PROG_CC_C_O
+ at acindex AM_PROG_CC_C_O
+This is an obsolescent macro that checks that the C compiler supports
+the @option{-c} and @option{-o} options together. Note that, since
+Automake 1.14, the @code{AC_PROG_CC} is rewritten to implement such
+checks itself, and thus the explicit use of @code{AM_PROG_CC_C_O}
+should no longer be required.
+
+ at item AM_PROG_LEX
+ at acindex AM_PROG_LEX
+ at acindex AC_PROG_LEX
+ at cindex HP-UX 10, @command{lex} problems
+ at 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
+ at command{missing} script on systems that do not have @command{lex}.
+HP-UX 10 is one such system.
+
+ at item AM_PROG_GCJ
+ at acindex AM_PROG_GCJ
+ at vindex GCJ
+ at vindex GCJFLAGS
+This macro finds the @command{gcj} program or causes an error. It sets
+ at code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
+GNU Compiler Collection.
+
+ at item AM_PROG_UPC([@var{compiler-search-list}])
+ at acindex AM_PROG_UPC
+ at 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.
+
+ at item AM_MISSING_PROG(@var{name}, @var{program})
+ at acindex AM_MISSING_PROG
+ at 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-mode}, for more information on when
+the @command{missing} script is appropriate.
+
+ at item AM_SILENT_RULES
+ at acindex AM_SILENT_RULES
+Control the machinery for less verbose build output
+(@pxref{Automake Silent Rules}).
+
+ at item AM_WITH_DMALLOC
+ at acindex AM_WITH_DMALLOC
+ at cindex @command{dmalloc}, support for
+ at vindex WITH_DMALLOC
+ at 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}.
+
+ at end table
+
+
+ at node Obsolete Macros
+ at subsection Obsolete Macros
+ at cindex obsolete macros
+ at cindex autoupdate
+
+Although using some of the following macros was required in past
+releases, you should not use any of them in new code. @emph{All
+these macros will be removed in the next major Automake version};
+if you are still using them, running @command{autoupdate} should
+adjust your @file{configure.ac} automatically (@pxref{autoupdate
+Invocation, , Using @command{autoupdate} to Modernize
+ at file{configure.ac}, autoconf, The Autoconf Manual}).
+ at emph{Do it NOW!}
+
+ at table @code
+
+ at item AM_PROG_MKDIR_P
+ at acindex AM_PROG_MKDIR_P
+ at cindex @code{mkdir -p}, macro check
+ at vindex MKDIR_P
+ at vindex mkdir_p
+
+From Automake 1.8 to 1.9.6 this macro used to define the output
+variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
+-d}, or @code{mkinstalldirs}.
+
+Nowadays Autoconf provides a similar functionality with
+ at code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}), however this defines
+the output variable @code{MKDIR_P} instead. In case you are still
+using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
+or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
+you are advised to switch ASAP to the more modern Autoconf-provided
+interface instead; both the macro and the variable might be removed
+in a future major Automake release.
+
+ at end table
+
+
+ at node Private Macros
+ at 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!
+
+ at ftable @code
+ at item _AM_DEPENDENCIES
+ at itemx AM_SET_DEPDIR
+ at itemx AM_DEP_TRACK
+ at itemx AM_OUTPUT_DEPENDENCY_COMMANDS
+These macros are used to implement Automake's automatic dependency
+tracking scheme. They are called automatically by Automake when
+required, and there should be no need to invoke them manually.
+
+ at item AM_MAKE_INCLUDE
+This macro is used to discover how the user's @command{make} handles
+ at code{include} statements. This macro is automatically invoked when
+needed; there should be no need to invoke it manually.
+
+ at 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.
+
+ at 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}.
+
+ at end ftable
+
+
+ at node Directories
+ at 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.
+
+ at menu
+* Subdirectories:: Building subdirectories recursively
+* Conditional Subdirectories:: Conditionally not building directories
+* Alternative:: Subdirectories without recursion
+* Subpackages:: Nesting packages
+ at end menu
+
+ at node Subdirectories
+ at section Recursing subdirectories
+
+ at 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.
+ at 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
+ at 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:
+
+ at example
+EXTRA_DIST = BUGS ChangeLog.O README-alpha
+SUBDIRS = doc intl po src tests
+ at end example
+
+When Automake invokes @command{make} in a subdirectory, it uses the value
+of the @code{MAKE} variable. It passes the value of the variable
+ at code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
+ at file{Makefile.am} if there are flags you must always pass to
+ at command{make}.
+ at vindex MAKE
+ at vindex AM_MAKEFLAGS
+
+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
+
+ at example
+SUBDIRS = lib src . test
+ at end example
+
+ at 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.
+
+ at 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.
+ at end example
+
+ at node Conditional Subdirectories
+ at section Conditional Subdirectories
+ at cindex Subdirectories, building conditionally
+ at cindex Conditional subdirectories
+ at cindex @code{SUBDIRS}, conditional
+ at 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
+ at 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
+ at 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}.
+
+ at 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}
+ at end menu
+
+ at node SUBDIRS vs DIST_SUBDIRS
+ at subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
+ at cindex @code{DIST_SUBDIRS}, explained
+
+Automake considers two sets of directories, defined by the variables
+ at code{SUBDIRS} and @code{DIST_SUBDIRS}.
+
+ at 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.
+
+ at 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
+ at file{opt/}, but yet we want to distribute it? This is where
+ at code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
+ at code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
+
+Precisely, @code{DIST_SUBDIRS} is used by @samp{make
+maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
+other recursive rules use @code{SUBDIRS}.
+
+If @code{SUBDIRS} is defined conditionally using Automake
+conditionals, Automake will define @code{DIST_SUBDIRS} automatically
+from the possible values of @code{SUBDIRS} in all conditions.
+
+If @code{SUBDIRS} contains @code{AC_SUBST} variables,
+ at code{DIST_SUBDIRS} will not be defined correctly because Automake
+does not know the possible values of these variables. In this case
+ at code{DIST_SUBDIRS} needs to be defined manually.
+
+ at node Subdirectories with AM_CONDITIONAL
+ at subsection Subdirectories with @code{AM_CONDITIONAL}
+ at cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
+ at cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
+
+ at c Keep in sync with subdir-am-cond.sh
+
+ at file{configure} should output the @file{Makefile} for each directory
+and define a condition into which @file{opt/} should be built.
+
+ at example
+ at dots{}
+AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
+AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
+ at dots{}
+ at end example
+
+Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
+as follows.
+
+ at example
+if COND_OPT
+ MAYBE_OPT = opt
+endif
+SUBDIRS = src $(MAYBE_OPT)
+ at end example
+
+As you can see, running @command{make} will rightly recurse into
+ at file{src/} and maybe @file{opt/}.
+
+ at vindex DIST_SUBDIRS
+As you can't see, running @samp{make dist} will recurse into both
+ at file{src/} and @file{opt/} directories because @samp{make dist}, unlike
+ at samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
+ at code{DIST_SUBDIRS} variable.
+
+In this case Automake will define @samp{DIST_SUBDIRS = src opt}
+automatically because it knows that @code{MAYBE_OPT} can contain
+ at samp{opt} in some condition.
+
+ at node Subdirectories with AC_SUBST
+ at subsection Subdirectories with @code{AC_SUBST}
+ at cindex @code{SUBDIRS} and @code{AC_SUBST}
+ at cindex @code{AC_SUBST} and @code{SUBDIRS}
+
+ at c Keep in sync with subdir-ac-subst.sh
+
+Another possibility is to define @code{MAYBE_OPT} from
+ at file{./configure} using @code{AC_SUBST}:
+
+ at example
+ at dots{}
+if test "$want_opt" = yes; then
+ MAYBE_OPT=opt
+else
+ MAYBE_OPT=
+fi
+AC_SUBST([MAYBE_OPT])
+AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
+ at dots{}
+ at end example
+
+In this case the top-level @file{Makefile.am} should look as follows.
+
+ at example
+SUBDIRS = src $(MAYBE_OPT)
+DIST_SUBDIRS = src opt
+ at end example
+
+The drawback is that since Automake cannot guess what the possible
+values of @code{MAYBE_OPT} are, it is necessary to define
+ at code{DIST_SUBDIRS}.
+
+ at node Unconfigured Subdirectories
+ at subsection Unconfigured Subdirectories
+ at cindex Subdirectories, configured conditionally
+
+The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
+users that try to @emph{configure and build} subdirectories
+conditionally. Here by configuring we mean creating the
+ at file{Makefile} (it might also involve running a nested
+ at command{configure} script: this is a costly operation that explains
+why people want to do it conditionally, but only the @file{Makefile}
+is relevant to the discussion).
+
+The above examples all assume that every @file{Makefile} is created,
+even in directories that are not going to be built. The simple reason
+is that we want @samp{make dist} to distribute even the directories
+that are not being built (e.g., platform-dependent code), hence
+ at file{make dist} must recurse into the subdirectory, hence this
+directory must be configured and appear in @code{DIST_SUBDIRS}.
+
+Building packages that do not configure every subdirectory is a tricky
+business, and we do not recommend it to the novice as it is easy to
+produce an incomplete tarball by mistake. We will not discuss this
+topic in depth here, yet for the adventurous here are a few rules to
+remember.
+
+ at cartouche
+ at itemize
+ at item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
+
+It makes little sense to have a directory in @code{SUBDIRS} that
+is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
+which directories listed in the latter should be built.
+ at item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
+must be configured.
+
+I.e., the @file{Makefile} must exists or the recursive @command{make}
+rules will not be able to process the directory.
+ at item Any configured directory must be listed in @code{DIST_SUBDIRS}.
+
+So that the cleaning rules remove the generated @file{Makefile}s.
+It would be correct to see @code{DIST_SUBDIRS} as a variable that
+lists all the directories that have been configured.
+ at end itemize
+ at end cartouche
+
+In order to prevent recursion in some unconfigured directory you
+must therefore ensure that this directory does not appear in
+ at code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
+ at code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
+ at code{DIST_SUBDIRS} explicitly, it will be default to
+ at samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
+= $(SUBDIRS)}.
+
+Of course, directories that are omitted from @code{DIST_SUBDIRS} will
+not be distributed unless you make other arrangements for this to
+happen (for instance, always running @samp{make dist} in a
+configuration where all directories are known to appear in
+ at code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
+distribute these directories).
+
+ at cindex Subdirectories, not distributed
+In few packages, unconfigured directories are not even expected to
+be distributed. Although these packages do not require the
+aforementioned extra arrangements, there is another pitfall. If the
+name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
+ at command{automake} will make sure the directory exists. Consequently
+ at command{automake} cannot be run on such a distribution when one
+directory has been omitted. One way to avoid this check is to use the
+ at code{AC_SUBST} method to declare conditional directories; since
+ at command{automake} does not know the values of @code{AC_SUBST}
+variables it cannot ensure the corresponding directory exists.
+
+ at node Alternative
+ at section An Alternative Approach to Subdirectories
+
+If you've ever read Peter Miller's excellent paper,
+ at uref{http://miller.emu.id.au/pmiller/books/rmch/,
+Recursive Make Considered Harmful}, the preceding sections on the use of
+make recursion will probably come as unwelcome advice. For those who
+haven't read the paper, Miller's main thesis is that recursive
+ at command{make} invocations are both slow and error-prone.
+
+Automake provides sufficient cross-directory support @footnote{We
+believe. This work is new and there are probably warts.
+ at xref{Introduction}, for information on reporting bugs.} to enable you
+to write a single @file{Makefile.am} for a complex multi-directory
+package.
+
+By default an installable file specified in a subdirectory will have its
+directory name stripped before installation. For instance, in this
+example, the header file will be installed as
+ at file{$(includedir)/stdio.h}:
+
+ at example
+include_HEADERS = inc/stdio.h
+ at end example
+
+ at vindex nobase_
+ at cindex @code{nobase_} prefix
+ at cindex Path stripping, avoiding
+ at cindex Avoiding path stripping
+
+However, the @samp{nobase_} prefix can be used to circumvent this path
+stripping. In this example, the header file will be installed as
+ at file{$(includedir)/sys/types.h}:
+
+ at example
+nobase_include_HEADERS = sys/types.h
+ at end example
+
+ at cindex @code{nobase_} and @code{dist_} or @code{nodist_}
+ at cindex @code{dist_} and @code{nobase_}
+ at cindex @code{nodist_} and @code{nobase_}
+ at vindex dist_
+ at vindex nodist_
+
+ at samp{nobase_} should be specified first when used in conjunction with
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
+
+ at example
+nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
+ at end example
+
+Finally, note that a variable using the @samp{nobase_} prefix can
+often be replaced by several variables, one for each destination
+directory (@pxref{Uniform}). For instance, the last example could be
+rewritten as follows:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at example
+imagesdir = $(pkgdatadir)/images
+soundsdir = $(pkgdatadir)/sounds
+dist_images_DATA = images/vortex.pgm
+dist_sounds_DATA = sounds/whirl.ogg
+ at end example
+
+ at noindent
+This latter syntax makes it possible to change one destination
+directory without changing the layout of the source tree.
+
+Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
+rule, in that there is no particular installation order guarantee for
+an otherwise equivalent set of variables without @samp{nobase_} prefix.
+
+ at node Subpackages
+ at section Nesting Packages
+ at cindex Nesting packages
+ at cindex Subpackages
+ at acindex AC_CONFIG_SUBDIRS
+ at acindex AC_CONFIG_AUX_DIR
+
+
+In the GNU Build System, packages can be nested to arbitrary depth.
+This means that a package can embed other packages with their own
+ at file{configure}, @file{Makefile}s, etc.
+
+These other packages should just appear as subdirectories of their
+parent package. They must be listed in @code{SUBDIRS} like other
+ordinary directories. However the subpackage's @file{Makefile}s
+should be output by its own @file{configure} script, not by the
+parent's @file{configure}. This is achieved using the
+ at code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
+AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
+autoconf, The Autoconf Manual}).
+
+Here is an example package for an @code{arm} program that links with
+a @code{hand} library that is a nested package in subdirectory
+ at file{hand/}.
+
+ at code{arm}'s @file{configure.ac}:
+
+ at example
+AC_INIT([arm], [1.0])
+AC_CONFIG_AUX_DIR([.])
+AM_INIT_AUTOMAKE
+AC_PROG_CC
+AC_CONFIG_FILES([Makefile])
+# Call hand's ./configure script recursively.
+AC_CONFIG_SUBDIRS([hand])
+AC_OUTPUT
+ at end example
+
+ at code{arm}'s @file{Makefile.am}:
+
+ at example
+# Build the library in the hand subdirectory first.
+SUBDIRS = hand
+
+# Include hand's header when compiling this directory.
+AM_CPPFLAGS = -I$(srcdir)/hand
+
+bin_PROGRAMS = arm
+arm_SOURCES = arm.c
+# link with the hand library.
+arm_LDADD = hand/libhand.a
+ at end example
+
+Now here is @code{hand}'s @file{hand/configure.ac}:
+
+ at example
+AC_INIT([hand], [1.2])
+AC_CONFIG_AUX_DIR([.])
+AM_INIT_AUTOMAKE
+AC_PROG_CC
+AM_PROG_AR
+AC_PROG_RANLIB
+AC_CONFIG_FILES([Makefile])
+AC_OUTPUT
+ at end example
+
+ at noindent
+and its @file{hand/Makefile.am}:
+
+ at example
+lib_LIBRARIES = libhand.a
+libhand_a_SOURCES = hand.c
+ at end example
+
+When @samp{make dist} is run from the top-level directory it will
+create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
+code as well as the @file{hand} subdirectory. This package can be
+built and installed like any ordinary package, with the usual
+ at samp{./configure && make && make install} sequence (the @code{hand}
+subpackage will be built and installed by the process).
+
+When @samp{make dist} is run from the hand directory, it will create a
+self-contained @file{hand-1.2.tar.gz} archive. So although it appears
+to be embedded in another package, it can still be used separately.
+
+The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
+force Automake and Autoconf to search for auxiliary scripts in the
+current directory. For instance, this means that there will be two
+copies of @file{install-sh}: one in the top-level of the @code{arm}
+package, and another one in the @file{hand/} subdirectory for the
+ at code{hand} package.
+
+The historical default is to search for these auxiliary scripts in
+the parent directory and the grandparent directory. So if the
+ at samp{AC_CONFIG_AUX_DIR([.])} line was removed from
+ at file{hand/configure.ac}, that subpackage would share the auxiliary
+script of the @code{arm} package. This may looks like a gain in size
+(a few kilobytes), but it is actually a loss of modularity as the
+ at code{hand} subpackage is no longer self-contained (@samp{make dist}
+in the subdirectory will not work anymore).
+
+Packages that do not use Automake need more work to be integrated this
+way. @xref{Third-Party Makefiles}.
+
+ at node Programs
+ at chapter Building Programs and Libraries
+
+A large part of Automake's functionality is dedicated to making it easy
+to build programs and libraries.
+
+ at menu
+* 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
+ at end menu
+
+
+ at node A Program
+ at section Building a program
+
+In order to build a program, you need to tell Automake which sources
+are part of it, and which libraries it should be linked with.
+
+This section also covers conditional compilation of sources or
+programs. Most of the comments about these also apply to libraries
+(@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
+
+ at menu
+* Program Sources:: Defining program sources
+* Linking:: Linking with libraries or extra objects
+* Conditional Sources:: Handling conditional sources
+* Conditional Programs:: Building a program conditionally
+ at end menu
+
+ at node Program Sources
+ at subsection Defining program sources
+
+ at cindex @code{PROGRAMS}, @code{bindir}
+ at vindex _PROGRAMS
+ at vindex bin_PROGRAMS
+ at vindex sbin_PROGRAMS
+ at vindex libexec_PROGRAMS
+ at vindex pkglibexec_PROGRAMS
+ at vindex noinst_PROGRAMS
+ at vindex check_PROGRAMS
+
+In a directory containing source that gets built into a program (as
+opposed to a library or a script), the @code{PROGRAMS} primary is used.
+Programs can be installed in @code{bindir}, @code{sbindir},
+ at code{libexecdir}, @code{pkglibexecdir}, or not at all
+(@code{noinst_}). They can also be built only for @samp{make check}, in
+which case the prefix is @samp{check_}.
+
+For instance:
+
+ at example
+bin_PROGRAMS = hello
+ at end example
+
+In this simple case, the resulting @file{Makefile.in} will contain code
+to generate a program named @code{hello}.
+
+Associated with each program are several assisting variables that are
+named after the program. These variables are all optional, and have
+reasonable defaults. Each variable, its use, and default is spelled out
+below; we use the ``hello'' example throughout.
+
+The variable @code{hello_SOURCES} is used to specify which source files
+get built into an executable:
+
+ at example
+hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
+ at end example
+
+This causes each mentioned @file{.c} file to be compiled into the
+corresponding @file{.o}. Then all are linked to produce @file{hello}.
+
+ at cindex @code{_SOURCES} primary, defined
+ at cindex @code{SOURCES} primary, defined
+ at cindex Primary variable, @code{SOURCES}
+ at vindex _SOURCES
+
+If @code{hello_SOURCES} is not specified, then it defaults to the single
+file @file{hello.c} (@pxref{Default _SOURCES}).
+ at vindex _SOURCES
+ at vindex SOURCES
+
+Multiple programs can be built in a single directory. Multiple programs
+can share a single source file, which must be listed in each
+ at code{_SOURCES} definition.
+
+ at cindex Header files in @code{_SOURCES}
+ at cindex @code{_SOURCES} and header files
+
+Header files listed in a @code{_SOURCES} definition will be included in
+the distribution but otherwise ignored. In case it isn't obvious, you
+should not include the header file generated by @file{configure} in a
+ at code{_SOURCES} variable; this file should not be distributed. Lex
+(@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
+and Lex}.
+
+
+ at node Linking
+ at subsection Linking the program
+
+If you need to link against libraries that are not found by
+ at command{configure}, you can use @code{LDADD} to do so. This variable is
+used to specify additional objects or libraries to link with; it is
+inappropriate for specifying specific linker flags, you should use
+ at code{AM_LDFLAGS} for this purpose.
+ at vindex LDADD
+ at vindex AM_LDFLAGS
+
+ at cindex @code{prog_LDADD}, defined
+
+Sometimes, multiple programs are built in one directory but do not share
+the same link-time requirements. In this case, you can use the
+ at code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
+program as it appears in some @code{_PROGRAMS} variable, and usually
+written in lowercase) to override @code{LDADD}. If this variable exists
+for a given program, then that program is not linked using @code{LDADD}.
+ at vindex maude_LDADD
+
+For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
+linked against the library @file{libcpio.a}. However, @code{rmt} is
+built in the same directory, and has no such link requirement. Also,
+ at code{mt} and @code{rmt} are only built on certain architectures. Here
+is what cpio's @file{src/Makefile.am} looks like (abridged):
+
+ at example
+bin_PROGRAMS = cpio pax $(MT)
+libexec_PROGRAMS = $(RMT)
+EXTRA_PROGRAMS = mt rmt
+
+LDADD = ../lib/libcpio.a $(INTLLIBS)
+rmt_LDADD =
+
+cpio_SOURCES = @dots{}
+pax_SOURCES = @dots{}
+mt_SOURCES = @dots{}
+rmt_SOURCES = @dots{}
+ at end example
+
+ at cindex @code{_LDFLAGS}, defined
+ at vindex maude_LDFLAGS
+ at code{@var{prog}_LDADD} is inappropriate for passing program-specific
+linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
+ at option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
+this purpose.
+
+ at cindex @code{_DEPENDENCIES}, defined
+ at vindex maude_DEPENDENCIES
+ at vindex EXTRA_maude_DEPENDENCIES
+It is also occasionally useful to have a program depend on some other
+target that is not actually part of that program. This can be done
+using either the @code{@var{prog}_DEPENDENCIES} or the
+ at code{EXTRA_ at var{prog}_DEPENDENCIES} variable. Each program depends on
+the contents both variables, but no further interpretation is done.
+
+Since these dependencies are associated to the link rule used to
+create the programs they should normally list files used by the link
+command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
+files. In rare cases you may need to add other kinds of files such as
+linker scripts, but @emph{listing a source file in
+ at code{_DEPENDENCIES} is wrong}. If some source file needs to be built
+before all the components of a program are built, consider using the
+ at code{BUILT_SOURCES} variable instead (@pxref{Sources}).
+
+If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
+Automake. The automatically-assigned value is the contents of
+ at code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
+ at option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
+configure substitutions that are left in are only @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)}; these are left because it is known that they will not
+cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
+generated.
+
+ at ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
+may be used.
+
+The @code{EXTRA_ at var{prog}_DEPENDENCIES} may be useful for cases where
+you merely want to augment the @command{automake}-generated
+ at code{@var{prog}_DEPENDENCIES} rather than replacing it.
+
+ at cindex @code{LDADD} and @option{-l}
+ at cindex @option{-l} and @code{LDADD}
+We recommend that you avoid using @option{-l} options in @code{LDADD}
+or @code{@var{prog}_LDADD} when referring to libraries built by your
+package. Instead, write the file name of the library explicitly as in
+the above @code{cpio} example. Use @option{-l} only to list
+third-party libraries. If you follow this rule, the default value of
+ at code{@var{prog}_DEPENDENCIES} will list all your local libraries and
+omit the other ones.
+
+
+ at node Conditional Sources
+ at subsection Conditional compilation of sources
+
+You can't put a configure substitution (e.g., @samp{@@FOO@@} or
+ at samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
+ at code{_SOURCES} variable. The reason for this is a bit hard to
+explain, but suffice to say that it simply won't work. Automake will
+give an error if you try to do this.
+
+Fortunately there are two other ways to achieve the same result. One is
+to use configure substitutions in @code{_LDADD} variables, the other is
+to use an Automake conditional.
+
+ at subsubheading Conditional Compilation using @code{_LDADD} Substitutions
+
+ at cindex @code{EXTRA_prog_SOURCES}, defined
+
+Automake must know all the source files that could possibly go into a
+program, even if not all the files are built in every circumstance. Any
+files that are only conditionally built should be listed in the
+appropriate @code{EXTRA_} variable. For instance, if
+ at file{hello-linux.c} or @file{hello-generic.c} were conditionally included
+in @code{hello}, the @file{Makefile.am} would contain:
+
+ at example
+bin_PROGRAMS = hello
+hello_SOURCES = hello-common.c
+EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
+hello_LDADD = $(HELLO_SYSTEM)
+hello_DEPENDENCIES = $(HELLO_SYSTEM)
+ at end example
+
+ at noindent
+You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
+ at file{configure.ac}:
+
+ at example
+ at dots{}
+case $host in
+ *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
+ *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
+esac
+AC_SUBST([HELLO_SYSTEM])
+ at dots{}
+ at end example
+
+In this case, the variable @code{HELLO_SYSTEM} should be replaced by
+either @file{hello-linux.o} or @file{hello-generic.o}, and added to
+both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
+built and linked in.
+
+ at subsubheading Conditional Compilation using Automake Conditionals
+
+An often simpler way to compile source files conditionally is to use
+Automake conditionals. For instance, you could use this
+ at file{Makefile.am} construct to build the same @file{hello} example:
+
+ at example
+bin_PROGRAMS = hello
+if LINUX
+hello_SOURCES = hello-linux.c hello-common.c
+else
+hello_SOURCES = hello-generic.c hello-common.c
+endif
+ at end example
+
+In this case, @file{configure.ac} should setup the @code{LINUX}
+conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
+
+When using conditionals like this you don't need to use the
+ at code{EXTRA_} variable, because Automake will examine the contents of
+each variable to construct the complete list of source files.
+
+If your program uses a lot of files, you will probably prefer a
+conditional @samp{+=}.
+
+ at example
+bin_PROGRAMS = hello
+hello_SOURCES = hello-common.c
+if LINUX
+hello_SOURCES += hello-linux.c
+else
+hello_SOURCES += hello-generic.c
+endif
+ at end example
+
+ at node Conditional Programs
+ at subsection Conditional compilation of programs
+ at cindex Conditional programs
+ at cindex Programs, conditional
+
+Sometimes it is useful to determine the programs that are to be built
+at configure time. For instance, GNU @code{cpio} only builds
+ at code{mt} and @code{rmt} under special circumstances. The means to
+achieve conditional compilation of programs are the same you can use
+to compile source files conditionally: substitutions or conditionals.
+
+ at subsubheading Conditional Programs using @command{configure} Substitutions
+
+ at vindex EXTRA_PROGRAMS
+ at cindex @code{EXTRA_PROGRAMS}, defined
+In this case, you must notify Automake of all the programs that can
+possibly be built, but at the same time cause the generated
+ at file{Makefile.in} to use the programs specified by @command{configure}.
+This is done by having @command{configure} substitute values into each
+ at code{_PROGRAMS} definition, while listing all optionally built programs
+in @code{EXTRA_PROGRAMS}.
+
+ at example
+bin_PROGRAMS = cpio pax $(MT)
+libexec_PROGRAMS = $(RMT)
+EXTRA_PROGRAMS = mt rmt
+ at end example
+
+As explained in @ref{EXEEXT}, Automake will rewrite
+ at code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
+ at code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
+Obviously it cannot rewrite values obtained at run-time through
+ at command{configure} substitutions, therefore you should take care of
+appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
+['mt$@{EXEEXT@}'])}.
+
+ at subsubheading Conditional Programs using Automake Conditionals
+
+You can also use Automake conditionals (@pxref{Conditionals}) to
+select programs to be built. In this case you don't have to worry
+about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
+
+ at c Keep in sync with exeext.sh
+ at example
+bin_PROGRAMS = cpio pax
+if WANT_MT
+ bin_PROGRAMS += mt
+endif
+if WANT_RMT
+ libexec_PROGRAMS = rmt
+endif
+ at end example
+
+
+ at node A Library
+ at section Building a library
+
+ at cindex @code{_LIBRARIES} primary, defined
+ at cindex @code{LIBRARIES} primary, defined
+ at cindex Primary variable, @code{LIBRARIES}
+ at vindex _LIBRARIES
+
+ at vindex lib_LIBRARIES
+ at vindex pkglib_LIBRARIES
+ at vindex noinst_LIBRARIES
+
+Building a library is much like building a program. In this case, the
+name of the primary is @code{LIBRARIES}. Libraries can be installed in
+ at code{libdir} or @code{pkglibdir}.
+
+ at xref{A Shared Library}, for information on how to build shared
+libraries using libtool and the @code{LTLIBRARIES} primary.
+
+Each @code{_LIBRARIES} variable is a list of the libraries to be built.
+For instance, to create a library named @file{libcpio.a}, but not install
+it, you would write:
+
+ at example
+noinst_LIBRARIES = libcpio.a
+libcpio_a_SOURCES = @dots{}
+ at end example
+
+The sources that go into a library are determined exactly as they are
+for programs, via the @code{_SOURCES} variables. Note that the library
+name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
+variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
+not @samp{libcpio.a_SOURCES}.
+
+ at vindex maude_LIBADD
+Extra objects can be added to a library using the
+ at code{@var{library}_LIBADD} variable. This should be used for objects
+determined by @command{configure}. Again from @code{cpio}:
+
+ at c Keep in sync with pr401c.sh
+ at example
+libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
+ at end example
+
+In addition, sources for extra objects that will not exist until
+configure-time must be added to the @code{BUILT_SOURCES} variable
+(@pxref{Sources}).
+
+Building a static library is done by compiling all object files, then
+by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
+library and the list of objects, and finally by calling
+ at samp{$(RANLIB)} on that library. You should call
+ at code{AC_PROG_RANLIB} from your @file{configure.ac} to define
+ at code{RANLIB} (Automake will complain otherwise). You should also
+call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
+archivers such as Microsoft lib. @code{ARFLAGS} will default to
+ at code{cru}; you can override this variable by setting it in your
+ at file{Makefile.am} or by @code{AC_SUBST}ing it from your
+ at file{configure.ac}. You can override the @code{AR} variable by
+defining a per-library @code{maude_AR} variable (@pxref{Program and
+Library Variables}).
+
+ at cindex Empty libraries
+Be careful when selecting library components conditionally. Because
+building an empty library is not portable, you should ensure that any
+library always contains at least one object.
+
+To use a static library when building a program, add it to
+ at code{LDADD} for this program. In the following example, the program
+ at file{cpio} is statically linked with the library @file{libcpio.a}.
+
+ at example
+noinst_LIBRARIES = libcpio.a
+libcpio_a_SOURCES = @dots{}
+
+bin_PROGRAMS = cpio
+cpio_SOURCES = cpio.c @dots{}
+cpio_LDADD = libcpio.a
+ at end example
+
+
+ at node A Shared Library
+ at section Building a Shared Library
+
+ at cindex Shared libraries, support for
+
+Building shared libraries portably is a relatively complex matter.
+For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
+Libtool Manual}) was created to help build shared libraries in a
+platform-independent way.
+
+ at menu
+* 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
+ at end menu
+
+ at node Libtool Concept
+ at subsection The Libtool Concept
+
+ at cindex @command{libtool}, introduction
+ at cindex libtool library, definition
+ at cindex suffix @file{.la}, defined
+ at cindex @file{.la} suffix, defined
+
+Libtool abstracts shared and static libraries into a unified concept
+henceforth called @dfn{libtool libraries}. Libtool libraries are
+files using the @file{.la} suffix, and can designate a static library,
+a shared library, or maybe both. Their exact nature cannot be
+determined until @file{./configure} is run: not all platforms support
+all kinds of libraries, and users can explicitly select which
+libraries should be built. (However the package's maintainers can
+tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
+macro, libtool, The Libtool Manual}.)
+
+ at cindex suffix @file{.lo}, defined
+Because object files for shared and static libraries must be compiled
+differently, libtool is also used during compilation. Object files
+built by libtool are called @dfn{libtool objects}: these are files
+using the @file{.lo} suffix. Libtool libraries are built from these
+libtool objects.
+
+You should not assume anything about the structure of @file{.la} or
+ at file{.lo} files and how libtool constructs them: this is libtool's
+concern, and the last thing one wants is to learn about libtool's
+guts. However the existence of these files matters, because they are
+used as targets and dependencies in @file{Makefile}s rules when
+building libtool libraries. There are situations where you may have
+to refer to these, for instance when expressing dependencies for
+building source files conditionally (@pxref{Conditional Libtool
+Sources}).
+
+ at cindex @file{libltdl}, introduction
+
+People considering writing a plug-in system, with dynamically loaded
+modules, should look into @file{libltdl}: libtool's dlopening library
+(@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
+This offers a portable dlopening facility to load libtool libraries
+dynamically, and can also achieve static linking where unavoidable.
+
+Before we discuss how to use libtool with Automake in details, it
+should be noted that the libtool manual also has a section about how
+to use Automake with libtool (@pxref{Using Automake, , Using Automake
+with Libtool, libtool, The Libtool Manual}).
+
+ at node Libtool Libraries
+ at subsection Building Libtool Libraries
+
+ at cindex @code{_LTLIBRARIES} primary, defined
+ at cindex @code{LTLIBRARIES} primary, defined
+ at cindex Primary variable, @code{LTLIBRARIES}
+ at cindex Example of shared libraries
+ at vindex lib_LTLIBRARIES
+ at vindex pkglib_LTLIBRARIES
+ at vindex _LTLIBRARIES
+
+Automake uses libtool to build libraries declared with the
+ at code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
+list of libtool libraries to build. For instance, to create a libtool
+library named @file{libgettext.la}, and install it in @code{libdir},
+write:
+
+ at example
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c gettext.h @dots{}
+ at end example
+
+Automake predefines the variable @code{pkglibdir}, so you can use
+ at code{pkglib_LTLIBRARIES} to install libraries in
+ at samp{$(libdir)/@@PACKAGE@@/}.
+
+If @file{gettext.h} is a public header file that needs to be installed
+in order for people to use the library, it should be declared using a
+ at code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
+Headers listed in the latter should be internal headers that are not
+part of the public interface.
+
+ at example
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c @dots{}
+include_HEADERS = gettext.h @dots{}
+ at end example
+
+A package can build and install such a library along with other
+programs that use it. This dependency should be specified using
+ at code{LDADD}. The following example builds a program named
+ at file{hello} that is linked with @file{libgettext.la}.
+
+ at example
+lib_LTLIBRARIES = libgettext.la
+libgettext_la_SOURCES = gettext.c @dots{}
+
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c @dots{}
+hello_LDADD = libgettext.la
+ at end example
+
+ at noindent
+Whether @file{hello} is statically or dynamically linked with
+ at file{libgettext.la} is not yet known: this will depend on the
+configuration of libtool and the capabilities of the host.
+
+
+ at node Conditional Libtool Libraries
+ at subsection Building Libtool Libraries Conditionally
+ at cindex libtool libraries, conditional
+ at cindex conditional libtool libraries
+
+Like conditional programs (@pxref{Conditional Programs}), there are
+two main ways to build conditional libraries: using Automake
+conditionals or using Autoconf @code{AC_SUBST}itutions.
+
+The important implementation detail you have to be aware of is that
+the place where a library will be installed matters to libtool: it
+needs to be indicated @emph{at link-time} using the @option{-rpath}
+option.
+
+For libraries whose destination directory is known when Automake runs,
+Automake will automatically supply the appropriate @option{-rpath}
+option to libtool. This is the case for libraries listed explicitly in
+some installable @code{_LTLIBRARIES} variables such as
+ at code{lib_LTLIBRARIES}.
+
+However, for libraries determined at configure time (and thus
+mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
+final installation directory. For such libraries you must add the
+ at option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
+hand.
+
+The examples below illustrate the differences between these two methods.
+
+Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
+variable set at @file{./configure}-time to either @file{libfoo.la},
+ at file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
+appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
+relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
+the link rule for these two libraries. Therefore the @option{-rpath}
+argument must be explicitly supplied.
+
+ at c Keep in sync with ltcond.sh
+ at example
+EXTRA_LTLIBRARIES = libfoo.la libbar.la
+lib_LTLIBRARIES = $(WANTEDLIBS)
+libfoo_la_SOURCES = foo.c @dots{}
+libfoo_la_LDFLAGS = -rpath '$(libdir)'
+libbar_la_SOURCES = bar.c @dots{}
+libbar_la_LDFLAGS = -rpath '$(libdir)'
+ at end example
+
+Here is how the same @file{Makefile.am} would look using Automake
+conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
+Automake is able to compute the @option{-rpath} setting itself, because
+it's clear that both libraries will end up in @samp{$(libdir)} if they
+are installed.
+
+ at c Keep in sync with ltcond.sh
+ at example
+lib_LTLIBRARIES =
+if WANT_LIBFOO
+lib_LTLIBRARIES += libfoo.la
+endif
+if WANT_LIBBAR
+lib_LTLIBRARIES += libbar.la
+endif
+libfoo_la_SOURCES = foo.c @dots{}
+libbar_la_SOURCES = bar.c @dots{}
+ at end example
+
+ at node Conditional Libtool Sources
+ at subsection Libtool Libraries with Conditional Sources
+
+Conditional compilation of sources in a library can be achieved in the
+same way as conditional compilation of sources in a program
+(@pxref{Conditional Sources}). The only difference is that
+ at code{_LIBADD} should be used instead of @code{_LDADD} and that it
+should mention libtool objects (@file{.lo} files).
+
+So, to mimic the @file{hello} example from @ref{Conditional Sources},
+we could build a @file{libhello.la} library using either
+ at file{hello-linux.c} or @file{hello-generic.c} with the following
+ at file{Makefile.am}.
+
+ at c Keep in sync with ltcond2.sh
+ at example
+lib_LTLIBRARIES = libhello.la
+libhello_la_SOURCES = hello-common.c
+EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
+libhello_la_LIBADD = $(HELLO_SYSTEM)
+libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
+ at end example
+
+ at noindent
+And make sure @command{configure} defines @code{HELLO_SYSTEM} as
+either @file{hello-linux.lo} or @file{hello- at -generic.lo}.
+
+Or we could simply use an Automake conditional as follows.
+
+ at c Keep in sync with ltcond2.sh
+ at example
+lib_LTLIBRARIES = libhello.la
+libhello_la_SOURCES = hello-common.c
+if LINUX
+libhello_la_SOURCES += hello-linux.c
+else
+libhello_la_SOURCES += hello-generic.c
+endif
+ at end example
+
+ at node Libtool Convenience Libraries
+ at subsection Libtool Convenience Libraries
+ at cindex convenience libraries, libtool
+ at cindex libtool convenience libraries
+ at vindex noinst_LTLIBRARIES
+ at vindex check_LTLIBRARIES
+
+Sometimes you want to build libtool libraries that should not be
+installed. These are called @dfn{libtool convenience libraries} and
+are typically used to encapsulate many sublibraries, later gathered
+into one big installed library.
+
+Libtool convenience libraries are declared by directory-less variables
+such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
+ at code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
+not need an @option{-rpath} flag at link time (actually this is the only
+difference).
+
+Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
+built. Those listed in @code{check_LTLIBRARIES} are built only upon
+ at samp{make check}. Finally, libraries listed in
+ at code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
+rules to build them, but if the library does not appear as a Makefile
+dependency anywhere it won't be built (this is why
+ at code{EXTRA_LTLIBRARIES} is used for conditional compilation).
+
+Here is a sample setup merging libtool convenience libraries from
+subdirectories into one main @file{libtop.la} library.
+
+ at c Keep in sync with ltconv.sh
+ at example
+# -- Top-level Makefile.am --
+SUBDIRS = sub1 sub2 @dots{}
+lib_LTLIBRARIES = libtop.la
+libtop_la_SOURCES =
+libtop_la_LIBADD = \
+ sub1/libsub1.la \
+ sub2/libsub2.la \
+ @dots{}
+
+# -- sub1/Makefile.am --
+noinst_LTLIBRARIES = libsub1.la
+libsub1_la_SOURCES = @dots{}
+
+# -- sub2/Makefile.am --
+# showing nested convenience libraries
+SUBDIRS = sub2.1 sub2.2 @dots{}
+noinst_LTLIBRARIES = libsub2.la
+libsub2_la_SOURCES =
+libsub2_la_LIBADD = \
+ sub21/libsub21.la \
+ sub22/libsub22.la \
+ @dots{}
+ at end example
+
+When using such setup, beware that @command{automake} will assume
+ at file{libtop.la} is to be linked with the C linker. This is because
+ at code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
+default language. If @code{libtop_la_SOURCES} was not empty,
+ at command{automake} would select the linker as explained in @ref{How
+the Linker is Chosen}.
+
+If one of the sublibraries contains non-C source, it is important that
+the appropriate linker be chosen. One way to achieve this is to
+pretend that there is such a non-C file among the sources of the
+library, thus forcing @command{automake} to select the appropriate
+linker. Here is the top-level @file{Makefile} of our example updated
+to force C++ linking.
+
+ at example
+SUBDIRS = sub1 sub2 @dots{}
+lib_LTLIBRARIES = libtop.la
+libtop_la_SOURCES =
+# Dummy C++ source to cause C++ linking.
+nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
+libtop_la_LIBADD = \
+ sub1/libsub1.la \
+ sub2/libsub2.la \
+ @dots{}
+ at end example
+
+ at samp{EXTRA_*_SOURCES} variables are used to keep track of source
+files that might be compiled (this is mostly useful when doing
+conditional compilation using @code{AC_SUBST}, @pxref{Conditional
+Libtool Sources}), and the @code{nodist_} prefix means the listed
+sources are not to be distributed (@pxref{Program and Library
+Variables}). In effect the file @file{dummy.cxx} does not need to
+exist in the source tree. Of course if you have some real source file
+to list in @code{libtop_la_SOURCES} there is no point in cheating with
+ at code{nodist_EXTRA_libtop_la_SOURCES}.
+
+
+ at node Libtool Modules
+ at subsection Libtool Modules
+ at cindex modules, libtool
+ at cindex libtool modules
+ at cindex @option{-module}, libtool
+
+These are libtool libraries meant to be dlopened. They are
+indicated to libtool by passing @option{-module} at link-time.
+
+ at example
+pkglib_LTLIBRARIES = mymodule.la
+mymodule_la_SOURCES = doit.c
+mymodule_la_LDFLAGS = -module
+ at end example
+
+Ordinarily, Automake requires that a library's name start with
+ at code{lib}. However, when building a dynamically loadable module you
+might wish to use a "nonstandard" name. Automake will not complain
+about such nonstandard names if it knows the library being built is a
+libtool module, i.e., if @option{-module} explicitly appears in the
+library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
+variable when no per-library @code{_LDFLAGS} variable is defined).
+
+As always, @code{AC_SUBST} variables are black boxes to Automake since
+their values are not yet known when @command{automake} is run.
+Therefore if @option{-module} is set via such a variable, Automake
+cannot notice it and will proceed as if the library was an ordinary
+libtool library, with strict naming.
+
+If @code{mymodule_la_SOURCES} is not specified, then it defaults to
+the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
+
+ at node Libtool Flags
+ at subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
+ at cindex @code{_LIBADD}, libtool
+ at cindex @code{_LDFLAGS}, libtool
+ at cindex @code{_LIBTOOLFLAGS}, libtool
+ at vindex AM_LIBTOOLFLAGS
+ at vindex LIBTOOLFLAGS
+ at vindex maude_LIBTOOLFLAGS
+
+As shown in previous sections, the @samp{@var{library}_LIBADD}
+variable should be used to list extra libtool objects (@file{.lo}
+files) or libtool libraries (@file{.la}) to add to @var{library}.
+
+The @samp{@var{library}_LDFLAGS} variable is the place to list
+additional libtool linking flags, such as @option{-version-info},
+ at option{-static}, and a lot more. @xref{Link mode, , Link mode,
+libtool, The Libtool Manual}.
+
+The @command{libtool} command has two kinds of options: mode-specific
+options and generic options. Mode-specific options such as the
+aforementioned linking flags should be lumped with the other flags
+passed to the tool invoked by @command{libtool} (hence the use of
+ at samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
+options include @option{--tag=@var{tag}} and @option{--silent}
+(@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
+Libtool Manual} for more options) should appear before the mode
+selection on the command line; in @file{Makefile.am}s they should
+be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
+
+If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
+ at code{AM_LIBTOOLFLAGS} is used instead.
+
+These flags are passed to libtool after the @option{--tag=@var{tag}}
+option computed by Automake (if any), so
+ at samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
+good place to override or supplement the @option{--tag=@var{tag}}
+setting.
+
+The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
+not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
+Variables Ordering}. It allows users to run @samp{make
+LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
+ at command{libtool} can also be influenced by the Automake support
+for silent rules (@pxref{Automake Silent Rules}).
+
+ at node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
+ at subsection @code{LTLIBOBJS} and @code{LTALLOCA}
+ at cindex @code{LTLIBOBJS}, special handling
+ at cindex @code{LIBOBJS}, and Libtool
+ at cindex @code{LTALLOCA}, special handling
+ at cindex @code{ALLOCA}, and Libtool
+ at vindex LTLIBOBJS
+ at vindex LIBOBJS
+ at vindex LTALLOCA
+ at vindex ALLOCA
+ at acindex AC_LIBOBJ
+
+Where an ordinary library might include @samp{$(LIBOBJS)} or
+ at samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
+ at samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
+the object files that libtool operates on do not necessarily end in
+ at file{.o}.
+
+Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
+performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
+ at code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
+
+ at node Libtool Issues
+ at subsection Common Issues Related to Libtool's Use
+
+ at menu
+* Error required file ltmain.sh not found:: The need to run libtoolize
+* Objects created both with libtool and without:: Avoid a specific build race
+ at end menu
+
+ at node Error required file ltmain.sh not found
+ at subsubsection Error: @samp{required file `./ltmain.sh' not found}
+ at cindex @file{ltmain.sh} not found
+ at cindex @command{libtoolize}, no longer run by @command{automake}
+ at cindex @command{libtoolize} and @command{autoreconf}
+ at cindex @command{autoreconf} and @command{libtoolize}
+ at cindex @file{bootstrap.sh} and @command{autoreconf}
+ at cindex @file{autogen.sh} and @command{autoreconf}
+
+Libtool comes with a tool called @command{libtoolize} that will
+install libtool's supporting files into a package. Running this
+command will install @file{ltmain.sh}. You should execute it before
+ at command{aclocal} and @command{automake}.
+
+People upgrading old packages to newer autotools are likely to face
+this issue because older Automake versions used to call
+ at command{libtoolize}. Therefore old build scripts do not call
+ at command{libtoolize}.
+
+Since Automake 1.6, it has been decided that running
+ at command{libtoolize} was none of Automake's business. Instead, that
+functionality has been moved into the @command{autoreconf} command
+(@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
+The Autoconf Manual}). If you do not want to remember what to run and
+when, just learn the @command{autoreconf} command. Hopefully,
+replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
+a call to @command{autoreconf} should also free you from any similar
+incompatible change in the future.
+
+ at node Objects created both with libtool and without
+ at subsubsection Objects @samp{created with both libtool and without}
+
+Sometimes, the same source file is used both to build a libtool
+library and to build another non-libtool target (be it a program or
+another library).
+
+Let's consider the following @file{Makefile.am}.
+
+ at example
+bin_PROGRAMS = prog
+prog_SOURCES = prog.c foo.c @dots{}
+
+lib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = foo.c @dots{}
+ at end example
+
+ at noindent
+(In this trivial case the issue could be avoided by linking
+ at file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
+ at code{prog_SOURCES}. But let's assume we really want to keep
+ at file{prog} and @file{libfoo.la} separate.)
+
+Technically, it means that we should build @file{foo.$(OBJEXT)} for
+ at file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
+that in the course of creating @file{foo.lo}, libtool may erase (or
+replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
+
+Therefore, when Automake detects this situation it will complain
+with a message such as
+ at example
+object 'foo.$(OBJEXT)' created both with libtool and without
+ at end example
+
+A workaround for this issue is to ensure that these two objects get
+different basenames. As explained in @ref{Renamed Objects}, this
+happens automatically when per-targets flags are used.
+
+ at example
+bin_PROGRAMS = prog
+prog_SOURCES = prog.c foo.c @dots{}
+prog_CFLAGS = $(AM_CFLAGS)
+
+lib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = foo.c @dots{}
+ at end example
+
+ at noindent
+Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
+when the @code{prog_CFLAGS} is defined, it is used instead of
+ at code{AM_CFLAGS}. However as a side effect it will cause
+ at file{prog.c} and @file{foo.c} to be compiled as
+ at file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
+the issue.
+
+ at node Program and Library Variables
+ at section Program and Library Variables
+
+Associated with each program is a collection of variables that can be
+used to modify how that program is built. There is a similar list of
+such variables for each library. The canonical name of the program (or
+library) is used as a base for naming these variables.
+
+In the list below, we use the name ``maude'' to refer to the program or
+library. In your @file{Makefile.am} you would replace this with the
+canonical name of your program. This list also refers to ``maude'' as a
+program, but in general the same rules apply for both static and dynamic
+libraries; the documentation below notes situations where programs and
+libraries differ.
+
+ at vtable @code
+ at item maude_SOURCES
+This variable, if it exists, lists all the source files that are
+compiled to build the program. These files are added to the
+distribution by default. When building the program, Automake will cause
+each source file to be compiled to a single @file{.o} file (or
+ at file{.lo} when using libtool). Normally these object files are named
+after the source file, but other factors can change this. If a file in
+the @code{_SOURCES} variable has an unrecognized extension, Automake
+will do one of two things with it. If a suffix rule exists for turning
+files with the unrecognized extension into @file{.o} files, then
+ at command{automake} will treat this file as it will any other source file
+(@pxref{Support for Other Languages}). Otherwise, the file will be
+ignored as though it were a header file.
+
+The prefixes @code{dist_} and @code{nodist_} can be used to control
+whether files listed in a @code{_SOURCES} variable are distributed.
+ at code{dist_} is redundant, as sources are distributed by default, but it
+can be specified for clarity if desired.
+
+It is possible to have both @code{dist_} and @code{nodist_} variants of
+a given @code{_SOURCES} variable at once; this lets you easily
+distribute some files and not others, for instance:
+
+ at example
+nodist_maude_SOURCES = nodist.c
+dist_maude_SOURCES = dist-me.c
+ at end example
+
+By default the output file (on Unix systems, the @file{.o} file) will
+be put into the current build directory. However, if the option
+ at option{subdir-objects} is in effect in the current directory then the
+ at file{.o} file will be put into the subdirectory named after the
+source file. For instance, with @option{subdir-objects} enabled,
+ at file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
+people prefer this mode of operation. You can specify
+ at option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
+ at cindex Subdirectory, objects in
+ at cindex Objects in subdirectory
+
+
+ at item EXTRA_maude_SOURCES
+Automake needs to know the list of files you intend to compile
+ at emph{statically}. For one thing, this is the only way Automake has of
+knowing what sort of language support a given @file{Makefile.in}
+requires. @footnote{There are other, more obscure reasons for
+this limitation as well.} This means that, for example, you can't put a
+configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
+variable. If you intend to conditionally compile source files and use
+ at file{configure} to substitute the appropriate object names into, e.g.,
+ at code{_LDADD} (see below), then you should list the corresponding source
+files in the @code{EXTRA_} variable.
+
+This variable also supports @code{dist_} and @code{nodist_} prefixes.
+For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
+sources that may need to be built, but should not be distributed.
+
+ at item maude_AR
+A static library is created by default by invoking @samp{$(AR)
+$(ARFLAGS)} followed by the name of the library and then the objects
+being put into the library. You can override this by setting the
+ at code{_AR} variable. This is usually used with C++; some C++
+compilers require a special invocation in order to instantiate all the
+templates that should go into a library. For instance, the SGI C++
+compiler likes this variable set like so:
+ at example
+libmaude_a_AR = $(CXX) -ar -o
+ at end example
+
+ at item maude_LIBADD
+Extra objects can be added to a @emph{library} using the @code{_LIBADD}
+variable. For instance, this should be used for objects determined by
+ at command{configure} (@pxref{A Library}).
+
+In the case of libtool libraries, @code{maude_LIBADD} can also refer
+to other libtool libraries.
+
+ at item maude_LDADD
+Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
+ at file{*.la}) can be added to a @emph{program} by listing them in the
+ at code{_LDADD} variable. For instance, this should be used for objects
+determined by @command{configure} (@pxref{Linking}).
+
+ at code{_LDADD} and @code{_LIBADD} are inappropriate for passing
+program-specific linker flags (except for @option{-l}, @option{-L},
+ at option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
+for this purpose.
+
+For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
+could link your program against the X libraries like so:
+
+ at example
+maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
+ at end example
+
+We recommend that you use @option{-l} and @option{-L} only when
+referring to third-party libraries, and give the explicit file names
+of any library built by your package. Doing so will ensure that
+ at code{maude_DEPENDENCIES} (see below) is correctly defined by default.
+
+ at item maude_LDFLAGS
+This variable is used to pass extra flags to the link step of a program
+or a shared library. It overrides the @code{AM_LDFLAGS} variable.
+
+ at item maude_LIBTOOLFLAGS
+This variable is used to pass extra options to @command{libtool}.
+It overrides the @code{AM_LIBTOOLFLAGS} variable.
+These options are output before @command{libtool}'s @option{--mode=@var{mode}}
+option, so they should not be mode-specific options (those belong to
+the compiler or linker flags). @xref{Libtool Flags}.
+
+ at item maude_DEPENDENCIES
+ at itemx EXTRA_maude_DEPENDENCIES
+It is also occasionally useful to have a target (program or library)
+depend on some other file that is not actually part of that target.
+This can be done using the @code{_DEPENDENCIES} variable. Each
+target depends on the contents of such a variable, but no further
+interpretation is done.
+
+Since these dependencies are associated to the link rule used to
+create the programs they should normally list files used by the link
+command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
+for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
+and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
+may need to add other kinds of files such as linker scripts, but
+ at emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
+some source file needs to be built before all the components of a
+program are built, consider using the @code{BUILT_SOURCES} variable
+(@pxref{Sources}).
+
+If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
+The automatically-assigned value is the contents of @code{_LDADD} or
+ at code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
+ at option{-dlopen} and @option{-dlpreopen} options removed. The configure
+substitutions that are left in are only @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)}; these are left because it is known that they will not
+cause an invalid value for @code{_DEPENDENCIES} to be generated.
+
+ at code{_DEPENDENCIES} is more likely used to perform conditional
+compilation using an @code{AC_SUBST} variable that contains a list of
+objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
+Sources}.
+
+The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
+you merely want to augment the @command{automake}-generated
+ at code{_DEPENDENCIES} variable rather than replacing it.
+
+ at item maude_LINK
+You can override the linker on a per-program basis. By default the
+linker is chosen according to the languages used by the program. For
+instance, a program that includes C++ source code would use the C++
+compiler to link. The @code{_LINK} variable must hold the name of a
+command that can be passed all the @file{.o} file names and libraries
+to link against as arguments. Note that the name of the underlying
+program is @emph{not} passed to @code{_LINK}; typically one uses
+ at samp{$@@}:
+
+ at example
+maude_LINK = $(CCLD) -magic -o $@@
+ at end example
+
+If a @code{_LINK} variable is not supplied, it may still be generated
+and used by Automake due to the use of per-target link flags such as
+ at code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
+they apply.
+
+ at item maude_CCASFLAGS
+ at itemx maude_CFLAGS
+ at itemx maude_CPPFLAGS
+ at itemx maude_CXXFLAGS
+ at itemx maude_FFLAGS
+ at itemx maude_GCJFLAGS
+ at itemx maude_LFLAGS
+ at itemx maude_OBJCFLAGS
+ at itemx maude_OBJCXXFLAGS
+ at itemx maude_RFLAGS
+ at itemx maude_UPCFLAGS
+ at itemx maude_YFLAGS
+ at cindex per-target compilation flags, defined
+Automake allows you to set compilation flags on a per-program (or
+per-library) basis. A single source file can be included in several
+programs, and it will potentially be compiled with different flags for
+each program. This works for any language directly supported by
+Automake. These @dfn{per-target compilation flags} are
+ at samp{_CCASFLAGS},
+ at samp{_CFLAGS},
+ at samp{_CPPFLAGS},
+ at samp{_CXXFLAGS},
+ at samp{_FFLAGS},
+ at samp{_GCJFLAGS},
+ at samp{_LFLAGS},
+ at samp{_OBJCFLAGS},
+ at samp{_OBJCXXFLAGS},
+ at samp{_RFLAGS},
+ at samp{_UPCFLAGS}, and
+ at samp{_YFLAGS}.
+
+When using a per-target compilation flag, Automake will choose a
+different name for the intermediate object files. Ordinarily a file
+like @file{sample.c} will be compiled to produce @file{sample.o}.
+However, if the program's @code{_CFLAGS} variable is set, then the
+object file will be named, for instance, @file{maude-sample.o}. (See
+also @ref{Renamed Objects}).
+
+In compilations with per-target flags, the ordinary @samp{AM_} form of
+the flags variable is @emph{not} automatically included in the
+compilation (however, the user form of the variable @emph{is} included).
+So for instance, if you want the hypothetical @file{maude} compilations
+to also use the value of @code{AM_CFLAGS}, you would need to write:
+
+ at example
+maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
+ at end example
+
+ at xref{Flag Variables Ordering}, for more discussion about the
+interaction between user variables, @samp{AM_} shadow variables, and
+per-target variables.
+
+ at item maude_SHORTNAME
+On some platforms the allowable file names are very short. In order to
+support these systems and per-target compilation flags at the same
+time, Automake allows you to set a ``short name'' that will influence
+how intermediate object files are named. For instance, in the following
+example,
+
+ at example
+bin_PROGRAMS = maude
+maude_CPPFLAGS = -DSOMEFLAG
+maude_SHORTNAME = m
+maude_SOURCES = sample.c @dots{}
+ at end example
+
+ at noindent
+the object file would be named @file{m-sample.o} rather than
+ at file{maude-sample.o}.
+
+This facility is rarely needed in practice,
+and we recommend avoiding it until you find it is required.
+ at end vtable
+
+ at node Default _SOURCES
+ at section Default @code{_SOURCES}
+
+ at vindex _SOURCES
+ at vindex SOURCES
+ at cindex @code{_SOURCES}, default
+ at cindex default @code{_SOURCES}
+ at vindex AM_DEFAULT_SOURCE_EXT
+
+ at code{_SOURCES} variables are used to specify source files of programs
+(@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
+libraries (@pxref{A Shared Library}).
+
+When no such variable is specified for a target, Automake will define
+one itself. The default is to compile a single C file whose base name
+is the name of the target itself, with any extension replaced by
+ at code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
+
+For example if you have the following somewhere in your
+ at file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
+
+ at example
+lib_LIBRARIES = libfoo.a sub/libc++.a
+ at end example
+
+ at noindent
+ at file{libfoo.a} will be built using a default source file named
+ at file{libfoo.c}, and @file{sub/libc++.a} will be built from
+ at file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
+would be built from @file{sub_libc___a.c}, i.e., the default source
+was the canonized name of the target, with @file{.c} appended.
+We believe the new behavior is more sensible, but for backward
+compatibility @command{automake} will use the old name if a file or a rule
+with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
+
+ at cindex @code{check_PROGRAMS} example
+ at vindex check_PROGRAMS
+Default sources are mainly useful in test suites, when building many
+test programs each from a single source. For instance, in
+
+ at example
+check_PROGRAMS = test1 test2 test3
+AM_DEFAULT_SOURCE_EXT = .cpp
+ at end example
+
+ at noindent
+ at file{test1}, @file{test2}, and @file{test3} will be built
+from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
+Without the last line, they will be built from @file{test1.c},
+ at file{test2.c}, and @file{test3.c}.
+
+ at cindex Libtool modules, default source example
+ at cindex default source, Libtool modules example
+Another case where this is convenient is building many Libtool modules
+(@file{module at var{n}.la}), each defined in its own file
+(@file{module at var{n}.c}).
+
+ at example
+AM_LDFLAGS = -module
+lib_LTLIBRARIES = module1.la module2.la module3.la
+ at end example
+
+ at cindex empty @code{_SOURCES}
+ at cindex @code{_SOURCES}, empty
+Finally, there is one situation where this default source computation
+needs to be avoided: when a target should not be built from sources.
+We already saw such an example in @ref{true}; this happens when all
+the constituents of a target have already been compiled and just need
+to be combined using a @code{_LDADD} variable. Then it is necessary
+to define an empty @code{_SOURCES} variable, so that @command{automake}
+does not compute a default.
+
+ at example
+bin_PROGRAMS = target
+target_SOURCES =
+target_LDADD = libmain.a libmisc.a
+ at end example
+
+ at node LIBOBJS
+ at section Special handling for @code{LIBOBJS} and @code{ALLOCA}
+
+ at cindex @code{LIBOBJS}, example
+ at cindex @code{ALLOCA}, example
+ at cindex @code{LIBOBJS}, special handling
+ at cindex @code{ALLOCA}, special handling
+ at vindex LTLIBOBJS
+ at vindex LIBOBJS
+ at vindex LTALLOCA
+ at vindex ALLOCA
+
+The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
+files that should be compiled into the project to provide an
+implementation for functions that are missing or broken on the host
+system. They are substituted by @file{configure}.
+
+ at acindex AC_LIBOBJ
+
+These variables are defined by Autoconf macros such as
+ at code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
+Generic Function Checks, autoconf, The Autoconf Manual}), or
+ at code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
+Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
+macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
+populate @samp{$(LIBOBJS)}.
+
+ at acindex AC_LIBSOURCE
+
+Using these variables is very similar to doing conditional compilation
+using @code{AC_SUBST} variables, as described in @ref{Conditional
+Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
+variable, or to the @samp{*_LIBADD} variable when building a library.
+However there is no need to list the corresponding sources in
+ at samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
+automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
+dependencies, and it will discover the list of corresponding source
+files automatically (by tracing the invocations of the
+ at code{AC_LIBSOURCE} Autoconf macros). If you have already defined
+ at samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
+either need to add these variables manually, or use
+ at samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
+
+These variables are usually used to build a portability library that
+is linked with all the programs of the project. We now review a
+sample setup. First, @file{configure.ac} contains some checks that
+affect either @code{LIBOBJS} or @code{ALLOCA}.
+
+ at example
+# configure.ac
+ at dots{}
+AC_CONFIG_LIBOBJ_DIR([lib])
+ at dots{}
+AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
+AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
+AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
+AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
+ at dots{}
+AC_CONFIG_FILES([
+ lib/Makefile
+ src/Makefile
+])
+AC_OUTPUT
+ at end example
+
+ at acindex AC_CONFIG_LIBOBJ_DIR
+
+The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
+of these object files are to be found in the @file{lib/} directory.
+Automake can also use this information, otherwise it expects the
+source files are to be in the directory where the @samp{$(LIBOBJS)}
+and @samp{$(ALLOCA)} variables are used.
+
+The @file{lib/} directory should therefore contain @file{malloc.c},
+ at file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
+ at file{Makefile.am}:
+
+ at example
+# lib/Makefile.am
+
+noinst_LIBRARIES = libcompat.a
+libcompat_a_SOURCES =
+libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
+ at end example
+
+The library can have any name, of course, and anyway it is not going
+to be installed: it just holds the replacement versions of the missing
+or broken functions so we can later link them in. Many projects
+also include extra functions, specific to the project, in that
+library: they are simply added on the @code{_SOURCES} line.
+
+ at cindex Empty libraries and @samp{$(LIBOBJS)}
+ at cindex @samp{$(LIBOBJS)} and empty libraries
+There is a small trap here, though: @samp{$(LIBOBJS)} and
+ at samp{$(ALLOCA)} might be empty, and building an empty library is not
+portable. You should ensure that there is always something to put in
+ at file{libcompat.a}. Most projects will also add some utility
+functions in that directory, and list them in
+ at code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
+be empty.
+
+Finally here is how this library could be used from the @file{src/}
+directory.
+
+ at example
+# src/Makefile.am
+
+# Link all programs in this directory with libcompat.a
+LDADD = ../lib/libcompat.a
+
+bin_PROGRAMS = tool1 tool2 @dots{}
+tool1_SOURCES = @dots{}
+tool2_SOURCES = @dots{}
+ at end example
+
+When option @option{subdir-objects} is not used, as in the above
+example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
+be used in the directory where their sources lie. E.g., here it would
+be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
+ at file{src/Makefile.am}. However if both @option{subdir-objects} and
+ at code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
+in other directories. For instance @file{src/Makefile.am} could be
+changed as follows.
+
+ at example
+# src/Makefile.am
+
+AUTOMAKE_OPTIONS = subdir-objects
+LDADD = $(LIBOBJS) $(ALLOCA)
+
+bin_PROGRAMS = tool1 tool2 @dots{}
+tool1_SOURCES = @dots{}
+tool2_SOURCES = @dots{}
+ at end example
+
+Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
+file names that end with @samp{.$(OBJEXT)}, they are not suitable for
+Libtool libraries (where the expected object extension is @file{.lo}):
+ at code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
+
+ at code{LTLIBOBJS} is defined automatically by Autoconf and should not
+be defined by hand (as in the past), however at the time of writing
+ at code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
+ at xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
+autoconf, The Autoconf Manual}.
+
+
+ at node Program Variables
+ at section Variables used when building a program
+
+Occasionally it is useful to know which @file{Makefile} variables
+Automake uses for compilations, and in which order (@pxref{Flag
+Variables Ordering}); for instance, you might need to do your own
+compilation in some special cases.
+
+Some variables are inherited from Autoconf; these are @code{CC},
+ at code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
+ at code{LIBS}.
+ at vindex CC
+ at vindex CFLAGS
+ at vindex CPPFLAGS
+ at vindex DEFS
+ at vindex LDFLAGS
+ at vindex LIBS
+
+There are some additional variables that Automake defines on its own:
+
+ at vtable @code
+ at item AM_CPPFLAGS
+The contents of this variable are passed to every compilation that invokes
+the C preprocessor; it is a list of arguments to the preprocessor. For
+instance, @option{-I} and @option{-D} options should be listed here.
+
+Automake already provides some @option{-I} options automatically, in a
+separate variable that is also passed to every compilation that invokes
+the C preprocessor. In particular it generates @samp{-I.},
+ at samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
+ at file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can
+disable the default @option{-I} options using the @option{nostdinc}
+option.
+
+When a file to be included is generated during the build and not part
+of a distribution tarball, its location is under @code{$(builddir)},
+not under @code{$(srcdir)}. This matters especially for packages that
+use header files placed in sub-directories and want to allow builds
+outside the source tree (@pxref{VPATH Builds}). In that case we
+recommend to use a pair of @option{-I} options, such as, e.g.,
+ at samp{-Isome/subdir -I$(srcdir)/some/subdir} or
+ at samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
+Note that the reference to the build tree should come before the
+reference to the source tree, so that accidentally leftover generated
+files in the source directory are ignored.
+
+ at code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
+per-library) @code{_CPPFLAGS} variable if it is defined.
+
+ at item INCLUDES
+This does the same job as @code{AM_CPPFLAGS} (or any per-target
+ at code{_CPPFLAGS} variable if it is used). It is an older name for the
+same functionality. This variable is deprecated; we suggest using
+ at code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
+
+ at item AM_CFLAGS
+This is the variable the @file{Makefile.am} author can use to pass
+in additional C compiler flags. In some situations, this is
+not used, in preference to the per-executable (or per-library)
+ at code{_CFLAGS}.
+
+ at item COMPILE
+This is the command used to actually compile a C source file. The
+file name is appended to form the complete command line.
+
+ at item AM_LDFLAGS
+This is the variable the @file{Makefile.am} author can use to pass
+in additional linker flags. In some situations, this is not used, in
+preference to the per-executable (or per-library) @code{_LDFLAGS}.
+
+ at item LINK
+This is the command used to actually link a C program. It already
+includes @samp{-o $@@} and the usual variable references (for instance,
+ at code{CFLAGS}); it takes as ``arguments'' the names of the object files
+and libraries to link in. This variable is not used when the linker is
+overridden with a per-target @code{_LINK} variable or per-target flags
+cause Automake to define such a @code{_LINK} variable.
+ at end vtable
+
+
+ at node Yacc and Lex
+ at section Yacc and Lex support
+
+Automake has somewhat idiosyncratic support for Yacc and Lex.
+
+Automake assumes that the @file{.c} file generated by @command{yacc}
+(or @command{lex}) should be named using the basename of the input
+file. That is, for a yacc source file @file{foo.y}, Automake will
+cause the intermediate file to be named @file{foo.c} (as opposed to
+ at file{y.tab.c}, which is more traditional).
+
+The extension of a yacc source file is used to determine the extension
+of the resulting C or C++ source and header files. Note that header
+files are generated only when the @option{-d} Yacc option is used; see
+below for more information about this flag, and how to specify it.
+Files with the extension @file{.y} will thus be turned into @file{.c}
+sources and @file{.h} headers; likewise, @file{.yy} will become
+ at file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
+ at file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
+and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
+
+Similarly, lex source files can be used to generate C or C++; the
+extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
+ at file{.lpp} are recognized.
+
+You should never explicitly mention the intermediate (C or C++) file
+in any @code{SOURCES} variable; only list the source file.
+
+The intermediate files generated by @command{yacc} (or @command{lex})
+will be included in any distribution that is made. That way the user
+doesn't need to have @command{yacc} or @command{lex}.
+
+If a @command{yacc} source file is seen, then your @file{configure.ac} must
+define the variable @code{YACC}. This is most easily done by invoking
+the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+ at vindex YFLAGS
+ at vindex AM_YFLAGS
+When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
+ at code{YFLAGS}. The latter is a user variable and the former is
+intended for the @file{Makefile.am} author.
+
+ at code{AM_YFLAGS} is usually used to pass the @option{-d} option to
+ at command{yacc}. Automake knows what this means and will automatically
+adjust its rules to update and distribute the header file built by
+ at samp{yacc -d}@footnote{Please note that @command{automake} recognizes
+ at option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
+options; for example, it won't be recognized if @code{AM_YFLAGS} is
+ at option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
+ at option{-t -d}.}.
+What Automake cannot guess, though, is where this
+header will be used: it is up to you to ensure the header gets built
+before it is first used. Typically this is necessary in order for
+dependency tracking to work when the header is included by another
+file. The common solution is listing the header file in
+ at code{BUILT_SOURCES} (@pxref{Sources}) as follows.
+
+ at example
+BUILT_SOURCES = parser.h
+AM_YFLAGS = -d
+bin_PROGRAMS = foo
+foo_SOURCES = @dots{} parser.y @dots{}
+ at end example
+
+If a @command{lex} source file is seen, then your @file{configure.ac}
+must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
+to do this (@pxref{Particular Programs, , Particular Program Checks,
+autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
+(@pxref{Macros}) is recommended.
+
+ at vindex LFLAGS
+ at vindex AM_LFLAGS
+When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
+ at code{LFLAGS}. The latter is a user variable and the former is
+intended for the @file{Makefile.am} author.
+
+When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
+rebuild rule for distributed Yacc and Lex sources are only used when
+ at code{maintainer-mode} is enabled, or when the files have been erased.
+
+ at cindex @command{ylwrap}
+ at cindex @command{yacc}, multiple parsers
+ at cindex Multiple @command{yacc} parsers
+ at cindex Multiple @command{lex} lexers
+ at cindex @command{lex}, multiple lexers
+
+When @command{lex} or @command{yacc} sources are used, @code{automake -a}
+automatically installs an auxiliary program called @command{ylwrap} in
+your package (@pxref{Auxiliary Programs}).
+This program is used by the build rules to rename the output of these
+tools, and makes it possible to include multiple @command{yacc} (or
+ at command{lex}) source files in a single directory. (This is necessary
+because yacc's output file name is fixed, and a parallel make could
+conceivably invoke more than one instance of @command{yacc}
+simultaneously.)
+
+For @command{yacc}, simply managing locking is insufficient. The output of
+ at command{yacc} always uses the same symbol names internally, so it isn't
+possible to link two @command{yacc} parsers into the same executable.
+
+We recommend using the following renaming hack used in @command{gdb}:
+ at example
+#define yymaxdepth c_maxdepth
+#define yyparse c_parse
+#define yylex c_lex
+#define yyerror c_error
+#define yylval c_lval
+#define yychar c_char
+#define yydebug c_debug
+#define yypact c_pact
+#define yyr1 c_r1
+#define yyr2 c_r2
+#define yydef c_def
+#define yychk c_chk
+#define yypgo c_pgo
+#define yyact c_act
+#define yyexca c_exca
+#define yyerrflag c_errflag
+#define yynerrs c_nerrs
+#define yyps c_ps
+#define yypv c_pv
+#define yys c_s
+#define yy_yys c_yys
+#define yystate c_state
+#define yytmp c_tmp
+#define yyv c_v
+#define yy_yyv c_yyv
+#define yyval c_val
+#define yylloc c_lloc
+#define yyreds c_reds
+#define yytoks c_toks
+#define yylhs c_yylhs
+#define yylen c_yylen
+#define yydefred c_yydefred
+#define yydgoto c_yydgoto
+#define yysindex c_yysindex
+#define yyrindex c_yyrindex
+#define yygindex c_yygindex
+#define yytable c_yytable
+#define yycheck c_yycheck
+#define yyname c_yyname
+#define yyrule c_yyrule
+ at end example
+
+For each define, replace the @samp{c_} prefix with whatever you like.
+These defines work for @command{bison}, @command{byacc}, and
+traditional @code{yacc}s. If you find a parser generator that uses a
+symbol not covered here, please report the new name so it can be added
+to the list.
+
+
+ at node C++ Support
+ at section C++ Support
+
+ at cindex C++ support
+ at cindex Support for C++
+
+Automake includes full support for C++.
+
+Any package including C++ code must define the output variable
+ at code{CXX} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when a C++ source file is seen:
+
+ at vtable @code
+ at item CXX
+The name of the C++ compiler.
+
+ at item CXXFLAGS
+Any flags to pass to the C++ compiler.
+
+ at item AM_CXXFLAGS
+The maintainer's variant of @code{CXXFLAGS}.
+
+ at item CXXCOMPILE
+The command used to actually compile a C++ source file. The file name
+is appended to form the complete command line.
+
+ at item CXXLINK
+The command used to actually link a C++ program.
+ at end vtable
+
+
+ at node Objective C Support
+ at section Objective C Support
+
+ at cindex Objective C support
+ at cindex Support for Objective C
+
+Automake includes some support for Objective C.
+
+Any package including Objective C code must define the output variable
+ at code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when an Objective C source file
+is seen:
+
+ at vtable @code
+ at item OBJC
+The name of the Objective C compiler.
+
+ at item OBJCFLAGS
+Any flags to pass to the Objective C compiler.
+
+ at item AM_OBJCFLAGS
+The maintainer's variant of @code{OBJCFLAGS}.
+
+ at item OBJCCOMPILE
+The command used to actually compile an Objective C source file. The
+file name is appended to form the complete command line.
+
+ at item OBJCLINK
+The command used to actually link an Objective C program.
+ at end vtable
+
+
+ at node Objective C++ Support
+ at section Objective C++ Support
+
+ at cindex Objective C++ support
+ at cindex Support for Objective C++
+
+Automake includes some support for Objective C++.
+
+Any package including Objective C++ code must define the output variable
+ at code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when an Objective C++ source file
+is seen:
+
+ at vtable @code
+ at item OBJCXX
+The name of the Objective C++ compiler.
+
+ at item OBJCXXFLAGS
+Any flags to pass to the Objective C++ compiler.
+
+ at item AM_OBJCXXFLAGS
+The maintainer's variant of @code{OBJCXXFLAGS}.
+
+ at item OBJCXXCOMPILE
+The command used to actually compile an Objective C++ source file. The
+file name is appended to form the complete command line.
+
+ at item OBJCXXLINK
+The command used to actually link an Objective C++ program.
+ at end vtable
+
+
+ at node Unified Parallel C Support
+ at section Unified Parallel C Support
+
+ at cindex Unified Parallel C support
+ at cindex Support for Unified Parallel C
+
+Automake includes some support for Unified Parallel C.
+
+Any package including Unified Parallel C code must define the output
+variable @code{UPC} in @file{configure.ac}; the simplest way to do
+this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
+
+A few additional variables are defined when a Unified Parallel C
+source file is seen:
+
+ at vtable @code
+ at item UPC
+The name of the Unified Parallel C compiler.
+
+ at item UPCFLAGS
+Any flags to pass to the Unified Parallel C compiler.
+
+ at item AM_UPCFLAGS
+The maintainer's variant of @code{UPCFLAGS}.
+
+ at item UPCCOMPILE
+The command used to actually compile a Unified Parallel C source file.
+The file name is appended to form the complete command line.
+
+ at item UPCLINK
+The command used to actually link a Unified Parallel C program.
+ at end vtable
+
+
+ at node Assembly Support
+ at section Assembly Support
+
+Automake includes some support for assembly code. There are two forms
+of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
+(@file{*.S} or @file{*.sx}).
+
+ at vindex CCAS
+ at vindex CCASFLAGS
+ at vindex CPPFLAGS
+ at vindex AM_CCASFLAGS
+ at vindex AM_CPPFLAGS
+The variable @code{CCAS} holds the name of the compiler used to build
+assembly code. This compiler must work a bit like a C compiler; in
+particular it must accept @option{-c} and @option{-o}. The values of
+ at code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
+definition) is passed to the compilation. For preprocessed files,
+ at code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
+and @code{AM_CPPFLAGS} are also used.
+
+The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
+ at code{CCASFLAGS} for you (unless they are already set, it simply sets
+ at code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
+flags), but you are free to define these variables by other means.
+
+Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
+ at command{automake} as being files containing assembly code.
+
+
+ at node Fortran 77 Support
+ at comment node-name, next, previous, up
+ at section Fortran 77 Support
+
+ at cindex Fortran 77 support
+ at cindex Support for Fortran 77
+
+Automake includes full support for Fortran 77.
+
+Any package including Fortran 77 code must define the output variable
+ at code{F77} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when a Fortran 77 source file is
+seen:
+
+ at vtable @code
+
+ at item F77
+The name of the Fortran 77 compiler.
+
+ at item FFLAGS
+Any flags to pass to the Fortran 77 compiler.
+
+ at item AM_FFLAGS
+The maintainer's variant of @code{FFLAGS}.
+
+ at item RFLAGS
+Any flags to pass to the Ratfor compiler.
+
+ at item AM_RFLAGS
+The maintainer's variant of @code{RFLAGS}.
+
+ at item F77COMPILE
+The command used to actually compile a Fortran 77 source file. The file
+name is appended to form the complete command line.
+
+ at item FLINK
+The command used to actually link a pure Fortran 77 program or shared
+library.
+
+ at end vtable
+
+Automake can handle preprocessing Fortran 77 and Ratfor source files in
+addition to compiling them at footnote{Much, if not most, of the
+information in the following sections pertaining to preprocessing
+Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
+Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
+also contains some support for creating programs and shared libraries
+that are a mixture of Fortran 77 and other languages (@pxref{Mixing
+Fortran 77 With C and C++}).
+
+These issues are covered in the following sections.
+
+ at menu
+* 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++
+ at end menu
+
+
+ at node Preprocessing Fortran 77
+ at comment node-name, next, previous, up
+ at subsection Preprocessing Fortran 77
+
+ at cindex Preprocessing Fortran 77
+ at cindex Fortran 77, Preprocessing
+ at cindex Ratfor programs
+
+ at file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
+rule runs just the preprocessor to convert a preprocessable Fortran 77
+or Ratfor source file into a strict Fortran 77 source file. The precise
+command used is as follows:
+
+ at table @file
+
+ at item .F
+ at code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
+$(AM_FFLAGS) $(FFLAGS)}
+
+ at item .r
+ at code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
+
+ at end table
+
+
+ at node Compiling Fortran 77 Files
+ at comment node-name, next, previous, up
+ at subsection Compiling Fortran 77 Files
+
+ at file{N.o} is made automatically from @file{N.f}, @file{N.F} or
+ at file{N.r} by running the Fortran 77 compiler. The precise command used
+is as follows:
+
+ at table @file
+
+ at item .f
+ at code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
+
+ at item .F
+ at code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
+$(AM_FFLAGS) $(FFLAGS)}
+
+ at item .r
+ at code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
+
+ at end table
+
+
+ at node Mixing Fortran 77 With C and C++
+ at comment node-name, next, previous, up
+ at subsection Mixing Fortran 77 With C and C++
+
+ at cindex Fortran 77, mixing with C and C++
+ at cindex Mixing Fortran 77 with C and C++
+ at cindex Linking Fortran 77 with C and C++
+ at cindex cfortran
+ at cindex Mixing Fortran 77 with C and/or C++
+
+Automake currently provides @emph{limited} support for creating programs
+and shared libraries that are a mixture of Fortran 77 and C and/or C++.
+However, there are many other issues related to mixing Fortran 77 with
+other languages that are @emph{not} (currently) handled by Automake, but
+that are handled by other packages at footnote{For example,
+ at uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
+addresses all of these inter-language issues, and runs under nearly all
+Fortran 77, C and C++ compilers on nearly all platforms. However,
+ at command{cfortran} is not yet Free Software, but it will be in the next
+major release.}.
+
+Automake can help in two ways:
+
+ at enumerate
+ at item
+Automatic selection of the linker depending on which combinations of
+source code.
+
+ at item
+Automatic selection of the appropriate linker flags (e.g., @option{-L} and
+ at option{-l}) to pass to the automatically selected linker in order to link
+in the appropriate Fortran 77 intrinsic and run-time libraries.
+
+ at cindex @code{FLIBS}, defined
+ at vindex FLIBS
+These extra Fortran 77 linker flags are supplied in the output variable
+ at code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
+ at xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
+The Autoconf Manual}.
+ at end enumerate
+
+If Automake detects that a program or shared library (as mentioned in
+some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
+code that is a mixture of Fortran 77 and C and/or C++, then it requires
+that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
+ at file{configure.ac}, and that either @code{$(FLIBS)}
+appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
+(for shared libraries) variables. It is the responsibility of the
+person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
+appears in the appropriate @code{_LDADD} or
+ at code{_LIBADD} variable.
+
+ at cindex Mixed language example
+ at cindex Example, mixed language
+
+For example, consider the following @file{Makefile.am}:
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = main.cc foo.f
+foo_LDADD = libfoo.la $(FLIBS)
+
+pkglib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = bar.f baz.c zardoz.cc
+libfoo_la_LIBADD = $(FLIBS)
+ at end example
+
+In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
+is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
+been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
+Automake would have issued a warning.
+
+ at menu
+* How the Linker is Chosen:: Automatic linker selection
+ at end menu
+
+ at node How the Linker is Chosen
+ at comment node-name, next, previous, up
+ at subsubsection How the Linker is Chosen
+
+ at cindex Automatic linker selection
+ at cindex Selecting the linker automatically
+
+When a program or library mixes several languages, Automake choose the
+linker according to the following priorities. (The names in
+parentheses are the variables containing the link command.)
+
+ at enumerate
+ at item
+ at vindex GCJLINK
+Native Java (@code{GCJLINK})
+ at item
+ at vindex OBJCXXLINK
+Objective C++ (@code{OBJCXXLINK})
+ at item
+ at vindex CXXLINK
+C++ (@code{CXXLINK})
+ at item
+ at vindex F77LINK
+Fortran 77 (@code{F77LINK})
+ at item
+ at vindex FCLINK
+Fortran (@code{FCLINK})
+ at item
+ at vindex OBJCLINK
+Objective C (@code{OBJCLINK})
+ at item
+ at vindex UPCLINK
+Unified Parallel C (@code{UPCLINK})
+ at item
+ at vindex LINK
+C (@code{LINK})
+ at end enumerate
+
+For example, if Fortran 77, C and C++ source code is compiled
+into a program, then the C++ linker will be used. In this case, if the
+C or Fortran 77 linkers required any special libraries that weren't
+included by the C++ linker, then they must be manually added to an
+ at code{_LDADD} or @code{_LIBADD} variable by the user writing the
+ at file{Makefile.am}.
+
+Automake only looks at the file names listed in @file{_SOURCES}
+variables to choose the linker, and defaults to the C linker.
+Sometimes this is inconvenient because you are linking against a
+library written in another language and would like to set the linker
+more appropriately. @xref{Libtool Convenience Libraries}, for a
+trick with @code{nodist_EXTRA_ at dots{}_SOURCES}.
+
+A per-target @code{_LINK} variable will override the above selection.
+Per-target link flags will cause Automake to write a per-target
+ at code{_LINK} variable according to the language chosen as above.
+
+
+ at node Fortran 9x Support
+ at comment node-name, next, previous, up
+ at section Fortran 9x Support
+
+ at cindex Fortran 9x support
+ at cindex Support for Fortran 9x
+
+Automake includes support for Fortran 9x.
+
+Any package including Fortran 9x code must define the output variable
+ at code{FC} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when a Fortran 9x source file is
+seen:
+
+ at vtable @code
+
+ at item FC
+The name of the Fortran 9x compiler.
+
+ at item FCFLAGS
+Any flags to pass to the Fortran 9x compiler.
+
+ at item AM_FCFLAGS
+The maintainer's variant of @code{FCFLAGS}.
+
+ at item FCCOMPILE
+The command used to actually compile a Fortran 9x source file. The file
+name is appended to form the complete command line.
+
+ at item FCLINK
+The command used to actually link a pure Fortran 9x program or shared
+library.
+
+ at end vtable
+
+ at menu
+* Compiling Fortran 9x Files:: Compiling Fortran 9x sources
+ at end menu
+
+ at node Compiling Fortran 9x Files
+ at comment node-name, next, previous, up
+ at subsection Compiling Fortran 9x Files
+
+ at file{@var{file}.o} is made automatically from @file{@var{file}.f90},
+ at file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
+by running the Fortran 9x compiler. The precise command used
+is as follows:
+
+ at table @file
+
+ at item .f90
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
+
+ at item .f95
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
+
+ at item .f03
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
+
+ at item .f08
+ at code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
+
+ at end table
+
+ at node Java Support with gcj
+ at comment node-name, next, previous, up
+ at section Compiling Java sources using gcj
+
+ at cindex Java support with gcj
+ at cindex Support for Java with gcj
+ at cindex Java to native code, compilation
+ at cindex Compilation of Java to native code
+
+Automake includes support for natively compiled Java, using @command{gcj},
+the Java front end to the GNU Compiler Collection (rudimentary support
+for compiling Java to bytecode using the @command{javac} compiler is
+also present, @emph{albeit deprecated}; @pxref{Java}).
+
+Any package including Java code to be compiled must define the output
+variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
+must also be defined somehow (either in @file{configure.ac} or
+ at file{Makefile.am}). The simplest way to do this is to use the
+ at code{AM_PROG_GCJ} macro.
+
+ at vindex GCJFLAGS
+
+By default, programs including Java source files are linked with
+ at command{gcj}.
+
+As always, the contents of @code{AM_GCJFLAGS} are passed to every
+compilation invoking @command{gcj} (in its role as an ahead-of-time
+compiler, when invoking it to create @file{.class} files,
+ at code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
+options to @command{gcj} from @file{Makefile.am}, this variable, and not
+the user variable @code{GCJFLAGS}, should be used.
+
+ at vindex AM_GCJFLAGS
+
+ at command{gcj} can be used to compile @file{.java}, @file{.class},
+ at file{.zip}, or @file{.jar} files.
+
+When linking, @command{gcj} requires that the main class be specified
+using the @option{--main=} option. The easiest way to do this is to use
+the @code{_LDFLAGS} variable for the program.
+
+
+ at node Vala Support
+ at comment node-name, next, previous, up
+ at section Vala Support
+
+ at cindex Vala Support
+ at cindex Support for Vala
+
+Automake provides initial support for Vala
+(@uref{http://www.vala-project.org/}).
+This requires valac version 0.7.0 or later, and currently requires
+the user to use GNU @command{make}.
+
+ at example
+foo_SOURCES = foo.vala bar.vala zardoc.c
+ at end example
+
+Any @file{.vala} file listed in a @code{_SOURCES} variable will be
+compiled into C code by the Vala compiler. The generated @file{.c} files
+are distributed. The end user does not need to have a Vala compiler installed.
+
+Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
+that will locate the Vala compiler and optionally check its version
+number.
+
+ at defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
+ @ovar{action-if-not-found})
+Search for a Vala compiler in @env{PATH}. If it is found, the variable
+ at code{VALAC} is set to point to it (see below for more details). This
+macro takes three optional arguments. The first argument, if present,
+is the minimum version of the Vala compiler required to compile this
+package. If a compiler is found and satisfies @var{minimum-version},
+then @var{action-if-found} is run (this defaults to do nothing).
+Otherwise, @var{action-if-not-found} is run. If @var{action-if-not-found}
+is not specified, the default value is to print a warning in case no
+compiler is found, or if a too-old version of the compiler is found.
+ at end defmac
+
+There are a few variables that are used when compiling Vala sources:
+
+ at vtable @code
+ at item VALAC
+Absolute path to the Vala compiler, or simply @samp{valac} if no
+suitable compiler Vala could be found at configure runtime.
+
+ at item VALAFLAGS
+Additional arguments for the Vala compiler.
+
+ at item AM_VALAFLAGS
+The maintainer's variant of @code{VALAFLAGS}.
+
+ at example
+lib_LTLIBRARIES = libfoo.la
+libfoo_la_SOURCES = foo.vala
+ at end example
+ at end vtable
+
+Note that currently, you cannot use per-target @code{*_VALAFLAGS}
+(@pxref{Renamed Objects}) to produce different C files from one Vala
+source file.
+
+
+ at node Support for Other Languages
+ at comment node-name, next, previous, up
+ at section Support for Other Languages
+
+Automake currently only includes full support for C, C++ (@pxref{C++
+Support}), Objective C (@pxref{Objective C Support}),
+Objective C++ (@pxref{Objective C++ Support}),
+Fortran 77
+(@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
+and Java (@pxref{Java Support with gcj}). There is only rudimentary
+support for other languages, support for which will be improved based
+on user demand.
+
+Some limited support for adding your own languages is available via the
+suffix rule handling (@pxref{Suffixes}).
+
+ at node Dependencies
+ at section Automatic dependency tracking
+
+As a developer it is often painful to continually update the
+ at file{Makefile.am} whenever the include-file dependencies change in a
+project. Automake supplies a way to automatically track dependency
+changes (@pxref{Dependency Tracking}).
+
+ at cindex Dependency tracking
+ at cindex Automatic dependency tracking
+
+Automake always uses complete dependencies for a compilation,
+including system headers. Automake's model is that dependency
+computation should be a side effect of the build. To this end,
+dependencies are computed by running all compilations through a
+special wrapper program called @command{depcomp}. @command{depcomp}
+understands how to coax many different C and C++ compilers into
+generating dependency information in the format it requires.
+ at samp{automake -a} will install @command{depcomp} into your source
+tree for you. If @command{depcomp} can't figure out how to properly
+invoke your compiler, dependency tracking will simply be disabled for
+your build.
+
+ at cindex @command{depcomp}
+
+Experience with earlier versions of Automake (@pxref{Dependency Tracking
+Evolution, , Dependency Tracking Evolution, automake-history, Brief History
+of Automake}) taught us that it is not reliable to generate dependencies
+only on the maintainer's system, as configurations vary too much. So
+instead Automake implements dependency tracking at build time.
+
+Automatic dependency tracking can be suppressed by putting
+ at option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
+passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
+(this should be the preferred way). Or, you can invoke @command{automake}
+with the @option{-i} option. Dependency tracking is enabled by default.
+
+ at vindex AUTOMAKE_OPTIONS
+ at opindex no-dependencies
+
+The person building your package also can choose to disable dependency
+tracking by configuring with @option{--disable-dependency-tracking}.
+
+ at cindex Disabling dependency tracking
+ at cindex Dependency tracking, disabling
+
+
+ at node EXEEXT
+ at section Support for executable extensions
+
+ at cindex Executable extension
+ at cindex Extension, executable
+ at cindex Windows
+
+On some platforms, such as Windows, executables are expected to have an
+extension such as @file{.exe}. On these platforms, some compilers (GCC
+among them) will automatically generate @file{foo.exe} when asked to
+generate @file{foo}.
+
+Automake provides mostly-transparent support for this. Unfortunately
+ at emph{mostly} doesn't yet mean @emph{fully}. Until the English
+dictionary is revised, you will have to assist Automake if your package
+must support those platforms.
+
+One thing you must be aware of is that, internally, Automake rewrites
+something like this:
+
+ at example
+bin_PROGRAMS = liver
+ at end example
+
+to this:
+
+ at example
+bin_PROGRAMS = liver$(EXEEXT)
+ at end example
+
+The targets Automake generates are likewise given the @samp{$(EXEEXT)}
+extension.
+
+The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
+are also rewritten if they contain filenames that have been declared as
+programs in the same @file{Makefile}. (This is mostly useful when some
+programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
+
+However, Automake cannot apply this rewriting to @command{configure}
+substitutions. This means that if you are conditionally building a
+program using such a substitution, then your @file{configure.ac} must
+take care to add @samp{$(EXEEXT)} when constructing the output variable.
+
+Sometimes maintainers like to write an explicit link rule for their
+program. Without executable extension support, this is easy---you
+simply write a rule whose target is the name of the program. However,
+when executable extension support is enabled, you must instead add the
+ at samp{$(EXEEXT)} suffix.
+
+This might be a nuisance for maintainers who know their package will
+never run on a platform that has
+executable extensions. For those maintainers, the @option{no-exeext}
+option (@pxref{Options}) will disable this feature. This works in a
+fairly ugly way; if @option{no-exeext} is seen, then the presence of a
+rule for a target named @code{foo} in @file{Makefile.am} will override
+an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
+the @option{no-exeext} option, this use will give a diagnostic.
+
+
+ at node Other Objects
+ at chapter Other Derived Objects
+
+Automake can handle derived objects that are not C programs. Sometimes
+the support for actually building such objects must be explicitly
+supplied, but Automake will still automatically handle installation and
+distribution.
+
+ at menu
+* Scripts:: Executable scripts
+* Headers:: Header files
+* Data:: Architecture-independent data files
+* Sources:: Derived sources
+ at end menu
+
+
+ at node Scripts
+ at section Executable Scripts
+
+ at cindex @code{_SCRIPTS} primary, defined
+ at cindex @code{SCRIPTS} primary, defined
+ at cindex Primary variable, @code{SCRIPTS}
+ at vindex _SCRIPTS
+ at cindex Installing scripts
+
+It is possible to define and install programs that are scripts. Such
+programs are listed using the @code{SCRIPTS} primary name. When the
+script is distributed in its final, installable form, the
+ at file{Makefile} usually looks as follows:
+ at vindex SCRIPTS
+
+ at example
+# Install my_script in $(bindir) and distribute it.
+dist_bin_SCRIPTS = my_script
+ at end example
+
+Scripts are not distributed by default; as we have just seen, those
+that should be distributed can be specified using a @code{dist_}
+prefix as with other primaries.
+
+ at cindex @code{SCRIPTS}, installation directories
+ at vindex bin_SCRIPTS
+ at vindex sbin_SCRIPTS
+ at vindex libexec_SCRIPTS
+ at vindex pkgdata_SCRIPTS
+ at vindex pkglibexec_SCRIPTS
+ at vindex noinst_SCRIPTS
+ at vindex check_SCRIPTS
+
+Scripts can be installed in @code{bindir}, @code{sbindir},
+ at code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
+
+Scripts that need not be installed can be listed in
+ at code{noinst_SCRIPTS}, and among them, those which are needed only by
+ at samp{make check} should go in @code{check_SCRIPTS}.
+
+When a script needs to be built, the @file{Makefile.am} should include
+the appropriate rules. For instance the @command{automake} program
+itself is a Perl script that is generated from @file{automake.in}.
+Here is how this is handled:
+
+ at example
+bin_SCRIPTS = automake
+CLEANFILES = $(bin_SCRIPTS)
+EXTRA_DIST = automake.in
+
+do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
+ -e 's,[@@]PERL[@@],$(PERL),g' \
+ -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
+ -e 's,[@@]VERSION[@@],$(VERSION),g' \
+ @dots{}
+
+automake: automake.in Makefile
+ $(do_subst) < $(srcdir)/automake.in > automake
+ chmod +x automake
+ at end example
+
+Such scripts for which a build rule has been supplied need to be
+deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
+sources have to be distributed, usually with @code{EXTRA_DIST}
+(@pxref{Basics of Distribution}).
+
+Another common way to build scripts is to process them from
+ at file{configure} with @code{AC_CONFIG_FILES}. In this situation
+Automake knows which files should be cleaned and distributed, and what
+the rebuild rules should look like.
+
+For instance if @file{configure.ac} contains
+
+ at example
+AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
+ at end example
+
+ at noindent
+to build @file{src/my_script} from @file{src/my_script.in}, then a
+ at file{src/Makefile.am} to install this script in @code{$(bindir)} can
+be as simple as
+
+ at example
+bin_SCRIPTS = my_script
+CLEANFILES = $(bin_SCRIPTS)
+ at end example
+
+ at noindent
+There is no need for @code{EXTRA_DIST} or any build rule: Automake
+infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
+ at code{CLEANFILES} is still useful, because by default Automake will
+clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
+ at code{clean}.
+
+Although this looks simpler, building scripts this way has one
+drawback: directory variables such as @code{$(datadir)} are not fully
+expanded and may refer to other directory variables.
+
+ at node Headers
+ at section Header files
+
+ at cindex @code{_HEADERS} primary, defined
+ at cindex @code{HEADERS} primary, defined
+ at cindex Primary variable, @code{HEADERS}
+ at vindex _HEADERS
+ at vindex noinst_HEADERS
+ at cindex @code{HEADERS}, installation directories
+ at cindex Installing headers
+ at vindex include_HEADERS
+ at vindex oldinclude_HEADERS
+ at vindex pkginclude_HEADERS
+
+
+Header files that must be installed are specified by the
+ at code{HEADERS} family of variables. Headers can be installed in
+ at code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
+other directory you may have defined (@pxref{Uniform}). For instance,
+
+ at example
+include_HEADERS = foo.h bar/bar.h
+ at end example
+
+ at noindent
+will install the two files as @file{$(includedir)/foo.h} and
+ at file{$(includedir)/bar.h}.
+
+The @code{nobase_} prefix is also supported,
+
+ at example
+nobase_include_HEADERS = foo.h bar/bar.h
+ at end example
+
+ at noindent
+will install the two files as @file{$(includedir)/foo.h} and
+ at file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
+
+ at vindex noinst_HEADERS
+Usually, only header files that accompany installed libraries need to
+be installed. Headers used by programs or convenience libraries are
+not installed. The @code{noinst_HEADERS} variable can be used for
+such headers. However when the header actually belongs to a single
+convenience library or program, we recommend listing it in the
+program's or library's @code{_SOURCES} variable (@pxref{Program
+Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
+the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
+right variable to use in a directory containing only headers and no
+associated library or program.
+
+All header files must be listed somewhere; in a @code{_SOURCES}
+variable or in a @code{_HEADERS} variable. Missing ones will not
+appear in the distribution.
+
+For header files that are built and must not be distributed, use the
+ at code{nodist_} prefix as in @code{nodist_include_HEADERS} or
+ at code{nodist_prog_SOURCES}. If these generated headers are needed
+during the build, you must also ensure they exist before they are
+used (@pxref{Sources}).
+
+
+ at node Data
+ at section Architecture-independent data files
+
+ at cindex @code{_DATA} primary, defined
+ at cindex @code{DATA} primary, defined
+ at cindex Primary variable, @code{DATA}
+ at vindex _DATA
+
+Automake supports the installation of miscellaneous data files using the
+ at code{DATA} family of variables.
+ at vindex DATA
+
+ at vindex data_DATA
+ at vindex sysconf_DATA
+ at vindex sharedstate_DATA
+ at vindex localstate_DATA
+ at vindex pkgdata_DATA
+
+Such data can be installed in the directories @code{datadir},
+ at code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
+ at code{pkgdatadir}.
+
+By default, data files are @emph{not} included in a distribution. Of
+course, you can use the @code{dist_} prefix to change this on a
+per-variable basis.
+
+Here is how Automake declares its auxiliary data files:
+
+ at example
+dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
+ at end example
+
+
+ at node Sources
+ at section Built Sources
+
+Because Automake's automatic dependency tracking works as a side-effect
+of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
+target should not be compiled before its dependencies are made, but
+these dependencies are unknown until the target is first compiled.
+
+Ordinarily this is not a problem, because dependencies are distributed
+sources: they preexist and do not need to be built. Suppose that
+ at file{foo.c} includes @file{foo.h}. When it first compiles
+ at file{foo.o}, @command{make} only knows that @file{foo.o} depends on
+ at file{foo.c}. As a side-effect of this compilation @command{depcomp}
+records the @file{foo.h} dependency so that following invocations of
+ at command{make} will honor it. In these conditions, it's clear there is
+no problem: either @file{foo.o} doesn't exist and has to be built
+(regardless of the dependencies), or accurate dependencies exist and
+they can be used to decide whether @file{foo.o} should be rebuilt.
+
+It's a different story if @file{foo.h} doesn't exist by the first
+ at command{make} run. For instance, there might be a rule to build
+ at file{foo.h}. This time @file{file.o}'s build will fail because the
+compiler can't find @file{foo.h}. @command{make} failed to trigger the
+rule to build @file{foo.h} first by lack of dependency information.
+
+ at vindex BUILT_SOURCES
+ at cindex @code{BUILT_SOURCES}, defined
+
+The @code{BUILT_SOURCES} variable is a workaround for this problem. A
+source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
+or @samp{make check} (or even @samp{make install}) before other
+targets are processed. However, such a source file is not
+ at emph{compiled} unless explicitly requested by mentioning it in some
+other @code{_SOURCES} variable.
+
+So, to conclude our introductory example, we could use
+ at samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
+any other target (including @file{foo.o}) during @samp{make all} or
+ at samp{make check}.
+
+ at code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
+must be created early in the build process can be listed in this
+variable. Moreover, all built sources do not necessarily have to be
+listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
+doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
+another source), because it's a known dependency of the associated
+object.
+
+It might be important to emphasize that @code{BUILT_SOURCES} is
+honored only by @samp{make all}, @samp{make check} and @samp{make
+install}. This means you cannot build a specific target (e.g.,
+ at samp{make foo}) in a clean tree if it depends on a built source.
+However it will succeed if you have run @samp{make all} earlier,
+because accurate dependencies are already available.
+
+The next section illustrates and discusses the handling of built sources
+on a toy example.
+
+ at menu
+* Built Sources Example:: Several ways to handle built sources.
+ at end menu
+
+ at node Built Sources Example
+ at subsection Built Sources Example
+
+Suppose that @file{foo.c} includes @file{bindir.h}, which is
+installation-dependent and not distributed: it needs to be built. Here
+ at file{bindir.h} defines the preprocessor macro @code{bindir} to the
+value of the @command{make} variable @code{bindir} (inherited from
+ at file{configure}).
+
+We suggest several implementations below. It's not meant to be an
+exhaustive listing of all ways to handle built sources, but it will give
+you a few ideas if you encounter this issue.
+
+ at subsubheading First Try
+
+This first implementation will illustrate the bootstrap issue mentioned
+in the previous section (@pxref{Sources}).
+
+Here is a tentative @file{Makefile.am}.
+
+ at example
+# This won't work.
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+nodist_foo_SOURCES = bindir.h
+CLEANFILES = bindir.h
+bindir.h: Makefile
+ echo '#define bindir "$(bindir)"' >$@@
+ at end example
+
+This setup doesn't work, because Automake doesn't know that @file{foo.c}
+includes @file{bindir.h}. Remember, automatic dependency tracking works
+as a side-effect of compilation, so the dependencies of @file{foo.o} will
+be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
+The symptom is as follows.
+
+ at example
+% make
+source='foo.c' object='foo.o' libtool=no \
+depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
+depmode=gcc /bin/sh ./depcomp \
+gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
+foo.c:2: bindir.h: No such file or directory
+make: *** [foo.o] Error 1
+ at end example
+
+In this example @file{bindir.h} is not distributed nor installed, and
+it is not even being built on-time. One may wonder if the
+ at samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
+line simply states that @file{bindir.h} is a source of @code{foo}, so
+for instance, it should be inspected while generating tags
+(@pxref{Tags}). In other words, it does not help our present problem,
+and the build would fail identically without it.
+
+ at subsubheading Using @code{BUILT_SOURCES}
+
+A solution is to require @file{bindir.h} to be built before anything
+else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+nodist_foo_SOURCES = bindir.h
+BUILT_SOURCES = bindir.h
+CLEANFILES = bindir.h
+bindir.h: Makefile
+ echo '#define bindir "$(bindir)"' >$@@
+ at end example
+
+See how @file{bindir.h} gets built first:
+
+ at example
+% make
+echo '#define bindir "/usr/local/bin"' >bindir.h
+make all-am
+make[1]: Entering directory `/home/adl/tmp'
+source='foo.c' object='foo.o' libtool=no \
+depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
+depmode=gcc /bin/sh ./depcomp \
+gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
+gcc -g -O2 -o foo foo.o
+make[1]: Leaving directory `/home/adl/tmp'
+ at end example
+
+However, as said earlier, @code{BUILT_SOURCES} applies only to the
+ at code{all}, @code{check}, and @code{install} targets. It still fails
+if you try to run @samp{make foo} explicitly:
+
+ at example
+% make clean
+test -z "bindir.h" || rm -f bindir.h
+test -z "foo" || rm -f foo
+rm -f *.o
+% : > .deps/foo.Po # Suppress previously recorded dependencies
+% make foo
+source='foo.c' object='foo.o' libtool=no \
+depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
+depmode=gcc /bin/sh ./depcomp \
+gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
+foo.c:2: bindir.h: No such file or directory
+make: *** [foo.o] Error 1
+ at end example
+
+ at subsubheading Recording Dependencies manually
+
+Usually people are happy enough with @code{BUILT_SOURCES} because they
+never build targets such as @samp{make foo} before @samp{make all}, as
+in the previous example. However if this matters to you, you can
+avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
+the @file{Makefile.am}.
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+nodist_foo_SOURCES = bindir.h
+foo.$(OBJEXT): bindir.h
+CLEANFILES = bindir.h
+bindir.h: Makefile
+ echo '#define bindir "$(bindir)"' >$@@
+ at end example
+
+You don't have to list @emph{all} the dependencies of @file{foo.o}
+explicitly, only those that might need to be built. If a dependency
+already exists, it will not hinder the first compilation and will be
+recorded by the normal dependency tracking code. (Note that after
+this first compilation the dependency tracking code will also have
+recorded the dependency between @file{foo.o} and
+ at file{bindir.h}; so our explicit dependency is really useful to
+the first build only.)
+
+Adding explicit dependencies like this can be a bit dangerous if you are
+not careful enough. This is due to the way Automake tries not to
+overwrite your rules (it assumes you know better than it).
+ at samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
+output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
+because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
+target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
+Always check the generated @file{Makefile.in} if you do this.
+
+ at subsubheading Build @file{bindir.h} from @file{configure}
+
+It's possible to define this preprocessor macro from @file{configure},
+either in @file{config.h} (@pxref{Defining Directories, , Defining
+Directories, autoconf, The Autoconf Manual}), or by processing a
+ at file{bindir.h.in} file using @code{AC_CONFIG_FILES}
+(@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
+Autoconf Manual}).
+
+At this point it should be clear that building @file{bindir.h} from
+ at file{configure} works well for this example. @file{bindir.h} will exist
+before you build any target, hence will not cause any dependency issue.
+
+The Makefile can be shrunk as follows. We do not even have to mention
+ at file{bindir.h}.
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+ at end example
+
+However, it's not always possible to build sources from
+ at file{configure}, especially when these sources are generated by a tool
+that needs to be built first.
+
+ at subsubheading Build @file{bindir.c}, not @file{bindir.h}.
+
+Another attractive idea is to define @code{bindir} as a variable or
+function exported from @file{bindir.o}, and build @file{bindir.c}
+instead of @file{bindir.h}.
+
+ at example
+noinst_PROGRAMS = foo
+foo_SOURCES = foo.c bindir.h
+nodist_foo_SOURCES = bindir.c
+CLEANFILES = bindir.c
+bindir.c: Makefile
+ echo 'const char bindir[] = "$(bindir)";' >$@@
+ at end example
+
+ at file{bindir.h} contains just the variable's declaration and doesn't
+need to be built, so it won't cause any trouble. @file{bindir.o} is
+always dependent on @file{bindir.c}, so @file{bindir.c} will get built
+first.
+
+ at subsubheading Which is best?
+
+There is no panacea, of course. Each solution has its merits and
+drawbacks.
+
+You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
+foo} on a clean tree is important to you.
+
+You won't add explicit dependencies if you are leery of overriding
+an Automake rule by mistake.
+
+Building files from @file{./configure} is not always possible, neither
+is converting @file{.h} files into @file{.c} files.
+
+
+ at node Other GNU Tools
+ at chapter Other GNU Tools
+
+Since Automake is primarily intended to generate @file{Makefile.in}s for
+use in GNU programs, it tries hard to interoperate with other GNU tools.
+
+ at menu
+* Emacs Lisp:: Emacs Lisp
+* gettext:: Gettext
+* Libtool:: Libtool
+* Java:: Java bytecode compilation (deprecated)
+* Python:: Python
+ at end menu
+
+
+ at node Emacs Lisp
+ at section Emacs Lisp
+
+ at cindex @code{_LISP} primary, defined
+ at cindex @code{LISP} primary, defined
+ at cindex Primary variable, @code{LISP}
+
+ at vindex _LISP
+ at vindex lisp_LISP
+ at vindex noinst_LISP
+
+Automake provides some support for Emacs Lisp. The @code{LISP} primary
+is used to hold a list of @file{.el} files. Possible prefixes for this
+primary are @code{lisp_} and @code{noinst_}. Note that if
+ at code{lisp_LISP} is defined, then @file{configure.ac} must run
+ at code{AM_PATH_LISPDIR} (@pxref{Macros}).
+
+ at vindex dist_lisp_LISP
+ at vindex dist_noinst_LISP
+Lisp sources are not distributed by default. You can prefix the
+ at code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
+ at code{dist_noinst_LISP}, to indicate that these files should be
+distributed.
+
+Automake will byte-compile all Emacs Lisp source files using the Emacs
+found by @code{AM_PATH_LISPDIR}, if any was found. When performing such
+byte-compilation, the flags specified in the (developer-reserved)
+ at code{AM_ELCFLAGS} and (user-reserved) @code{ELCFLAGS} make variables
+will be passed to the Emacs invocation.
+
+Byte-compiled Emacs Lisp files are not portable among all versions of
+Emacs, so it makes sense to turn this off if you expect sites to have
+more than one version of Emacs installed. Furthermore, many packages
+don't actually benefit from byte-compilation. Still, we recommend
+that you byte-compile your Emacs Lisp sources. It is probably better
+for sites with strange setups to cope for themselves than to make the
+installation less nice for everybody else.
+
+There are two ways to avoid byte-compiling. Historically, we have
+recommended the following construct.
+
+ at example
+lisp_LISP = file1.el file2.el
+ELCFILES =
+ at end example
+
+ at noindent
+ at code{ELCFILES} is an internal Automake variable that normally lists
+all @file{.elc} files that must be byte-compiled. Automake defines
+ at code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
+variable explicitly prevents byte-compilation.
+
+Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at example
+lisp_DATA = file1.el file2.el
+ at end example
+
+Note that these two constructs are not equivalent. @code{_LISP} will
+not install a file if Emacs is not installed, while @code{_DATA} will
+always install its files.
+
+ at node gettext
+ at section Gettext
+
+ at cindex GNU Gettext support
+ at cindex Gettext support
+ at cindex Support for GNU Gettext
+
+If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
+turns on support for GNU gettext, a message catalog system for
+internationalization
+(@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
+
+The @code{gettext} support in Automake requires the addition of one or
+two subdirectories to the package: @file{po} and possibly also @file{intl}.
+The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
+ at samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
+Automake ensures that these directories exist and are mentioned in
+ at code{SUBDIRS}.
+
+ at node Libtool
+ at section Libtool
+
+Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
+libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
+ at xref{A Shared Library}.
+
+
+ at node Java
+ at section Java bytecode compilation (deprecated)
+
+ at cindex @code{_JAVA} primary, defined
+ at cindex @code{JAVA} primary, defined
+ at cindex Primary variable, @code{JAVA}
+ at cindex Java to bytecode, compilation
+ at cindex Compilation of Java to bytecode
+
+Automake provides some minimal support for Java bytecode compilation with
+the @code{JAVA} primary (in addition to the support for compiling Java to
+native machine code; @pxref{Java Support with gcj}). Note however that
+ at emph{the interface and most features described here are deprecated}.
+Future Automake releases will strive to provide a better and cleaner
+interface, which however @emph{won't be backward-compatible}; the present
+interface will probably be removed altogether some time after the
+introduction of the new interface (if that ever materializes).
+
+Any @file{.java} files listed in a @code{_JAVA} variable will be
+compiled with @code{JAVAC} at build time. By default, @file{.java}
+files are not included in the distribution, you should use the
+ at code{dist_} prefix to distribute them.
+
+Here is a typical setup for distributing @file{.java} files and
+installing the @file{.class} files resulting from their compilation.
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at example
+javadir = $(datadir)/java
+dist_java_JAVA = a.java b.java @dots{}
+ at end example
+
+ at cindex @code{JAVA} restrictions
+ at cindex Restrictions for @code{JAVA}
+
+Currently Automake enforces the restriction that only one @code{_JAVA}
+primary can be used in a given @file{Makefile.am}. The reason for this
+restriction is that, in general, it isn't possible to know which
+ at file{.class} files were generated from which @file{.java} files, so
+it would be impossible to know which files to install where. For
+instance, a @file{.java} file can define multiple classes; the resulting
+ at file{.class} file names cannot be predicted without parsing the
+ at file{.java} file.
+
+There are a few variables that are used when compiling Java sources:
+
+ at vtable @code
+ at item JAVAC
+The name of the Java compiler. This defaults to @samp{javac}.
+
+ at item JAVACFLAGS
+The flags to pass to the compiler. This is considered to be a user
+variable (@pxref{User Variables}).
+
+ at item AM_JAVACFLAGS
+More flags to pass to the Java compiler. This, and not
+ at code{JAVACFLAGS}, should be used when it is necessary to put Java
+compiler flags into @file{Makefile.am}.
+
+ at item JAVAROOT
+The value of this variable is passed to the @option{-d} option to
+ at code{javac}. It defaults to @samp{$(top_builddir)}.
+
+ at item CLASSPATH_ENV
+This variable is a shell expression that is used to set the
+ at env{CLASSPATH} environment variable on the @code{javac} command line.
+(In the future we will probably handle class path setting differently.)
+ at end vtable
+
+
+ at node Python
+ at section Python
+
+ at cindex @code{_PYTHON} primary, defined
+ at cindex @code{PYTHON} primary, defined
+ at cindex Primary variable, @code{PYTHON}
+ at vindex _PYTHON
+
+Automake provides support for Python compilation with the
+ at code{PYTHON} primary. A typical setup is to call
+ at code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
+following in @file{Makefile.am}:
+
+ at example
+python_PYTHON = tree.py leave.py
+ at end example
+
+Any files listed in a @code{_PYTHON} variable will be byte-compiled
+with @command{py-compile} at install time. @command{py-compile}
+actually creates both standard (@file{.pyc}) and optimized
+(@file{.pyo}) byte-compiled versions of the source files. Note that
+because byte-compilation occurs at install time, any files listed in
+ at code{noinst_PYTHON} will not be compiled. Python source files are
+included in the distribution by default, prepend @code{nodist_} (as in
+ at code{nodist_python_PYTHON}) to omit them.
+
+Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
+that will determine some Python-related directory variables (see
+below). If you have called @code{AM_PATH_PYTHON} from
+ at file{configure.ac}, then you may use the variables
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
+files in your @file{Makefile.am}, depending on where you want your files
+installed (see the definitions of @code{pythondir} and
+ at code{pkgpythondir} below).
+
+ at defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
+ @ovar{action-if-not-found})
+
+Search for a Python interpreter on the system. This macro takes three
+optional arguments. The first argument, if present, is the minimum
+version of Python required for this package: @code{AM_PATH_PYTHON}
+will skip any Python interpreter that is older than @var{version}.
+If an interpreter is found and satisfies @var{version}, then
+ at var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
+run.
+
+If @var{action-if-not-found} is not specified, as in the following
+example, the default is to abort @command{configure}.
+
+ at example
+AM_PATH_PYTHON([2.2])
+ at end example
+
+ at noindent
+This is fine when Python is an absolute requirement for the package.
+If Python >= 2.5 was only @emph{optional} to the package,
+ at code{AM_PATH_PYTHON} could be called as follows.
+
+ at example
+AM_PATH_PYTHON([2.5],, [:])
+ at end example
+
+If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
+called, then that will be the only Python interpreter that is tried.
+
+ at code{AM_PATH_PYTHON} creates the following output variables based on
+the Python installation found during configuration.
+ at end defmac
+
+ at vtable @code
+ at item PYTHON
+The name of the Python executable, or @samp{:} if no suitable
+interpreter could be found.
+
+Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
+will abort if Python is absent), the value of @code{PYTHON} can be used
+to setup a conditional in order to disable the relevant part of a build
+as follows.
+
+ at example
+AM_PATH_PYTHON(,, [:])
+AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
+ at end example
+
+ at item PYTHON_VERSION
+The Python version number, in the form @var{major}. at var{minor}
+(e.g., @samp{2.5}). This is currently the value of
+ at samp{sys.version[:3]}.
+
+ at item PYTHON_PREFIX
+The string @samp{$@{prefix@}}. This term may be used in future work
+that needs the contents of Python's @samp{sys.prefix}, but general
+consensus is to always use the value from @command{configure}.
+
+ at item PYTHON_EXEC_PREFIX
+The string @samp{$@{exec_prefix@}}. This term may be used in future work
+that needs the contents of Python's @samp{sys.exec_prefix}, but general
+consensus is to always use the value from @command{configure}.
+
+ at item PYTHON_PLATFORM
+The canonical name used by Python to describe the operating system, as
+given by @samp{sys.platform}. This value is sometimes needed when
+building Python extensions.
+
+ at item pythondir
+The directory name for the @file{site-packages} subdirectory of the
+standard Python install tree.
+
+ at item pkgpythondir
+This is the directory under @code{pythondir} that is named after the
+package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
+as a convenience.
+
+ at item pyexecdir
+This is the directory where Python extension modules (shared libraries)
+should be installed. An extension module written in C could be declared
+as follows to Automake:
+
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at example
+pyexec_LTLIBRARIES = quaternion.la
+quaternion_la_SOURCES = quaternion.c support.c support.h
+quaternion_la_LDFLAGS = -avoid-version -module
+ at end example
+
+ at item pkgpyexecdir
+This is a convenience variable that is defined as
+ at samp{$(pyexecdir)/$(PACKAGE)}.
+ at end vtable
+
+All of these directory variables have values that start with either
+ at samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
+fine in @file{Makefiles}, but it makes these variables hard to use in
+ at file{configure}. This is mandated by the GNU coding standards, so
+that the user can run @samp{make prefix=/foo install}. The Autoconf
+manual has a section with more details on this topic
+(@pxref{Installation Directory Variables, , Installation Directory
+Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
+Install Paths}.
+
+
+ at node Documentation
+ at chapter Building documentation
+
+Currently Automake provides support for Texinfo and man pages.
+
+ at menu
+* Texinfo:: Texinfo
+* Man Pages:: Man pages
+ at end menu
+
+
+ at node Texinfo
+ at section Texinfo
+
+ at cindex @code{_TEXINFOS} primary, defined
+ at cindex @code{TEXINFOS} primary, defined
+ at cindex Primary variable, @code{TEXINFOS}
+ at cindex HTML output using Texinfo
+ at cindex PDF output using Texinfo
+ at cindex PS output using Texinfo
+ at cindex DVI output using Texinfo
+ at vindex _TEXINFOS
+ at vindex info_TEXINFOS
+
+If the current directory contains Texinfo source, you must declare it
+with the @code{TEXINFOS} primary. Generally Texinfo files are converted
+into info, and thus the @code{info_TEXINFOS} variable is most commonly used
+here. Any Texinfo source file should have the @file{.texi} extension.
+Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their
+use is discouraged now, and will elicit runtime warnings.
+
+Automake generates rules to build @file{.info}, @file{.dvi},
+ at file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
+sources. Following the GNU Coding Standards, only the @file{.info}
+files are built by @samp{make all} and installed by @samp{make
+install} (unless you use @option{no-installinfo}, see below).
+Furthermore, @file{.info} files are automatically distributed so that
+Texinfo is not a prerequisite for installing your package.
+
+It is worth noting that, contrary to what happens with the other formats,
+the generated @file{.info} files are by default placed in @code{srcdir}
+rather than in the @code{builddir}. This can be changed with the
+ at option{info-in-builddir} option.
+
+ at trindex dvi
+ at trindex html
+ at trindex pdf
+ at trindex ps
+ at trindex install-dvi
+ at trindex install-html
+ at trindex install-pdf
+ at trindex install-ps
+Other documentation formats can be built on request by @samp{make
+dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
+can be installed with @samp{make install-dvi}, @samp{make install-ps},
+ at samp{make install-pdf} and @samp{make install-html} explicitly.
+ at samp{make uninstall} will remove everything: the Texinfo
+documentation installed by default as well as all the above optional
+formats.
+
+All of these targets can be extended using @samp{-local} rules
+(@pxref{Extending}).
+
+ at cindex Texinfo flag, @code{VERSION}
+ at cindex Texinfo flag, @code{UPDATED}
+ at cindex Texinfo flag, @code{EDITION}
+ at cindex Texinfo flag, @code{UPDATED-MONTH}
+
+ at cindex @code{VERSION} Texinfo flag
+ at cindex @code{UPDATED} Texinfo flag
+ at cindex @code{EDITION} Texinfo flag
+ at cindex @code{UPDATED-MONTH} Texinfo flag
+
+ at cindex @file{mdate-sh}
+
+If the @file{.texi} file @code{@@include}s @file{version.texi}, then
+that file will be automatically generated. The file @file{version.texi}
+defines four Texinfo flag you can reference using
+ at code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
+ at code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
+
+ at table @code
+ at item EDITION
+ at itemx VERSION
+Both of these flags hold the version number of your program. They are
+kept separate for clarity.
+
+ at item UPDATED
+This holds the date the primary @file{.texi} file was last modified.
+
+ at item UPDATED-MONTH
+This holds the name of the month in which the primary @file{.texi} file
+was last modified.
+ at end table
+
+The @file{version.texi} support requires the @command{mdate-sh}
+script; this script is supplied with Automake and automatically
+included when @command{automake} is invoked with the
+ at option{--add-missing} option.
+
+If you have multiple Texinfo files, and you want to use the
+ at file{version.texi} feature, then you have to have a separate version
+file for each Texinfo file. Automake will treat any include in a
+Texinfo file that matches @file{vers*.texi} just as an automatically
+generated version file.
+
+Sometimes an info file actually depends on more than one @file{.texi}
+file. For instance, in GNU Hello, @file{hello.texi} includes the file
+ at file{fdl.texi}. You can tell Automake about these dependencies using
+the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
+ at vindex TEXINFOS
+ at vindex _TEXINFOS
+
+ at example
+info_TEXINFOS = hello.texi
+hello_TEXINFOS = fdl.texi
+ at end example
+
+ at cindex @file{texinfo.tex}
+
+By default, Automake requires the file @file{texinfo.tex} to appear in
+the same directory as the @file{Makefile.am} file that lists the
+ at file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
+ at file{configure.ac} (@pxref{Input, , Finding `configure' Input,
+autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
+there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
+ at option{--add-missing} is given, and takes care of its distribution.
+However, if you set the @code{TEXINFO_TEX} variable (see below),
+it overrides the location of the file and turns off its installation
+into the source as well as its distribution.
+
+The option @option{no-texinfo.tex} can be used to eliminate the
+requirement for the file @file{texinfo.tex}. Use of the variable
+ at code{TEXINFO_TEX} is preferable, however, because that allows the
+ at code{dvi}, @code{ps}, and @code{pdf} targets to still work.
+
+ at cindex Option, @code{no-installinfo}
+ at cindex Target, @code{install-info}
+ at cindex @code{install-info} target
+ at cindex @code{no-installinfo} option
+
+ at opindex no-installinfo
+ at trindex install-info
+
+Automake generates an @code{install-info} rule; some people apparently
+use this. By default, info pages are installed by @samp{make
+install}, so running @code{make install-info} is pointless. This can
+be prevented via the @code{no-installinfo} option. In this case,
+ at file{.info} files are not installed by default, and user must
+request this explicitly using @samp{make install-info}.
+
+ at vindex AM_UPDATE_INFO_DIR
+By default, @code{make install-info} and @code{make uninstall-info}
+will try to run the @command{install-info} program (if available) to
+update (or create/remove) the @file{@code{$@{infodir@}}/dir} index.
+If this is undesired, it can be prevented by exporting the
+ at code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
+
+The following variables are used by the Texinfo build rules.
+
+ at vtable @code
+ at item MAKEINFO
+The name of the program invoked to build @file{.info} files. This
+variable is defined by Automake. If the @command{makeinfo} program is
+found on the system then it will be used by default; otherwise
+ at command{missing} will be used instead.
+
+ at item MAKEINFOHTML
+The command invoked to build @file{.html} files. Automake
+defines this to @samp{$(MAKEINFO) --html}.
+
+ at item MAKEINFOFLAGS
+User flags passed to each invocation of @samp{$(MAKEINFO)} and
+ at samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
+not expected to be defined in any @file{Makefile}; it can be used by
+users to pass extra flags to suit their needs.
+
+ at item AM_MAKEINFOFLAGS
+ at itemx AM_MAKEINFOHTMLFLAGS
+Maintainer flags passed to each @command{makeinfo} invocation. Unlike
+ at code{MAKEINFOFLAGS}, these variables are meant to be defined by
+maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
+passed to @code{makeinfo} when building @file{.info} files; and
+ at samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
+files.
+
+ at c Keep in sync with txinfo-many-output-formats.sh
+For instance, the following setting can be used to obtain one single
+ at file{.html} file per manual, without node separators.
+ at example
+AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
+ at end example
+
+ at code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
+This means that defining @code{AM_MAKEINFOFLAGS} without defining
+ at code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
+and @file{.html} files.
+
+ at item TEXI2DVI
+The name of the command that converts a @file{.texi} file into a
+ at file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
+with the Texinfo package.
+
+ at item TEXI2PDF
+The name of the command that translates a @file{.texi} file into a
+ at file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
+
+ at item DVIPS
+The name of the command that builds a @file{.ps} file out of a
+ at file{.dvi} file. This defaults to @samp{dvips}.
+
+ at item TEXINFO_TEX
+
+If your package has Texinfo files in many directories, you can use the
+variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
+ at file{texinfo.tex} for your package. The value of this variable should
+be the relative path from the current @file{Makefile.am} to
+ at file{texinfo.tex}:
+
+ at example
+TEXINFO_TEX = ../doc/texinfo.tex
+ at end example
+ at end vtable
+
+
+ at node Man Pages
+ at section Man Pages
+
+ at cindex @code{_MANS} primary, defined
+ at cindex @code{MANS} primary, defined
+ at cindex Primary variable, @code{MANS}
+
+ at vindex _MANS
+ at vindex man_MANS
+A package can also include man pages (but see the GNU standards on this
+matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
+pages are declared using the @code{MANS} primary. Generally the
+ at code{man_MANS} variable is used. Man pages are automatically installed in
+the correct subdirectory of @code{mandir}, based on the file extension.
+
+File extensions such as @file{.1c} are handled by looking for the valid
+part of the extension and using that to determine the correct
+subdirectory of @code{mandir}. Valid section names are the digits
+ at samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
+
+Sometimes developers prefer to name a man page something like
+ at file{foo.man} in the source, and then rename it to have the correct
+suffix, for example @file{foo.1}, when installing the file. Automake
+also supports this mode. For a valid section named @var{section},
+there is a corresponding directory named @samp{man at var{section}dir},
+and a corresponding @code{_MANS} variable. Files listed in such a
+variable are installed in the indicated section. If the file already
+has a valid suffix, then it is installed as-is; otherwise the file
+suffix is changed to match the section.
+
+For instance, consider this example:
+ at example
+man1_MANS = rename.man thesame.1 alsothesame.1c
+ at end example
+
+ at noindent
+In this case, @file{rename.man} will be renamed to @file{rename.1} when
+installed, but the other files will keep their names.
+
+ at cindex Target, @code{install-man}
+ at cindex Option, @option{no-installman}
+ at cindex @code{install-man} target
+ at cindex @option{no-installman} option
+ at opindex no-installman
+ at trindex install-man
+
+By default, man pages are installed by @samp{make install}. However,
+since the GNU project does not require man pages, many maintainers do
+not expend effort to keep the man pages up to date. In these cases, the
+ at option{no-installman} option will prevent the man pages from being
+installed by default. The user can still explicitly install them via
+ at samp{make install-man}.
+
+For fast installation, with many files it is preferable to use
+ at samp{man at var{section}_MANS} over @samp{man_MANS} as well as files that
+do not need to be renamed.
+
+Man pages are not currently considered to be source, because it is not
+uncommon for man pages to be automatically generated. Therefore they
+are not automatically included in the distribution. However, this can
+be changed by use of the @code{dist_} prefix. For instance here is
+how to distribute and install the two man pages of GNU @command{cpio}
+(which includes both Texinfo documentation and man pages):
+
+ at example
+dist_man_MANS = cpio.1 mt.1
+ at end example
+
+The @code{nobase_} prefix is meaningless for man pages and is
+disallowed.
+
+ at vindex notrans_
+ at cindex @code{notrans_} prefix
+ at cindex Man page renaming, avoiding
+ at cindex Avoiding man page renaming
+
+Executables and manpages may be renamed upon installation
+(@pxref{Renaming}). For manpages this can be avoided by use of the
+ at code{notrans_} prefix. For instance, suppose an executable @samp{foo}
+allowing to access a library function @samp{foo} from the command line.
+The way to avoid renaming of the @file{foo.3} manpage is:
+
+ at example
+man_MANS = foo.1
+notrans_man_MANS = foo.3
+ at end example
+
+ at cindex @code{notrans_} and @code{dist_} or @code{nodist_}
+ at cindex @code{dist_} and @code{notrans_}
+ at cindex @code{nodist_} and @code{notrans_}
+
+ at samp{notrans_} must be specified first when used in conjunction with
+either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
+Control}). For instance:
+
+ at example
+notrans_dist_man3_MANS = bar.3
+ at end example
+
+ at node Install
+ at chapter What Gets Installed
+
+ at cindex Installation support
+ at cindex @samp{make install} support
+
+Naturally, Automake handles the details of actually installing your
+program once it has been built. All files named by the various
+primaries are automatically installed in the appropriate places when the
+user runs @samp{make install}.
+
+ at menu
+* 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
+ at end menu
+
+ at node Basics of Installation
+ at section Basics of Installation
+
+A file named in a primary is installed by copying the built file into
+the appropriate directory. The base name of the file is used when
+installing.
+
+ at example
+bin_PROGRAMS = hello subdir/goodbye
+ at end example
+
+In this example, both @samp{hello} and @samp{goodbye} will be installed
+in @samp{$(bindir)}.
+
+Sometimes it is useful to avoid the basename step at install time. For
+instance, you might have a number of header files in subdirectories of
+the source tree that are laid out precisely how you want to install
+them. In this situation you can use the @code{nobase_} prefix to
+suppress the base name step. For example:
+
+ at example
+nobase_include_HEADERS = stdio.h sys/types.h
+ at end example
+
+ at noindent
+will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
+in @samp{$(includedir)/sys}.
+
+For most file types, Automake will install multiple files at once, while
+avoiding command line length issues (@pxref{Length Limitations}). Since
+some @command{install} programs will not install the same file twice in
+one invocation, you may need to ensure that file lists are unique within
+one variable such as @samp{nobase_include_HEADERS} above.
+
+You should not rely on the order in which files listed in one variable
+are installed. Likewise, to cater for parallel make, you should not
+rely on any particular file installation order even among different
+file types (library dependencies are an exception here).
+
+
+ at node The Two Parts of Install
+ at section The Two Parts of Install
+
+Automake generates separate @code{install-data} and @code{install-exec}
+rules, in case the installer is installing on multiple machines that
+share directory structure---these targets allow the machine-independent
+parts to be installed only once. @code{install-exec} installs
+platform-dependent files, and @code{install-data} installs
+platform-independent files. The @code{install} target depends on both
+of these targets. While Automake tries to automatically segregate
+objects into the correct category, the @file{Makefile.am} author is, in
+the end, responsible for making sure this is done correctly.
+ at trindex install-data
+ at trindex install-exec
+ at trindex install
+ at cindex Install, two parts of
+
+Variables using the standard directory prefixes @samp{data},
+ at samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
+ at samp{pkgdata}, or @samp{pkginclude} are installed by
+ at code{install-data}.
+
+Variables using the standard directory prefixes @samp{bin},
+ at samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
+ at samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
+
+For instance, @code{data_DATA} files are installed by @code{install-data},
+while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
+
+Any variable using a user-defined directory prefix with
+ at samp{exec} in the name (e.g.,
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+ at code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
+other user-defined prefixes are installed by @code{install-data}.
+
+ at node Extending Installation
+ at section Extending Installation
+
+It is possible to extend this mechanism by defining an
+ at code{install-exec-local} or @code{install-data-local} rule. If these
+rules exist, they will be run at @samp{make install} time. These
+rules can do almost anything; care is required.
+ at trindex install-exec-local
+ at trindex install-data-local
+
+Automake also supports two install hooks, @code{install-exec-hook} and
+ at code{install-data-hook}. These hooks are run after all other install
+rules of the appropriate type, exec or data, have completed. So, for
+instance, it is possible to perform post-installation modifications
+using an install hook. @xref{Extending}, for some examples.
+ at cindex Install hook
+
+ at node Staged Installs
+ at section Staged Installs
+
+ at vindex DESTDIR
+Automake generates support for the @code{DESTDIR} variable in all
+install rules. @code{DESTDIR} is used during the @samp{make install}
+step to relocate install objects into a staging area. Each object and
+path is prefixed with the value of @code{DESTDIR} before being copied
+into the install area. Here is an example of typical DESTDIR usage:
+
+ at example
+mkdir /tmp/staging &&
+make DESTDIR=/tmp/staging install
+ at end example
+
+The @command{mkdir} command avoids a security problem if the attacker
+creates a symbolic link from @file{/tmp/staging} to a victim area;
+then @command{make} places install objects in a directory tree built under
+ at file{/tmp/staging}. If @file{/gnu/bin/foo} and
+ at file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
+would install @file{/tmp/staging/gnu/bin/foo} and
+ at file{/tmp/staging/gnu/share/aclocal/foo.m4}.
+
+This feature is commonly used to build install images and packages
+(@pxref{DESTDIR}).
+
+Support for @code{DESTDIR} is implemented by coding it directly into
+the install rules. If your @file{Makefile.am} uses a local install
+rule (e.g., @code{install-exec-local}) or an install hook, then you
+must write that code to respect @code{DESTDIR}.
+
+ at xref{Makefile Conventions, , , standards, The GNU Coding Standards},
+for another usage example.
+
+ at node Install Rules for the User
+ at section Install Rules for the User
+
+Automake also generates rules for targets @code{uninstall},
+ at code{installdirs}, and @code{install-strip}.
+ at trindex uninstall
+ at trindex installdirs
+ at trindex install-strip
+
+Automake supports @code{uninstall-local} and @code{uninstall-hook}.
+There is no notion of separate uninstalls for ``exec'' and ``data'', as
+these features would not provide additional functionality.
+
+Note that @code{uninstall} is not meant as a replacement for a real
+packaging tool.
+
+
+ at node Clean
+ at chapter What Gets Cleaned
+
+ at cindex @samp{make clean} support
+
+The GNU Makefile Standards specify a number of different clean rules.
+ at xref{Standard Targets, , Standard Targets for Users, standards,
+The GNU Coding Standards}.
+
+Generally the files that can be cleaned are determined automatically by
+Automake. Of course, Automake also recognizes some variables that can
+be defined to specify additional files to clean. These variables are
+ at code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
+ at code{MAINTAINERCLEANFILES}.
+ at vindex MOSTLYCLEANFILES
+ at vindex CLEANFILES
+ at vindex DISTCLEANFILES
+ at vindex MAINTAINERCLEANFILES
+
+ at trindex mostlyclean-local
+ at trindex clean-local
+ at trindex distclean-local
+ at trindex maintainer-clean-local
+When cleaning involves more than deleting some hard-coded list of
+files, it is also possible to supplement the cleaning rules with your
+own commands. Simply define a rule for any of the
+ at code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
+or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
+case is deleting a directory, for instance, a directory created by the
+test suite:
+
+ at example
+clean-local:
+ -rm -rf testSubDir
+ at end example
+
+Since @command{make} allows only one set of rules for a given target,
+a more extensible way of writing this is to use a separate target
+listed as a dependency:
+
+ at example
+clean-local: clean-local-check
+.PHONY: clean-local-check
+clean-local-check:
+ -rm -rf testSubDir
+ at end example
+
+As the GNU Standards aren't always explicit as to which files should
+be removed by which rule, we've adopted a heuristic that we believe
+was first formulated by Fran@,{c}ois Pinard:
+
+ at itemize @bullet
+ at item
+If @command{make} built it, and it is commonly something that one would
+want to rebuild (for instance, a @file{.o} file), then
+ at code{mostlyclean} should delete it.
+
+ at item
+Otherwise, if @command{make} built it, then @code{clean} should delete it.
+
+ at item
+If @command{configure} built it, then @code{distclean} should delete it.
+
+ at item
+If the maintainer built it (for instance, a @file{.info} file), then
+ at code{maintainer-clean} should delete it. However
+ at code{maintainer-clean} should not delete anything that needs to exist
+in order to run @samp{./configure && make}.
+ at end itemize
+
+We recommend that you follow this same set of heuristics in your
+ at file{Makefile.am}.
+
+
+ at node Dist
+ at chapter What Goes in a Distribution
+
+ at menu
+* 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
+ at end menu
+
+ at node Basics of Distribution
+ at section Basics of Distribution
+
+ at cindex @samp{make dist}
+
+ at vindex PACKAGE
+ at vindex VERSION
+ at trindex dist
+The @code{dist} rule in the generated @file{Makefile.in} can be used
+to generate a gzipped @code{tar} file and other flavors of archive for
+distribution. The file is named based on the @code{PACKAGE} and
+ at code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
+(@pxref{Macros}); more precisely the gzipped @code{tar} file is named
+ at samp{@var{package}- at var{version}.tar.gz}.
+ at vindex GZIP_ENV
+You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
+is run. The default setting is @option{--best}.
+
+ at cindex @code{m4_include}, distribution
+ at cindex @code{include}, distribution
+ at acindex m4_include
+ at cmindex include
+For the most part, the files to distribute are automatically found by
+Automake: all source files are automatically included in a distribution,
+as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
+has a built-in list of commonly used files that are automatically
+included if they are found in the current directory (either physically,
+or as the target of a @file{Makefile.am} rule); this list is printed by
+ at samp{automake --help}. Note that some files in this list are actually
+distributed only if other certain conditions hold (for example,
+ at c Keep in sync with autodist-config-headers.sh
+the @file{config.h.top} and @file{config.h.bot} files are automatically
+distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
+in @file{configure.ac}). Also, files that are read by @command{configure}
+(i.e.@: the source files corresponding to the files specified in various
+Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
+automatically distributed. Files included in a @file{Makefile.am} (using
+ at code{include}) or in @file{configure.ac} (using @code{m4_include}), and
+helper scripts installed with @samp{automake --add-missing} are also
+distributed.
+
+ at vindex EXTRA_DIST
+Still, sometimes there are files that must be distributed, but which
+are not covered in the automatic rules. These files should be listed in
+the @code{EXTRA_DIST} variable. You can mention files from
+subdirectories in @code{EXTRA_DIST}.
+
+You can also mention a directory in @code{EXTRA_DIST}; in this case the
+entire directory will be recursively copied into the distribution.
+Please note that this will also copy @emph{everything} in the directory,
+including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
+version control files; thus we recommend against using this feature
+as-is. However, you can use the @code{dist-hook} feature to
+ameliorate the problem; @pxref{The dist Hook}.
+
+ at vindex SUBDIRS
+ at vindex DIST_SUBDIRS
+If you define @code{SUBDIRS}, Automake will recursively include the
+subdirectories in the distribution. If @code{SUBDIRS} is defined
+conditionally (@pxref{Conditionals}), Automake will normally include
+all directories that could possibly appear in @code{SUBDIRS} in the
+distribution. If you need to specify the set of directories
+conditionally, you can set the variable @code{DIST_SUBDIRS} to the
+exact list of subdirectories to include in the distribution
+(@pxref{Conditional Subdirectories}).
+
+
+ at node Fine-grained Distribution Control
+ at section Fine-grained Distribution Control
+
+ at vindex dist_
+ at vindex nodist_
+Sometimes you need tighter control over what does @emph{not} go into the
+distribution; for instance, you might have source files that are
+generated and that you do not want to distribute. In this case
+Automake gives fine-grained control using the @code{dist} and
+ at code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
+prefixed with @code{dist_} to add the listed files to the distribution.
+Similarly, @code{nodist_} can be used to omit the files from the
+distribution.
+
+As an example, here is how you would cause some data to be distributed
+while leaving some source code out of the distribution:
+
+ at example
+dist_data_DATA = distribute-this
+bin_PROGRAMS = foo
+nodist_foo_SOURCES = do-not-distribute.c
+ at end example
+
+ at node The dist Hook
+ at section The dist Hook
+
+ at trindex dist-hook
+
+Occasionally it is useful to be able to change the distribution before
+it is packaged up. If the @code{dist-hook} rule exists, it is run
+after the distribution directory is filled, but before the actual
+distribution archives are created. One way to use this is for
+removing unnecessary files that get recursively included by specifying
+a directory in @code{EXTRA_DIST}:
+
+ at example
+EXTRA_DIST = doc
+dist-hook:
+ rm -rf `find $(distdir)/doc -type d -name .svn`
+ at end example
+
+ at c The caveates described here should be documented in 'disthook.sh'.
+ at noindent
+Note that the @code{dist-hook} recipe shouldn't assume that the regular
+files in the distribution directory are writable; this might not be the
+case if one is packaging from a read-only source tree, or when a
+ at code{make distcheck} is being done. For similar reasons, the recipe
+shouldn't assume that the subdirectories put into the distribution
+directory as effect of having them listed in @code{EXTRA_DIST} are
+writable. So, if the @code{dist-hook} recipe wants to modify the
+content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
+distribution directory, it should explicitly to make it writable first:
+
+ at example
+EXTRA_DIST = README doc
+dist-hook:
+ chmod u+w $(distdir)/README $(distdir)/doc
+ echo "Distribution date: `date`" >> README
+ rm -f $(distdir)/doc/HACKING
+ at end example
+
+ at vindex distdir
+ at vindex top_distdir
+Two variables that come handy when writing @code{dist-hook} rules are
+ at samp{$(distdir)} and @samp{$(top_distdir)}.
+
+ at samp{$(distdir)} points to the directory where the @code{dist} rule
+will copy files from the current directory before creating the
+tarball. If you are at the top-level directory, then @samp{distdir =
+$(PACKAGE)-$(VERSION)}. When used from subdirectory named
+ at file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
+ at samp{$(distdir)} can be a relative or absolute path, do not assume
+any form.
+
+ at samp{$(top_distdir)} always points to the root directory of the
+distributed tree. At the top-level it's equal to @samp{$(distdir)}.
+In the @file{foo/} subdirectory
+ at samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
+ at samp{$(top_distdir)} too can be a relative or absolute path.
+
+Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
+(@pxref{Subpackages}), then @samp{$(distdir)} and
+ at samp{$(top_distdir)} are relative to the package where @samp{make
+dist} was run, not to any sub-packages involved.
+
+ at node Checking the Distribution
+ at section Checking the Distribution
+
+ at cindex @samp{make distcheck}
+ at trindex distcheck
+Automake also generates a @code{distcheck} rule that can be of help
+to ensure that a given distribution will actually work. Simplifying
+a bit, we can say this rule first makes a distribution, and then,
+ at emph{operating from it}, takes the following steps:
+ at itemize
+ at item
+tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
+ at code{srcdir} and all its content made @emph{read-only};
+ at item
+runs the test suite (with @command{make check}) on this fresh build;
+ at item
+installs the package in a temporary directory (with @command{make
+install}), and tries runs the test suite on the resulting installation
+(with @command{make installcheck});
+ at item
+checks that the package can be correctly uninstalled (by @command{make
+uninstall}) and cleaned (by @code{make distclean});
+ at item
+finally, makes another tarball to ensure the distribution is
+self-contained.
+ at end itemize
+
+ at vindex AM_DISTCHECK_CONFIGURE_FLAGS
+ at vindex DISTCHECK_CONFIGURE_FLAGS
+ at subheading DISTCHECK_CONFIGURE_FLAGS
+Building the package involves running @samp{./configure}. If you need
+to supply additional flags to @command{configure}, define them in the
+ at code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
+ at file{Makefile.am}. The user can still extend or override the flags
+provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
+on the command line when invoking @command{make}.
+
+Still, developers are encouraged to strive to make their code buildable
+without requiring any special configure option; thus, in general, you
+shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
+might be few scenarios in which the use of this variable is justified.
+GNU @command{m4} offers an example. GNU @command{m4} configures by
+default with its experimental and seldom used "changeword" feature
+disabled; so in its case it is useful to have @command{make distcheck}
+run configure with the @option{--with-changeword} option, to ensure that
+the code for changeword support still compiles correctly.
+GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
+variable to stress-test the use of @option{--program-prefix=g}, since at
+one point the @command{m4} build system had a bug where @command{make
+installcheck} was wrongly assuming it could blindly test "@command{m4}",
+rather than the just-installed "@command{gm4}".
+
+ at trindex distcheck-hook
+ at subheading distcheck-hook
+If the @code{distcheck-hook} rule is defined in your top-level
+ at file{Makefile.am}, then it will be invoked by @code{distcheck} after
+the new distribution has been unpacked, but before the unpacked copy
+is configured and built. Your @code{distcheck-hook} can do almost
+anything, though as always caution is advised. Generally this hook is
+used to check for potential distribution errors not caught by the
+standard mechanism. Note that @code{distcheck-hook} as well as
+ at code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
+are not honored in a subpackage @file{Makefile.am}, but the flags from
+ at code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
+are passed down to the @command{configure} script of the subpackage.
+
+ at cindex @samp{make distcleancheck}
+ at trindex distcleancheck
+ at vindex DISTCLEANFILES
+ at vindex distcleancheck_listfiles
+
+ at subheading distcleancheck
+Speaking of potential distribution errors, @code{distcheck} also
+ensures that the @code{distclean} rule actually removes all built
+files. This is done by running @samp{make distcleancheck} at the end of
+the @code{VPATH} build. By default, @code{distcleancheck} will run
+ at code{distclean} and then make sure the build tree has been emptied by
+running @samp{$(distcleancheck_listfiles)}. Usually this check will
+find generated files that you forgot to add to the @code{DISTCLEANFILES}
+variable (@pxref{Clean}).
+
+The @code{distcleancheck} behavior should be OK for most packages,
+otherwise you have the possibility to override the definition of
+either the @code{distcleancheck} rule, or the
+ at samp{$(distcleancheck_listfiles)} variable. For instance, to disable
+ at code{distcleancheck} completely, add the following rule to your
+top-level @file{Makefile.am}:
+
+ at example
+distcleancheck:
+ @@:
+ at end example
+
+If you want @code{distcleancheck} to ignore built files that have not
+been cleaned because they are also part of the distribution, add the
+following definition instead:
+
+ at c Keep in sync with distcleancheck.sh
+ at example
+distcleancheck_listfiles = \
+ find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
+ sh '@{@}' ';'
+ at end example
+
+The above definition is not the default because it's usually an error if
+your Makefiles cause some distributed files to be rebuilt when the user
+build the package. (Think about the user missing the tool required to
+build the file; or if the required tool is built by your package,
+consider the cross-compilation case where it can't be run.) There is
+an entry in the FAQ about this (@pxref{Errors with distclean}), make
+sure you read it before playing with @code{distcleancheck_listfiles}.
+
+ at cindex @samp{make distuninstallcheck}
+ at trindex distuninstallcheck
+ at vindex distuninstallcheck_listfiles
+
+ at subheading distuninstallcheck
+ at code{distcheck} also checks that the @code{uninstall} rule works
+properly, both for ordinary and @code{DESTDIR} builds. It does this
+by invoking @samp{make uninstall}, and then it checks the install tree
+to see if any files are left over. This check will make sure that you
+correctly coded your @code{uninstall}-related rules.
+
+By default, the checking is done by the @code{distuninstallcheck} rule,
+and the list of files in the install tree is generated by
+ at samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
+a shell command to run that prints the list of files to stdout).
+
+Either of these can be overridden to modify the behavior of
+ at code{distcheck}. For instance, to disable this check completely, you
+would write:
+
+ at example
+distuninstallcheck:
+ @@:
+ at end example
+
+ at node The Types of Distributions
+ at section The Types of Distributions
+
+Automake generates rules to provide archives of the project for
+distributions in various formats. Their targets are:
+
+ at table @asis
+ at item @code{dist-gzip}
+Generate a @samp{gzip} tar archive of the distribution. This is the
+only format enabled by default.
+ at trindex dist-gzip
+
+ at vindex BZIP2
+ at item @code{dist-bzip2}
+Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives
+are frequently smaller than gzipped archives.
+By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
+To make it use a different one, set the @env{BZIP2} environment variable.
+For example, @samp{make dist-bzip2 BZIP2=-7}.
+ at trindex dist-bzip2
+
+ at item @code{dist-lzip}
+Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
+archives are frequently smaller than @command{bzip2}-compressed archives.
+ at trindex dist-lzip
+
+ at vindex XZ_OPT
+ at item @code{dist-xz}
+Generate an @samp{xz} tar archive of the distribution. @command{xz}
+archives are frequently smaller than @command{bzip2}-compressed archives.
+By default, this rule makes @samp{xz} use a compression option of
+ at option{-e}. To make it use a different one, set the @env{XZ_OPT}
+environment variable. For example, run this command to use the
+default compression ratio, but with a progress indicator:
+ at samp{make dist-xz XZ_OPT=-ve}.
+ at trindex dist-xz
+
+ at item @code{dist-zip}
+Generate a @samp{zip} archive of the distribution.
+ at trindex dist-zip
+
+ at item @code{dist-tarZ}
+Generate a tar archive of the distribution, compressed with the
+historical (and obsolescent) program @command{compress}. This
+option is deprecated, and it and the corresponding functionality
+will be removed altogether in Automake 2.0.
+ at trindex dist-tarZ
+
+ at item @code{dist-shar}
+Generate a @samp{shar} archive of the distribution. This format
+archive is obsolescent, and use of this option is deprecated.
+It and the corresponding functionality will be removed altogether
+in Automake 2.0.
+ at trindex dist-shar
+
+ at end table
+
+The rule @code{dist} (and its historical synonym @code{dist-all})
+will create archives in all the enabled formats (@pxref{List of
+Automake options} for how to change this list). By default, only
+the @code{dist-gzip} target is hooked to @code{dist}.
+
+
+ at node Tests
+ at chapter Support for test suites
+
+ at cindex Test suites
+ at cindex @code{make check}
+ at trindex check
+
+Automake can generate code to handle two kinds of test suites. One is
+based on integration with the @command{dejagnu} framework. The other
+(and most used) form is based on the use of generic test scripts, and
+its activation is triggered by the definition of the special @code{TESTS}
+variable. This second form allows for various degrees of sophistication
+and customization; in particular, it allows for concurrent execution
+of test scripts, use of established test protocols such as TAP, and
+definition of custom test drivers and test runners.
+
+ at noindent
+In either case, the testsuite is invoked via @samp{make check}.
+
+ at menu
+* Generalities about Testing:: 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
+ at end menu
+
+ at node Generalities about Testing
+ at section Generalities about Testing
+
+The purpose of testing is to determine whether a program or system behaves
+as expected (e.g., known inputs produce the expected outputs, error
+conditions are correctly handled or reported, and older bugs do not
+resurface).
+
+ at cindex test case
+The minimal unit of testing is usually called @emph{test case}, or simply
+ at emph{test}. How a test case is defined or delimited, and even what
+exactly @emph{constitutes} a test case, depends heavily on the testing
+paradigm and/or framework in use, so we won't attempt any more precise
+definition. The set of the test cases for a given program or system
+constitutes its @emph{testsuite}.
+
+ at cindex test harness
+ at cindex testsuite harness
+A @emph{test harness} (also @emph{testsuite harness}) is a program or
+software component that executes all (or part of) the defined test cases,
+analyzes their outcomes, and report or register these outcomes
+appropriately. Again, the details of how this is accomplished (and how
+the developer and user can influence it or interface with it) varies
+wildly, and we'll attempt no precise definition.
+
+ at cindex test pass
+ at cindex test failure
+A test is said to @emph{pass} when it can determine that the condition or
+behaviour it means to verify holds, and is said to @emph{fail} when it can
+determine that such condition of behaviour does @emph{not} hold.
+
+ at cindex test skip
+Sometimes, tests can rely on non-portable tools or prerequisites, or
+simply make no sense on a given system (for example, a test checking a
+Windows-specific feature makes no sense on a GNU/Linux system). In this
+case, accordingly to the definition above, the tests can neither be
+considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
+they are not run, or their result is anyway ignored for what concerns
+the count of failures an successes. Skips are usually explicitly
+reported though, so that the user will be aware that not all of the
+testsuite has really run.
+
+ at cindex xfail
+ at cindex expected failure
+ at cindex expected test failure
+ at cindex xpass
+ at cindex unexpected pass
+ at cindex unexpected test pass
+It's not uncommon, especially during early development stages, that some
+tests fail for known reasons, and that the developer doesn't want to
+tackle these failures immediately (this is especially true when the
+failing tests deal with corner cases). In this situation, the better
+policy is to declare that each of those failures is an @emph{expected
+failure} (or @emph{xfail}). In case a test that is expected to fail ends
+up passing instead, many testing environments will flag the result as a
+special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
+
+ at cindex hard error
+ at cindex Distinction between errors and failures in testsuites
+Many testing environments and frameworks distinguish between test failures
+and hard errors. As we've seen, a test failure happens when some invariant
+or expected behaviour of the software under test is not met. An @emph{hard
+error} happens when e.g., the set-up of a test case scenario fails, or when
+some other unexpected or highly undesirable condition is encountered (for
+example, the program under test experiences a segmentation fault).
+
+ at emph{TODO}: Links to other test harnesses (esp. those sharing our
+terminology)?
+
+ at node Simple Tests
+ at section Simple Tests
+
+ at menu
+* Scripts-based Testsuites:: Automake-specific concepts and terminology
+* Serial Test Harness:: Older (and discouraged) serial test harness
+* Parallel Test Harness:: Generic concurrent test harness
+ at end menu
+
+ at node Scripts-based Testsuites
+ at subsection Scripts-based Testsuites
+
+If the special variable @code{TESTS} is defined, its value is taken to be
+a list of programs or scripts to run in order to do the testing. Under
+the appropriate circumstances, it's possible for @code{TESTS} to list
+also data files to be passed to one or more test scripts defined by
+different means (the so-called ``log compilers'', @pxref{Parallel Test
+Harness}).
+
+Test scripts can be executed serially or concurrently. Automake supports
+both these kinds of test execution, with the parallel test harness being
+the default. The concurrent test harness relies on the concurrence
+capabilities (if any) offered by the underlying @command{make}
+implementation, and can thus only be as good as those are.
+
+By default, only the exit statuses of the test scripts are considered when
+determining the testsuite outcome. But Automake allows also the use of
+more complex test protocols, either standard (@pxref{Using the TAP test
+protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't
+enable such protocols when the serial harness is used, though.
+In the rest of this section we are going to concentrate mostly on
+protocol-less tests, since we cover test protocols in a later section
+(again, @pxref{Custom Test Drivers}).
+
+ at cindex Exit status 77, special interpretation
+ at cindex Exit status 99, special interpretation
+When no test protocol is in use, an exit status of 0 from a test script will
+denote a success, an exit status of 77 a skipped test, an exit status of 99
+an hard error, and any other exit status will denote a failure.
+
+ at cindex Tests, expected failure
+ at cindex Expected test failure
+ at vindex XFAIL_TESTS
+ at vindex DISABLE_HARD_ERRORS
+ at cindex Disabling hard errors
+You may define the variable @code{XFAIL_TESTS} to a list of tests
+(usually a subset of @code{TESTS}) that are expected to fail; this will
+effectively reverse the result of those tests (with the provision that
+skips and hard errors remain untouched). You may also instruct the
+testsuite harness to treat hard errors like simple failures, by defining
+the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
+
+Note however that, for tests based on more complex test protocols,
+the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
+might change, or they might even have no effect at all (for example,
+ at c Keep this in sync with tap-no-disable-hard-errors.sh
+in tests using TAP, there is not way to disable hard errors, and the
+ at code{DISABLE_HARD_ERRORS} variable has no effect on them).
+
+ at anchor{Testsuite progress on console}
+ at cindex Testsuite progress on console
+The result of each test case run by the scripts in @code{TESTS} will be
+printed on standard output, along with the test name. For test protocols
+that allow more test cases per test script (such as TAP), a number,
+identifier and/or brief description specific for the single test case is
+expected to be printed in addition to the name of the test script. The
+possible results (whose meanings should be clear from the previous
+ at ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
+ at code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
+example of output from an hypothetical testsuite that uses both plain
+and TAP tests:
+ at c Keep in sync with tap-doc.sh
+ at example
+PASS: foo.sh
+PASS: zardoz.tap 1 - Daemon started
+PASS: zardoz.tap 2 - Daemon responding
+SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
+PASS: zardoz.tap 4 - Daemon stopped
+SKIP: bar.sh
+PASS: mu.tap 1
+XFAIL: mu.tap 2 # TODO frobnication not yet implemented
+ at end example
+
+ at noindent
+A testsuite summary (expected to report at least the number of run,
+skipped and failed tests) will be printed at the end of the testsuite
+run.
+
+ at anchor{Simple tests and color-tests}
+ at vindex AM_COLOR_TESTS
+ at cindex Colorized testsuite output
+If the standard output is connected to a capable terminal, then the test
+results and the summary are colored appropriately. The developer and the
+user can disable colored output by setting the @command{make} variable
+ at samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
+even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
+It's also worth noting that some @command{make} implementations,
+when used in parallel mode, have slightly different semantics
+(@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can
+break the automatic detection of a connection to a capable terminal.
+If this is the case, the user will have to resort to the use of
+ at samp{AM_COLOR_TESTS=always} in order to have the testsuite output
+colorized.
+
+Test programs that need data files should look for them in @code{srcdir}
+(which is both a make variable and an environment variable made available
+to the tests), so that they work when building in a separate directory
+(@pxref{Build Directories, , Build Directories , autoconf,
+The Autoconf Manual}), and in particular for the @code{distcheck} rule
+(@pxref{Checking the Distribution}).
+
+ at vindex TESTS
+ at vindex TESTS_ENVIRONMENT
+ at vindex AM_TESTS_ENVIRONMENT
+The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
+be used to run initialization code and set environment variables for the
+test scripts. The former variable is developer-reserved, and can be
+defined in the @file{Makefile.am}, while the latter is reserved for the
+user, which can employ it to extend or override the settings in the
+former; for this to work portably, however, the contents of a non-empty
+ at code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
+
+ at vindex AM_TESTS_FD_REDIRECT
+The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
+descriptor redirections for the test scripts. One might think that
+ at code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
+has shown that doing so portably is practically impossible. The main
+hurdle is constituted by Korn shells, which usually set the close-on-exec
+flag on file descriptors opened with the @command{exec} builtin, thus
+rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
+ineffectual. This issue also affects some Bourne shells, such as the
+HP-UX's @command{/bin/sh},
+ at c FIXME: should we offer a link to the relevant discussions on the
+ at c bug-autoconf list?
+
+ at c Keep in sync with tests-environment-backcompat.sh
+ at example
+AM_TESTS_ENVIRONMENT = \
+## Some environment initializations are kept in a separate shell
+## file 'tests-env.sh', which can make it easier to also run tests
+## from the command line.
+ . $(srcdir)/tests-env.sh; \
+## On Solaris, prefer more POSIX-compliant versions of the standard
+## tools by default.
+ if test -d /usr/xpg4/bin; then \
+ PATH=/usr/xpg4/bin:$$PATH; export PATH; \
+ fi;
+ at c $$ restore font-lock
+## With this, the test scripts will be able to print diagnostic
+## messages to the original standard error stream, even if the test
+## driver redirects the stderr of the test scripts to a log file
+## before executing them.
+AM_TESTS_FD_REDIRECT = 9>&2
+ at end example
+
+ at noindent
+Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
+implementation reasons, @emph{not} supported by the serial harness
+(@pxref{Serial Test Harness}).
+
+Automake ensures that each file listed in @code{TESTS} is built before
+it is run; you can list both source and derived programs (or scripts)
+in @code{TESTS}; the generated rule will look both in @code{srcdir} and
+ at file{.}. For instance, you might want to run a C program as a test.
+To do this you would list its name in @code{TESTS} and also in
+ at code{check_PROGRAMS}, and then specify it as you would any other
+program.
+
+Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
+ at code{check_LTLIBRARIES}...) are only built during @code{make check},
+not during @code{make all}. You should list there any program needed
+by your tests that does not need to be built by @code{make all}. Note
+that @code{check_PROGRAMS} are @emph{not} automatically added to
+ at code{TESTS} because @code{check_PROGRAMS} usually lists programs used
+by the tests, not the tests themselves. Of course you can set
+ at code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
+
+ at node Serial Test Harness
+ at subsection Older (and discouraged) serial test harness
+ at cindex @option{serial-tests}, Using
+
+First, note that today the use of this harness is strongly discouraged in
+favour of the parallel test harness (@pxref{Parallel Test Harness}).
+Still, there are @emph{few} situations when the advantages offered by
+the parallel harness are irrelevant, and when test concurrency can
+even cause tricky problems. In those cases, it might make sense to
+still use the serial harness, for simplicity and reliability (we still
+suggest trying to give the parallel harness a shot though).
+
+The serial test harness is enabled by the Automake option
+ at option{serial-tests}. It operates by simply running the tests serially,
+one at the time, without any I/O redirection. It's up to the user to
+implement logging of tests' output, if that's requited or desired.
+ at c TODO: give an example of how this can be done.
+
+For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
+variable is @emph{not} supported by this harness (it will be silently
+ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
+considered a developer-reserved variable. This is done so that, when
+using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
+invocation of an interpreter through which the tests are to be run.
+For instance, the following setup may be used to run tests with Perl:
+
+ at example
+TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
+TESTS = foo.pl bar.pl baz.pl
+ at end example
+
+ at noindent
+It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
+here would be @emph{invalid} with the parallel harness. That harness
+provides a more elegant way to achieve the same effect, with the further
+benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
+(@pxref{Parallel Test Harness}).
+
+Another, less serious limit of the serial harness is that it doesn't
+really distinguish between simple failures and hard errors; this is
+due to historical reasons only, and might be fixed in future Automake
+versions.
+
+ at node Parallel Test Harness
+ at subsection Parallel Test Harness
+
+By default, Automake generated a parallel (concurrent) test harness. It
+features automatic collection of the test scripts output in @file{.log}
+files, concurrent execution of tests with @code{make -j}, specification
+of inter-test dependencies, lazy reruns of tests that have not completed
+in a prior run, and hard errors for exceptional failures.
+
+ at anchor{Basics of test metadata}
+ at vindex TEST_SUITE_LOG
+ at vindex TESTS
+ at cindex @file{.log} files
+ at cindex @file{.trs} files
+ at cindex test metadata
+The parallel test harness operates by defining a set of @command{make}
+rules that run the test scripts listed in @code{TESTS}, and, for each
+such script, save its output in a corresponding @file{.log} file and
+its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
+in a corresponding @file{.trs} (as in @b{T}est @b{R}e at b{S}ults) file.
+ at c We choose the '.trs' extension also because, at the time of writing,
+ at c it isn't already used for other significant purposes; see e.g.:
+ at c - http://filext.com/file-extension/trs
+ at c - http://www.file-extensions.org/search/?searchstring=trs
+The @file{.log} file will contain all the output emitted by the test on
+its standard output and its standard error. The @file{.trs} file will
+contain, among the other things, the results of the test cases run by
+the script.
+
+The parallel test harness will also create a summary log file,
+ at code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
+a @file{.log} suffix. This file depends upon all the @file{.log} and
+ at file{.trs} files created for the test scripts listed in @code{TESTS}.
+
+ at vindex VERBOSE
+As with the serial harness above, by default one status line is printed
+per completed test, and a short summary after the suite has completed.
+However, standard output and standard error of the test are redirected
+to a per-test log file, so that parallel execution does not produce
+intermingled output. The output from failed tests is collected in the
+ at file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
+file is output after the summary.
+ at c FIXME: we should be clearer about what we mean exactly here ...
+For best results, the tests should be verbose by default now.
+
+ at vindex TEST_EXTENSIONS
+ at vindex TEST_LOGS
+Each couple of @file{.log} and @file{.trs} files is created when the
+corresponding test has completed. The set of log files is listed in
+the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
+with the executable extension if any (@pxref{EXEEXT}), as well as any
+suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
+Results are undefined if a test file name ends in several concatenated
+suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
+overridden by the user, in which case any extension listed in it must be
+constituted by a dot, followed by a non-digit alphabetic character,
+followed by any number of alphabetic characters.
+ at c Keep in sync with test-extensions.sh
+For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
+while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
+
+ at cindex Configure substitutions in @code{TESTS}
+It is important to note that, due to current limitations (unlikely to be
+lifted), configure substitutions in the definition of @code{TESTS} can
+only work if they will expand to a list of tests that have a suffix listed
+in @code{TEST_EXTENSIONS}.
+
+ at vindex _LOG_COMPILE
+ at vindex _LOG_COMPILER
+ at vindex _LOG_FLAGS
+ at vindex LOG_COMPILE
+ at vindex LOG_COMPILER
+ at vindex LOG_FLAGS
+ at vindex @var{ext}_LOG_COMPILE
+ at vindex @var{ext}_LOG_COMPILER
+ at vindex @var{ext}_LOG_FLAGS
+ at vindex AM_ at var{ext}_LOG_FLAGS
+ at vindex AM_LOG_FLAGS
+For tests that match an extension @code{. at var{ext}} listed in
+ at code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
+the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
+extension) and pass options in @code{AM_ at var{ext}_LOG_FLAGS} and allow
+the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
+all tests with this extension to be called with this runner. For all
+tests without a registered extension, the variables @code{LOG_COMPILER},
+ at code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
+
+ at c Keep in sync with parallel-tests-log-compiler-example.sh
+ at example
+TESTS = foo.pl bar.py baz
+TEST_EXTENSIONS = .pl .py
+PL_LOG_COMPILER = $(PERL)
+AM_PL_LOG_FLAGS = -w
+PY_LOG_COMPILER = $(PYTHON)
+AM_PY_LOG_FLAGS = -v
+LOG_COMPILER = ./wrapper-script
+AM_LOG_FLAGS = -d
+ at end example
+
+ at noindent
+will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
+and @samp{./wrapper-script -d baz} to produce @file{foo.log},
+ at file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
+ at file{bar.trs} and @file{baz.trs} files will be automatically produced
+as a side-effect.
+
+It's important to note that, differently from what we've seen for the
+serial test harness (@pxref{Parallel Test Harness}), the
+ at code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
+ at emph{cannot} be use to define a custom test runner; the
+ at code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
+counterparts) should be used instead:
+
+ at example
+## This is WRONG!
+AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
+ at end example
+
+ at example
+## Do this instead.
+AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
+LOG_COMPILER = $(PERL)
+AM_LOG_FLAGS = -Mstrict -w
+ at end example
+
+By default, the test suite harness will run all tests, but there are
+several ways to limit the set of tests that are run:
+
+ at itemize @bullet
+ at item
+You can set the @code{TESTS} variable. For example, you can use a
+command like this to run only a subset of the tests:
+
+ at example
+env TESTS="foo.test bar.test" make -e check
+ at end example
+
+Note however that the command above will unconditionally overwrite the
+ at file{test-suite.log} file, thus clobbering the recorded results
+of any previous testsuite run. This might be undesirable for packages
+whose testsuite takes long time to execute. Luckily, this problem can
+easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
+for example,
+
+ at c Keep in sync with parallel-tests-log-override-2.sh
+ at example
+env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
+ at end example
+
+will write the result of the partial testsuite runs to the
+ at file{partial.log}, without touching @file{test-suite.log}.
+
+ at item
+You can set the @code{TEST_LOGS} variable. By default, this variable is
+computed at @command{make} run time from the value of @code{TESTS} as
+described above. For example, you can use the following:
+
+ at example
+set x subset*.log; shift
+env TEST_LOGS="foo.log $*" make -e check
+ at end example
+
+The comments made above about @code{TEST_SUITE_LOG} overriding applies
+here too.
+
+ at item
+ at vindex RECHECK_LOGS
+ at cindex lazy test execution
+By default, the test harness removes all old per-test @file{.log} and
+ at file{.trs} files before it starts running tests to regenerate them. The
+variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
+implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
+defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
+By overriding this variable, you can choose which tests need to be
+reconsidered. For example, you can lazily rerun only those tests which
+are outdated, i.e., older than their prerequisite test files, by setting
+this variable to the empty value:
+
+ at example
+env RECHECK_LOGS= make -e check
+ at end example
+
+ at item
+ at trindex recheck
+You can ensure that all tests are rerun which have failed or passed
+unexpectedly, by running @code{make recheck} in the test directory.
+This convenience target will set @code{RECHECK_LOGS} appropriately
+before invoking the main test harness.
+ at end itemize
+
+ at noindent
+In order to guarantee an ordering between tests even with @code{make
+-j at var{N}}, dependencies between the corresponding @file{.log} files
+may be specified through usual @command{make} dependencies. For example,
+the following snippet lets the test named @file{foo-execute.test} depend
+upon completion of the test @file{foo-compile.test}:
+
+ at example
+TESTS = foo-compile.test foo-execute.test
+foo-execute.log: foo-compile.log
+ at end example
+
+ at noindent
+Please note that this ordering ignores the @emph{results} of required
+tests, thus the test @file{foo-execute.test} is run even if the test
+ at file{foo-compile.test} failed or was skipped beforehand. Further,
+please note that specifying such dependencies currently works only for
+tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
+
+Tests without such specified dependencies may be run concurrently with
+parallel @command{make -j at var{N}}, so be sure they are prepared for
+concurrent execution.
+
+ at cindex Unit tests
+ at c Keep in sync with 'parallel-tests-extra-programs.sh'.
+The combination of lazy test execution and correct dependencies between
+tests and their sources may be exploited for efficient unit testing
+during development. To further speed up the edit-compile-test cycle, it
+may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
+instead of with @code{check_PROGRAMS}, as the former allows intertwined
+compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
+not cleaned automatically, @pxref{Uniform}).
+
+The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
+conditional parts as well as configure substitutions. In the latter
+case, however, certain restrictions apply: substituted test names
+must end with a nonempty test suffix like @file{.test}, so that one of
+the inference rules generated by @command{automake} can apply. For
+literal test names, @command{automake} can generate per-target rules
+to avoid this limitation.
+
+Please note that it is currently not possible to use @code{$(srcdir)/}
+or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
+limitation is necessary to avoid generating test logs in the source tree
+and has the unfortunate consequence that it is not possible to specify
+distributed tests that are themselves generated by means of explicit
+rules, in a way that is portable to all @command{make} implementations
+(@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
+semantics of FreeBSD and OpenBSD @command{make} conflict with this).
+In case of doubt you may want to require to use GNU @command{make},
+or work around the issue with inference rules to generate the tests.
+
+ at node Custom Test Drivers
+ at section Custom Test Drivers
+
+ at menu
+* Overview of Custom Test Drivers Support::
+* Declaring Custom Test Drivers::
+* API for Custom Test Drivers::
+ at end menu
+
+ at node Overview of Custom Test Drivers Support
+ at subsection Overview of Custom Test Drivers Support
+
+Starting from Automake version 1.12, the parallel test harness allows
+the package authors to use third-party custom test drivers, in case the
+default ones are inadequate for their purposes, or do not support their
+testing protocol of choice.
+
+A custom test driver is expected to properly run the test programs passed
+to it (including the command-line arguments passed to those programs, if
+any), to analyze their execution and outcome, to create the @file{.log}
+and @file{.trs} files associated to these test runs, and to display the test
+results on the console. It is responsibility of the author of the test
+driver to ensure that it implements all the above steps meaningfully and
+correctly; Automake isn't and can't be of any help here. On the other
+hand, the Automake-provided code for testsuite summary generation offers
+support for test drivers allowing several test results per test script,
+if they take care to register such results properly (@pxref{Log files
+generation and test results recording}).
+
+The exact details of how test scripts' results are to be determined and
+analyzed is left to the individual drivers. Some drivers might only
+consider the test script exit status (this is done for example by the
+default test driver used by the parallel test harness, described
+in the previous section). Other drivers might implement more complex and
+advanced test protocols, which might require them to parse and interpreter
+the output emitted by the test script they're running (examples of such
+protocols are TAP and SubUnit).
+
+It's very important to note that, even when using custom test drivers,
+most of the infrastructure described in the previous section about the
+parallel harness remains in place; this includes:
+
+ at itemize
+ at item
+list of test scripts defined in @code{TESTS}, and overridable at
+runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
+ at item
+concurrency through the use of @command{make}'s option @option{-j};
+ at item
+per-test @file{.log} and @file{.trs} files, and generation of a summary
+ at file{.log} file from them;
+ at item
+ at code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
+of tests;
+ at item
+inter-test dependencies;
+ at item
+support for @code{check_*} variables (@code{check_PROGRAMS},
+ at code{check_LIBRARIES}, ...);
+ at item
+use of @code{VERBOSE} environment variable to get verbose output on
+testsuite failures;
+ at item
+definition and honoring of @code{TESTS_ENVIRONMENT},
+ at code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
+variables;
+ at item
+definition of generic and extension-specific @code{LOG_COMPILER} and
+ at code{LOG_FLAGS} variables.
+ at end itemize
+
+ at noindent
+On the other hand, the exact semantics of how (and if) testsuite output
+colorization, @code{XFAIL_TESTS}, and hard errors are supported and
+handled is left to the individual test drivers.
+
+ at c TODO: We should really add a working example in the doc/ directory,
+ at c TODO: and reference if from here.
+
+ at node Declaring Custom Test Drivers
+ at subsection Declaring Custom Test Drivers
+
+ at vindex _LOG_DRIVER
+ at vindex _LOG_DRIVER_FLAGS
+ at vindex LOG_DRIVER
+ at vindex LOG_DRIVER_FLAGS
+ at vindex @var{ext}_LOG_DRIVER
+ at vindex @var{ext}_LOG_DRIVER_FLAGS
+ at vindex AM_ at var{ext}_LOG_DRIVER_FLAGS
+ at vindex AM_LOG_DRIVER_FLAGS
+Custom testsuite drivers are declared by defining the make variables
+ at code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
+be declared in @code{TEST_EXTENSIONS}). They must be defined to
+programs or scripts that will be used to drive the execution, logging,
+and outcome report of the tests with corresponding extensions (or of
+those with no registered extension in the case of @code{LOG_DRIVER}).
+Clearly, multiple distinct test drivers can be declared in the same
+ at file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
+are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
+two sets of variables can, and often do, usefully and legitimately
+coexist.
+
+ at c TODO: We should really be able to point to a clarifying example here!
+
+The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
+user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
+flags that will be passed to each invocation of @code{LOG_DRIVER},
+with the user-defined flags obviously taking precedence over the
+developer-reserved ones. Similarly, for each extension @var{ext}
+declared in @code{TEST_EXTENSIONS}, flags listed in
+ at code{AM_ at var{ext}_LOG_DRIVER_FLAGS} and
+ at code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
+invocations of @code{@var{ext}_LOG_DRIVER}.
+
+ at node API for Custom Test Drivers
+ at subsection API for Custom Test Drivers
+
+Note that @emph{the APIs described here are still highly experimental},
+and will very likely undergo tightenings and likely also extensive changes
+in the future, to accommodate for new features or to satisfy additional
+portability requirements.
+
+The main characteristic of these APIs is that they are designed to share
+as much infrastructure, semantics, and implementation details as possible
+with the parallel test harness and its default driver.
+
+ at menu
+* Command-line arguments for test drivers::
+* Log files generation and test results recording::
+* Testsuite progress output::
+ at end menu
+
+ at node Command-line arguments for test drivers
+ at subsubsection Command-line arguments for test drivers
+
+A custom driver can rely on various command-line options and arguments
+being passed to it automatically by the Automake-generated test harness.
+It is @emph{mandatory} that it understands all of them (even if the exact
+interpretation of the associated semantics can legitimately change
+between a test driver and another, and even be a no-op in some drivers).
+
+ at noindent
+Here is the list of options:
+
+ at table @option
+ at item --test-name=@var{NAME}
+The name of the test, with VPATH prefix (if any) removed. This can have a
+suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
+mostly meant to be used in console reports about testsuite advancements and
+results (@pxref{Testsuite progress output}).
+ at item --log-file=@file{@var{PATH}.log}
+The @file{.log} file the test driver must create (@pxref{Basics of
+test metadata}). If it has a directory component (as in e.g.,
+ at file{sub/foo.log}), the test harness will ensure that such directory
+exists @emph{before} the test driver is called.
+ at item --trs-file=@file{@var{PATH}.trs}
+The @file{.trs} file the test driver must create (@pxref{Basics of
+test metadata}). If it has a directory component (as in e.g.,
+ at file{sub/foo.trs}), the test harness will ensure that such directory
+exists @emph{before} the test driver is called.
+ at item --color-tests=@{yes|no@}
+Whether the console output should be colorized or not (@pxref{Simple
+tests and color-tests}, to learn when this option gets activated and
+when it doesn't).
+ at item --expect-failure=@{yes|no@}
+Whether the tested program is expected to fail.
+ at item --enable-hard-errors=@{yes|no@}
+Whether ``hard errors'' in the tested program should be treated differently
+from normal failures or not (the default should be @code{yes}). The exact
+meaning of ``hard error'' is highly dependent from the test protocols or
+conventions in use.
+ at item --
+Explicitly terminate the list of options.
+ at end table
+
+ at noindent
+The first non-option argument passed to the test driver is the program to
+be run, and all the following ones are command-line options and arguments
+for this program.
+
+Note that the exact semantics attached to the @option{--color-tests},
+ at option{--expect-failure} and @option{--enable-hard-errors} options are
+left up to the individual test drivers. Still, having a behaviour
+compatible or at least similar to that provided by the default driver
+is advised, as that would offer a better consistency and a more pleasant
+user experience.
+
+ at node Log files generation and test results recording
+ at subsubsection Log files generation and test results recording
+
+The test driver must correctly generate the files specified by the
+ at option{--log-file} and @option{--trs-file} option (even when the tested
+program fails or crashes).
+
+The @file{.log} file should ideally contain all the output produced by the
+tested program, plus optionally other information that might facilitate
+debugging or analysis of bug reports. Apart from that, its format is
+basically free.
+
+The @file{.trs} file is used to register some metadata through the use
+of custom reStructuredText fields. This metadata is expected to be
+employed in various ways by the parallel test harness; for example, to
+count the test results when printing the testsuite summary, or to decide
+which tests to re-run upon @command{make reheck}. Unrecognized metadata
+in a @file{.trs} file is currently ignored by the harness, but this might
+change in the future. The list of currently recognized metadata follows.
+
+ at table @code
+
+ at item :test-result:
+ at cindex Register test result
+ at cindex Register test case result
+ at cindex Test result, registering
+ at cindex Test case result, registering
+ at cindex @code{:test-result:}
+ at cindex reStructuredText field, @code{:test-result:}
+The test driver must use this field to register the results of @emph{each}
+test case run by a test script file. Several @code{:test-result:} fields
+can be present in the same @file{.trs} file; this is done in order to
+support test protocols that allow a single test script to run more test
+cases.
+
+ at c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
+The only recognized test results are currently @code{PASS}, @code{XFAIL},
+ at code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
+when declared with @code{:test-result:}, can be optionally followed by
+text holding the name and/or a brief description of the corresponding
+test; the harness will ignore such extra text when generating
+ at file{test-suite.log} and preparing the testsuite summary.
+
+ at c Keep in sync with 'test-metadata-recheck.sh'.
+ at item @code{:recheck:}
+ at cindex :recheck:
+ at cindex reStructuredText field, @code{:recheck:}
+If this field is present and defined to @code{no}, then the corresponding
+test script will @emph{not} be run upon a @command{make recheck}. What
+happens when two or more @code{:recheck:} fields are present in the same
+ at file{.trs} file is undefined behaviour.
+
+ at c Keep in sync with 'test-metadata-global-log.sh'.
+ at item @code{:copy-in-global-log:}
+ at cindex :copy-in-global-log:
+ at cindex reStructuredText field, @code{:copy-in-global-log:}
+If this field is present and defined to @code{no}, then the content
+of the @file{.log} file will @emph{not} be copied into the global
+ at file{test-suite.log}. We allow to forsake such copying because, while
+it can be useful in debugging and analysis of bug report, it can also be
+just a waste of space in normal situations, e.g., when a test script is
+successful. What happens when two or more @code{:copy-in-global-log:}
+fields are present in the same @file{.trs} file is undefined behaviour.
+
+ at c Keep in sync with 'test-metadata-global-result.sh'.
+ at item @code{:test-global-result:}
+ at cindex :test-global-result:
+ at cindex reStructuredText field, @code{:test-global-result:}
+This is used to declare the "global result" of the script. Currently,
+the value of this field is needed only to be reported (more or less
+verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
+so it's quite free-form. For example, a test script which run 10 test
+cases, 6 of which pass and 4 of which are skipped, could reasonably have
+a @code{PASS/SKIP} value for this field, while a test script which run
+19 successful tests and one failed test could have an @code{ALMOST
+PASSED} value. What happens when two or more @code{:test-global-result:}
+fields are present in the same @file{.trs} file is undefined behaviour.
+ at end table
+
+ at noindent
+Let's see a small example. Assume a @file{.trs} file contains the
+following lines:
+
+ at example
+:test-result: PASS server starts
+:global-log-copy: no
+:test-result: PASS HTTP/1.1 request
+:test-result: FAIL HTTP/1.0 request
+:recheck: yes
+:test-result: SKIP HTTPS request (TLS library wasn't available)
+:test-result: PASS server stops
+ at end example
+
+ at noindent
+Then the corresponding test script will be re-run by @command{make check},
+will contribute with @emph{five} test results to the testsuite summary
+(three of these tests being successful, one failed, and one skipped), and
+the content of the corresponding @file{.log} file will @emph{not} be
+copied in the global log file @file{test-suite.log}.
+
+ at node Testsuite progress output
+ at subsubsection Testsuite progress output
+
+A custom test driver also has the task of displaying, on the standard
+output, the test results as soon as they become available. Depending on
+the protocol in use, it can also display the reasons for failures and
+skips, and, more generally, any useful diagnostic output (but remember
+that each line on the screen is precious, so that cluttering the screen
+with overly verbose information is bad idea). The exact format of this
+progress output is left up to the test driver; in fact, a custom test
+driver might @emph{theoretically} even decide not to do any such report,
+leaving it all to the testsuite summary (that would be a very lousy idea,
+of course, and serves only to illustrate the flexibility that is
+granted here).
+
+Remember that consistency is good; so, if possible, try to be consistent
+with the output of the built-in Automake test drivers, providing a similar
+``look & feel''. In particular, the testsuite progress output should be
+colorized when the @option{--color-tests} is passed to the driver. On the
+other end, if you are using a known and widespread test protocol with
+well-established implementations, being consistent with those
+implementations' output might be a good idea too.
+
+ at c TODO: Give an example, maybe inspired to py.test-style output.
+ at c TODO: That is a good idea because it shows a test driver that allows
+ at c TODO: for different levels of verbosity in the progress output (could
+ at c TODO: be implemented either using a driver cmdline flag, or an
+ at c TODO: environment variable, or both).
+
+ at node Using the TAP test protocol
+ at section Using the TAP test protocol
+
+ at menu
+* Introduction to TAP::
+* Use TAP with the Automake test harness::
+* Incompatibilities with other TAP parsers and drivers::
+* Links and external resources on TAP::
+ at end menu
+
+ at node Introduction to TAP
+ at subsection Introduction to TAP
+
+TAP, the Test Anything Protocol, is a simple text-based interface between
+testing modules or programs and a test harness. The tests (also called
+``TAP producers'' in this context) write test results in a simple format
+on standard output; a test harness (also called ``TAP consumer'') will
+parse and interpret these results, and properly present them to the user,
+and/or register them for later analysis. The exact details of how this
+is accomplished can vary among different test harnesses. The Automake
+harness will present the results on the console in the usual
+fashion (@pxref{Testsuite progress on console}), and will use the
+ at file{.trs} files (@pxref{Basics of test metadata}) to store the test
+results and related metadata. Apart from that, it will try to remain
+as much compatible as possible with pre-existing and widespread utilities,
+such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
+ at command{prove} utility}, at least for the simpler usages.
+
+TAP started its life as part of the test harness for Perl, but today
+it has been (mostly) standardized, and has various independent
+implementations in different languages; among them, C, C++, Perl,
+Python, PHP, and Java. For a semi-official specification of the
+TAP protocol, please refer to the documentation of
+ at uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
+ @samp{Test::Harness::TAP}}.
+
+The most relevant real-world usages of TAP are obviously in the testsuites
+of @command{perl} and of many perl modules. Still, also other important
+third-party packages, such as @uref{http://git-scm.com/, @command{git}},
+use TAP in their testsuite.
+
+ at node Use TAP with the Automake test harness
+ at subsection Use TAP with the Automake test harness
+
+Currently, the TAP driver that comes with Automake requires some by-hand
+steps on the developer's part (this situation should hopefully be improved
+in future Automake versions). You'll have to grab the @file{tap-driver.sh}
+script from the Automake distribution by hand, copy it in your source tree,
+add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
+proper awk program, and use the Automake support for third-party test
+drivers to instruct the harness to use the @file{tap-driver.sh} script
+and that awk program to run your TAP-producing tests. See the example
+below for clarification.
+
+Apart from the options common to all the Automake test drivers
+(@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
+supports the following options, whose names are chosen for enhanced
+compatibility with the @command{prove} utility.
+
+ at table @option
+ at c Keep in sync with 'tap-exit.sh' and 'tap-signal.tap'.
+ at item --ignore-exit
+Causes the test driver to ignore the exit status of the test scripts;
+by default, the driver will report an error if the script exits with a
+non-zero status. This option has effect also on non-zero exit statuses
+due to termination by a signal.
+ at item --comments
+Instruct the test driver to display TAP diagnostic (i.e., lines beginning
+with the @samp{#} character) in the testsuite progress output too; by
+default, TAP diagnostic is only copied to the @file{.log} file.
+ at item --no-comments
+Revert the effects of @option{--comments}.
+ at item --merge
+Instruct the test driver to merge the test scripts' standard error into
+their standard output. This is necessary if you want to ensure that
+diagnostics from the test scripts are displayed in the correct order
+relative to test results; this can be of great help in debugging
+(especially if your test scripts are shell scripts run with shell
+tracing active). As a downside, this option might cause the test
+harness to get confused if anything that appears on standard error
+looks like a test result.
+ at item --no-merge
+Revert the effects of @option{--merge}.
+ at item --diagnostic-string=@var{STRING}
+Change the string that introduces TAP diagnostic from the default value
+of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
+TAP-based test scripts produce verbose output on which they have limited
+control (because, say, the output comes from other tools invoked in the
+scripts), and it might contain text that gets spuriously interpreted as
+TAP diagnostic: such an issue can be solved by redefining the string that
+activates TAP diagnostic to a value you know won't appear by chance in
+the tests' output. Note however that this feature is non-standard, as
+the ``official'' TAP protocol does not allow for such a customization; so
+don't use it if you can avoid it.
+ at end table
+
+ at noindent
+Here is an example of how the TAP driver can be set up and used.
+
+ at c Keep in sync with tap-doc2.sh
+ at example
+% @kbd{cat configure.ac}
+AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
+AC_CONFIG_AUX_DIR([build-aux])
+AM_INIT_AUTOMAKE([foreign -Wall -Werror])
+AC_CONFIG_FILES([Makefile])
+AC_REQUIRE_AUX_FILE([tap-driver.sh])
+AC_PROG_AWK
+AC_OUTPUT
+
+% @kbd{cat Makefile.am}
+TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
+ $(top_srcdir)/build-aux/tap-driver.sh
+TESTS = foo.test bar.test baz.test
+EXTRA_DIST = $(TESTS)
+
+% @kbd{cat foo.test}
+#!/bin/sh
+echo 1..4 # Number of tests to be executed.
+echo 'ok 1 - Swallows fly'
+echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
+echo 'ok 3 - Pigs fly # SKIP not enough acid'
+echo '# I just love word plays ...'
+echo 'ok 4 - Flies fly too :-)'
+
+% @kbd{cat bar.test}
+#!/bin/sh
+echo 1..3
+echo 'not ok 1 - Bummer, this test has failed.'
+echo 'ok 2 - This passed though.'
+echo 'Bail out! Ennui kicking in, sorry...'
+echo 'ok 3 - This will not be seen.'
+
+% @kbd{cat baz.test}
+#!/bin/sh
+echo 1..1
+echo ok 1
+# Exit with error, even if all the tests have been successful.
+exit 7
+
+% @kbd{cp @var{PREFIX}/share/automake- at var{APIVERSION}/tap-driver.pl .}
+% @kbd{autoreconf -vi && ./configure && make check}
+...
+PASS: foo.test 1 - Swallows fly
+XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
+SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
+PASS: foo.test 4 - Flies fly too :-)
+FAIL: bar.test 1 - Bummer, this test has failed.
+PASS: bar.test 2 - This passed though.
+ERROR: bar.test - Bail out! Ennui kicking in, sorry...
+PASS: baz.test 1
+ERROR: baz.test - exited with status 7
+...
+Please report to bug-automake@@gnu.org
+...
+% @kbd{echo exit status: $?}
+exit status: 1
+
+ at c Keep the "skewed" indentation below, it produces pretty PDF output.
+% @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
+ TESTS='foo.test baz.test' make -e check}
+...
+PASS: foo.test 1 - Swallows fly
+XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
+SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
+# foo.test: I just love word plays...
+PASS: foo.test 4 - Flies fly too :-)
+PASS: baz.test 1
+...
+% @kbd{echo exit status: $?}
+exit status: 0
+ at end example
+
+ at node Incompatibilities with other TAP parsers and drivers
+ at subsection Incompatibilities with other TAP parsers and drivers
+
+For implementation or historical reasons, the TAP driver and harness as
+implemented by Automake have some minors incompatibilities with the
+mainstream versions, which you should be aware of.
+
+ at itemize @bullet
+ at item
+A @code{Bail out!} directive doesn't stop the whole testsuite, but only
+the test script it occurs in. This doesn't follow TAP specifications,
+but on the other hand it maximizes compatibility (and code sharing) with
+the ``hard error'' concept of the default testsuite driver.
+ at item
+The @code{version} and @code{pragma} directives are not supported.
+ at item
+The @option{--diagnostic-string} option of our driver allows to modify
+the string that introduces TAP diagnostic from the default value
+of ``@code{#}''. The standard TAP protocol has currently no way to
+allow this, so if you use it your diagnostic will be lost to more
+compliant tools like @command{prove} and @code{Test::Harness}
+ at item
+And there are probably some other small and yet undiscovered
+incompatibilities, especially in corner cases or with rare usages.
+ at end itemize
+
+ at node Links and external resources on TAP
+ at subsection Links and external resources on TAP
+
+ at noindent
+Here are some links to more extensive official or third-party
+documentation and resources about the TAP protocol and related
+tools and libraries.
+ at itemize @bullet
+ at item
+ at uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
+ @samp{Test::Harness::TAP}},
+the (mostly) official documentation about the TAP format and protocol.
+ at item
+ at uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
+ @command{prove}},
+the most famous command-line TAP test driver, included in the distribution
+of @command{perl} and
+ at uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
+ @samp{Test::Harness}}.
+ at item
+The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
+ at item
+A ``gentle introduction'' to testing for perl coders:
+ at uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
+ @samp{Test::Tutorial}}.
+ at item
+ at uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
+ @samp{Test::Simple}}
+and
+ at uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
+ @samp{Test::More}},
+the standard perl testing libraries, which are based on TAP.
+ at item
+ at uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
+a C-based project implementing both a TAP producer and a TAP consumer.
+ at item
+ at uref{http://www.tap4j.org/,tap4j},
+a Java-based project implementing both a TAP producer and a TAP consumer.
+ at end itemize
+
+ at node DejaGnu Tests
+ at section DejaGnu Tests
+
+If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
+ at code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
+assumed. The variable @code{DEJATOOL} is a list of names that are
+passed, one at a time, as the @option{--tool} argument to
+ at command{runtest} invocations; it defaults to the name of the package.
+
+The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
+ at option{--srcdir} flags that are passed to dejagnu by default; this can be
+overridden if necessary.
+ at vindex RUNTESTDEFAULTFLAGS
+
+The variables @code{EXPECT} and @code{RUNTEST} can
+also be overridden to provide project-specific values. For instance,
+you will need to do this if you are testing a compiler toolchain,
+because the default values do not take into account host and target
+names.
+ at opindex dejagnu
+ at vindex DEJATOOL
+ at vindex EXPECT
+ at vindex RUNTEST
+
+The contents of the variable @code{RUNTESTFLAGS} are passed to the
+ at code{runtest} invocation. This is considered a ``user variable''
+(@pxref{User Variables}). If you need to set @command{runtest} flags in
+ at file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
+ at vindex RUNTESTFLAGS
+ at vindex AM_RUNTESTFLAGS
+
+ at cindex @file{site.exp}
+Automake will generate rules to create a local @file{site.exp} file,
+defining various variables detected by @command{configure}. This file
+is automatically read by DejaGnu. It is OK for the user of a package
+to edit this file in order to tune the test suite. However this is
+not the place where the test suite author should define new variables:
+this should be done elsewhere in the real test suite code.
+Especially, @file{site.exp} should not be distributed.
+
+Still, if the package author has legitimate reasons to extend
+ at file{site.exp} at @command{make} time, he can do so by defining
+the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
+there will be considered @file{site.exp} prerequisites, and their
+content will be appended to it (in the same order in which they
+appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
+ at emph{not} distributed by default.
+
+For more information regarding DejaGnu test suites, see @ref{Top, , ,
+dejagnu, The DejaGnu Manual}.
+
+ at node Install Tests
+ at section Install Tests
+
+The @code{installcheck} target is available to the user as a way to
+run any tests after the package has been installed. You can add tests
+to this by writing an @code{installcheck-local} rule.
+
+
+ at node Rebuilding
+ at chapter Rebuilding Makefiles
+ at cindex rebuild rules
+
+Automake generates rules to automatically rebuild @file{Makefile}s,
+ at file{configure}, and other derived files like @file{Makefile.in}.
+
+ at acindex AM_MAINTAINER_MODE
+If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
+these automatic rebuilding rules are only enabled in maintainer mode.
+
+ at vindex CONFIG_STATUS_DEPENDENCIES
+ at vindex CONFIGURE_DEPENDENCIES
+ at cindex @file{version.sh}, example
+ at cindex @file{version.m4}, example
+
+Sometimes it is convenient to supplement the rebuild rules for
+ at file{configure} or @file{config.status} with additional dependencies.
+The variables @code{CONFIGURE_DEPENDENCIES} and
+ at code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
+dependencies. These variables should be defined in all
+ at file{Makefile}s of the tree (because these two rebuild rules are
+output in all them), so it is safer and easier to @code{AC_SUBST} them
+from @file{configure.ac}. For instance, the following statement will
+cause @file{configure} to be rerun each time @file{version.sh} is
+changed.
+
+ at c Keep in sync with remake-config-status-dependencies.sh
+ at example
+AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
+ at end example
+
+ at noindent
+Note the @samp{$(top_srcdir)/} in the file name. Since this variable
+is to be used in all @file{Makefile}s, its value must be sensible at
+any level in the build hierarchy.
+
+Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
+ at code{CONFIG_STATUS_DEPENDENCIES}.
+
+ at c Keep in sync with remake-configure-dependencies.sh
+ at code{CONFIGURE_DEPENDENCIES} adds dependencies to the
+ at file{configure} rule, whose effect is to run @command{autoconf}. This
+variable should be seldom used, because @command{automake} already tracks
+ at code{m4_include}d files. However it can be useful when playing
+tricky games with @code{m4_esyscmd} or similar non-recommendable
+macros with side effects. Be also aware that interactions of this
+variable with the @ref{Autom4te Cache, , autom4te cache, autoconf,
+The Autoconf Manual} are quite problematic and can cause subtle
+breakage, so you might want to disable the cache if you want to use
+ at code{CONFIGURE_DEPENDENCIES}.
+
+ at code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
+ at file{config.status} rule, whose effect is to run @file{configure}.
+This variable should therefore carry any non-standard source that may
+be read as a side effect of running @command{configure}, like @file{version.sh}
+in the example above.
+
+Speaking of @file{version.sh} scripts, we recommend against them
+today. They are mainly used when the version of a package is updated
+automatically by a script (e.g., in daily builds). Here is what some
+old-style @file{configure.ac}s may look like:
+
+ at example
+AC_INIT
+. $srcdir/version.sh
+AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
+ at dots{}
+ at end example
+
+ at noindent
+Here, @file{version.sh} is a shell fragment that sets
+ at code{VERSION_NUMBER}. The problem with this example is that
+ at command{automake} cannot track dependencies (listing @file{version.sh}
+in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
+to the user), and that it uses the obsolete form of @code{AC_INIT} and
+ at code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
+straightforward, because shell variables are not allowed in
+ at code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
+replaced by an M4 file that is included by @file{configure.ac}:
+
+ at example
+m4_include([version.m4])
+AC_INIT([name], VERSION_NUMBER)
+AM_INIT_AUTOMAKE
+ at dots{}
+ at end example
+
+ at noindent
+Here @file{version.m4} could contain something like
+ at samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
+second form is that @command{automake} will take care of the
+dependencies when defining the rebuild rule, and will also distribute
+the file automatically. An inconvenience is that @command{autoconf}
+will now be rerun each time the version number is bumped, when only
+ at file{configure} had to be rerun in the previous setup.
+
+
+ at node Options
+ at chapter Changing Automake's Behavior
+
+ at menu
+* Options generalities:: Semantics of Automake option
+* List of Automake options:: A comprehensive list of Automake options
+ at end menu
+
+ at node Options generalities
+ at section Options generalities
+
+Various features of Automake can be controlled by options. Except where
+noted otherwise, options can be specified in one of several ways. Most
+options can be applied on a per- at file{Makefile} basis when listed in a
+special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
+of these options only make sense when specified in the toplevel
+ at file{Makefile.am} file. Options are applied globally to all processed
+ at file{Makefile} files when listed in the first argument of
+ at code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
+require changes to the @command{configure} script can only be specified
+there. These are annotated below.
+
+As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
+precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
+turn take precedence over those specified on the command line.
+
+Also, some care must be taken about the interactions among strictness
+level and warning categories. As a general rule, strictness-implied
+warnings are overridden by those specified by explicit options. For
+example, even if @samp{portability} warnings are disabled by default
+in @option{foreign} strictness, an usage like this will end up enabling
+them:
+
+ at example
+AUTOMAKE_OPTIONS = -Wportability foreign
+ at end example
+
+However, a strictness level specified in a higher-priority context
+will override all the explicit warnings specified in a lower-priority
+context. For example, if @file{configure.ac} contains:
+
+ at example
+AM_INIT_AUTOMAKE([-Wportability])
+ at end example
+
+ at noindent
+and @file{Makefile.am} contains:
+
+ at example
+AUTOMAKE_OPTIONS = foreign
+ at end example
+
+ at noindent
+then @samp{portability} warnings will be @emph{disabled} in
+ at file{Makefile.am}.
+
+ at node List of Automake options
+ at section List of Automake options
+
+ at vindex AUTOMAKE_OPTIONS
+
+ at table @asis
+ at item @option{gnits}
+ at itemx @option{gnu}
+ at itemx @option{foreign}
+ at cindex Option, @option{gnits}
+ at cindex Option, @option{gnu}
+ at cindex Option, @option{foreign}
+ at opindex gnits
+ at opindex gnu
+ at opindex foreign
+
+Set the strictness as appropriate. The @option{gnits} option also
+implies options @option{readme-alpha} and @option{check-news}.
+
+ at item @option{check-news}
+ at cindex Option, @option{check-news}
+ at opindex check-news
+Cause @samp{make dist} to fail unless the current version number appears
+in the first few lines of the @file{NEWS} file.
+
+ at item @option{dejagnu}
+ at cindex Option, @option{dejagnu}
+ at opindex dejagnu
+Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
+
+ at item @option{dist-bzip2}
+ at cindex Option, @option{dist-bzip2}
+ at opindex dist-bzip2
+Hook @code{dist-bzip2} to @code{dist}.
+ at trindex dist-bzip2
+
+ at item @option{dist-lzip}
+ at cindex Option, @option{dist-lzip}
+ at opindex dist-lzip
+Hook @code{dist-lzip} to @code{dist}.
+ at trindex dist-lzip
+
+ at item @option{dist-xz}
+ at cindex Option, @option{dist-xz}
+ at opindex dist-xz
+Hook @code{dist-xz} to @code{dist}.
+ at trindex dist-xz
+
+ at item @option{dist-zip}
+ at cindex Option, @option{dist-zip}
+ at opindex dist-zip
+Hook @code{dist-zip} to @code{dist}.
+ at trindex dist-zip
+
+ at item @option{dist-shar}
+ at cindex Option, @option{dist-shar}
+ at opindex dist-shar
+Hook @code{dist-shar} to @code{dist}. Use of this option
+is deprecated, as the @samp{shar} format is obsolescent and
+problematic. Support for it will be removed altogether in
+Automake 2.0.
+ at trindex dist-shar
+
+ at item @option{dist-tarZ}
+ at cindex Option, @option{dist-tarZ}
+ at opindex dist-tarZ
+Hook @code{dist-tarZ} to @code{dist}. Use of this option
+is deprecated, as the @samp{compress} program is obsolete.
+Support for it will be removed altogether in Automake 2.0.
+ at trindex dist-tarZ
+
+ at item @option{filename-length-max=99}
+ at cindex Option, @option{filename-length-max=99}
+ at opindex filename-length-max=99
+Abort if file names longer than 99 characters are found during
+ at samp{make dist}. Such long file names are generally considered not to
+be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
+options below. This option should be used in the top-level
+ at file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
+ at file{configure.ac}, it will be ignored otherwise. It will also be
+ignored in sub-packages of nested packages (@pxref{Subpackages}).
+
+ at item @option{info-in-builddir}
+ at cindex Option, @option{info-in-builddir}
+ at opindex info-in-builddir
+Instruct Automake to place the generated @file{.info} files in the
+ at code{builddir} rather than in the @code{srcdir}. Note that this
+might make VPATH builds with some non-GNU make implementations more
+brittle.
+
+ at item @option{no-define}
+ at cindex Option, @option{no-define}
+ at opindex no-define
+This option is meaningful only when passed as an argument to
+ at code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
+ at code{VERSION} variables from being @code{AC_DEFINE}d.
+
+ at item @option{no-dependencies}
+ at cindex Option, @option{no-dependencies}
+ at opindex no-dependencies
+This is similar to using @option{--ignore-deps} on the command line,
+but is useful for those situations where you don't have the necessary
+bits to make automatic dependency tracking work
+(@pxref{Dependencies}). In this case the effect is to effectively
+disable automatic dependency tracking.
+
+ at item @option{no-dist}
+ at cindex Option, @option{no-dist}
+ at opindex no-dist
+Don't emit any code related to @code{dist} target. This is useful
+when a package has its own method for making distributions.
+
+ at item @option{no-dist-gzip}
+ at cindex Option, @option{no-dist-gzip}
+ at opindex no-dist-gzip
+Do not hook @code{dist-gzip} to @code{dist}.
+ at trindex no-dist-gzip
+
+ at item @option{no-exeext}
+ at cindex Option, @option{no-exeext}
+ at opindex no-exeext
+If your @file{Makefile.am} defines a rule for target @code{foo}, it
+will override a rule for a target named @samp{foo$(EXEEXT)}. This is
+necessary when @code{EXEEXT} is found to be empty. However, by
+default @command{automake} will generate an error for this use. The
+ at option{no-exeext} option will disable this error. This is intended for
+use only where it is known in advance that the package will not be
+ported to Windows, or any other operating system using extensions on
+executables.
+
+ at item @option{no-installinfo}
+ at cindex Option, @option{no-installinfo}
+ at opindex no-installinfo
+The generated @file{Makefile.in} will not cause info pages to be built
+or installed by default. However, @code{info} and @code{install-info}
+targets will still be available. This option is disallowed at
+ at option{gnu} strictness and above.
+ at trindex info
+ at trindex install-info
+
+ at item @option{no-installman}
+ at cindex Option, @option{no-installman}
+ at opindex no-installman
+The generated @file{Makefile.in} will not cause man pages to be
+installed by default. However, an @code{install-man} target will still
+be available for optional installation. This option is disallowed at
+ at option{gnu} strictness and above.
+ at trindex install-man
+
+ at item @option{nostdinc}
+ at cindex Option, @option{nostdinc}
+ at opindex nostdinc
+This option can be used to disable the standard @option{-I} options that
+are ordinarily automatically provided by Automake.
+
+ at item @option{no-texinfo.tex}
+ at cindex Option, @option{no-texinfo.tex}
+ at opindex no-texinfo.tex
+Don't require @file{texinfo.tex}, even if there are texinfo files in
+this directory.
+
+ at item @option{serial-tests}
+ at cindex Option, @option{serial-tests}
+ at opindex serial-tests
+Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
+Test Harness}, for more information).
+
+ at item @option{parallel-tests}
+ at cindex Option, @option{parallel-tests}
+ at opindex parallel-tests
+Enable test suite harness for @code{TESTS} that can run tests in parallel
+(@pxref{Parallel Test Harness}, for more information). This option is
+only kept for backward-compatibility, since the parallel test harness is
+the default now.
+
+ at item @option{readme-alpha}
+ at cindex Option, @option{readme-alpha}
+ at opindex readme-alpha
+If this release is an alpha release, and the file @file{README-alpha}
+exists, then it will be added to the distribution. If this option is
+given, version numbers are expected to follow one of two forms. The
+first form is @samp{@var{major}. at var{minor}. at var{alpha}}, where each
+element is a number; the final period and number should be left off for
+non-alpha releases. The second form is
+ at samp{@var{major}. at var{minor}@var{alpha}}, where @var{alpha} is a
+letter; it should be omitted for non-alpha releases.
+
+ at item @option{std-options}
+ at cindex Options, @option{std-options}
+ at cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
+ at cindex @option{--help} check
+ at cindex @option{--version} check
+ at opindex std-options
+
+Make the @code{installcheck} rule check that installed scripts and
+programs support the @option{--help} and @option{--version} options.
+This also provides a basic check that the program's
+run-time dependencies are satisfied after installation.
+
+ at vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
+In a few situations, programs (or scripts) have to be exempted from this
+test. For instance, @command{false} (from GNU coreutils) is never
+successful, even for @option{--help} or @option{--version}. You can list
+such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
+Programs (not scripts) listed in this variable should be suffixed by
+ at samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
+build @file{false} as a program but @file{true.sh} as a script, and that
+neither of them support @option{--help} or @option{--version}:
+
+ at example
+AUTOMAKE_OPTIONS = std-options
+bin_PROGRAMS = false ...
+bin_SCRIPTS = true.sh ...
+AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
+ at end example
+
+ at item @option{subdir-objects}
+ at cindex Options, @option{subdir-objects}
+ at opindex subdir-objects
+If this option is specified, then objects are placed into the
+subdirectory of the build directory corresponding to the subdirectory of
+the source file. For instance, if the source file is
+ at file{subdir/file.cxx}, then the output file would be
+ at file{subdir/file.o}.
+
+ at anchor{tar-formats}
+ at item @option{tar-v7}
+ at itemx @option{tar-ustar}
+ at itemx @option{tar-pax}
+ at cindex Option, @option{tar-v7}
+ at cindex Option, @option{tar-ustar}
+ at cindex Option, @option{tar-pax}
+ at cindex @command{tar} formats
+ at cindex v7 @command{tar} format
+ at cindex ustar format
+ at cindex pax format
+ at opindex tar-v7
+ at opindex tar-ustar
+ at opindex tar-pax
+
+These three mutually exclusive options select the tar format to use
+when generating tarballs with @samp{make dist}. (The tar file created
+is then compressed according to the set of @option{no-dist-gzip},
+ at option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
+ at option{dist-tarZ} options in use.)
+
+These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
+(@pxref{Macros}) because they can require additional configure checks.
+Automake will complain if it sees such options in an
+ at code{AUTOMAKE_OPTIONS} variable.
+
+ at option{tar-v7} selects the old V7 tar format. This is the historical
+default. This antiquated format is understood by all tar
+implementations and supports file names with up to 99 characters. When
+given longer file names some tar implementations will diagnose the
+problem while other will generate broken tarballs or use non-portable
+extensions. Furthermore, the V7 format cannot store empty
+directories. When using this format, consider using the
+ at option{filename-length-max=99} option to catch file names too long.
+
+ at option{tar-ustar} selects the ustar format defined by POSIX
+1003.1-1988. This format is believed to be old enough to be portable.
+It fully supports empty directories. It can store file names with up
+to 256 characters, provided that the file name can be split at
+directory separator in two parts, first of them being at most 155
+bytes long. So, in most cases the maximum file name length will be
+shorter than 256 characters. However you may run against broken tar
+implementations that incorrectly handle file names longer than 99
+characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
+can document this accurately).
+
+ at option{tar-pax} selects the new pax interchange format defined by POSIX
+1003.1-2001. It does not limit the length of file names. However,
+this format is very young and should probably be restricted to
+packages that target only very modern platforms. There are moves to
+change the pax format in an upward-compatible way, so this option may
+refer to a more recent version in the future.
+
+ at xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
+further discussion about tar formats.
+
+ at command{configure} knows several ways to construct these formats. It
+will not abort if it cannot find a tool up to the task (so that the
+package can still be built), but @samp{make dist} will fail.
+
+ at item @var{version}
+ at cindex Option, @var{version}
+A version number (e.g., @samp{0.30}) can be specified. If Automake is not
+newer than the version specified, creation of the @file{Makefile.in}
+will be suppressed.
+
+ at item @option{-W at var{category}} or @option{--warnings=@var{category}}
+ at cindex Option, warnings
+ at cindex Option, @option{-W at var{category}}
+ at cindex Option, @option{--warnings=@var{category}}
+These options behave exactly like their command-line counterpart
+(@pxref{automake Invocation}). This allows you to enable or disable some
+warning categories on a per-file basis. You can also setup some warnings
+for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
+in your @file{configure.ac}.
+
+ at end table
+
+Unrecognized options are diagnosed by @command{automake}.
+
+If you want an option to apply to all the files in the tree, you can use
+the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
+ at xref{Macros}.
+
+
+ at node Miscellaneous
+ at chapter Miscellaneous Rules
+
+There are a few rules and variables that didn't fit anywhere else.
+
+ at menu
+* Tags:: Interfacing to cscope, etags and mkid
+* Suffixes:: Handling new file extensions
+ at end menu
+
+
+ at node Tags
+ at section Interfacing to @command{etags}
+
+ at cindex @file{TAGS} support
+
+Automake will generate rules to generate @file{TAGS} files for use with
+GNU Emacs under some circumstances.
+
+ at trindex tags
+If any C, C++ or Fortran 77 source code or headers are present, then
+ at code{tags} and @code{TAGS} rules will be generated for the directory.
+All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
+ at code{_LISP} primaries will be used to generate tags. Note that
+generated source files that are not distributed must be declared in
+variables like @code{nodist_noinst_HEADERS} or
+ at code{nodist_ at var{prog}_SOURCES} or they will be ignored.
+
+A @code{tags} rule will be output at the topmost directory of a
+multi-directory package. When run from this topmost directory,
+ at samp{make tags} will generate a @file{TAGS} file that includes by
+reference all @file{TAGS} files from subdirectories.
+
+The @code{tags} rule will also be generated if the variable
+ at code{ETAGS_ARGS} is defined. This variable is intended for use in
+directories that contain taggable source that @command{etags} does
+not understand. The user can use the @code{ETAGSFLAGS} to pass
+additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
+available for use in @file{Makefile.am}.
+ at vindex ETAGS_ARGS
+ at vindex ETAGSFLAGS
+ at vindex AM_ETAGSFLAGS
+
+Here is how Automake generates tags for its source, and for nodes in its
+Texinfo file:
+
+ at example
+ETAGS_ARGS = automake.in --lang=none \
+ --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
+ at end example
+
+If you add file names to @code{ETAGS_ARGS}, you will probably also
+want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
+are added directly to the dependencies for the @code{tags} rule.
+ at vindex TAGS_DEPENDENCIES
+
+Automake also generates a @code{ctags} rule that can be used to
+build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
+is the name of the program to invoke (by default @command{ctags});
+ at code{CTAGSFLAGS} can be used by the user to pass additional flags,
+and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
+
+ at trindex id
+Automake will also generate an @code{ID} rule that will run
+ at command{mkid} on the source. This is only supported on a
+directory-by-directory basis.
+
+Similarly, the @code{cscope} rule will create a list of all the source
+files in the tree and run @command{cscope} to build an inverted index
+database. The variable @code{CSCOPE} is the name of the program to invoke
+(by default @command{cscope}); @code{CSCOPEFLAGS} and
+ at code{CSCOPE_ARGS} can be used by the user to pass additional flags and
+file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
+ at file{Makefile.am}. Note that, currently, the Automake-provided
+ at code{cscope} support, when used in a VPATH build, might not work well
+with non-GNU make implementations (especially with make implementations
+performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
+The Autoconf Manual}).
+
+Finally, Automake also emits rules to support the
+ at uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
+The @code{GTAGS} rule runs Global Tags and puts the
+result in the top build directory. The variable @code{GTAGS_ARGS}
+holds arguments that are passed to @command{gtags}.
+ at vindex GTAGS_ARGS
+
+
+ at node Suffixes
+ at section Handling new file extensions
+
+ at cindex Adding new @code{SUFFIXES}
+ at cindex @code{SUFFIXES}, adding
+ at vindex SUFFIXES
+
+It is sometimes useful to introduce a new implicit rule to handle a file
+type that Automake does not know about.
+
+For instance, suppose you had a compiler that could compile @file{.foo}
+files to @file{.o} files. You would simply define a suffix rule for
+your language:
+
+ at example
+.foo.o:
+ foocc -c -o $@@ $<
+ at end example
+
+Then you could directly use a @file{.foo} file in a @code{_SOURCES}
+variable and expect the correct results:
+
+ at example
+bin_PROGRAMS = doit
+doit_SOURCES = doit.foo
+ at end example
+
+This was the simpler and more common case. In other cases, you will
+have to help Automake to figure out which extensions you are defining your
+suffix rule for. This usually happens when your extension does not
+start with a dot. Then, all you have to do is to put a list of new
+suffixes in the @code{SUFFIXES} variable @strong{before} you define your
+implicit rule.
+
+For instance, the following definition prevents Automake from misinterpreting
+the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
+ at file{.cpp} files.
+
+ at c Keep in sync with suffix7.sh
+ at example
+SUFFIXES = .idl C.cpp
+.idlC.cpp:
+ # whatever
+ at end example
+
+As you may have noted, the @code{SUFFIXES} variable behaves like the
+ at code{.SUFFIXES} special target of @command{make}. You should not touch
+ at code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
+Automake generate the suffix list for @code{.SUFFIXES}. Any given
+ at code{SUFFIXES} go at the start of the generated suffixes list, followed
+by Automake generated suffixes not already in the list.
+
+ at node Include
+ at chapter Include
+
+ at cmindex include
+ at cindex Including @file{Makefile} fragment
+ at cindex @file{Makefile} fragment, including
+
+Automake supports an @code{include} directive that can be used to
+include other @file{Makefile} fragments when @command{automake} is run.
+Note that these fragments are read and interpreted by @command{automake},
+not by @command{make}. As with conditionals, @command{make} has no idea that
+ at code{include} is in use.
+
+There are two forms of @code{include}:
+
+ at table @code
+ at item include $(srcdir)/file
+Include a fragment that is found relative to the current source
+directory.
+
+ at item include $(top_srcdir)/file
+Include a fragment that is found relative to the top source directory.
+ at end table
+
+Note that if a fragment is included inside a conditional, then the
+condition applies to the entire contents of that fragment.
+
+Makefile fragments included this way are always distributed because
+they are needed to rebuild @file{Makefile.in}.
+
+Inside a fragment, the construct @code{%reldir%} is replaced with the
+directory of the fragment relative to the base @file{Makefile.am}.
+Similarly, @code{%canon_reldir%} is replaced with the canonicalized
+(@pxref{Canonicalization}) form of @code{%reldir%}. As a convenience,
+ at code{%D%} is a synonym for @code{%reldir%}, and @code{%C%}
+is a synonym for @code{%canon_reldir%}.
+
+A special feature is that if the fragment is in the same directory as
+the base @file{Makefile.am} (i.e., @code{%reldir%} is @code{.}), then
+ at code{%reldir%} and @code{%canon_reldir%} will expand to the empty
+string as well as eat, if present, a following slash or underscore
+respectively.
+
+Thus, a makefile fragment might look like this:
+
+ at example
+bin_PROGRAMS += %reldir%/mumble
+%canon_reldir%_mumble_SOURCES = %reldir%/one.c
+ at end example
+
+ at node Conditionals
+ at chapter Conditionals
+
+ at cindex Conditionals
+
+Automake supports a simple type of conditionals.
+
+These conditionals are not the same as conditionals in
+GNU Make. Automake conditionals are checked at configure time by the
+ at file{configure} script, and affect the translation from
+ at file{Makefile.in} to @file{Makefile}. They are based on options passed
+to @file{configure} and on results that @file{configure} has discovered
+about the host system. GNU Make conditionals are checked at @command{make}
+time, and are based on variables passed to the make program or defined
+in the @file{Makefile}.
+
+Automake conditionals will work with any make program.
+
+ at menu
+* Usage of Conditionals:: Declaring conditional content
+* Limits of Conditionals:: Enclosing complete statements
+ at end menu
+
+ at node Usage of Conditionals
+ at section Usage of Conditionals
+
+ at acindex AM_CONDITIONAL
+Before using a conditional, you must define it by using
+ at code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
+
+ at defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
+The conditional name, @var{conditional}, should be a simple string
+starting with a letter and containing only letters, digits, and
+underscores. It must be different from @samp{TRUE} and @samp{FALSE}
+that are reserved by Automake.
+
+The shell @var{condition} (suitable for use in a shell @code{if}
+statement) is evaluated when @command{configure} is run. Note that you
+must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
+time @command{configure} is run. If @code{AM_CONDITIONAL} is run
+conditionally (e.g., in a shell @code{if} statement), then the result
+will confuse @command{automake}.
+ at end defmac
+
+ at cindex @option{--enable-debug}, example
+ at cindex Example conditional @option{--enable-debug}
+ at cindex Conditional example, @option{--enable-debug}
+
+Conditionals typically depend upon options that the user provides to
+the @command{configure} script. Here is an example of how to write a
+conditional that is true if the user uses the @option{--enable-debug}
+option.
+
+ at example
+AC_ARG_ENABLE([debug],
+[ --enable-debug Turn on debugging],
+[case "$@{enableval@}" in
+ yes) debug=true ;;
+ no) debug=false ;;
+ *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
+esac],[debug=false])
+AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
+ at end example
+
+Here is an example of how to use that conditional in @file{Makefile.am}:
+
+ at cmindex if
+ at cmindex endif
+ at cmindex else
+
+ at example
+if DEBUG
+DBG = debug
+else
+DBG =
+endif
+noinst_PROGRAMS = $(DBG)
+ at end example
+
+This trivial example could also be handled using @code{EXTRA_PROGRAMS}
+(@pxref{Conditional Programs}).
+
+You may only test a single variable in an @code{if} statement, possibly
+negated using @samp{!}. The @code{else} statement may be omitted.
+Conditionals may be nested to any depth. You may specify an argument to
+ at code{else} in which case it must be the negation of the condition used
+for the current @code{if}. Similarly you may specify the condition
+that is closed on the @code{endif} line:
+
+ at example
+if DEBUG
+DBG = debug
+else !DEBUG
+DBG =
+endif !DEBUG
+ at end example
+
+ at noindent
+Unbalanced conditions are errors. The @code{if}, @code{else}, and
+ at code{endif} statements should not be indented, i.e., start on column
+one.
+
+The @code{else} branch of the above two examples could be omitted,
+since assigning the empty string to an otherwise undefined variable
+makes no difference.
+
+ at acindex AM_COND_IF
+In order to allow access to the condition registered by
+ at code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
+conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
+
+ at defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
+If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
+execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
+it will cause @command{automake} to output the rules for the respective
+files only for the given condition.
+ at end defmac
+
+ at code{AM_COND_IF} macros may be nested when m4 quotation is used
+properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
+
+ at cindex Example conditional @code{AC_CONFIG_FILES}
+ at cindex @code{AC_CONFIG_FILES}, conditional
+
+Here is an example of how to define a conditional config file:
+
+ at example
+AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
+AM_COND_IF([SHELL_WRAPPER],
+ [AC_CONFIG_FILES([wrapper:wrapper.in])])
+ at end example
+
+ at node Limits of Conditionals
+ at section Limits of Conditionals
+
+Conditionals should enclose complete statements like variables or
+rules definitions. Automake cannot deal with conditionals used inside
+a variable definition, for instance, and is not even able to diagnose
+this situation. The following example would not work:
+
+ at example
+# This syntax is not understood by Automake
+AM_CPPFLAGS = \
+ -DFEATURE_A \
+if WANT_DEBUG
+ -DDEBUG \
+endif
+ -DFEATURE_B
+ at end example
+
+However the intended definition of @code{AM_CPPFLAGS} can be achieved
+with
+
+ at example
+if WANT_DEBUG
+ DEBUGFLAGS = -DDEBUG
+endif
+AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
+ at end example
+
+ at noindent
+or
+
+ at example
+AM_CPPFLAGS = -DFEATURE_A
+if WANT_DEBUG
+AM_CPPFLAGS += -DDEBUG
+endif
+AM_CPPFLAGS += -DFEATURE_B
+ at end example
+
+More details and examples of conditionals are described alongside
+various Automake features in this manual (@pxref{Conditional
+Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
+Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
+Libtool Sources}).
+
+ at node Silencing Make
+ at chapter Silencing @command{make}
+
+ at cindex Silent @command{make}
+ at cindex Silencing @command{make}
+ at cindex Silent rules
+ at cindex Silent @command{make} rules
+
+ at menu
+* 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
+ at end menu
+
+ at node Make verbosity
+ at section Make is verbose by default
+
+Normally, when executing the set of rules associated with a target,
+ at command{make} prints each rule before it is executed. This behaviour,
+while having been in place for a long time, and being even mandated by
+the POSIX standard, starkly violates the ``silence is golden'' UNIX
+principle at footnote{See also
+ at uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
+
+ at quotation
+When a program has nothing interesting or surprising to say, it should
+say nothing. Well-behaved Unix programs do their jobs unobtrusively,
+with a minimum of fuss and bother. Silence is golden.
+ at end quotation
+
+In fact, while such verbosity of @command{make} can theoretically be
+useful to track bugs and understand reasons of failures right away, it
+can also hide warning and error messages from @command{make}-invoked
+tools, drowning them in a flood of uninteresting and seldom useful
+messages, and thus allowing them to go easily undetected.
+
+This problem can be very annoying, especially for developers, who usually
+know quite well what's going on behind the scenes, and for whom the
+verbose output from @command{make} ends up being mostly noise that hampers
+the easy detection of potentially important warning messages.
+
+ at node Tricks For Silencing Make
+ at section Standard and generic ways to silence make
+
+Here we describe some common idioms/tricks to obtain a quieter make
+output, with their relative advantages and drawbacks. In the next
+section (@ref{Automake Silent Rules}) we'll see how Automake can help
+in this respect, providing more elaborate and flexible idioms.
+
+ at itemize @bullet
+
+ at item @command{make -s}
+
+This simply causes @command{make} not to print @emph{any} rule before
+executing it.
+
+The @option{-s} flag is mandated by POSIX, universally supported, and
+its purpose and function are easy to understand.
+
+But it also has its serious limitations too. First of all, it embodies
+an ``all or nothing'' strategy, i.e., either everything is silenced, or
+nothing is; this lack of granularity can sometimes be a fatal flaw.
+Moreover, when the @option{-s} flag is used, the @command{make} output
+might turn out to be too much terse; in case of errors, the user won't
+be able to easily see what rule or command have caused them, or even,
+in case of tools with poor error reporting, what the errors were!
+
+ at item @command{make >/dev/null || make}
+
+Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
+from stderr are passed through, output reporting is done only in case of
+error, and in that case it should provide a verbose-enough report to allow
+an easy determination of the error location and causes.
+
+However, calling @command{make} two times in a row might hide errors
+(especially intermittent ones), or subtly change the expected semantic
+of the @command{make} calls --- things these which can clearly make
+debugging and error assessment very difficult.
+
+ at item @command{make --no-print-directory}
+
+This is GNU @command{make} specific. When called with the
+ at option{--no-print-directory} option, GNU @command{make} will disable
+printing of the working directory by invoked sub- at command{make}s (the
+well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
+to decrease the verbosity of the output, but experience has shown that
+it can also often render debugging considerably harder in projects using
+deeply-nested @command{make} recursion.
+
+As an aside, notice that the @option{--no-print-directory} option is
+automatically activated if the @option{-s} flag is used.
+
+ at c TODO: Other tricks?
+ at c TODO: Maybe speak about the @code{.SILENT} target?
+ at c TODO: - Pros: More granularity on what to silence.
+ at c TODO: - Cons: No easy way to temporarily override.
+
+ at end itemize
+
+ at node Automake Silent Rules
+ at section How Automake can help in silencing make
+
+The tricks and idioms for silencing @command{make} described in the
+previous section can be useful from time to time, but we've seen that
+they all have their serious drawbacks and limitations. That's why
+automake provides support for a more advanced and flexible way of
+obtaining quieter output from @command{make} (for most rules at least).
+
+ at c TODO: Maybe describe in brief the precedent set by the build system
+ at c of the Linux Kernel, from which Automake took inspiration ... Links?
+
+To give the gist of what Automake can do in this respect, here is a simple
+comparison between a typical @command{make} output (where silent rules
+are disabled) and one with silent rules enabled:
+
+ at example
+% @kbd{cat Makefile.am}
+bin_PROGRAMS = foo
+foo_SOURCES = main.c func.c
+% @kbd{cat main.c}
+int main (void) @{ return func (); @} /* func used undeclared */
+% @kbd{cat func.c}
+int func (void) @{ int i; return i; @} /* i used uninitialized */
+
+ at i{The make output is by default very verbose. This causes warnings
+from the compiler to be somewhat hidden, and not immediate to spot.}
+% @kbd{make CFLAGS=-Wall}
+gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
+-DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
+-DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
+-MD -MP -MF .deps/main.Tpo -c -o main.o main.c
+main.c: In function ‘main’:
+main.c:3:3: warning: implicit declaration of function ‘func’
+mv -f .deps/main.Tpo .deps/main.Po
+gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
+-DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
+-DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
+-MD -MP -MF .deps/func.Tpo -c -o func.o func.c
+func.c: In function ‘func’:
+func.c:4:3: warning: ‘i’ used uninitialized in this function
+mv -f .deps/func.Tpo .deps/func.Po
+gcc -Wall -o foo main.o func.o
+
+ at i{Clean up, so that we we can rebuild everything from scratch.}
+% @kbd{make clean}
+test -z "foo" || rm -f foo
+rm -f *.o
+
+ at i{Silent rules enabled: the output is minimal but informative. In
+particular, the warnings from the compiler stick out very clearly.}
+% @kbd{make V=0 CFLAGS=-Wall}
+ CC main.o
+main.c: In function ‘main’:
+main.c:3:3: warning: implicit declaration of function ‘func’
+ CC func.o
+func.c: In function ‘func’:
+func.c:4:3: warning: ‘i’ used uninitialized in this function
+ CCLD foo
+ at end example
+
+ at cindex silent rules and libtool
+Also, in projects using @command{libtool}, the use of silent rules can
+automatically enable the @command{libtool}'s @option{--silent} option:
+
+ at example
+% @kbd{cat Makefile.am}
+lib_LTLIBRARIES = libx.la
+
+% @kbd{make # Both make and libtool are verbose by default.}
+...
+libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
+ -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
+ -DPIC -o .libs/libx.o
+mv -f .deps/libx.Tpo .deps/libx.Plo
+/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
+ /usr/local/lib libx.lo
+libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
+ -o .libs/libx.so.0.0.0
+libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
+...
+
+% @kbd{make V=0}
+ CC libx.lo
+ CCLD libx.la
+ at end example
+
+For Automake-generated @file{Makefile}s, the user may influence the
+verbosity at @command{configure} run time as well as at @command{make}
+run time:
+
+ at itemize @bullet
+ at item
+ at opindex --enable-silent-rules
+ at opindex --disable-silent-rules
+Passing @option{--enable-silent-rules} to @command{configure} will cause
+build rules to be less verbose; the option @option{--disable-silent-rules}
+will cause normal verbose output.
+ at item
+ at vindex @code{V}
+At @command{make} run time, the default chosen at @command{configure}
+time may be overridden: @code{make V=1} will produce verbose output,
+ at code{make V=0} less verbose output.
+ at end itemize
+
+ at cindex default verbosity for silent rules
+Note that silent rules are @emph{disabled} by default; the user must
+enable them explicitly at either @command{configure} run time or at
+ at command{make} run time. We think that this is a good policy, since
+it provides the casual user with enough information to prepare a good
+bug report in case anything breaks.
+
+Still, notwithstanding the rationales above, a developer who really
+wants to make silent rules enabled by default in his own package can
+do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
+
+ at c Keep in sync with silent-configsite.sh
+Users who prefer to have silent rules enabled by default can edit their
+ at file{config.site} file to make the variable @code{enable_silent_rules}
+default to @samp{yes}. This should still allow disabling silent rules
+at @command{configure} time and at @command{make} time.
+
+ at c FIXME: there's really a need to specify this explicitly?
+For portability to different @command{make} implementations, package authors
+are advised to not set the variable @code{V} inside the @file{Makefile.am}
+file, to allow the user to override the value for subdirectories as well.
+
+To work at its best, the current implementation of this feature normally
+uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
+feature that is not required by POSIX 2008 but is widely supported in
+practice. On the rare @command{make} implementations that do not support
+nested variable expansion, whether rules are silent is always determined at
+configure time, and cannot be overridden at make time. Future versions of
+POSIX are likely to require nested variable expansion, so this minor
+limitation should go away with time.
+
+ at vindex @code{AM_V_GEN}
+ at vindex @code{AM_V_at}
+ at vindex @code{AM_DEFAULT_VERBOSITY}
+ at vindex @code{AM_V}
+ at vindex @code{AM_DEFAULT_V}
+To extend the silent mode to your own rules, you have few choices:
+
+ at itemize @bullet
+
+ at item
+You can use the predefined variable @code{AM_V_GEN} as a prefix to
+commands that should output a status line in silent mode, and
+ at code{AM_V_at} as a prefix to commands that should not output anything
+in silent mode. When output is to be verbose, both of these variables
+will expand to the empty string.
+
+ at item
+You can silence a recipe unconditionally with @code{@@}, and then use
+the predefined variable @code{AM_V_P} to know whether make is being run
+in silent or verbose mode, adjust the verbose information your recipe
+displays accordingly:
+
+ at example
+generate-headers:
+ @set -e; \
+ ... [commands defining a shell variable '$headers'] ...; \
+ if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \
+ rm -f $$headers && generate-header --flags $$headers
+ at end example
+
+ at item
+You can add your own variables, so strings of your own choice are shown.
+The following snippet shows how you would define your own equivalent of
+ at code{AM_V_GEN}:
+
+ at example
+pkg_verbose = $(pkg_verbose_@@AM_V@@)
+pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
+pkg_verbose_0 = @@echo PKG-GEN $@@;
+
+foo: foo.in
+ $(pkg_verbose)cp $(srcdir)/foo.in $@@
+ at end example
+
+ at end itemize
+
+As a final note, observe that, even when silent rules are enabled,
+the @option{--no-print-directory} option is still required with GNU
+ at command{make} if the ``@i{Entering/Leaving directory ...}'' messages
+are to be disabled.
+
+ at node Gnits
+ at chapter The effect of @option{--gnu} and @option{--gnits}
+
+ at cindex @option{--gnu}, required files
+ at cindex @option{--gnu}, complete description
+
+The @option{--gnu} option (or @option{gnu} in the
+ at code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
+the following:
+
+ at itemize @bullet
+ at item
+The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
+and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
+or @file{COPYING}, are required at the topmost directory of the package.
+
+If the @option{--add-missing} option is given, @command{automake} will
+add a generic version of the @file{INSTALL} file as well as the
+ at file{COPYING} file containing the text of the current version of the
+GNU General Public License existing at the time of this Automake release
+(version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
+However, an existing @file{COPYING} file will never be overwritten by
+ at command{automake}.
+
+ at item
+The options @option{no-installman} and @option{no-installinfo} are
+prohibited.
+ at end itemize
+
+Note that this option will be extended in the future to do even more
+checking; it is advisable to be familiar with the precise requirements
+of the GNU standards. Also, @option{--gnu} can require certain
+non-standard GNU programs to exist for use by various maintainer-only
+rules; for instance, in the future @command{pathchk} might be required for
+ at samp{make dist}.
+
+ at cindex @option{--gnits}, complete description
+
+The @option{--gnits} option does everything that @option{--gnu} does, and
+checks the following as well:
+
+ at itemize @bullet
+ at item
+ at samp{make installcheck} will check to make sure that the @option{--help}
+and @option{--version} really print a usage message and a version string,
+respectively. This is the @option{std-options} option (@pxref{Options}).
+
+ at item
+ at samp{make dist} will check to make sure the @file{NEWS} file has been
+updated to the current version.
+
+ at item
+ at code{VERSION} is checked to make sure its format complies with Gnits
+standards.
+ at c FIXME xref when standards are finished
+
+ at item
+ at cindex @file{README-alpha}
+If @code{VERSION} indicates that this is an alpha release, and the file
+ at file{README-alpha} appears in the topmost directory of a package, then
+it is included in the distribution. This is done in @option{--gnits}
+mode, and no other, because this mode is the only one where version
+number formats are constrained, and hence the only mode where Automake
+can automatically determine whether @file{README-alpha} should be
+included.
+
+ at item
+The file @file{THANKS} is required.
+ at end itemize
+
+
+ at node Not Enough
+ at chapter When Automake Isn't Enough
+
+In some situations, where Automake is not up to one task, one has to
+resort to handwritten rules or even handwritten @file{Makefile}s.
+
+ at menu
+* Extending:: Adding new rules or overriding existing ones.
+* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
+ at end menu
+
+ at node Extending
+ at section Extending Automake Rules
+
+With some minor exceptions (for example @code{_PROGRAMS} variables,
+ at code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
+ at samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
+ at file{Makefile.in} verbatim.
+
+ at cindex copying semantics
+
+These copying semantics mean that many problems can be worked around
+by simply adding some @command{make} variables and rules to
+ at file{Makefile.am}. Automake will ignore these additions.
+
+ at cindex conflicting definitions
+ at cindex rules, conflicting
+ at cindex variables, conflicting
+ at cindex definitions, conflicts
+
+Since a @file{Makefile.in} is built from data gathered from three
+different places (@file{Makefile.am}, @file{configure.ac}, and
+ at command{automake} itself), it is possible to have conflicting
+definitions of rules or variables. When building @file{Makefile.in}
+the following priorities are respected by @command{automake} to ensure
+the user always has the last word:
+
+ at itemize
+ at item
+User defined variables in @file{Makefile.am} have priority over
+variables @code{AC_SUBST}ed from @file{configure.ac}, and
+ at code{AC_SUBST}ed variables have priority over
+ at command{automake}-defined variables.
+ at item
+As far as rules are concerned, a user-defined rule overrides any
+ at command{automake}-defined rule for the same target.
+ at end itemize
+
+ at cindex overriding rules
+ at cindex overriding semantics
+ at cindex rules, overriding
+
+These overriding semantics make it possible to fine tune some default
+settings of Automake, or replace some of its rules. Overriding
+Automake rules is often inadvisable, particularly in the topmost
+directory of a package with subdirectories. The @option{-Woverride}
+option (@pxref{automake Invocation}) comes in handy to catch overridden
+definitions.
+
+Note that Automake does not make any distinction between rules with
+commands and rules that only specify dependencies. So it is not
+possible to append new dependencies to an @command{automake}-defined
+target without redefining the entire rule.
+
+ at cindex @option{-local} targets
+ at cindex local targets
+
+However, various useful targets have a @samp{-local} version you can
+specify in your @file{Makefile.am}. Automake will supplement the
+standard target with these user-supplied targets.
+
+ at trindex all
+ at trindex all-local
+ at trindex info
+ at trindex info-local
+ at trindex dvi
+ at trindex dvi-local
+ at trindex ps
+ at trindex ps-local
+ at trindex pdf
+ at trindex pdf-local
+ at trindex html
+ at trindex html-local
+ at trindex check
+ at trindex check-local
+ at trindex install
+ at trindex install-data
+ at trindex install-data-local
+ at trindex install-dvi
+ at trindex install-dvi-local
+ at trindex install-exec
+ at trindex install-exec-local
+ at trindex install-html
+ at trindex install-html-local
+ at trindex install-info
+ at trindex install-info-local
+ at trindex install-pdf
+ at trindex install-pdf-local
+ at trindex install-ps
+ at trindex install-ps-local
+ at trindex uninstall
+ at trindex uninstall-local
+ at trindex mostlyclean
+ at trindex mostlyclean-local
+ at trindex clean
+ at trindex clean-local
+ at trindex distclean
+ at trindex distclean-local
+ at trindex installdirs
+ at trindex installdirs-local
+ at trindex installcheck
+ at trindex installcheck-local
+
+The targets that support a local version are @code{all}, @code{info},
+ at code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
+ at code{install-data}, @code{install-dvi}, @code{install-exec},
+ at code{install-html}, @code{install-info}, @code{install-pdf},
+ at code{install-ps}, @code{uninstall}, @code{installdirs},
+ at code{installcheck} and the various @code{clean} targets
+(@code{mostlyclean}, @code{clean}, @code{distclean}, and
+ at code{maintainer-clean}).
+
+Note that there are no @code{uninstall-exec-local} or
+ at code{uninstall-data-local} targets; just use @code{uninstall-local}.
+It doesn't make sense to uninstall just data or just executables.
+
+For instance, here is one way to erase a subdirectory during
+ at samp{make clean} (@pxref{Clean}).
+
+ at example
+clean-local:
+ -rm -rf testSubDir
+ at end example
+
+You may be tempted to use @code{install-data-local} to install a file
+to some hard-coded location, but you should avoid this
+(@pxref{Hard-Coded Install Paths}).
+
+With the @code{-local} targets, there is no particular guarantee of
+execution order; typically, they are run early, but with parallel
+make, there is no way to be sure of that.
+
+ at cindex @option{-hook} targets
+ at cindex hook targets
+ at trindex install-data-hook
+ at trindex install-exec-hook
+ at trindex uninstall-hook
+ at trindex dist-hook
+
+In contrast, some rules also have a way to run another rule, called a
+ at dfn{hook}; hooks are always executed after the main rule's work is done.
+The hook is named after the principal target, with @samp{-hook} appended.
+The targets allowing hooks are @code{install-data},
+ at code{install-exec}, @code{uninstall}, @code{dist}, and
+ at code{distcheck}.
+
+For instance, here is how to create a hard link to an installed program:
+
+ at example
+install-exec-hook:
+ ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
+ $(DESTDIR)$(bindir)/proglink$(EXEEXT)
+ at end example
+
+Although cheaper and more portable than symbolic links, hard links
+will not work everywhere (for instance, OS/2 does not have
+ at command{ln}). Ideally you should fall back to @samp{cp -p} when
+ at command{ln} does not work. An easy way, if symbolic links are
+acceptable to you, is to add @code{AC_PROG_LN_S} to
+ at file{configure.ac} (@pxref{Particular Programs, , Particular Program
+Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
+ at file{Makefile.am}.
+
+ at cindex versioned binaries, installing
+ at cindex installing versioned binaries
+ at cindex @code{LN_S} example
+For instance, here is how you could install a versioned copy of a
+program using @samp{$(LN_S)}:
+
+ at c Keep in sync with insthook.sh
+ at example
+install-exec-hook:
+ cd $(DESTDIR)$(bindir) && \
+ mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
+ $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
+ at end example
+
+Note that we rename the program so that a new version will erase the
+symbolic link, not the real binary. Also we @command{cd} into the
+destination directory in order to create relative links.
+
+When writing @code{install-exec-hook} or @code{install-data-hook},
+please bear in mind that the exec/data distinction is based on the
+installation directory, not on the primary used (@pxref{The Two Parts of
+Install}).
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
+So a @code{foo_SCRIPTS} will be installed by
+ at code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
+ at code{install-exec}. You should define your hooks consequently.
+
+ at c FIXME should include discussion of variables you can use in these
+ at c rules
+
+ at node Third-Party Makefiles
+ at section Third-Party @file{Makefile}s
+
+ at cindex Third-party packages, interfacing with
+ at cindex Interfacing with third-party packages
+
+In most projects all @file{Makefile}s are generated by Automake. In
+some cases, however, projects need to embed subdirectories with
+handwritten @file{Makefile}s. For instance, one subdirectory could be
+a third-party project with its own build system, not using Automake.
+
+It is possible to list arbitrary directories in @code{SUBDIRS} or
+ at code{DIST_SUBDIRS} provided each of these directories has a
+ at file{Makefile} that recognizes all the following recursive targets.
+
+ at cindex recursive targets and third-party @file{Makefile}s
+When a user runs one of these targets, that target is run recursively
+in all subdirectories. This is why it is important that even
+third-party @file{Makefile}s support them.
+
+ at table @code
+ at item all
+Compile the entire package. This is the default target in
+Automake-generated @file{Makefile}s, but it does not need to be the
+default in third-party @file{Makefile}s.
+
+ at item distdir
+ at trindex distdir
+ at vindex distdir
+ at vindex top_distdir
+Copy files to distribute into @samp{$(distdir)}, before a tarball is
+constructed. Of course this target is not required if the
+ at option{no-dist} option (@pxref{Options}) is used.
+
+The variables @samp{$(top_distdir)} and @samp{$(distdir)}
+(@pxref{The dist Hook}) will be passed from the outer package to the subpackage
+when the @code{distdir} target is invoked. These two variables have
+been adjusted for the directory that is being recursed into, so they
+are ready to use.
+
+ at item install
+ at itemx install-data
+ at itemx install-exec
+ at itemx uninstall
+Install or uninstall files (@pxref{Install}).
+
+ at item install-dvi
+ at itemx install-html
+ at itemx install-info
+ at itemx install-ps
+ at itemx install-pdf
+Install only some specific documentation format (@pxref{Texinfo}).
+
+ at item installdirs
+Create install directories, but do not install any files.
+
+ at item check
+ at itemx installcheck
+Check the package (@pxref{Tests}).
+
+ at item mostlyclean
+ at itemx clean
+ at itemx distclean
+ at itemx maintainer-clean
+Cleaning rules (@pxref{Clean}).
+
+ at item dvi
+ at itemx pdf
+ at itemx ps
+ at itemx info
+ at itemx html
+Build the documentation in various formats (@pxref{Texinfo}).
+
+ at item tags
+ at itemx ctags
+Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
+ at end table
+
+If you have ever used Gettext in a project, this is a good example of
+how third-party @file{Makefile}s can be used with Automake. The
+ at file{Makefile}s @command{gettextize} puts in the @file{po/} and
+ at file{intl/} directories are handwritten @file{Makefile}s that
+implement all of these targets. That way they can be added to
+ at code{SUBDIRS} in Automake packages.
+
+Directories that are only listed in @code{DIST_SUBDIRS} but not in
+ at code{SUBDIRS} need only the @code{distclean},
+ at code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
+Subdirectories}).
+
+Usually, many of these rules are irrelevant to the third-party
+subproject, but they are required for the whole package to work. It's
+OK to have a rule that does nothing, so if you are integrating a
+third-party project with no documentation or tag support, you could
+simply augment its @file{Makefile} as follows:
+
+ at example
+EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
+.PHONY: $(EMPTY_AUTOMAKE_TARGETS)
+$(EMPTY_AUTOMAKE_TARGETS):
+ at end example
+
+Another aspect of integrating third-party build systems is whether
+they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
+subpackage does not support VPATH builds the whole package will not
+support VPATH builds. This in turns means that @samp{make distcheck}
+will not work, because it relies on VPATH builds. Some people can
+live without this (actually, many Automake users have never heard of
+ at samp{make distcheck}). Other people may prefer to revamp the
+existing @file{Makefile}s to support VPATH at . Doing so does not
+necessarily require Automake, only Autoconf is needed (@pxref{Build
+Directories, , Build Directories, autoconf, The Autoconf Manual}).
+The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
+and @samp{@@top_builddir@@} are defined by @file{configure} when it
+processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
+Output Variables, autoconf, The Autoconf Manual}), they are not
+computed by the Makefile like the aforementioned @samp{$(distdir)} and
+ at samp{$(top_distdir)} variables.
+
+It is sometimes inconvenient to modify a third-party @file{Makefile}
+to introduce the above required targets. For instance, one may want to
+keep the third-party sources untouched to ease upgrades to new
+versions.
+
+ at cindex @file{GNUmakefile} including @file{Makefile}
+Here are two other ideas. If GNU make is assumed, one possibility is
+to add to that subdirectory a @file{GNUmakefile} that defines the
+required targets and includes the third-party @file{Makefile}. For
+this to work in VPATH builds, @file{GNUmakefile} must lie in the build
+directory; the easiest way to do this is to write a
+ at file{GNUmakefile.in} instead, and have it processed with
+ at code{AC_CONFIG_FILES} from the outer package. For example if we
+assume @file{Makefile} defines all targets except the documentation
+targets, and that the @code{check} target is actually called
+ at code{test}, we could write @file{GNUmakefile} (or
+ at file{GNUmakefile.in}) like this:
+
+ at example
+# First, include the real Makefile
+include Makefile
+# Then, define the other targets needed by Automake Makefiles.
+.PHONY: dvi pdf ps info html check
+dvi pdf ps info html:
+check: test
+ at end example
+
+ at cindex Proxy @file{Makefile} for third-party packages
+A similar idea that does not use @code{include} is to write a proxy
+ at file{Makefile} that dispatches rules to the real @file{Makefile},
+either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
+it's OK to rename the original @file{Makefile}) or with @samp{cd
+subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
+subdirectory project one directory deeper). The good news is that
+this proxy @file{Makefile} can be generated with Automake. All we
+need are @option{-local} targets (@pxref{Extending}) that perform the
+dispatch. Of course the other Automake features are available, so you
+could decide to let Automake perform distribution or installation.
+Here is a possible @file{Makefile.am}:
+
+ at example
+all-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
+check-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
+clean-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
+
+# Assuming the package knows how to install itself
+install-data-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
+install-exec-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
+uninstall-local:
+ cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
+
+# Distribute files from here.
+EXTRA_DIST = subdir/Makefile subdir/program.c ...
+ at end example
+
+Pushing this idea to the extreme, it is also possible to ignore the
+subproject build system and build everything from this proxy
+ at file{Makefile.am}. This might sound very sensible if you need VPATH
+builds but the subproject does not support them.
+
+ at node Distributing
+ at chapter Distributing @file{Makefile.in}s
+
+Automake places no restrictions on the distribution of the resulting
+ at file{Makefile.in}s. We still encourage software authors to
+distribute their work under terms like those of the GPL, but doing so
+is not required to use Automake.
+
+Some of the files that can be automatically installed via the
+ at option{--add-missing} switch do fall under the GPL at . However, these also
+have a special exception allowing you to distribute them with your
+package, regardless of the licensing you choose.
+
+
+ at node API Versioning
+ at chapter Automake API Versioning
+
+New Automake releases usually include bug fixes and new features.
+Unfortunately they may also introduce new bugs and incompatibilities.
+This makes four reasons why a package may require a particular Automake
+version.
+
+Things get worse when maintaining a large tree of packages, each one
+requiring a different version of Automake. In the past, this meant that
+any developer (and sometimes users) had to install several versions of
+Automake in different places, and switch @samp{$PATH} appropriately for
+each package.
+
+Starting with version 1.6, Automake installs versioned binaries. This
+means you can install several versions of Automake in the same
+ at samp{$prefix}, and can select an arbitrary Automake version by running
+ at command{automake-1.6} or @command{automake-1.7} without juggling with
+ at samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
+will use @command{automake-1.6} explicitly in their rebuild rules.
+
+The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
+not Automake's version. If a bug fix release is made, for instance
+Automake 1.6.1, the API version will remain 1.6. This means that a
+package that works with Automake 1.6 should also work with 1.6.1; after
+all, this is what people expect from bug fix releases.
+
+If your package relies on a feature or a bug fix introduced in
+a release, you can pass this version as an option to Automake to ensure
+older releases will not be used. For instance, use this in your
+ at file{configure.ac}:
+
+ at example
+ AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
+ at end example
+
+ at noindent
+or, in a particular @file{Makefile.am}:
+
+ at example
+ AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
+ at end example
+
+ at noindent
+Automake will print an error message if its version is
+older than the requested version.
+
+
+ at heading What is in the API
+
+Automake's programming interface is not easy to define. Basically it
+should include at least all @strong{documented} variables and targets
+that a @file{Makefile.am} author can use, any behavior associated with
+them (e.g., the places where @samp{-hook}'s are run), the command line
+interface of @command{automake} and @command{aclocal}, @dots{}
+
+ at heading What is not in the API
+
+Every undocumented variable, target, or command line option, is not part
+of the API at . You should avoid using them, as they could change from one
+version to the other (even in bug fix releases, if this helps to fix a
+bug).
+
+If it turns out you need to use such an undocumented feature, contact
+ at email{automake@@gnu.org} and try to get it documented and exercised by
+the test-suite.
+
+ at node Upgrading
+ at chapter Upgrading a Package to a Newer Automake Version
+
+Automake maintains three kind of files in a package.
+
+ at itemize
+ at item @file{aclocal.m4}
+ at item @file{Makefile.in}s
+ at item auxiliary tools like @file{install-sh} or @file{py-compile}
+ at end itemize
+
+ at file{aclocal.m4} is generated by @command{aclocal} and contains some
+Automake-supplied M4 macros. Auxiliary tools are installed by
+ at samp{automake --add-missing} when needed. @file{Makefile.in}s are
+built from @file{Makefile.am} by @command{automake}, and rely on the
+definitions of the M4 macros put in @file{aclocal.m4} as well as the
+behavior of the auxiliary tools installed.
+
+Because all of these files are closely related, it is important to
+regenerate all of them when upgrading to a newer Automake release.
+The usual way to do that is
+
+ at example
+aclocal # with any option needed (such a -I m4)
+autoconf
+automake --add-missing --force-missing
+ at end example
+
+ at noindent
+or more conveniently:
+
+ at example
+autoreconf -vfi
+ at end example
+
+The use of @option{--force-missing} ensures that auxiliary tools will be
+overridden by new versions (@pxref{automake Invocation}).
+
+It is important to regenerate all of these files each time Automake is
+upgraded, even between bug fixes releases. For instance, it is not
+unusual for a bug fix to involve changes to both the rules generated
+in @file{Makefile.in} and the supporting M4 macros copied to
+ at file{aclocal.m4}.
+
+Presently @command{automake} is able to diagnose situations where
+ at file{aclocal.m4} has been generated with another version of
+ at command{aclocal}. However it never checks whether auxiliary scripts
+are up-to-date. In other words, @command{automake} will tell you when
+ at command{aclocal} needs to be rerun, but it will never diagnose a
+missing @option{--force-missing}.
+
+Before upgrading to a new major release, it is a good idea to read the
+file @file{NEWS}. This file lists all changes between releases: new
+features, obsolete constructs, known incompatibilities, and
+workarounds.
+
+ at node FAQ
+ at chapter Frequently Asked Questions about Automake
+
+This chapter covers some questions that often come up on the mailing
+lists.
+
+ at menu
+* CVS:: CVS and generated files
+* maintainer-mode:: missing and AM_MAINTAINER_MODE
+* 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
+ at end menu
+
+ at node CVS
+ at section CVS and generated files
+
+ at subheading Background: distributed generated Files
+ at cindex generated files, distributed
+ at cindex rebuild rules
+
+Packages made with Autoconf and Automake ship with some generated
+files like @file{configure} or @file{Makefile.in}. These files were
+generated on the developer's machine and are distributed so that
+end-users do not have to install the maintainer tools required to
+rebuild them. Other generated files like Lex scanners, Yacc parsers,
+or Info documentation, are usually distributed on similar grounds.
+
+Automake output rules in @file{Makefile}s to rebuild these files. For
+instance, @command{make} will run @command{autoconf} to rebuild
+ at file{configure} whenever @file{configure.ac} is changed. This makes
+development safer by ensuring a @file{configure} is never out-of-date
+with respect to @file{configure.ac}.
+
+As generated files shipped in packages are up-to-date, and because
+ at command{tar} preserves times-tamps, these rebuild rules are not
+triggered when a user unpacks and builds a package.
+
+ at subheading Background: CVS and Timestamps
+ at cindex timestamps and CVS
+ at cindex CVS and timestamps
+
+Unless you use CVS keywords (in which case files must be updated at
+commit time), CVS preserves timestamp during @samp{cvs commit} and
+ at samp{cvs import -d} operations.
+
+When you check out a file using @samp{cvs checkout} its timestamp is
+set to that of the revision that is being checked out.
+
+However, during @command{cvs update}, files will have the date of the
+update, not the original timestamp of this revision. This is meant to
+make sure that @command{make} notices sources files have been updated.
+
+This timestamp shift is troublesome when both sources and generated
+files are kept under CVS at . Because CVS processes files in lexical
+order, @file{configure.ac} will appear newer than @file{configure}
+after a @command{cvs update} that updates both files, even if
+ at file{configure} was newer than @file{configure.ac} when it was
+checked in. Calling @command{make} will then trigger a spurious rebuild
+of @file{configure}.
+
+ at subheading Living with CVS in Autoconfiscated Projects
+ at cindex CVS and generated files
+ at cindex generated files and CVS
+
+There are basically two clans amongst maintainers: those who keep all
+distributed files under CVS, including generated files, and those who
+keep generated files @emph{out} of CVS.
+
+ at subsubheading All Files in CVS
+
+ at itemize @bullet
+ at item
+The CVS repository contains all distributed files so you know exactly
+what is distributed, and you can checkout any prior version entirely.
+
+ at item
+Maintainers can see how generated files evolve (for instance, you can
+see what happens to your @file{Makefile.in}s when you upgrade Automake
+and make sure they look OK).
+
+ at item
+Users do not need the autotools to build a checkout of the project, it
+works just like a released tarball.
+
+ at item
+If users use @command{cvs update} to update their copy, instead of
+ at command{cvs checkout} to fetch a fresh one, timestamps will be
+inaccurate. Some rebuild rules will be triggered and attempt to
+run developer tools such as @command{autoconf} or @command{automake}.
+
+Calls to such tools are all wrapped into a call to the @command{missing}
+script discussed later (@pxref{maintainer-mode}), so that the user will
+see more descriptive warnings about missing or out-of-date tools, and
+possible suggestions about how to obtain them, rather than just some
+``command not found'' error, or (worse) some obscure message from some
+older version of the required tool they happen to have installed.
+
+Maintainers interested in keeping their package buildable from a CVS
+checkout even for those users that lack maintainer-specific tools might
+want to provide an helper script (or to enhance their existing bootstrap
+script) to fix the timestamps after a
+ at command{cvs update} or a @command{git checkout}, to prevent spurious
+rebuilds. In case of a project committing the Autotools-generated
+files, as well as the generated @file{.info} files, such script might
+look something like this:
+
+ at smallexample
+#!/bin/sh
+# fix-timestamp.sh: prevents useless rebuilds after "cvs update"
+sleep 1
+# aclocal-generated aclocal.m4 depends on locally-installed
+# '.m4' macro files, as well as on 'configure.ac'
+touch aclocal.m4
+sleep 1
+# autoconf-generated configure depends on aclocal.m4 and on
+# configure.ac
+configure config.h.in
+# so does autoheader-generated config.h.in
+configure config.h.in
+# and all the automake-generated Makefile.in files
+touch `find . -name Makefile.in -print`
+# finally, the makeinfo-generated '.info' files depend on the
+# corresponding '.texi' files
+touch doc/*.info
+ at end smallexample
+
+ at item
+In distributed development, developers are likely to have different
+version of the maintainer tools installed. In this case rebuilds
+triggered by timestamp lossage will lead to spurious changes
+to generated files. There are several solutions to this:
+
+ at itemize
+ at item
+All developers should use the same versions, so that the rebuilt files
+are identical to files in CVS at . (This starts to be difficult when each
+project you work on uses different versions.)
+ at item
+Or people use a script to fix the timestamp after a checkout (the GCC
+folks have such a script).
+ at item
+Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
+disable all of these rebuild rules by default. This is further discussed
+in @ref{maintainer-mode}.
+ at end itemize
+
+ at item
+Although we focused on spurious rebuilds, the converse can also
+happen. CVS's timestamp handling can also let you think an
+out-of-date file is up-to-date.
+
+For instance, suppose a developer has modified @file{Makefile.am} and
+has rebuilt @file{Makefile.in}, and then decides to do a last-minute
+change to @file{Makefile.am} right before checking in both files
+(without rebuilding @file{Makefile.in} to account for the change).
+
+This last change to @file{Makefile.am} makes the copy of
+ at file{Makefile.in} out-of-date. Since CVS processes files
+alphabetically, when another developer @samp{cvs update}s his or her
+tree, @file{Makefile.in} will happen to be newer than
+ at file{Makefile.am}. This other developer will not see that
+ at file{Makefile.in} is out-of-date.
+
+ at end itemize
+
+ at subsubheading Generated Files out of CVS
+
+One way to get CVS and @command{make} working peacefully is to never
+store generated files in CVS, i.e., do not CVS-control files that
+are @file{Makefile} targets (also called @emph{derived} files).
+
+This way developers are not annoyed by changes to generated files. It
+does not matter if they all have different versions (assuming they are
+compatible, of course). And finally, timestamps are not lost, changes
+to sources files can't be missed as in the
+ at file{Makefile.am}/@file{Makefile.in} example discussed earlier.
+
+The drawback is that the CVS repository is not an exact copy of what
+is distributed and that users now need to install various development
+tools (maybe even specific versions) before they can build a checkout.
+But, after all, CVS's job is versioning, not distribution.
+
+Allowing developers to use different versions of their tools can also
+hide bugs during distributed development. Indeed, developers will be
+using (hence testing) their own generated files, instead of the
+generated files that will be released actually. The developer who
+prepares the tarball might be using a version of the tool that
+produces bogus output (for instance a non-portable C file), something
+other developers could have noticed if they weren't using their own
+versions of this tool.
+
+ at subheading Third-party Files
+ at cindex CVS and third-party files
+ at cindex third-party files and CVS
+
+Another class of files not discussed here (because they do not cause
+timestamp issues) are files that are shipped with a package, but
+maintained elsewhere. For instance, tools like @command{gettextize}
+and @command{autopoint} (from Gettext) or @command{libtoolize} (from
+Libtool), will install or update files in your package.
+
+These files, whether they are kept under CVS or not, raise similar
+concerns about version mismatch between developers' tools. The
+Gettext manual has a section about this, see @ref{CVS Issues, CVS
+Issues, Integrating with CVS, gettext, GNU gettext tools}.
+
+ at node maintainer-mode
+ at section @command{missing} and @code{AM_MAINTAINER_MODE}
+
+ at subheading @command{missing}
+ at cindex @command{missing}, purpose
+
+The @command{missing} script is a wrapper around several maintainer
+tools, designed to warn users if a maintainer tool is required but
+missing. Typical maintainer tools are @command{autoconf},
+ at command{automake}, @command{bison}, etc. Because file generated by
+these tools are shipped with the other sources of a package, these
+tools shouldn't be required during a user build and they are not
+checked for in @file{configure}.
+
+However, if for some reason a rebuild rule is triggered and involves a
+missing tool, @command{missing} will notice it and warn the user, even
+suggesting how to obtain such a tool (at least in case it is a well-known
+one, like @command{makeinfo} or @command{bison}). This is more helpful
+and user-friendly than just having the rebuild rules spewing out a terse
+error message like @samp{sh: @var{tool}: command not found}. Similarly,
+ at command{missing} will warn the user if it detects that a maintainer
+tool it attempted to use seems too old (be warned that diagnosing this
+correctly is typically more difficult that detecting missing tools, and
+requires cooperation from the tool itself, so it won't always work).
+
+If the required tool is installed, @command{missing} will run it and
+won't attempt to continue after failures. This is correct during
+development: developers love fixing failures. However, users with
+missing or too old maintainer tools may get an error when the rebuild
+rule is spuriously triggered, halting the build. This failure to let
+the build continue is one of the arguments of the
+ at code{AM_MAINTAINER_MODE} advocates.
+
+ at subheading @code{AM_MAINTAINER_MODE}
+ at cindex @code{AM_MAINTAINER_MODE}, purpose
+ at acindex AM_MAINTAINER_MODE
+
+ at code{AM_MAINTAINER_MODE} allows you to choose whether the so called
+"rebuild rules" should be enabled or disabled. With
+ at code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
+otherwise they are disabled by default. In the latter case, if
+you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
+ at samp{./configure && make}, then @command{make} will *never* attempt to
+rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
+I.e., this disables build rules for files that are usually distributed
+and that users should normally not have to update.
+
+The user can override the default setting by passing either
+ at samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
+to @command{configure}.
+
+People use @code{AM_MAINTAINER_MODE} either because they do not want their
+users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
+because they simply can't stand the rebuild rules and prefer running
+maintainer tools explicitly.
+
+ at code{AM_MAINTAINER_MODE} also allows you to disable some custom build
+rules conditionally. Some developers use this feature to disable
+rules that need exotic tools that users may not have available.
+
+Several years ago Fran@,{c}ois Pinard pointed out several arguments
+against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
+insecurity. By removing dependencies you get non-dependable builds:
+changes to sources files can have no effect on generated files and this
+can be very confusing when unnoticed. He adds that security shouldn't
+be reserved to maintainers (what @option{--enable-maintainer-mode}
+suggests), on the contrary. If one user has to modify a
+ at file{Makefile.am}, then either @file{Makefile.in} should be updated
+or a warning should be output (this is what Automake uses
+ at command{missing} for) but the last thing you want is that nothing
+happens and the user doesn't notice it (this is what happens when
+rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
+
+Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
+swayed by Fran@,{c}ois's arguments, and got rid of
+ at code{AM_MAINTAINER_MODE} in all of his packages.
+
+Still many people continue to use @code{AM_MAINTAINER_MODE}, because
+it helps them working on projects where all files are kept under version
+control, and because @command{missing} isn't enough if you have the
+wrong version of the tools.
+
+
+ at node Wildcards
+ at section Why doesn't Automake support wildcards?
+ at cindex wildcards
+
+Developers are lazy. They would often like to use wildcards in
+ at file{Makefile.am}s, so that they would not need to remember to
+update @file{Makefile.am}s every time they add, delete, or rename
+a file.
+
+There are several objections to this:
+ at itemize
+ at item
+When using CVS (or similar) developers need to remember they have to
+run @samp{cvs add} or @samp{cvs rm} anyway. Updating
+ at file{Makefile.am} accordingly quickly becomes a reflex.
+
+Conversely, if your application doesn't compile
+because you forgot to add a file in @file{Makefile.am}, it will help
+you remember to @samp{cvs add} it.
+
+ at item
+Using wildcards makes it easy to distribute files by mistake. For
+instance, some code a developer is experimenting with (a test case,
+say) that should not be part of the distribution.
+
+ at item
+Using wildcards it's easy to omit some files by mistake. For
+instance, one developer creates a new file, uses it in many places,
+but forgets to commit it. Another developer then checks out the
+incomplete project and is able to run @samp{make dist} successfully,
+even though a file is missing. By listing files, @samp{make dist}
+ at emph{will} complain.
+
+ at item
+Wildcards are not portable to some non-GNU @command{make} implementations,
+e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
+prerequisites of a target.
+
+ at item
+Finally, it's really hard to @emph{forget} to add a file to
+ at file{Makefile.am}: files that are not listed in @file{Makefile.am} are
+not compiled or installed, so you can't even test them.
+ at end itemize
+
+Still, these are philosophical objections, and as such you may disagree,
+or find enough value in wildcards to dismiss all of them. Before you
+start writing a patch against Automake to teach it about wildcards,
+let's see the main technical issue: portability.
+
+Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
+not portable to other @command{make} implementations.
+
+The only way Automake could support @command{$(wildcard ...)} is by
+expanding @command{$(wildcard ...)} when @command{automake} is run.
+The resulting @file{Makefile.in}s would be portable since they would
+list all files and not use @samp{$(wildcard ...)}. However that
+means developers would need to remember to run @command{automake} each
+time they add, delete, or rename files.
+
+Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
+it's easier and faster to type @samp{automake; make} than to type
+ at samp{emacs Makefile.am; make}. But nobody bothered enough to write a
+patch to add support for this syntax. Some people use scripts to
+generate file lists in @file{Makefile.am} or in separate
+ at file{Makefile} fragments.
+
+Even if you don't care about portability, and are tempted to use
+ at samp{$(wildcard ...)} anyway because you target only GNU Make, you
+should know there are many places where Automake needs to know exactly
+which files should be processed. As Automake doesn't know how to
+expand @samp{$(wildcard ...)}, you cannot use it in these places.
+ at samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
+variables as far Automake is concerned.
+
+You can get warnings about @samp{$(wildcard ...}) constructs using the
+ at option{-Wportability} flag.
+
+ at node Limitations on File Names
+ at section Limitations on File Names
+ at cindex file names, limitations on
+
+Automake attempts to support all kinds of file names, even those that
+contain unusual characters or are unusually long. However, some
+limitations are imposed by the underlying operating system and tools.
+
+Most operating systems prohibit the use of the null byte in file
+names, and reserve @samp{/} as a directory separator. Also, they
+require that file names are properly encoded for the user's locale.
+Automake is subject to these limits.
+
+Portable packages should limit themselves to POSIX file
+names. These can contain ASCII letters and digits,
+ at samp{_}, @samp{.}, and @samp{-}. File names consist of components
+separated by @samp{/}. File name components cannot begin with
+ at samp{-}.
+
+Portable POSIX file names cannot contain components that exceed a
+14-byte limit, but nowadays it's normally safe to assume the
+more-generous XOPEN limit of 255 bytes. POSIX
+limits file names to 255 bytes (XOPEN allows 1023 bytes),
+but you may want to limit a source tarball to file names of 99 bytes
+to avoid interoperability problems with old versions of @command{tar}.
+
+If you depart from these rules (e.g., by using non-ASCII
+characters in file names, or by using lengthy file names), your
+installers may have problems for reasons unrelated to Automake.
+However, if this does not concern you, you should know about the
+limitations imposed by Automake itself. These limitations are
+undesirable, but some of them seem to be inherent to underlying tools
+like Autoconf, Make, M4, and the shell. They fall into three
+categories: install directories, build directories, and file names.
+
+The following characters:
+
+ at example
+ at r{newline} " # $ ' `
+ at end example
+
+should not appear in the names of install directories. For example,
+the operand of @command{configure}'s @option{--prefix} option should
+not contain these characters.
+
+Build directories suffer the same limitations as install directories,
+and in addition should not contain the following characters:
+
+ at example
+& @@ \
+ at end example
+
+For example, the full name of the directory containing the source
+files should not contain these characters.
+
+Source and installation file names like @file{main.c} are limited even
+further: they should conform to the POSIX/XOPEN
+rules described above. In addition, if you plan to port to
+non-POSIX environments, you should avoid file names that
+differ only in case (e.g., @file{makefile} and @file{Makefile}).
+Nowadays it is no longer worth worrying about the 8.3 limits of
+DOS file systems.
+
+ at c FIXME This should probably be moved in the "Checking the Distribution"
+ at c FIXME section...
+ at node Errors with distclean
+ at section Errors with distclean
+ at cindex @code{distclean}, diagnostic
+ at cindex @samp{make distclean}, diagnostic
+ at cindex dependencies and distributed files
+ at trindex distclean
+
+This is a diagnostic you might encounter while running @samp{make
+distcheck}.
+
+As explained in @ref{Checking the Distribution}, @samp{make distcheck}
+attempts to build and check your package for errors like this one.
+
+ at samp{make distcheck} will perform a @code{VPATH} build of your
+package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
+Files left in the build directory after @samp{make distclean} has run
+are listed after this error.
+
+This diagnostic really covers two kinds of errors:
+
+ at itemize @bullet
+ at item
+files that are forgotten by distclean;
+ at item
+distributed files that are erroneously rebuilt.
+ at end itemize
+
+The former left-over files are not distributed, so the fix is to mark
+them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
+more explanations.
+
+The latter bug is not always easy to understand and fix, so let's
+proceed with an example. Suppose our package contains a program for
+which we want to build a man page using @command{help2man}. GNU
+ at command{help2man} produces simple manual pages from the @option{--help}
+and @option{--version} output of other commands (@pxref{Top, , Overview,
+help2man, The Help2man Manual}). Because we don't want to force our
+users to install @command{help2man}, we decide to distribute the
+generated man page using the following setup.
+
+ at example
+# This Makefile.am is bogus.
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+dist_man_MANS = foo.1
+
+foo.1: foo$(EXEEXT)
+ help2man --output=foo.1 ./foo$(EXEEXT)
+ at end example
+
+This will effectively distribute the man page. However,
+ at samp{make distcheck} will fail with:
+
+ at example
+ERROR: files left in build directory after distclean:
+./foo.1
+ at end example
+
+Why was @file{foo.1} rebuilt? Because although distributed,
+ at file{foo.1} depends on a non-distributed built file:
+ at file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
+will always appear to be newer than the distributed @file{foo.1}.
+
+ at samp{make distcheck} caught an inconsistency in our package. Our
+intent was to distribute @file{foo.1} so users do not need to install
+ at command{help2man}, however since this rule causes this file to be
+always rebuilt, users @emph{do} need @command{help2man}. Either we
+should ensure that @file{foo.1} is not rebuilt by users, or there is
+no point in distributing @file{foo.1}.
+
+More generally, the rule is that distributed files should never depend
+on non-distributed built files. If you distribute something
+generated, distribute its sources.
+
+One way to fix the above example, while still distributing
+ at file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
+assuming @command{foo --version} and @command{foo --help} do not
+change unless @file{foo.c} or @file{configure.ac} change, we could
+write the following @file{Makefile.am}:
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c
+dist_man_MANS = foo.1
+
+foo.1: foo.c $(top_srcdir)/configure.ac
+ $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
+ help2man --output=foo.1 ./foo$(EXEEXT)
+ at end example
+
+This way, @file{foo.1} will not get rebuilt every time
+ at file{foo$(EXEEXT)} changes. The @command{make} call makes sure
+ at file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
+way to ensure this would be to use separate directories for binaries
+and man pages, and set @code{SUBDIRS} so that binaries are built
+before man pages.
+
+We could also decide not to distribute @file{foo.1}. In
+this case it's fine to have @file{foo.1} dependent upon
+ at file{foo$(EXEEXT)}, since both will have to be rebuilt.
+However it would be impossible to build the package in a
+cross-compilation, because building @file{foo.1} involves
+an @emph{execution} of @file{foo$(EXEEXT)}.
+
+Another context where such errors are common is when distributed files
+are built by tools that are built by the package. The pattern is
+similar:
+
+ at example
+distributed-file: built-tools distributed-sources
+ build-command
+ at end example
+
+ at noindent
+should be changed to
+
+ at example
+distributed-file: distributed-sources
+ $(MAKE) $(AM_MAKEFLAGS) built-tools
+ build-command
+ at end example
+
+ at noindent
+or you could choose not to distribute @file{distributed-file}, if
+cross-compilation does not matter.
+
+The points made through these examples are worth a summary:
+
+ at cartouche
+ at itemize
+ at item
+Distributed files should never depend upon non-distributed built
+files.
+ at item
+Distributed files should be distributed with all their dependencies.
+ at item
+If a file is @emph{intended} to be rebuilt by users, then there is no point
+in distributing it.
+ at end itemize
+ at end cartouche
+
+ at vrindex distcleancheck_listfiles
+For desperate cases, it's always possible to disable this check by
+setting @code{distcleancheck_listfiles} as documented in @ref{Checking
+the Distribution}.
+Make sure you do understand the reason why @samp{make distcheck}
+complains before you do this. @code{distcleancheck_listfiles} is a
+way to @emph{hide} errors, not to fix them. You can always do better.
+
+ at node Flag Variables Ordering
+ at section Flag Variables Ordering
+ at cindex Ordering flag variables
+ at cindex Flag variables, ordering
+
+ at display
+What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
+ at code{mumble_CFLAGS}?
+ at end display
+
+ at display
+Why does @command{automake} output @code{CPPFLAGS} after
+ at code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
+ at end display
+
+ at display
+My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
+one @file{Makefile.am} I would like to append a new flag, however if I
+put the flag into @code{AM_CXXFLAGS} it is prepended to the other
+flags, not appended.
+ at end display
+
+ at subheading Compile Flag Variables
+ at cindex Flag Variables, Ordering
+ at cindex Compile Flag Variables
+ at cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
+ at cindex @code{AM_CFLAGS} and @code{CFLAGS}
+ at cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
+ at cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
+ at cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
+ at cindex @code{AM_FFLAGS} and @code{FFLAGS}
+ at cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
+ at cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
+ at cindex @code{AM_LFLAGS} and @code{LFLAGS}
+ at cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
+ at cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
+ at cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
+ at cindex @code{AM_RFLAGS} and @code{RFLAGS}
+ at cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
+ at cindex @code{AM_YFLAGS} and @code{YFLAGS}
+ at cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
+ at cindex @code{CFLAGS} and @code{AM_CFLAGS}
+ at cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
+ at cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
+ at cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
+ at cindex @code{FFLAGS} and @code{AM_FFLAGS}
+ at cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
+ at cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
+ at cindex @code{LFLAGS} and @code{AM_LFLAGS}
+ at cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
+ at cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
+ at cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
+ at cindex @code{RFLAGS} and @code{AM_RFLAGS}
+ at cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
+ at cindex @code{YFLAGS} and @code{AM_YFLAGS}
+
+This section attempts to answer all the above questions. We will
+mostly discuss @code{CPPFLAGS} in our examples, but actually the
+answer holds for all the compile flags used in Automake:
+ at code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
+ at code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
+ at code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
+ at code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
+
+ at code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
+three variables that can be used to pass flags to the C preprocessor
+(actually these variables are also used for other languages like C++
+or preprocessed Fortran). @code{CPPFLAGS} is the user variable
+(@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
+and @code{mumble_CPPFLAGS} is the variable specific to the
+ at code{mumble} target (we call this a per-target variable,
+ at pxref{Program and Library Variables}).
+
+Automake always uses two of these variables when compiling C sources
+files. When compiling an object file for the @code{mumble} target,
+the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
+ at code{AM_CPPFLAGS} otherwise. The second variable is always
+ at code{CPPFLAGS}.
+
+In the following example,
+
+ at example
+bin_PROGRAMS = foo bar
+foo_SOURCES = xyz.c
+bar_SOURCES = main.c
+foo_CPPFLAGS = -DFOO
+AM_CPPFLAGS = -DBAZ
+ at end example
+
+ at noindent
+ at file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
+(because @file{xyz.o} is part of the @code{foo} target), while
+ at file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
+(because there is no per-target variable for target @code{bar}).
+
+The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
+being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
+is a user variable, i.e., a variable that users are entitled to modify
+in order to compile the package. This variable, like many others,
+is documented at the end of the output of @samp{configure --help}.
+
+For instance, someone who needs to add @file{/home/my/usr/include} to
+the C compiler's search path would configure a package with
+
+ at example
+./configure CPPFLAGS='-I /home/my/usr/include'
+ at end example
+
+ at noindent
+and this flag would be propagated to the compile rules of all
+ at file{Makefile}s.
+
+It is also not uncommon to override a user variable at
+ at command{make}-time. Many installers do this with @code{prefix}, but
+this can be useful with compiler flags too. For instance, if, while
+debugging a C++ project, you need to disable optimization in one
+specific object file, you can run something like
+
+ at example
+rm file.o
+make CXXFLAGS=-O0 file.o
+make
+ at end example
+
+The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
+ at samp{$(mumble_CPPFLAGS)} in the compile command is that users
+should always have the last say. It probably makes more sense if you
+think about it while looking at the @samp{CXXFLAGS=-O0} above, which
+should supersede any other switch from @code{AM_CXXFLAGS} or
+ at code{mumble_CXXFLAGS} (and this of course replaces the previous value
+of @code{CXXFLAGS}).
+
+You should never redefine a user variable such as @code{CPPFLAGS} in
+ at file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
+mistakes. Even something like
+
+ at example
+CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
+ at end example
+
+ at noindent
+is erroneous. Although this preserves @file{configure}'s value of
+ at code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
+user attempts to override @code{CPPFLAGS} from the @command{make}
+command line.
+
+ at example
+AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
+ at end example
+
+ at noindent
+is all that is needed here if no per-target flags are used.
+
+You should not add options to these user variables within
+ at file{configure} either, for the same reason. Occasionally you need
+to modify these variables to perform a test, but you should reset
+their values afterwards. In contrast, it is OK to modify the
+ at samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
+them, but it is rather rare that you need to do this, unless you
+really want to change the default definitions of the @samp{AM_}
+variables in all @file{Makefile}s.
+
+What we recommend is that you define extra flags in separate
+variables. For instance, you may write an Autoconf macro that computes
+a set of warning options for the C compiler, and @code{AC_SUBST} them
+in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
+determines which compiler and which linker flags should be used to
+link with library @file{libfoo}, and @code{AC_SUBST} these in
+ at code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
+ at file{Makefile.am} could use these variables as follows:
+
+ at example
+AM_CFLAGS = $(WARNINGCFLAGS)
+bin_PROGRAMS = prog1 prog2
+prog1_SOURCES = @dots{}
+prog2_SOURCES = @dots{}
+prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
+prog2_LDFLAGS = $(LIBFOOLDFLAGS)
+ at end example
+
+In this example both programs will be compiled with the flags
+substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
+additionally be compiled with the flags required to link with
+ at file{libfoo}.
+
+Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
+variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
+every target in a @file{Makefile.in}.
+
+Using variables like this gives you full control over the ordering of
+the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
+you want to negate for a particular target, you can use something like
+ at samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
+been forcefully appended to @code{CFLAGS}, there would be no way to
+disable one flag. Yet another reason to leave user variables to
+users.
+
+Finally, we have avoided naming the variable of the example
+ at code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
+Automake to think that this is actually a per-target variable (like
+ at code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
+
+ at subheading Other Variables
+
+There are other variables in Automake that follow similar principles
+to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
+use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
+DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
+ at code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
+(@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
+ at code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
+(@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
+of these rules support per-target flags (yet).
+
+To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
+obeys this naming scheme. The slight difference is that
+ at code{MAKEFLAGS} is passed to sub- at command{make}s implicitly by
+ at command{make} itself.
+
+ at code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
+has neither @code{AM_} nor per-target cousin.
+
+Finally you should not think that the existence of a per-target
+variable implies the existence of an @code{AM_} variable or of a user
+variable. For instance, the @code{mumble_LDADD} per-target variable
+overrides the makefile-wide @code{LDADD} variable (which is not a user
+variable), and @code{mumble_LIBADD} exists only as a per-target
+variable. @xref{Program and Library Variables}.
+
+
+ at node Renamed Objects
+ at section Why are object files sometimes renamed?
+
+This happens when per-target compilation flags are used. Object
+files need to be renamed just in case they would clash with object
+files compiled from the same sources, but with different flags.
+Consider the following example.
+
+ at example
+bin_PROGRAMS = true false
+true_SOURCES = generic.c
+true_CPPFLAGS = -DEXIT_CODE=0
+false_SOURCES = generic.c
+false_CPPFLAGS = -DEXIT_CODE=1
+ at end example
+
+ at noindent
+Obviously the two programs are built from the same source, but it
+would be bad if they shared the same object, because @file{generic.o}
+cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
+ at samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
+build two different objects: @file{true-generic.o} and
+ at file{false-generic.o}.
+
+ at command{automake} doesn't actually look whether source files are
+shared to decide if it must rename objects. It will just rename all
+objects of a target as soon as it sees per-target compilation flags
+used.
+
+It's OK to share object files when per-target compilation flags are not
+used. For instance, @file{true} and @file{false} will both use
+ at file{version.o} in the following example.
+
+ at example
+AM_CPPFLAGS = -DVERSION=1.0
+bin_PROGRAMS = true false
+true_SOURCES = true.c version.c
+false_SOURCES = false.c version.c
+ at end example
+
+Note that the renaming of objects is also affected by the
+ at code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
+
+
+ at node Per-Object Flags
+ at section Per-Object Flags Emulation
+ at cindex Per-object flags, emulated
+
+ at display
+One of my source files needs to be compiled with different flags. How
+do I do?
+ at end display
+
+Automake supports per-program and per-library compilation flags (see
+ at ref{Program and Library Variables} and @ref{Flag Variables
+Ordering}). With this you can define compilation flags that apply to
+all files compiled for a target. For instance, in
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = foo.c foo.h bar.c bar.h main.c
+foo_CFLAGS = -some -flags
+ at end example
+
+ at noindent
+ at file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
+compiled with @samp{-some -flags}. (If you wonder about the names of
+these object files, see @ref{Renamed Objects}.) Note that
+ at code{foo_CFLAGS} gives the flags to use when compiling all the C
+sources of the @emph{program} @code{foo}, it has nothing to do with
+ at file{foo.c} or @file{foo-foo.o} specifically.
+
+What if @file{foo.c} needs to be compiled into @file{foo.o} using some
+specific flags, that none of the other files requires? Obviously
+per-program flags are not directly applicable here. Something like
+per-object flags are expected, i.e., flags that would be used only
+when creating @file{foo-foo.o}. Automake does not support that,
+however this is easy to simulate using a library that contains only
+that object, and compiling this library with per-library flags.
+
+ at example
+bin_PROGRAMS = foo
+foo_SOURCES = bar.c bar.h main.c
+foo_CFLAGS = -some -flags
+foo_LDADD = libfoo.a
+noinst_LIBRARIES = libfoo.a
+libfoo_a_SOURCES = foo.c foo.h
+libfoo_a_CFLAGS = -some -other -flags
+ at end example
+
+Here @file{foo-bar.o} and @file{foo-main.o} will all be
+compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
+be compiled using @samp{-some -other -flags}. Eventually, all
+three objects will be linked to form @file{foo}.
+
+This trick can also be achieved using Libtool convenience libraries,
+for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
+Convenience Libraries}).
+
+Another tempting idea to implement per-object flags is to override the
+compile rules @command{automake} would output for these files.
+Automake will not define a rule for a target you have defined, so you
+could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
+We recommend against this, because this is error prone. For instance,
+if you add such a rule to the first example, it will break the day you
+decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
+compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
+Objects}). Also in order to support dependency tracking, the two
+ at file{.o}/@file{.obj} extensions, and all the other flags variables
+involved in a compilation, you will end up modifying a copy of the
+rule previously output by @command{automake} for this file. If a new
+release of Automake generates a different rule, your copy will need to
+be updated by hand.
+
+ at node Multiple Outputs
+ at section Handling Tools that Produce Many Outputs
+ at cindex multiple outputs, rules with
+ at cindex many outputs, rules with
+ at cindex rules with multiple outputs
+
+This section describes a @command{make} idiom that can be used when a
+tool produces multiple output files. It is not specific to Automake
+and can be used in ordinary @file{Makefile}s.
+
+Suppose we have a program called @command{foo} that will read one file
+called @file{data.foo} and produce two files named @file{data.c} and
+ at file{data.h}. We want to write a @file{Makefile} rule that captures
+this one-to-two dependency.
+
+The naive rule is incorrect:
+
+ at example
+# This is incorrect.
+data.c data.h: data.foo
+ foo data.foo
+ at end example
+
+ at noindent
+What the above rule really says is that @file{data.c} and
+ at file{data.h} each depend on @file{data.foo}, and can each be built by
+running @samp{foo data.foo}. In other words it is equivalent to:
+
+ at example
+# We do not want this.
+data.c: data.foo
+ foo data.foo
+data.h: data.foo
+ foo data.foo
+ at end example
+
+ at noindent
+which means that @command{foo} can be run twice. Usually it will not
+be run twice, because @command{make} implementations are smart enough
+to check for the existence of the second file after the first one has
+been built; they will therefore detect that it already exists.
+However there are a few situations where it can run twice anyway:
+
+ at itemize
+ at item
+The most worrying case is when running a parallel @command{make}. If
+ at file{data.c} and @file{data.h} are built in parallel, two @samp{foo
+data.foo} commands will run concurrently. This is harmful.
+ at item
+Another case is when the dependency (here @file{data.foo}) is
+(or depends upon) a phony target.
+ at end itemize
+
+A solution that works with parallel @command{make} but not with
+phony dependencies is the following:
+
+ at example
+data.c data.h: data.foo
+ foo data.foo
+data.h: data.c
+ at end example
+
+ at noindent
+The above rules are equivalent to
+
+ at example
+data.c: data.foo
+ foo data.foo
+data.h: data.foo data.c
+ foo data.foo
+ at end example
+
+ at noindent
+therefore a parallel @command{make} will have to serialize the builds
+of @file{data.c} and @file{data.h}, and will detect that the second is
+no longer needed once the first is over.
+
+Using this pattern is probably enough for most cases. However it does
+not scale easily to more output files (in this scheme all output files
+must be totally ordered by the dependency relation), so we will
+explore a more complicated solution.
+
+Another idea is to write the following:
+
+ at example
+# There is still a problem with this one.
+data.c: data.foo
+ foo data.foo
+data.h: data.c
+ at end example
+
+ at noindent
+The idea is that @samp{foo data.foo} is run only when @file{data.c}
+needs to be updated, but we further state that @file{data.h} depends
+upon @file{data.c}. That way, if @file{data.h} is required and
+ at file{data.foo} is out of date, the dependency on @file{data.c} will
+trigger the build.
+
+This is almost perfect, but suppose we have built @file{data.h} and
+ at file{data.c}, and then we erase @file{data.h}. Then, running
+ at samp{make data.h} will not rebuild @file{data.h}. The above rules
+just state that @file{data.c} must be up-to-date with respect to
+ at file{data.foo}, and this is already the case.
+
+What we need is a rule that forces a rebuild when @file{data.h} is
+missing. Here it is:
+
+ at example
+data.c: data.foo
+ foo data.foo
+data.h: data.c
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ rm -f data.c; \
+ $(MAKE) $(AM_MAKEFLAGS) data.c; \
+ fi
+ at end example
+
+The above scheme can be extended to handle more outputs and more
+inputs. One of the outputs is selected to serve as a witness to the
+successful completion of the command, it depends upon all inputs, and
+all other outputs depend upon it. For instance, if @command{foo}
+should additionally read @file{data.bar} and also produce
+ at file{data.w} and @file{data.x}, we would write:
+
+ at example
+data.c: data.foo data.bar
+ foo data.foo data.bar
+data.h data.w data.x: data.c
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ rm -f data.c; \
+ $(MAKE) $(AM_MAKEFLAGS) data.c; \
+ fi
+ at end example
+
+However there are now three minor problems in this setup. One is related
+to the timestamp ordering of @file{data.h}, @file{data.w},
+ at file{data.x}, and @file{data.c}. Another one is a race condition
+if a parallel @command{make} attempts to run multiple instances of the
+recover block at once. Finally, the recursive rule breaks @samp{make -n}
+when run with GNU @command{make} (as well as some other @command{make}
+implementations), as it may remove @file{data.h} even when it should not
+(@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
+The GNU Make Manual}).
+
+Let us deal with the first problem. @command{foo} outputs four files,
+but we do not know in which order these files are created. Suppose
+that @file{data.h} is created before @file{data.c}. Then we have a
+weird situation. The next time @command{make} is run, @file{data.h}
+will appear older than @file{data.c}, the second rule will be
+triggered, a shell will be started to execute the @samp{if at dots{}fi}
+command, but actually it will just execute the @code{then} branch,
+that is: nothing. In other words, because the witness we selected is
+not the first file created by @command{foo}, @command{make} will start
+a shell to do nothing each time it is run.
+
+A simple riposte is to fix the timestamps when this happens.
+
+ at example
+data.c: data.foo data.bar
+ foo data.foo data.bar
+data.h data.w data.x: data.c
+ @@if test -f $@@; then \
+ touch $@@; \
+ else \
+## Recover from the removal of $@@
+ rm -f data.c; \
+ $(MAKE) $(AM_MAKEFLAGS) data.c; \
+ fi
+ at end example
+
+Another solution is to use a different and dedicated file as witness,
+rather than using any of @command{foo}'s outputs.
+
+ at example
+data.stamp: data.foo data.bar
+ @@rm -f data.tmp
+ @@touch data.tmp
+ foo data.foo data.bar
+ @@mv -f data.tmp $@@
+data.c data.h data.w data.x: data.stamp
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ rm -f data.stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
+ fi
+ at end example
+
+ at file{data.tmp} is created before @command{foo} is run, so it has a
+timestamp older than output files output by @command{foo}. It is then
+renamed to @file{data.stamp} after @command{foo} has run, because we
+do not want to update @file{data.stamp} if @command{foo} fails.
+
+This solution still suffers from the second problem: the race
+condition in the recover rule. If, after a successful build, a user
+erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
+ at command{make} may start both recover rules in parallel. If the two
+instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
+data.stamp} concurrently the build is likely to fail (for instance, the
+two rules will create @file{data.tmp}, but only one can rename it).
+
+Admittedly, such a weird situation does not arise during ordinary
+builds. It occurs only when the build tree is mutilated. Here
+ at file{data.c} and @file{data.h} have been explicitly removed without
+also removing @file{data.stamp} and the other output files.
+ at code{make clean; make} will always recover from these situations even
+with parallel makes, so you may decide that the recover rule is solely
+to help non-parallel make users and leave things as-is. Fixing this
+requires some locking mechanism to ensure only one instance of the
+recover rule rebuilds @file{data.stamp}. One could imagine something
+along the following lines.
+
+ at example
+data.c data.h data.w data.x: data.stamp
+## Recover from the removal of $@@
+ @@if test -f $@@; then :; else \
+ trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
+## mkdir is a portable test-and-set
+ if mkdir data.lock 2>/dev/null; then \
+## This code is being executed by the first process.
+ rm -f data.stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
+ result=$$?; rm -rf data.lock; exit $$result; \
+ else \
+## This code is being executed by the follower processes.
+## Wait until the first process is done.
+ while test -d data.lock; do sleep 1; done; \
+## Succeed if and only if the first process succeeded.
+ test -f data.stamp; \
+ fi; \
+ fi
+ at end example
+
+Using a dedicated witness, like @file{data.stamp}, is very handy when
+the list of output files is not known beforehand. As an illustration,
+consider the following rules to compile many @file{*.el} files into
+ at file{*.elc} files in a single command. It does not matter how
+ at code{ELFILES} is defined (as long as it is not empty: empty targets
+are not accepted by POSIX).
+
+ at example
+ELFILES = one.el two.el three.el @dots{}
+ELCFILES = $(ELFILES:=c)
+
+elc-stamp: $(ELFILES)
+ @@rm -f elc-temp
+ @@touch elc-temp
+ $(elisp_comp) $(ELFILES)
+ @@mv -f elc-temp $@@
+
+$(ELCFILES): elc-stamp
+ @@if test -f $@@; then :; else \
+## Recover from the removal of $@@
+ trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
+ if mkdir elc-lock 2>/dev/null; then \
+## This code is being executed by the first process.
+ rm -f elc-stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
+ rmdir elc-lock; \
+ else \
+## This code is being executed by the follower processes.
+## Wait until the first process is done.
+ while test -d elc-lock; do sleep 1; done; \
+## Succeed if and only if the first process succeeded.
+ test -f elc-stamp; exit $$?; \
+ at c $$
+ fi; \
+ fi
+ at end example
+
+These solutions all still suffer from the third problem, namely that
+they break the promise that @samp{make -n} should not cause any actual
+changes to the tree. For those solutions that do not create lock files,
+it is possible to split the recover rules into two separate recipe
+commands, one of which does all work but the recursion, and the
+other invokes the recursive @samp{$(MAKE)}. The solutions involving
+locking could act upon the contents of the @samp{MAKEFLAGS} variable,
+but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
+autoconf, The Autoconf Manual}). Here is an example:
+
+ at example
+ELFILES = one.el two.el three.el @dots{}
+ELCFILES = $(ELFILES:=c)
+
+elc-stamp: $(ELFILES)
+ @@rm -f elc-temp
+ @@touch elc-temp
+ $(elisp_comp) $(ELFILES)
+ @@mv -f elc-temp $@@
+
+$(ELCFILES): elc-stamp
+## Recover from the removal of $@@
+ @@dry=; for f in x $$MAKEFLAGS; do \
+ case $$f in \
+ *=*|--*);; \
+ *n*) dry=:;; \
+ esac; \
+ done; \
+ if test -f $@@; then :; else \
+ $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
+ if $$dry mkdir elc-lock 2>/dev/null; then \
+## This code is being executed by the first process.
+ $$dry rm -f elc-stamp; \
+ $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
+ $$dry rmdir elc-lock; \
+ else \
+## This code is being executed by the follower processes.
+## Wait until the first process is done.
+ while test -d elc-lock && test -z "$$dry"; do \
+ at c $$
+ sleep 1; \
+ done; \
+## Succeed if and only if the first process succeeded.
+ $$dry test -f elc-stamp; exit $$?; \
+ fi; \
+ fi
+ at end example
+
+For completeness it should be noted that GNU @command{make} is able to
+express rules with multiple output files using pattern rules
+(@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
+Manual}). We do not discuss pattern rules here because they are not
+portable, but they can be convenient in packages that assume GNU
+ at command{make}.
+
+
+ at node Hard-Coded Install Paths
+ at section Installing to Hard-Coded Locations
+
+ at display
+My package needs to install some configuration file. I tried to use
+the following rule, but @samp{make distcheck} fails. Why?
+
+ at example
+# Do not do this.
+install-data-local:
+ $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
+ at end example
+ at end display
+
+ at display
+My package needs to populate the installation directory of another
+package at install-time. I can easily compute that installation
+directory in @file{configure}, but if I install files therein,
+ at samp{make distcheck} fails. How else should I do?
+ at end display
+
+These two setups share their symptoms: @samp{make distcheck} fails
+because they are installing files to hard-coded paths. In the later
+case the path is not really hard-coded in the package, but we can
+consider it to be hard-coded in the system (or in whichever tool that
+supplies the path). As long as the path does not use any of the
+standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
+ at samp{$(datadir)}, etc.), the effect will be the same:
+user-installations are impossible.
+
+As a (non-root) user who wants to install a package, you usually have no
+right to install anything in @file{/usr} or @file{/usr/local}. So you
+do something like @samp{./configure --prefix ~/usr} to install a
+package in your own @file{~/usr} tree.
+
+If a package attempts to install something to some hard-coded path
+(e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
+then the installation will fail. @samp{make distcheck} performs such
+a @option{--prefix} installation, hence it will fail too.
+
+Now, there are some easy solutions.
+
+The above @code{install-data-local} example for installing
+ at file{/etc/afile} would be better replaced by
+
+ at example
+sysconf_DATA = afile
+ at end example
+
+ at noindent
+by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
+this is what the GNU Standards require. When such a package is
+installed on an FHS compliant system, the installer will have to set
+ at samp{--sysconfdir=/etc}. As the maintainer of the package you
+should not be concerned by such site policies: use the appropriate
+standard directory variable to install your files so that the installer
+can easily redefine these variables to match their site conventions.
+
+Installing files that should be used by another package is slightly
+more involved. Let's take an example and assume you want to install
+a shared library that is a Python extension module. If you ask Python
+where to install the library, it will answer something like this:
+
+ at example
+% @kbd{python -c 'from distutils import sysconfig;
+ print sysconfig.get_python_lib(1,0)'}
+/usr/lib/python2.5/site-packages
+ at end example
+
+If you indeed use this absolute path to install your shared library,
+non-root users will not be able to install the package, hence
+distcheck fails.
+
+Let's do better. The @samp{sysconfig.get_python_lib()} function
+actually accepts a third argument that will replace Python's
+installation prefix.
+
+ at example
+% @kbd{python -c 'from distutils import sysconfig;
+ print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
+$@{exec_prefix@}/lib/python2.5/site-packages
+ at end example
+
+You can also use this new path. If you do
+ at itemize @bullet
+ at item
+root users can install your package with the same @option{--prefix}
+as Python (you get the behavior of the previous attempt)
+
+ at item
+non-root users can install your package too, they will have the
+extension module in a place that is not searched by Python but they
+can work around this using environment variables (and if you installed
+scripts that use this shared library, it's easy to tell Python were to
+look in the beginning of your script, so the script works in both
+cases).
+ at end itemize
+
+The @code{AM_PATH_PYTHON} macro uses similar commands to define
+ at samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
+
+Of course not all tools are as advanced as Python regarding that
+substitution of @var{prefix}. So another strategy is to figure the
+part of the installation directory that must be preserved. For
+instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
+computes @samp{$(lispdir)}:
+
+ at example
+$EMACS -batch -q -eval '(while load-path
+ (princ (concat (car load-path) "\n"))
+ (setq load-path (cdr load-path)))' >conftest.out
+lispdir=`sed -n
+ -e 's,/$,,'
+ -e '/.*\/lib\/x*emacs\/site-lisp$/@{
+ s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
+ @}'
+ -e '/.*\/share\/x*emacs\/site-lisp$/@{
+ s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
+ @}'
+ conftest.out`
+ at end example
+
+I.e., it just picks the first directory that looks like
+ at file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
+the search path of emacs, and then substitutes @samp{$@{libdir@}} or
+ at samp{$@{datadir@}} appropriately.
+
+The emacs case looks complicated because it processes a list and
+expects two possible layouts, otherwise it's easy, and the benefits for
+non-root users are really worth the extra @command{sed} invocation.
+
+
+ at node Debugging Make Rules
+ at section Debugging Make Rules
+ at cindex debugging rules
+ at cindex rules, debugging
+
+The rules and dependency trees generated by @command{automake} can get
+rather complex, and leave the developer head-scratching when things
+don't work as expected. Besides the debug options provided by the
+ at command{make} command (@pxref{Options Summary,,, make, The GNU Make
+Manual}), here's a couple of further hints for debugging makefiles
+generated by @command{automake} effectively:
+
+ at itemize
+ at item
+If less verbose output has been enabled in the package with the use
+of silent rules (@pxref{Automake Silent Rules}), you can use
+ at code{make V=1} to see the commands being executed.
+ at item
+ at code{make -n} can help show what would be done without actually doing
+it. Note however, that this will @emph{still execute} commands prefixed
+with @samp{+}, and, when using GNU @command{make}, commands that contain
+the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
+Execution,,, make, The GNU Make Manual}).
+Typically, this is helpful to show what recursive rules would do, but it
+means that, in your own rules, you should not mix such recursion with
+actions that change any files. at footnote{Automake's @samp{dist} and
+ at samp{distcheck} rules had a bug in this regard in that they created
+directories even with @option{-n}, but this has been fixed in Automake
+1.11.} Furthermore, note that GNU @command{make} will update
+prerequisites for the @file{Makefile} file itself even with @option{-n}
+(@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
+ at item
+ at code{make SHELL="/bin/bash -vx"} can help debug complex rules.
+ at xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
+portability quirks associated with this construct.
+ at item
+ at code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
+can be handy to examine the expanded value of variables. You may need
+to use a target other than @samp{print} if that is already used or a
+file with that name exists.
+ at item
+ at url{http://bashdb.sourceforge.net/@/remake/} provides a modified
+GNU @command{make} command called @command{remake} that copes with
+complex GNU @command{make}-specific Makefiles and allows to trace
+execution, examine variables, and call rules interactively, much like
+a debugger.
+ at end itemize
+
+
+ at node Reporting Bugs
+ at section Reporting Bugs
+
+Most nontrivial software has bugs. Automake is no exception. Although
+we cannot promise we can or will fix a bug, and we might not even agree
+that it is a bug, we want to hear about problems you encounter. Often we
+agree they are bugs and want to fix them.
+
+To make it possible for us to fix a bug, please report it. In order to
+do so effectively, it helps to know when and how to do it.
+
+Before reporting a bug, it is a good idea to see if it is already known.
+You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
+and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
+bug-automake mailing list archives} for previous bug reports. We
+previously used a
+ at uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
+Gnats database} for bug tracking, so some bugs might have been reported
+there already. Please do not use it for new bug reports, however.
+
+If the bug is not already known, it should be reported. It is very
+important to report bugs in a way that is useful and efficient. For
+this, please familiarize yourself with
+ at uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
+Report Bugs Effectively} and
+ at uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
+Questions the Smart Way}. This helps you and developers to save time
+which can then be spent on fixing more bugs and implementing more
+features.
+
+For a bug report, a feature request or other suggestions, please send
+email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
+bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
+sure to include the versions of Autoconf and Automake that you use.
+Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
+reproduces the problem you encounter. If you have encountered test
+suite failures, please attach the @file{test-suite.log} file.
+
+ at c ========================================================== Appendices
+
+ at page
+ at node Copying This Manual
+ at appendix Copying This Manual
+
+ at menu
+* GNU Free Documentation License:: License for copying this manual
+ at end menu
+
+ at node GNU Free Documentation License
+ at appendixsec GNU Free Documentation License
+ at include fdl.texi
+
+ at page
+ at node Indices
+ at appendix Indices
+
+ at menu
+* Macro Index:: Index of Autoconf macros
+* Variable Index:: Index of Makefile variables
+* General Index:: General index
+ at end menu
+
+ at node Macro Index
+ at appendixsec Macro Index
+
+ at printindex fn
+
+ at node Variable Index
+ at appendixsec Variable Index
+
+ at printindex vr
+
+ at node General Index
+ at appendixsec General Index
+
+ at printindex cp
+
+
+ at bye
+
+ at c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
+ at c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
+ at c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
+ at c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
+ at c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
+ at c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
+ at c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
+ at c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
+ at c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
+ at c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
+ at c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
+ at c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
+ at c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
+ at c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
+ at c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
+ at c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
+ at c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
+ at c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
+ at c LocalWords: dirlist noindent usr TIOCGWINSZ sc
+ at c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
+ at c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
+ at c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
+ at c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
+ at c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
+ at c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
+ at c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
+ at c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
+ at c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
+ at c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
+ at c LocalWords: OBJCXXFLAGS
+ at c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
+ at c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
+ at c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
+ at c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
+ at c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
+ at c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
+ at c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
+ at c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
+ at c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
+ at c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
+ at c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
+ at c LocalWords: depfile tmpdepfile depmode const interoperate
+ at c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
+ at c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
+ at c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
+ at c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
+ at c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
+ at c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
+ at c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
+ at c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
+ at c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
+ at c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
+ at c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
+ at c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
+ at c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
+ at c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
+ at c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
+ at c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
+ at c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
+ at c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
+ at c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
+ at c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
+ at c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
+ at c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
+ at c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
+ at c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
+ at c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
+ at c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
+ at c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
+ at c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
+ at c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
+ at c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
+ at c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
+ at c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
+ at c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
+ at c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
+ at c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
+ at c LocalWords: barexec Pinard's automatize initialize lzip xz cscope
diff --git a/debian/docs/src/automake/1.14/fdl.texi b/debian/docs/src/automake/1.14/fdl.texi
new file mode 100644
index 0000000..bcabd3a
--- /dev/null
+++ b/debian/docs/src/automake/1.14/fdl.texi
@@ -0,0 +1,506 @@
+ at c The GNU Free Documentation License.
+ at center Version 1.3, 3 November 2008
+
+ at c This file is intended to be included within another document,
+ at c hence no sectioning command or @node.
+
+ at display
+Copyright @copyright{} 2000-2013 Free Software Foundation, Inc.
+ at uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+ at end display
+
+ at enumerate 0
+ at item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+ at item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ at sc{ascii} without markup, Texinfo input format, La at TeX{} input
+format, @acronym{SGML} or @acronym{XML} using a publicly available
+ at acronym{DTD}, and standard-conforming simple @acronym{HTML},
+PostScript or @acronym{PDF} designed for human modification. Examples
+of transparent image formats include @acronym{PNG}, @acronym{XCF} and
+ at acronym{JPG}. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, @acronym{SGML} or
+ at acronym{XML} for which the @acronym{DTD} and/or processing tools are
+not generally available, and the machine-generated @acronym{HTML},
+PostScript or @acronym{PDF} produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+ at item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+ at item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all of these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+ at item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+ at enumerate A
+ at item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+ at item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+ at item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+ at item
+Preserve all the copyright notices of the Document.
+
+ at item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+ at item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+ at item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+ at item
+Include an unaltered copy of this License.
+
+ at item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+ at item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+ at item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+ at item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+ at item
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+ at item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+ at item
+Preserve any Warranty Disclaimers.
+ at end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+ at item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
+ at item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+ at item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+ at item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+ at item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+ at item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+ at uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+ at item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+ at end enumerate
+
+ at page
+ at heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+ at smallexample
+ at group
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+ at end group
+ at end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with at dots{}Texts.'' line with this:
+
+ at smallexample
+ at group
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
+ at end group
+ at end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+ at c Local Variables:
+ at c ispell-local-pdict: "ispell-dict"
+ at c End:
+
diff --git a/debian/docs/src/automake/1.14/version.texi b/debian/docs/src/automake/1.14/version.texi
new file mode 100644
index 0000000..6789d40
--- /dev/null
+++ b/debian/docs/src/automake/1.14/version.texi
@@ -0,0 +1,4 @@
+ at set UPDATED 20 June 2013
+ at set UPDATED-MONTH June 2013
+ at set EDITION 1.14
+ at set VERSION 1.14
diff --git a/debian/patches/autotools-add-distro-version-to-list.patch b/debian/patches/autotools-add-distro-version-to-list.patch
index edaf8c3..c08bd31 100644
--- a/debian/patches/autotools-add-distro-version-to-list.patch
+++ b/debian/patches/autotools-add-distro-version-to-list.patch
@@ -24,7 +24,7 @@ index 5755bfb..5496bc3 100644
public static final String LATEST_AC_VERSION = fACVersions[fACVersions.length - 1];
- public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1"}; // $NON-NLS-1$
-+ public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5", "1.13.3"}; // $NON-NLS-1$
++ public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5", "1.13.3", "1.14"}; // $NON-NLS-1$
public static final String LATEST_AM_VERSION = fAMVersions[fAMVersions.length - 1];
public static final String CLEAN_MAKE_TARGET_DEFAULT = "distclean"; // $NON-NLS-1$
@@ -41,7 +41,7 @@ index 3fda416..b65a848 100644
public static final String LATEST_AC_VERSION = fACVersions[fACVersions.length - 1];
- private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1"};
-+ private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5", "1.13.3"};
++ private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5", "1.13.3", "1.14"};
public static final String LATEST_AM_VERSION = fAMVersions[fAMVersions.length - 1];
/** The keys of the overlay store. */
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/eclipse-cdt.git
More information about the pkg-java-commits
mailing list