8. Bootstrapping
There are many programs in the GNU Autotools, each of which has a complex
set of inputs. When one of these inputs changes, it is important to run
the proper programs in the proper order. Unfortunately, it is hard to
remember both the dependencies and the ordering.
For instance, whenever you edit `configure.in', you must remember
to re-run aclocal in case you added a reference to a new macro.
You must also rebuild `configure' by running autoconf;
`config.h' by running autoheader, in case you added a new
AC_DEFINE; and automake to propagate any new
AC_SUBSTs to the various `Makefile.in's. If you edit a
`Makefile.am', you must re-run automake. In both these
cases, you must then remember to re-run config.status --recheck
if `configure' changed, followed by config.status to rebuild
the `Makefile's.
When doing active development on the build system for your project,
these dependencies quickly become painful. Of course, Automake knows
how to handle this automatically. By default, automake
generates a `Makefile.in' which knows all these dependencies and
which automatically re-runs the appropriate tools in the appropriate
order. These rules assume that the correct versions of the tools are
all in your PATH.
It helps to have a script ready to do all of this for you once, before
you have generated a `Makefile' that will automatically run the
tools in the correct order, or when you make a fresh checkout of the
code from a CVS repository where the developers don't keep
generated files under source control. There are at least two opposing
schools of thought regarding how to go about this -- the
autogen.sh school and the bootstrap school:
autogen.sh
- From the outset, this is a poor name for a bootstrap script, since there
is already a GNU automatic text generation tool called AutoGen.
Often packages that follow this convention have the script automatically
run the generated
configure script after the boostrap process,
passing autogen.sh arguments through to configure.
Except you don't know what options you want yet, since you can't run
`configure --help' until configure has been generated. I
suggest that if you find yourself compiling a project set up in this way
that you type:
| |
$ /bin/sh ./autogen.sh --help
|
and ignore the spurious warning that tells you configure will
be executed.
bootstrap
- Increasingly, projects are starting to call their bootstrap scripts
`bootstrap'. Such scripts simply run the various commands required
to bring the source tree into a state where the end user can simply:
| |
$ configure
$ make
$ make install
|
Unfortunately, proponents of this school of thought don't put the
bootstrap script in their distributed tarballs, since the script is
unnecessary except when the build environment of a developer's machine
has changed. This means the proponents of the autogen.sh school may
never see the advantages of the other method.
Autoconf comes with a program called autoreconf which essentially
does the work of the bootstrap script. autoreconf is
rarely used because, historically, has not been very well known, and only
in Autoconf 2.13 did it acquire the ability to work with Automake.
Unfortunately, even the Autoconf 2.13 autoreconf does not handle
libtoolize and some automake-related options that are
frequently nice to use.
We recommend the bootstrap method, until autoreconf is
fixed. At this point bootstrap has not been standardized, so
here is a version of the script we used while writing this book
(3):
| |
#! /bin/sh
aclocal \
&& automake --gnu --add-missing \
&& autoconf
|
We don't use autoreconf here because that script (as of Autoconf
2.13) also does not handle the `--add-missing' option, which we
want. A typical bootstrap might also run libtoolize or
autoheader.
It is also important for all developers on a project to have the same
versions of the tools installed so that these rules don't inadvertantly
cause problems due to differences between tool versions. This version
skew problem turns out to be fairly significant in the field. So,
automake provides a way to disable these rules by default,
while still allowing users to enable them when they know their
environment is set up correctly.
In order to enable this mode, you must first add
AM_MAINTAINER_MODE to
`configure.in'. This will add the
`--enable-maintainer-mode' option to `configure'; when
specified this flag will cause these so-called `maintainer rules' to
be enabled.
Note that maintainer mode is a controversial feature. Some people like
to use it because it causes fewer bug reports in some situations. For
instance, CVS does not preserve relative timestamps on
files. If your project has both `configure.in' and
`configure' checked in, and maintainer mode is not in use, then
sometimes make will decide to rebuild `configure' even
though it is not really required. This in turn means more headaches for
your developers -- on a large project most developers won't touch
`configure.in' and many may not even want to install the GNU Autotools
(4).
The other camp claims that end users should use the same build system
that developers use, that maintainer mode is simply unaesthetic, and
furthermore that the modality of maintainer mode is dangerous--you can
easily forget what mode you are in and thus forget to rebuild, and thus
correctly test, a change to the configure or build system. When
maintainer mode is not in use, the Automake-supplied missing
script will be used to warn users when it appears that they need a
maintainer tool that they do not have.
The approach you take depends strongly on the social structures
surrounding your project.
| 
