Autoconf, Automake, and Libtool: Bootstrapping

  | # 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_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 `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 bootstrap 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 inadvertently 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.

This document was generated by Gary V. Vaughan on February, 8 2006 using texi2html