Subject: Autotools Introduction chapter + amhello-1.0.tar.gz - msg#00026

Here is the patch. make distcheck is still running, but anyway
I'll let this patch mellow until the week-end.

I haven't changed the prompt or font usage for "Makefile". I'm
not against these changes, it just that they'd require a full
pass over the manual anyway, so that can be done separately.

2006-08-16 Alexandre Duret-Lutz <adl@xxxxxxx>

* doc/automake.texi (Autotools Introduction) New chapter.
Thanks to Ben Pfaff and Ralf Wildenhues for comments.
(Auxiliary Programs, Install, Dist, Third-Party Makefiles)
(distcleancheck): More cross references.
* doc/amhello/configure.ac, doc/amhello/README,
doc/amhello/Makefile.am, doc/amhello/src/Makefile.am,
doc/amhello/src/main.c: New files.
* doc/Makefile.am (dist_noinst_DATA): Distribute them.
($(srcdir)/amhello-1.0.tar.gz): New rule.
(dist_doc_DATA): Install amhello-1.0.tar.gz.
* Makefile.am (SUBDIRS): Update comment.

Index: Makefile.am
===================================================================
RCS file: /cvs/automake/automake/Makefile.am,v
retrieving revision 1.243
diff -u -r1.243 Makefile.am
--- Makefile.am 11 May 2006 17:33:31 -0000 1.243
+++ Makefile.am 16 Aug 2006 17:07:46 -0000
@@ -21,7 +21,7 @@
## 02110-1301, USA.

## We need `.' in SUBDIRS because we want `check' to build `.' before
-## tests.
+## tests. It should go before `doc', because doc/amhello uses automake.
SUBDIRS = . doc m4 lib tests

bin_SCRIPTS = automake aclocal
Index: NEWS
===================================================================
RCS file: /cvs/automake/automake/NEWS,v
retrieving revision 1.307
diff -u -r1.307 NEWS
--- NEWS 14 Aug 2006 20:38:39 -0000 1.307
+++ NEWS 16 Aug 2006 17:07:46 -0000
@@ -122,6 +122,10 @@
- New support for Unified Parallel C:
- AM_PROG_UPC looks for a UPC compiler.
- A new section of the manual documents the support.
+
+ - Automake installs an "Hello World!" example package in $(docdir).
+ This example is used thorough the new "Autotools Introduction"
+ chapter of the manual.

New in 1.9:

Index: THANKS
===================================================================
RCS file: /cvs/automake/automake/THANKS,v
retrieving revision 1.287
diff -u -r1.287 THANKS
--- THANKS 4 Aug 2006 10:23:14 -0000 1.287
+++ THANKS 16 Aug 2006 17:07:46 -0000
@@ -24,6 +24,7 @@
Assar Westerlund assar@xxxxxxx
Axel Belinfante Axel.Belinfante@xxxxxxxxxxxxx
Bas Wijnen shevek@xxxxxx
+Ben Pfaff blp@xxxxxxxxxxxxxxxx
Bernard Giroud bernard.giroud@xxxxxxxxxxxxxxxxx
Bernard Urban Bernard.Urban@xxxxxxxx
Bernd Jendrissek berndfoobar@xxxxxxxxxxxxxxxxxxxxx
Index: doc/.cvsignore
===================================================================
RCS file: /cvs/automake/automake/doc/.cvsignore,v
retrieving revision 1.2
diff -u -r1.2 .cvsignore
--- doc/.cvsignore 26 Sep 2004 21:16:56 -0000 1.2
+++ doc/.cvsignore 16 Aug 2006 17:07:46 -0000
@@ -9,3 +9,4 @@
automake.ov automake.toc automake.pg automake.ky automake.tp
automake.vr automake.fn automake.cp automake.aux
automake.cm automake.ps automake.html
+*.gz
Index: doc/Makefile.am
===================================================================
RCS file: /cvs/automake/automake/doc/Makefile.am,v
retrieving revision 1.3
diff -u -r1.3 Makefile.am
--- doc/Makefile.am 14 May 2005 20:28:50 -0000 1.3
+++ doc/Makefile.am 16 Aug 2006 17:07:46 -0000
@@ -2,7 +2,7 @@

## Makefile for Automake.

-## Copyright (C) 2003 Free Software Foundation, Inc.
+## Copyright (C) 2003, 2006 Free Software Foundation, Inc.

## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
@@ -26,3 +26,40 @@
ETAGS_ARGS = --lang=none \
--regex='/^@node[ \t]+\([^,]+\)/\1/' $(srcdir)/automake.texi
TAGS_DEPENDENCIES = automake.texi
+
+amhello_sources = \
+ amhello/configure.ac \
+ amhello/Makefile.am \
+ amhello/README \
+ amhello/src/main.c \
+ amhello/src/Makefile.am
+
+amhello_configury = \
+ aclocal.m4 \
+ autom4te.cache \
+ Makefile.in \
+ config.h.in \
+ configure \
+ depcomp \
+ install-sh \
+ missing \
+ src/Makefile.in
+
+dist_noinst_DATA = $(amhello_sources)
+dist_doc_DATA = $(srcdir)/amhello-1.0.tar.gz
+
+# We depend on configure.ac so that we regenerate the tarball
+# whenever the Automake version changes.
+# aclocal-$(APIVERSION) and automake-$(APIVERSION) are generated by
+# configure in tests/.
+$(srcdir)/amhello-1.0.tar.gz: $(amhello_sources) $(top_srcdir)/configure.ac
+ PATH="`pwd`/../tests$(PATH_SEPARATOR)$$PATH" && \
+ export PATH && \
+ cd $(srcdir)/amhello && \
+ ACLOCAL=aclocal-$(APIVERSION) AUTOMAKE=automake-$(APIVERSION) \
+ autoreconf -vfi && \
+ ./configure && \
+ make distcheck && \
+ make distclean && \
+ rm -rf $(amhello_configury) && \
+ mv amhello-1.0.tar.gz ..
Index: doc/automake.texi
===================================================================
RCS file: /cvs/automake/automake/doc/automake.texi,v
retrieving revision 1.142
diff -u -r1.142 automake.texi
--- doc/automake.texi 15 Aug 2006 06:45:24 -0000 1.142
+++ doc/automake.texi 16 Aug 2006 17:07:48 -0000
@@ -57,6 +57,14 @@
@insertcopying
@end titlepage

+
+@c We use the following macros to define indices:
+@c @cindex concepts, and anything that does not fit elsewhere
+@c @vindex Makefile variables
+@c @trindex targets
+@c @acindex Autoconf/Automake/Libtool/M4/... macros
+@c @opindex tool options
+
@c Define an index of configure macros.
@defcodeindex ac
@c Define an index of options.
@@ -83,6 +91,7 @@

@menu
* Introduction:: Automake's purpose
+* Autotools Introduction:: An Introduction to the Autotools
* Generalities:: General ideas
* Examples:: Some example packages
* Invoking Automake:: Creating a Makefile.in
@@ -115,6 +124,34 @@
@detailmenu
--- The Detailed Node Listing ---

+An Introduction to the Autotools
+
+* GNU Build System:: Introducing the GNU Build System
+* Use Cases:: Use case 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 installtion 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 Explained:: @file{configure.ac} and @file{Makefile.am}
explained
+
General ideas

* General Operation:: General operation of Automake
@@ -288,13 +325,14 @@
@node Introduction
@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@footnote{These variables are
-also called @dfn{make macros} in Make terminology, however in this
-manual we reserve the term @dfn{macro} for Autoconf's macros.}, with
-rules being thrown in occasionally. The generated @file{Makefile.in}s
-are compliant with the GNU Makefile standards.
+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@footnote{These variables are also called @dfn{make macros}
+in Make terminology, however in this manual we reserve the term
+@dfn{macro} for Autoconf's macros.}, with rules being thrown in
+occasionally. The generated @file{Makefile.in}s are compliant with
+the GNU Makefile standards.

@cindex GNU Makefile standards

@@ -303,7 +341,7 @@
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
-maintainer).
+maintainers).

The typical Automake input file is simply a series of variable definitions.
Each such file is processed to create a @file{Makefile.in}. There
@@ -336,6 +374,1305 @@
Mail suggestions and bug reports for Automake to
@email{bug-automake@@gnu.org}.

+@node Autotools Introduction
+@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},
+@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 this machinery,
+to show you how it works and how powerful it is. If you've never
+installed or seen such a package, do not worry: this chapter will walk
+you through it.
+
+If you need some teaching material, more illustrations, or a less
+@command{automake}-centred continuation, some slides for this
+introduction are available in Alexandre Duret-Lutz's
+@uref{Autotools Turorial,
+http://www-src.lip6.fr/~Alexandre.Duret-Lutz/autotools.html}.
+This chapter is the written version of the first part of his tutorial.
+
+@menu
+* GNU Build System:: Introducing the GNU Build System
+* Use Cases:: Use case for the GNU Build System
+* Why Autotools:: How Autotools Help
+* Hello World:: A Small Hello World Package
+@end menu
+
+@node GNU Build System
+@section Introducing the GNU Build System
+@cindex GNU Build System, introduction
+
+It is a truth universally acknowledged, that a developer in
+possession of a new package, must be in want of a build system.
+
+In the Unix world, such a build system is traditionally achieved using
+the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
+Manual}). The developer expresses the recipe to build his package in
+a @file{Makefile}. This file is a set of rules to build the files in
+the package. For instance the program @file{prog} may be built by
+running the linker on the files @file{main.o}, @file{foo.o}, and
+@file{bar.o}; the file @file{main.o} may be built by running the
+compiler on @file{main.c}; etc. Each time @command{make} is run, it
+reads @file{Makefile}, checks the existence and modification time of
+the files mentioned, decides what files need to be built (or rebuilt),
+and run 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 customising
+@file{Makefile} for the 20 platforms he had to deal with. Instead, he
+handcrafted a little shell script called @file{configure} to
+automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
+autoconf, The Autoconf Manual}). Compiling his package was now
+as simple as running @code{./configure && make}.
+
+@cindex GNU Coding Standards
+
+Today this process has been standardised in the GNU project. The GNU
+Coding Standards (@pxref{Managing Releases, The Release Process, ,
+standards, The GNU Coding Standards}) explains how each package of the
+GNU project should have a @file{configure} script, and the minimal
+interface it should have. The @file{Makefile} too should follow some
+established conventions. The result? A unified build system that
+makes all packages almost indistinguishable by the installer. In its
+simplest scenario, all the installer has to do is to unpack the
+package, run @code{./configure && make && make install}, and repeat
+with the next package to install.
+
+We call this build system the @dfn{GNU Build System}, since it was
+grown out of the GNU project. However it is used by a vast number of
+other packages: following any existing convention has its advantages.
+
+@cindex Autotools, introduction
+
+The Autotools are tools that will create a GNU Build System for your
+package. Autoconf mostly focuses on @file{configure} and Automake on
+@file{Makefile}s. It is entirely possible to create a GNU Build
+System without the help of these tools. However it is rather
+burdensome and error-prone. We will discuss this again after some
+illustration of the GNU Build System in action.
+
+@node Use Cases
+@section Use Cases for the GNU Build System
+@cindex GNU Build System, use cases
+@cindex GNU Build System, features
+@cindex Features of the GNU Build System
+@cindex Use cases for the GNU Build System
+@cindex @file{amhello-1.0.tar.gz}, location
+@cindex @file{amhello-1.0.tar.gz}, use cases
+
+In this section we explore several use cases for the GNU Build System.
+You can replay all 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
+@file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
+@var{prefix} is the installation prefix specified during configuration
+(@var{prefix} defaults to @file{/usr/local}, however if Automake 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 Standard, but they are nonetheless part of the build
+system created by the Autotools. To keep things simple we do not
+point out the difference. Our objective is to show you many of the
+features that the build system created by the Autotools will offer to
+you.
+
+@menu
+* Basic Installation:: Common installtion procedure
+* Standard Targets:: A list of standard Makefile targets
+* Standard Directory Variables:: A list of standard directory variables
+* Standard Configuration Variables:: Using configuration variables
+* config.site:: Using a config.site file
+* VPATH Builds:: Parallel build trees
+* Two-Part Install:: Installing data and programs separately
+* Cross-Compilation:: Building for other architectures
+* Renaming:: Renaming programs at install time
+* DESTDIR:: Building binary packages with DESTDIR
+* Preparing Distributions:: Rolling out tarballs
+* Dependency Tracking:: Automatic dependency tracking
+* Nested Packages:: The GNU Build Systems can be nested
+@end menu
+
+@node Basic Installation
+@subsection Basic Installation
+@cindex Configuration, basics
+@cindex Installation, basics
+@cindex GNU Build System, basics
+
+The most common installation procedure looks as follows.
+
+@example
+~ % @kbd{tar zxf amhello-1.0.tar.gz}
+~ % @kbd{cd amhello-1.0}
+~/amhello-1.0 % @kbd{./configure}
+@dots{}
+config.status: creating Makefile
+config.status: creating src/Makefile
+@dots{}
+~/amhello-1.0 % @kbd{make}
+@dots{}
+~/amhello-1.0 % @kbd{make check}
+@dots{}
+~/amhello-1.0 % @kbd{su}
+Password:
+/home/adl/amhello-1.0 # @kbd{make install}
+@dots{}
+/home/adl/amhello-1.0 # @kbd{exit}
+~/amhello-1.0 % @kbd{make installcheck}
+@dots{}
+@end example
+
+@cindex Unpacking
+
+The user first unpacks the package. Here, and in the following
+examples, we will use the non-portable @code{tar zxf} command for
+simplicity. On a system without GNU @command{tar} installed, this
+command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
+
+The user then enters the newly created directory to run the
+@file{configure} script. This script probes the system for various
+features, and finally create the @file{Makefile}s. In this toy
+example there are only two @file{Makefile}s, but in real-world project
+there may be many more, usually one @file{Makefile} per directory.
+
+It is now possible to run @code{make}. This will construct all the
+programs, libraries, and scripts that need to be constructed for the
+package. In our example, this compiles the @file{hello} program.
+All files are constructed in place, in the source tree; we will see
+later how this can be changed.
+
+@code{make check} causes the package's tests to be run. This step is
+not mandatory, but it is often good to make sure the programs that
+have been built behave as they should, before you decide to install
+them. Our example does not contain any tests, so running @code{make
+check} is a no-op.
+
+@cindex su, before @code{make install}
+After everything has been built, and maybe tested, it is time to
+install them 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 into
+@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 former. For instance, there are tests that cannot
+be run in the source tree. Conversely, some packages are set up so
+that @code{make installcheck} will run the very same tests as
+@code{make check}, only on different files (non-installed
+vs. installed). It can make a difference, for instance when the
+source tree's layout is different from that of the installation.
+Furthermore it may help to diagnose an incomplete installation.
+
+Presently most packages do not have any @code{installcheck} tests
+because the existence of @code{installcheck} is little known, and its
+usefulness is neglected. Our little toy package is no better: @code{make
+installcheck} does nothing.
+
+@node Standard Targets
+@subsection Standard @file{Makefile} Targets
+
+So far we have come across four ways to run @command{make} in the GNU
+Build System: @code{make}, @code{make check}, @code{make install}, and
+@code{make installcheck}. The words @code{check}, @code{install}, and
+@code{installcheck}, passed as arguments to @command{make}, are called
+@dfn{targets}. @code{make} is a shorthand for @code{make all},
+@code{all} being the default target in the GNU Build System.
+
+Here is a list of the most useful targets that the GNU Coding Standards
+specify.
+
+@table @code
+@item make all
+@trindex all
+Build programs, libraries, documentation, etc. (Same as @code{make}.)
+@item make install
+@trindex install
+Install what needs to be installed, copying the files from the
+package's tree to system-wide directories.
+@item make install-strip
+@trindex install-strip
+Same as @code{make install}, then strip debugging symbols. Some
+users like to trade space for useful bug reports...
+@item make uninstall
+@trindex uninstall
+The opposite of @code{make install}: erase the installed files.
+(This needs to be run from the same build tree that was installed.)
+@item make clean
+@trindex clean
+Erase from the build tree the files built by @code{make all}.
+@item make distclean
+@trindex distclean
+Additionally erase anything @code{./configure} created.
+@item make check
+@trindex check
+Run the test suite, if any.
+@item make installcheck
+@trindex installcheck
+Check the installed programs or libraries, if supported.
+@item make dist
+@trindex dist
+Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
+files.
+@end table
+
+@node Standard Directory Variables
+@subsection Standard Directory Variables
+@cindex directory variables
+
+The GNU Coding Standards also specify a hierarchy of variables to
+denote installation directories.
+
+@multitable {Directory variable} {@file{@code{datarootdir}/doc/@code{PACKAGE}}}
+@headitem Directory variable @tab Default value
+@item @code{prefix} @tab @code{/usr/local}
+@item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
+@item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
+@item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
+@item @w{@ @ @ @ @dots{}}
+@item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
+@item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
+@item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
+@item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
+@item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
+@item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
+@item @w{@ @ @dots{}}
+@end multitable
+
+@c We should provide a complete table somewhere, but not here. The
+@c complete list of directory variables it too confusing as-is. It
+@c requires some explanations that are too complicated for this
+@c introduction. Besides listing directories like localstatedir
+@c would make the explanations in ``Two-Part Install'' harder.
+
+Each of these directories has a role which is often obvious from its
+name. In a package, any installable file will be installed in one of
+these directories. For instance in @code{amhello-1.0}, the program
+@file{hello} is to be installed in @var{bindir}, the directory for
+binaries. The default value for this directory is
+@file{/usr/local/bin}, but the user can supply a different value when
+calling @command{configure}. Also the file @file{README} will be
+installed into @var{docdir}, which defaults to
+@file{/usr/local/share/doc/amhello}.
+
+@opindex --prefix
+
+A user who wish to install a package on his own account could proceed
+as follows:
+
+@example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
+@dots{}
+~/amhello-1.0 % @kbd{make}
+@dots{}
+~/amhello-1.0 % @kbd{make install}
+@dots{}
+@end example
+
+This would install @file{~/usr/bin/hello} and
+@file{~/usr/share/doc/amhello/README}.
+
+The list of all such directory options is shown by
+@code{./configure --help}.
+
+@node Standard Configuration Variables
+@subsection Standard Configuration Variables
+@cindex configuration variables, overriding
+
+The GNU Coding Standards also define a set of standard configuration
+variables used during the build. Here are some:
+
+@table @asis
+@item @code{CC}
+C compiler command
+@item @code{CFLAGS}
+C compiler flags
+@item @code{CXX}
+C++ compiler command
+@item @code{CXXFLAGS}
+C++ compiler flags
+@item @code{LDFLAGS}
+linker flags
+@item @code{CPPFLAGS}
+C/C++ preprocessor flags
+@item @dots{}
+@end table
+
+@command{configure} usually does a good job at setting appropriate
+values for these variables, but there are cases where you may want to
+override them. For instance you may have several versions of a
+compiler installed and would like to use another one, you may have
+header files installed outside the default search path of the
+compiler, or even libraries out of the way of the linker.
+
+Here is how one would call @command{configure} to force it to use
+@command{gcc-3} as C compiler, use header files from
+@file{~/usr/include} when compiling, and libraries from
+@file{~/usr/lib} when linking.
+
+@example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
+CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
+@end example
+
+Again, a full list of these variables appears in the output of
+@code{./configure --help}.
+
+@node config.site
+@subsection Overriding Default Configuration Setting with @file{config.site}
+@cindex @file{config.site} example
+
+When installing several packages using the same setup, it can be
+convenient to create a @file{config.site} to capture common settings.
+If a file named @file{@var{prefix}/share/config.site} exists,
+@command{configure} will source it at the beginning of its execution.
+
+Recall the command from the previous section:
+
+@example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
+CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
+@end example
+
+Assuming we are installing many package in @file{~/usr}, and will
+always want to use these definition of @code{CC}, @code{CPPFLAGS}, and
+@code{LDFLAGS}, we can automatize this by creating the following
+@file{~/usr/share/config.site} file:
+
+@example
+test -z "$CC" && CC=gcc-3
+test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
+test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
+@end example
+
+Now any time a @file{configure} script is using the @file{~/usr}
+prefix, it will execute the above @file{config.site} and define
+these three variables.
+
+@example
+~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
+configure: loading site script /home/adl/usr/share/config.site
+@dots{}
+@end example
+
+@xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
+Manual}, for more information about this feature.
+
+
+@node VPATH Builds
+@subsection Parallel Build Trees (a.k.a. VPATH Builds)
+@cindex Parallel build trees
+@cindex VPATH builds
+@cindex source tree and build tree
+@cindex build tree and source tree
+@cindex trees, source vs. build
+
+The GNU Build System distinguishes two trees: the source tree, and
+the build tree.
+
+The source tree is rooted in the directory containing
+@file{configure}. it contains all the sources files (those that are
+distributed), and may be arranged using several subdirectories.
+
+The build tree is rooted in the directory where the @file{configure}
+were 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
+directory as their sources. This was the case in our first
+installation example (@pxref{Basic Installation}).
+
+A common request from users is that they want to confine all derived
+files to a single directory, to keep their source directories
+uncluttered. Here is how we could run @file{configure} to build
+everything in a subdirectory called @file{build/}.
+
+@example
+~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
+~ % @kbd{cd amhello-1.0}
+~/amhello-1.0 % @kbd{mkdir build && cd build}
+~/amhello-1.0/build % @kbd{../configure}
+@dots{}
+~/amhello-1.0/build % @kbd{make}
+@dots{}
+@end example
+
+These setups, where source and build trees are different, are often
+called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
+@emph{parallel build} is misleading: the word @emph{parallel} is a
+reference to the way the build tree shadows the source tree, it is not
+about some concurrency in the way build commands are run. For this
+reason we refer to such setups using the name @emph{VPATH builds} in
+the sequel. @emph{VPATH} is the name of the @command{make} feature
+used by the @file{Makefile}s to allow these builds (@pxref{General
+Search, , @code{VPATH}: Search Path for All Prerequisites, make, The
+GNU Make Manual}).
+
+@cindex multiple configurations, example
+@cindex debug build, example
+@cindex optimized build, example
+
+VPATH builds have other interesting uses. One is to build the same
+sources with multiple configurations. For instance:
+
+@example
+~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
+~ % @kbd{cd amhello-1.0}
+~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
+~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
+@dots{}
+~/amhello-1.0/debug % @kbd{make}
+@dots{}
+~/amhello-1.0/debug % cd ../optim
+~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
+@dots{}
+~/amhello-1.0/optim % @kbd{make}
+@dots{}
+@end example
+
+With network file systems, a similar approach can be used to build the
+same sources on different machines. For instance, suppose that the
+sources are installed on a directory shared by two hosts: @code{HOST1}
+and @code{HOST2}, which may be different platforms.
+
+@example
+~ % @kbd{cd /nfs/src}
+/nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
+@end example
+
+On the first host, you could create a local build directory:
+@example
+[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
+...
+[HOST1] /tmp/amh % @kbd{make && sudo make install}
+...
+@end example
+
+@noindent
+(Here we assume the that installer has configured @command{sudo} so it
+can execute @code{make install} with root privileges; it is more convenient
+than using @command{su} like in @ref{Basic Installation}).
+
+On the second host, you would do exactly the same, possibly at
+the same time:
+@example
+[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
+...
+[HOST2] /tmp/amh % @kbd{make && sudo make install}
+...
+@end example
+
+@cindex read-only source tree
+@cindex source tree, read-only
+
+In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
+directory from being read-only. In fact VPATH builds are also a means
+of building packages from a read-only medium such as a CD-ROM. (The
+FSF used to sell CD-ROM with unpacked source code, before the GNU
+project grew so big.)
+
+@node Two-Part Install
+@subsection Two-Part Installation
+
+In our last example (@pxref{VPATH Builds}), a source tree was shared
+by two hosts, but compilation and installation were done separately on
+each host.
+
+The GNU Build System also supports networked setups where part of the
+installed files should be shared amongst multiple hosts. It does so
+by distinguishing architecture-dependent files from
+architecture-independent files, and providing two @file{Makefile}
+targets to install each of these classes of files.
+
+@trindex install-exec
+@trindex install-data
+
+These targets are @code{install-exec} for architecture-dependent files
+and @code{install-data} for architecture-independent files.
+The command we used up to now, @code{make install}, can be thought of
+as a shorthand for @code{make install-exec install-data}.
+
+From the GNU Build System point of view, the distinction between
+architecture-dependent files and architecture-independent files is
+based exclusively on the directory variable used to specify their
+installation destination. In the list of directory variables we
+provided earlier (@pxref{Standard Directory Variables}), all the
+variables based on @var{exec-prefix} designate architecture-dependent
+directories whose files will be installed by @code{make install-exec}.
+The others designate architecture-independent directories and will
+serve files installed by @code{make install-data}. @xref{Install},
+for more details.
+
+Here is how we could revisit our two-host installation example,
+assuming that (1) we want to install the package directly in
+@file{/usr}, and (2) the directory @file{/usr/share} is shared by the
+two hosts.
+
+On the first host we would run
+@example
+[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
+...
+[HOST1] /tmp/amh % @kbd{make && sudo make install}
+...
+@end example
+
+On the second host, however, we need only to install the
+architecture-specific files.
+@example
+[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
+[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
+...
+[HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
+...
+@end example
+
+In packages that have installation checks, it would make sense to run
+@code{make installcheck} (@pxref{Basic Installation}) to verify that
+the package works correctly despite the apparent partial installation.
+
+@node Cross-Compilation
+@subsection Cross-Compilation
+@cindex Cross-compilation
+
+To @dfn{cross-compile} is to build on one platform a binary that will
+be run on another platform. When speaking of cross-compilation, it is
+important to distinguish between the @dfn{build platform} on which
+the compilation is performed, and the @dfn{host platform} on which the
+resulting executable is expected to run. The following
+@command{configure} options are used to specify each of them:
+
+@table @option
+@item --build=@var{BUILD}
+@opindex --build=@var{BUILD}
+The system on which the package is built.
+@item --host=@var{HOST}
+@opindex --host=@var{HOST}
+The system where built programs and libraries will run.
+@end table
+
+When the @option{--host} is used, @command{configure} will search for
+the cross-compiling suite for this platform. cross-compilation tools
+commonly have their target architecture as prefix of their name. For
+instance my cross-compiler for MinGW32 has its binaries called
+@code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
+@code{i586-mingw32msvc-as}, etc.
+
+@cindex MinGW cross-compilation example
+@cindex cross-compilation example
+
+Here is how we could build @code{amhello-1.0} for
+@code{i586-mingw32msvc} on a GNU/Linux PC.
+
+@smallexample
+~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host
i586-mingw32msvc}
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking for gawk... gawk
+checking whether make sets $(MAKE)... yes
+checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
+checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
+checking for C compiler default output file name... a.exe
+checking whether the C compiler works... yes
+checking whether we are cross compiling... yes
+checking for suffix of executables... .exe
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether i586-mingw32msvc-gcc accepts -g... yes
+checking for i586-mingw32msvc-gcc option to accept ANSI C...
+@dots{}
+~/amhello-1.0 % @kbd{make}
+@dots{}
+~/amhello-1.0 % @kbd{cd src; file hello.exe}
+hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
+@end smallexample
+
+The @option{--host} and @option{--build} options are usually all we
+need for cross-compiling. The only exception is if the package being
+built is itself a cross-compiler: we need a third option to specify
+its target architecture.
+
+@table @option
+@item --target=@var{TARGET}
+@opindex --target=@var{TARGET}
+When building compiler tools: the system for which the tools will
+create output.
+@end table
+
+For instance when installing GCC, the GNU Compiler Collection, we can
+use @option{--target=@var{TARGET}} to specify that we want to build
+GCC as a cross-compiler for @var{TARGET}. Mixing @option{--build} and
+@option{--target}, we can actually cross-compile a cross-compiler;
+such a three-way cross-compilation is known as a @dfn{Canadian cross}.
+
+@xref{Specifying Names, , Specifying the System Type, autoconf, The
+Autoconf Manual}, for more information about these @command{configure}
+options.
+
+@node Renaming
+@subsection Renaming Programs at Install Time
+@cindex Renaming programs
+@cindex Transforming program names
+@cindex Programs, renaming during installation
+
+The GNU build system provides means to automatically rename
+executables before they are installed. This is especially convenient
+when installing a GNU package on a system that already has a
+proprietary implementation you do not want to overwrite. For instance,
+you may want to install GNU @command{tar} as @command{gtar} so you can
+distinguish it from your vendor's @command{tar}.
+
+This can be done using one of these three @command{configure} options.
+
+@table @option
+@item --program-prefix=@var{PREFIX}
+@opindex --program-prefix=@var{PREFIX}
+Prepend @var{PREFIX} to installed program names.
+@item --program-suffix=@var{SUFFIX}
+@opindex --program-suffix=@var{SUFFIX}
+Append @var{SUFFIX} to installed program names.
+@item --program-transform-name=@var{PROGRAM}
+@opindex --program-transform-name=@var{PROGRAM}
+Run @code{sed @var{PROGRAM}} on installed program names.
+@end table
+
+The following commands would install @file{hello}
+as @file{/usr/local/bin/test-hello}, for instance.
+
+@example
+~/amhello-1.0 % @kbd{./configure --program-prefix test-}
+@dots{}
+~/amhello-1.0 % @kbd{make}
+@dots{}
+~/amhello-1.0 % @kbd{sudo make install}
+@dots{}
+@end example
+
+@node DESTDIR
+@subsection Building Binary Packages Using DESTDIR
+@vindex DESTDIR
+
+The GNU build system's @code{make install} and @code{make uninstall}
+interface does not exactly fit the needs of a system administrator
+who has to deploy and upgrade packages on lots of hosts. In other
+words, the GNU build system does not replace a package manager.
+
+Such package managers usually need to know which files have been
+installed by a package, so a mere @code{make install} is
+inappropriate.
+
+@cindex Staged installation
+
+The @code{DESTDIR} variable can be used to perform a staged
+installation. The package should be configured as if it was going to
+be installed in its final location (e.g., @code{--prefix /usr}), but
+when running @code{make install} the @code{DESTDIR} should be set to
+the absolute name of a directory in which all 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 any means.
+
+@cindex Binary package
+
+For instance here is how we could create a binary package containing a
+snapshot of all the files to be installed.
+
+@example
+~/amhello-1.0 % @kbd{./configure --prefix /usr}
+@dots{}
+~/amhello-1.0 % @kbd{make}
+@dots{}
+~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
+@dots{}
+~/amhello-1.0 % @kbd{cd ~/inst}
+~/inst % @kbd{find . -type f -print > files.lst}
+~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat file.lst`}
+./usr/bin/hello
+./usr/share/doc/amhello/README
+@end example
+
+After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
+uncompressed in @file{/} on many hosts. (Using @code{`cat file.lst`}
+instead of @samp{.} as argument for @command{tar} avoid entries for
+each subdirectory in the archive: we would not like @command{tar} to
+restore the modification time of @file{/}, @file{/usr/}, etc.)
+
+Note that when building packages for several architectures, it might
+be convenient to use @code{make install-data} and @code{make
+install-exec} (@pxref{Two-Part Install}) to gather
+architecture-independent files in a single package.
+
+@xref{Install}, for more information.
+
+@c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
+@c UNINSTALL counterparts.
+
+@node Preparing Distributions
+@subsection Preparing Distributions
+@cindex Preparing distributions
+@cindex Packages, preparation
+@cindex Distributions, preparation
+
+We have already mentioned @code{make dist}. This target collects all
+your source files, and the necessary parts of the build system, to
+create a tarball named @file{@var{package}-@var{version}.tar.gz}.
+
+@cindex @code{distcheck} better than @code{dist}
+
+Another, more useful command is @code{make distcheck}. The
+@code{distcheck} target constructs
+@file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
+but it additionally ensures most of the use-cases presented so far
+work:
+
+@itemize @bullet
+@item
+It attempts a full compilation of the package (@pxref{Basic
+Installation}), unpacking the newly constructed tarball, running
+@code{make}, @code{make check}, @code{make install}, as well as
+@code{make installcheck}, and even @code{make dist},
+@item
+it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
+@item
+it makes sure @code{make clean}, @code{make distclean}, and @code{make
+uninstall} do not omit any file (@pxref{Standard Targets}),
+@item
+and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
+@end itemize
+
+All of these actions are performed in a temporary subdirectory, so
+that no root privileges are required.
+
+Releasing a package that fails @code{make distcheck} means that one of
+the scenarios we presented will not work and some users will be
+disappointed. Therefore it is a good practice to release a package
+only after a successful @code{make distcheck}. This of course does
+not imply that the package will be flawless, but at least it will
+prevent some of the embarrassing errors you may find in packages
+released by people who have never heard about @code{distcheck} (like
+@code{DESTDIR} not working because of a typo, or a distributed file
+being erased by @code{make clean}, or even @code{VPATH} builds not
+working).
+
+@xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
+@code{make distcheck}. @xref{Dist}, for more information about
+@code{distcheck}.
+
+@node Dependency Tracking
+@subsection Automatic Dependency Tracking
+@cindex Dependency tracking
+
+Dependency tracking is performed as a side-effect of compilation.
+Each time the build system compiles a source file, it computes its
+list of dependencies (in C these are the header files included by the
+source being compiled). Later, any time @command{make} is run and a
+dependency appears to have changed, the dependent files will be
+rebuilt.
+
+When @command{configure} is executed, you can see it probing each
+compiler for the dependency mechanism it supports (several mechanisms
+can be used):
+
+@example
+~/amhello-1.0 % @kbd{./configure --prefix /usr}
+@dots{}
+checking dependency style of gcc... gcc3
+@dots{}
+@end example
+
+Because dependencies are only computed as a side-effect of the
+compilation, no dependency information exists the first time a package
+is built. This is OK because all the files need to be built anyway:
+@code{make} does not have to decide which files need to be rebuilt.
+In fact, dependency tracking is completely useless for one-time builds
+and there is a @command{configure} option to disable this:
+
+@table @option
+@item --disable-dependency-tracking
+@opindex --disable-dependency-tracking
+Speed up one-time builds.
+@end table
+
+Some compilers do not offer any practical way to derive the list of
+dependencies as a side-effect of the compilation, requiring a separate
+run (maybe of another tool) to compute these dependencies. The
+performance penalty implied my these methods is important enough to
+disable them by default. The option @option{--enable-dependency-tracking}
+must be passed to @command{configure} to activate them.
+
+@table @option
+@item --enable-dependency-tracking
+@opindex --enable-dependency-tracking
+Do not reject slow dependency extractors.
+@end table
+
+@xref{Dependency Tracking Evolution}, for some discussion about the
+different dependency tracking schemes used by Automake over the years.
+
+@node Nested Packages
+@subsection Nested Packages
+@cindex Nested packages
+@cindex Packages, nested
+@cindex Subpackages
+
+Although nesting packages isn't something we would recommend to
+someone who is discovering the Autotools, it is a nice feature worthy
+of mention in this small advertising tour.
+
+Autoconfiscated packages (that means packages whose build system have
+been created by Autoconf and friends) can be nested to arbitrary
+depth.
+
+A typical setup is that a package A will distribute one of the library
+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 package like this. GCC is a heavy
+user of this feature. This gives installers a single package to
+configure, build and install, while it allows developers to work on
+subpackages independently.
+
+When configuring nested packages, the @command{configure} options
+given to the top-level @command{configure} are passed recursively to
+nested @command{configure}s. A package that does not understand an
+option will ignore it, assuming it is meaningful to some other
+package.
+
+@opindex --help=recursive
+
+The command @code{configure --help=recursive} can be used to display
+the options supported by all the included packages.
+
+@xref{Subpackages}, for an example setup.
+
+@node Why Autotools
+@section How Autotools Help
+@cindex Autotools, purpose
+
+There are several reasons why you may not want to implement the GNU
+Build System yourself (read: write a @file{configure} script and
+@file{Makefile}s yourself).
+
+@itemize @bullet
+@item
+As we have seen, the GNU Build System has a lot of
+features (@pxref{Use Cases}).
+Some users may expect features you have not implemented because
+you did not need them.
+@item
+Implementing these features portably is difficult and exhausting.
+Think of writing portable shell scripts, and portable
+@file{Makefile}s, for systems you may not have handy. @xref{Portable
+Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
+convince yourself.
+@item
+You will have to upgrade your setup to follow changes to the GNU
+Coding Standards.
+@end itemize
+
+The GNU Autotools take all this burden off your back and provide:
+
+@itemize @bullet
+@item
+Tools to create a portable, complete, and self-contained GNU Build
+System, from simple instructions.
+@emph{Self-contained} meaning the resulting build system does not
+require the GNU Autotools.
+@item
+A central place where fixes and improvements are made:
+a bug-fix for a portability issue will benefit every package.
+@end itemize
+
+Yet there also exist reasons why you may want NOT to use the
+Autotools@enddots{} For instance you may be already using (or used to)
+another incompatible build system. Autotools will only be useful if
+you do accept the concepts of GNU Build System. People who have their
+own idea of how a build system should work will feel frustrated by the
+Autotools.
+
+@node Hello World
+@section A Small Hello World
+@cindex Example Hello World
+@cindex Hello World example
+@cindex @file{amhello-1.0.tar.gz}, creation
+
+In this section we recreate the @file{amhello-1.0} package from
+scratch. The first subsection shows how to call the Autotools to
+instantiate the GNU Build System, while the second explains the
+meaning of the @file{configure.ac} and @file{Makefile.am} files read
+by the Autotools.
+
+@menu
+* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
+* amhello Explained:: @file{configure.ac} and @file{Makefile.am}
explained
+@end menu
+
+@node Creating amhello
+@subsection Creating @file{amhello-1.0.tar.gz}
+
+Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
+The package is simple enough so that we will only need to write 5
+files. (You may copy them from the final @file{amhello-1.0.tar.gz}
+that is distributed with Automake if you do not want to write them.)
+
+Create the following files in an empty directory.
+
+@itemize @bullet
+
+@item
+@file{src/main.c} is the source file for the @file{hello} program. We
+store it in the @file{src/} subdirectory, because later, when the package
+evolves, it will ease the addition of a @file{man/} directory for man
+pages, a @file{data/} directory for data files, etc.
+@example
+~/amhello % @kbd{cat src/main.c}
+#include <config.h>
+#include <stdio.h>
+
+int
+main (void)
+@{
+ puts ("Hello World!");
+ puts ("This is " PACKAGE_STRING ".");
+ return 0;
+@}
+@end example
+
+@item
+@file{README} contains some very limited documentation for our little
+package.
+@example
+~/amhello % @kbd{cat README}
+This is a demonstration package for GNU Automake.
+Type `info Automake' to read the Automake manual.
+@end example
+
+@item
+@file{Makefile.am} and @file{src/Makefile.am} contain Automake
+instructions for these two directories.
+
+@example
+~/amhello % @kbd{cat src/Makefile.am}
+bin_PROGRAMS = hello
+hello_SOURCES = main.c
+~/amhello % @kbd{cat Makefile.am}
+SUBDIRS = src
+dist_doc_DATA = README
+@end example
+
+@item
+Finally, @file{configure.ac} contains Autoconf instructions to
+create the @command{configure} script.
+
+@example
+~/amhello % @kbd{cat configure.ac}
+AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign])
+AC_PROG_CC
+AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_FILES([
+ Makefile
+ src/Makefile
+])
+AC_OUTPUT
+@end example
+@end itemize
+
+@cindex @command{autoreconf}, example
+
+Once you have these five files, it is time to run the Autotools to
+instantiate the build system. Do this using the @command{autoreconf}
+command as follows:
+
+@example
+~/amhello % @kbd{autoreconf --install}
+configure.ac: installing `./install-sh'
+configure.ac: installing `./missing'
+src/Makefile.am: installing `./depcomp'
+@end example
+
+At this point the build system is complete.
+
+In addition to the three scripts mentioned in its output, you can see
+that @command{autoreconf} created four other files: @file{configure},
+@file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
+The latter three files are templates that will be adapted to the
+system by @command{configure} under the names @file{config.h},
+@file{Makefile}, and @file{src/Makefile}. Let's do this:
+
+@example
+~/amhello % @kbd{./configure}
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking for gawk... no
+checking for mawk... mawk
+checking whether make sets $(MAKE)... yes
+checking for gcc... gcc
+checking for C compiler default output file name... a.out
+checking whether the C compiler works... yes
+checking whether we are cross compiling... no
+checking for suffix of executables...
+checking for suffix of object files... o
+checking whether we are using the GNU C compiler... yes
+checking whether gcc accepts -g... yes
+checking for gcc option to accept ISO C89... none needed
+checking for style of include used by make... GNU
+checking dependency style of gcc... gcc3
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: creating src/Makefile
+config.status: creating config.h
+config.status: executing depfiles commands
+@end example
+
+@trindex distcheck
+@cindex @code{distcheck} example
+
+You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
+being created at the end after @command{configure} has probed the
+system. It is now possible to run all the targets we wish
+(@pxref{Standard Targets}). For instance:
+
+@example
+~/amhello % @kbd{make}
+@dots{}
+~/amhello % @kbd{src/hello}
+Hello World!
+This is amhello 1.0.
+~/amhello % @kbd{make distcheck}
+@dots{}
+=============================================
+amhello-1.0 archives ready for distribution:
+amhello-1.0.tar.gz
+=============================================
+@end example
+
+Note that running @command{autoreconf} is only needed initially when
+the GNU Build System does not exist. When you later change some
+instructions in a @file{Makefile.am} or @file{configure.ac}, the
+relevant part of the build system will be regenerated automatically
+when you execute @command{make}.
+
+@command{autoreconf} is a script that calls @command{autoconf},
+@command{automake}, and a bunch of other commands in the right order.
+If you are beginning with these tools, it is not important to figure
+out in which order all 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
+@command{automake} is in charge of creating @file{Makefile.in}s from
+@file{Makefile.am}s and @file{configure.ac}. This should at least
+direct you to the correct manual when seeking answers.
+
+
+@node amhello Explained
+@subsection @file{amhello-1.0} Explained
+
+Let us begin with the contents of @file{configure.ac}.
+
+@example
+AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign])
+AC_PROG_CC
+AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_FILES([
+ Makefile
+ src/Makefile
+])
+AC_OUTPUT
+@end example
+
+This file is read by both @command{autoconf} (to create
+@file{configure.ac}) and @command{automake} (to create the various
+@file{Makefile.in}s). It contains a series of M4 macros that will be
+expanded as shell code to finally form the @file{configure} script.
+We will not elaborate on the syntax of this file, because the Autoconf
+manual has a whole section about it (@pxref{Writing configure.ac, ,
+Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
+
+The macros prefixed with @code{AC_} are Autoconf macros, documented
+in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
+Index, autoconf, The Autoconf Manual}). The macros that start with
+@code{AM_} are Automake macros, documented later in this manual
+(@pxref{Macro Index}).
+
+The first two lines of @file{configure.ac} initialize Autoconf and
+Automake. @code{AC_INIT} takes in parameters the name of the package,
+its version number, and a contact address for bug-reports about the
+package (this address is output at the end of @code{./configure
+--help}, for instance). When adapting this setup to your own package,
+by all means please do not blindly copy Automake's address: use the
+mailing list of your package, or your own mail address.
+
+@opindex -Wall
+@opindex -Werror
+@opindex foreign
+
+The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
+@command{automake} (@pxref{Options}). @option{-Wall} and
+@option{-Werror} ask @command{automake} to turn on all warnings and
+report them as errors. We are speaking of @strong{Automake} warnings
+here, such as dubious instructions in @file{Makefile.am}. This has
+absolutely nothing to do with how the compiler will be called, even
+though it may support options with similar names. Using @option{-Wall
+-Werror} is a safe setting when starting to work on a package: you do
+not want to miss any issues. Later you may decide to relax things a
+bit. The @option{foreign} option tells Automake that this package
+will not follow the GNU Standards. GNU packages should always
+distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
+etc. We do not want @command{automake} to complain about these
+missing files in our small example.
+
+The @code{AC_PROG_CC} line causes the @command{configure} script to
+search for a C compiler and define the variable @code{CC} with its
+name. The @file{src/Makefile.in} file generated by Automake uses the
+variable @code{CC} to build @file{hello}, so when @command{configure}
+creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
+@code{CC} with the value it has found. If Automake is asked to create
+a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
+not define it, it will suggest you add a call to @code{AC_PROG_CC}.
+
+The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
+@command{configure} script to create a @file{config.h} file gathering
+@samp{#define}s defined by other macros in @file{configure.ac}. In our
+case, the @code{AC_INIT} macro already defined a few of them. Here
+is an excerpt of @file{config.h} after @command{configure} has run:
+
+@smallexample
+@dots{}
+/* Define to the address where bug reports for this package should be sent. */
+#define PACKAGE_BUGREPORT "bug-automake@@gnu.org"
+
+/* Define to the full name and version of this package. */
+#define PACKAGE_STRING "amhello 1.0"
+@dots{}
+@end smallexample
+
+As you probably noticed, @file{src/main.c} includes @file{config.h} so
+it can use @code{PACKAGE_STRING}. In a real work project,
+@file{config.h} can grow really big, with one @samp{#define} per
+feature probed on the system.
+
+The @code{AC_CONFIG_FILES} macro declares the list of files that
+@command{configure} should create from their @file{*.in} template.
+Automake also scans this list to find the @file{Makefile.am} it must
+process. (This is important to remember: when adding a new directory
+to your project, you should add its @file{Makefile} to this list,
+otherwise Automake will never process the new @file{Makefile.am} you
+wrote in that directory.)
+
+Finally, the @code{AC_OUTPUT} line is a closing command that actually
+produces the part of the script in charge of creating the files
+registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
+
+@cindex @command{autoscan}
+
+When starting a new project, we suggest you start with such a simple
+@file{configure.ac}, and gradually add the other tests it requires.
+The command @command{autoscan} can also suggest a few of the tests
+your package may need (@pxref{autoscan Invocation, , Using
+@command{autoscan} to Create @file{configure.ac}, autoconf, The
+Autoconf Manual}).
+
+@cindex @file{Makefile.am}, Hello World
+
+We now turn to @file{src/Makefile.am}. This file contains
+Automake instructions to build and install @file{hello}.
+
+@example
+bin_PROGRAMS = hello
+hello_SOURCES = main.c
+@end example
+
+A @file{Makefile.am} has the same syntax as an ordinary
+@file{Makefile}. When @command{automake} processes a
+@file{Makefile.am} it copies the entire file into the output
+@file{Makefile.in} (that will be later turned into @file{Makefile} by
+@command{configure}) but will react to certain variable definitions
+by generating some build rules and other variables.
+Often @file{Makefile.am}s contain only a list of variable definitions as
+above, but it can also contain other variable and rule definitions that
+@command{automake} will pass along without interpretation.
+
+Variables that end with @code{_PROGRAMS} are special variables
+that list programs that the resulting @file{Makefile} should build.
+In Automake speak, this @code{_PROGRAMS} suffix is called a
+@dfn{primary}; Automake recognizes other primaries such as
+@code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc. corresponding
+to different types of files.
+
+The @samp{bin} part of the @code{bin_PROGRAMS} tells
+@command{automake} that the resulting programs should be installed in
+@var{bindir}. Recall that the GNU Build System uses a set of variables
+to denote destination directories and allow users to customize these
+locations (@pxref{Standard Directory Variables}). Any such directory
+variable can be put in front of a primary (omitting the @code{dir}
+suffix) to tell @command{automake} where to install the listed files.
+
+Programs need to be built from source files, so for each program
+@code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
+@command{automake} will look for another variable named
+@code{@var{prog}_SOURCES} listing its source files. There may be more
+than one source file: they will all be compiled and linked together.
+
+Automake also knows that source files need to be distributed when
+creating a tarball (unlike built programs). So a side-effect of this
+@code{hello_SOURCES} declaration is that @file{main.c} will be
+part of the tarball created by @code{make dist}.
+
+Finally here are some explanations regarding the top-level
+@file{Makefile.am}.
+
+@example
+SUBDIRS = src
+dist_doc_DATA = README
+@end example
+
+@code{SUBDIRS} is a special variable listing all directories that
+@command{make} should recurse into before processing the current
+directory. So this line is responsible for @command{make} building
+@file{src/hello} even though we run it from the top-level. This line
+also causes @code{make install} to install @file{src/hello} before
+installing @file{README} (not that this order matters).
+
+The line @code{dist_doc_DATA = README} causes @file{README} to be
+distributed and installed in @var{docdir}. Files listed with the
+@code{_DATA} primary are not automatically part of the tarball built
+with @code{make dist}, so we add the @code{dist_} prefix so they get
+distributed. However, for @file{README} it would not have been
+necessary: @command{automake} automatically distributes any
+@file{README} file it encounters (the list of other files
+automatically distributed is presented by @code{automake --help}).
+The only important effect of this second line is therefore to install
+@file{README} during @code{make install}.
+

@node Generalities
@chapter General ideas
@@ -733,7 +2070,8 @@
@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.
+that is then used by the automatic dependency tracking feature
+(@pxref{Dependencies}).

@item elisp-comp
This program is used to byte-compile Emacs Lisp code.
@@ -5218,7 +6556,7 @@
As a developer it is often painful to continually update the
@file{Makefile.in} whenever the include-file dependencies change in a
project. Automake supplies a way to automatically track dependency
-changes.
+changes (@pxref{Dependency Tracking}).

@cindex Dependency tracking
@cindex Automatic dependency tracking
@@ -6472,14 +7810,16 @@
would install @file{/tmp/staging/gnu/bin/foo} and
@file{/tmp/staging/gnu/share/aclocal/foo.m4}.

-This feature is commonly used to build install images and packages. For
-more information, see @ref{Makefile Conventions, , , standards, The GNU
-Coding Standards}.
-
-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}.
+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}.
+
+@xref{Makefile Conventions, , , standards, The GNU Coding Standards},
+for another usage example.

@section Rules for the user

@@ -6703,11 +8043,11 @@
@vindex distuninstallcheck_listfiles

@trindex distcheck
-Automake also generates a @code{distcheck} rule that can be of help
-to ensure that a given distribution will actually work.
-@code{distcheck} makes a distribution, then tries to do a @code{VPATH}
-build, run the test suite, and finally make another tarball to ensure the
-distribution is self-contained.
+Automake also generates a @code{distcheck} rule that can be of help to
+ensure that a given distribution will actually work. @code{distcheck}
+makes a distribution, then tries to do a @code{VPATH} build
+(@pxref{VPATH Builds}), run the test suite, and finally make another
+tarball to ensure the distribution is self-contained.

@vindex DISTCHECK_CONFIGURE_FLAGS
Building the package involves running @samp{./configure}. If you need
@@ -8047,17 +9387,17 @@
@end example

Another aspect of integrating third-party build systems is whether
-they support 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 @samp{make
-distcheck}). Other people may prefer to revamp the existing
-@file{Makefile}s to support VPATH@. Doing so does not necessarily
-require Automake, only Autoconf is needed (@pxref{Build Directories, ,
-Build Directories, autoconf, The Autoconf Manual}). The necessary
-substitutions: @samp{@@scrdir@@}, @samp{@@top_srcdir@@}, and
-@samp{@@top_builddir@@} are defined by @file{configure} when it
+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
+@samp{make distcheck}). Other people may prefer to revamp the
+existing @file{Makefile}s to support VPATH@. Doing so does not
+necessarily require Automake, only Autoconf is needed (@pxref{Build
+Directories, , Build Directories, autoconf, The Autoconf Manual}).
+The necessary substitutions: @samp{@@scrdir@@}, @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
@@ -8678,9 +10018,9 @@
and check your package for errors like this one.

@samp{make distcheck} will perform a @code{VPATH} build of your
-package, and then call @samp{make distclean}. Files left in the build
-directory after @samp{make distclean} has run are listed after this
-error.
+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:

@@ -10177,7 +11517,7 @@
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 that two years, it hurt users.
+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.
@@ -10272,7 +11612,7 @@
The most striking update is probably that of @command{aclocal}.

@command{aclocal} now uses @code{m4_include} in the produced
-@code{aclocal.m4} when the included macros are already distributed
+@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}
@@ -10789,4 +12129,4 @@
@c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
@c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
@c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
-@c LocalWords: barexec Pinard's
+@c LocalWords: barexec Pinard's automatize initialize
Index: doc/amhello/Makefile.am
===================================================================
RCS file: doc/amhello/Makefile.am
diff -N doc/amhello/Makefile.am
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/amhello/Makefile.am 16 Aug 2006 17:07:48 -0000
@@ -0,0 +1,6 @@
+## Copyright (C) 2006 Free Software Foundation, Inc.
+## This Makefile.am is free software; the Free Software Foundation
+## gives unlimited permission to copy, distribute and modify it.
+
+SUBDIRS = src
+dist_doc_DATA = README
Index: doc/amhello/README
===================================================================
RCS file: doc/amhello/README
diff -N doc/amhello/README
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/amhello/README 16 Aug 2006 17:07:48 -0000
@@ -0,0 +1,2 @@
+This is a demonstration package for GNU Automake.
+Type `info Automake' to read the Automake manual.
Index: doc/amhello/configure.ac
===================================================================
RCS file: doc/amhello/configure.ac
diff -N doc/amhello/configure.ac
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/amhello/configure.ac 16 Aug 2006 17:07:48 -0000
@@ -0,0 +1,13 @@
+# Copyright (C) 2006 Free Software Foundation, Inc.
+# This configure.ac script is free software; the Free Software Foundation
+# gives unlimited permission to copy, distribute and modify it.
+
+AC_INIT([amhello], [1.0], [bug-automake@xxxxxxx])
+AM_INIT_AUTOMAKE([-Wall -Werror foreign])
+AC_PROG_CC
+AC_CONFIG_HEADERS([config.h])
+AC_CONFIG_FILES([
+ Makefile
+ src/Makefile
+])
+AC_OUTPUT
Index: doc/amhello/src/Makefile.am
===================================================================
RCS file: doc/amhello/src/Makefile.am
diff -N doc/amhello/src/Makefile.am
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/amhello/src/Makefile.am 16 Aug 2006 17:07:48 -0000
@@ -0,0 +1,6 @@
+## Copyright (C) 2006 Free Software Foundation, Inc.
+## This Makefile.am is free software; the Free Software Foundation
+## gives unlimited permission to copy, distribute and modify it.
+
+bin_PROGRAMS = hello
+hello_SOURCES = main.c
Index: doc/amhello/src/main.c
===================================================================
RCS file: doc/amhello/src/main.c
diff -N doc/amhello/src/main.c
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/amhello/src/main.c 16 Aug 2006 17:07:48 -0000
@@ -0,0 +1,14 @@
+/* Copyright (C) 2006 Free Software Foundation, Inc.
+ This program is free software; the Free Software Foundation
+ gives unlimited permission to copy, distribute and modify it. */
+
+#include <config.h>
+#include <stdio.h>
+
+int
+main (void)
+{
+ puts ("Hello World!");
+ puts ("This is " PACKAGE_STRING ".");
+ return 0;
+}

--
Alexandre Duret-Lutz

Shared books are happy books. http://www.bookcrossing.com/friend/gadl