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.