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_SUBST s 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
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
- 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.
- 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
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
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
`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.