5. Maintainer mode and the missing script

It is common, both during the development of a project, or during the packaging phase, to edit the source files of the build system, configure.ac, Makefile.am and so on. Depending on which files are modified, it is possible that one or more tools of the Autotools stack need to be executed to produce a new build system, or part of it.

To facilitate the work of both developers and users, automake makes available what is called maintainer mode, a set of rules that regenerate the build system out of its source files, when the modification times no longer match. So if you edit Makefile.am, automake will run, and then ./config.status will recheck Makefile.in to produce the final Makefile.

At the centre of these rules is the missing script, which is usually copied over when generating the build system. This script is designed to check for the presence of, and execute, a given tool. When this fails, because the tool is not present, or for other reasons not compatible, it will warn the user, and mangle the timestamps, as if the tool did its job.

The tool has, of course, limitations; if a tool is missing, which is required to build either an intermediary, or final target which is not already present in the source tree, the build cannot proceed. Another limitation is that, while it does not limit itself to the Autotools stack proper, it only includes support for a handful of tools, and it's not possible to extend it above and beyond those without implementing it in a new version of Automake.

The missing script has been designed to work for source trees where the generated build system is wholly committed to a source control manager, or, conversely, on source trees coming from a distribution tarball where all the files have been already generated once. As committing generated files is generally not recommended, the second case is the one covered in this guide.

As mentioned earlier, by default, generated Makefile will include rules that execute autoconf and automake through missing is either of their source file has a later modification time than their output. Another common situation is to use it with help2man: a man page is generated when creating the distribution; users who have the tool installed can ensure it is kept up-to-date with the command itself, but at the same time those without the tool installed will not be stopped because of the make rule.

5.1. Execution of ./configure

When configure.ac is modified, and the maintainer mode rules cause a regeneration of the configure script, they also need to execute it, to make sure that the changes take effect, this is achieved through the ./config.status --recheck command. Usually, this also leads to the re-execution of a number of other tools including automake.

The parameters passed to the original ./configure call are cached in the generated Makefile and are used again, together with any variable that was marked as precious (see Section 3.3, “Environment Variables as Arguments”).

If configure.ac is untouched, but the files that are substituted at the end of ./configure changed (by themselves, or because of automake), a faster ./config.status command is executed instead. This will re-generate the files that go through the final substitution without executing all the previous checks.

5.2. Disabling maintainer mode

While this configuration works out quite well to protect against clock skews on pristine, properly generated source archives, often times it leads to unexpected behaviour when the archive is not generated through make dist, as there is no guarantee that the generated build system is up to date with its sources.

A similar problem happens to distributions' packagers: if a patch is applied that modifies the build system, you need to ensure that it gets regenerated fully. Simply relying on maintainer mode does not always fit the process, as the wrong version of automake might be present, causing the missing script to just touch the files, without regenerating them. Even when explicitly running the Autotools stack, there has been corner cases where maintainer mode got in the way, mainly due to timestamp skew.

A macro called AM_MAINTAINER_MODE exists that controls the behaviour of the self-regenerating rules. If no call to the macro is present, maintainer mode is enabled, and it's not possible to disable it at the configuration time. If a call is present without any parameter, maintainer mode is disabled by default and can be re-enabled with ./configure --enable-maintainer-mode.

The suggested call would be like in the following example, as that enables maintainer mode by default (which does the right thing for developers, and for power users), but allows packaging software to disable the automatic rules, which would only be hindering the process.

Example 2.8. Suggested configuration for automake maintainer mode