automake-1.16: maintainer-mode
26.2 ‘missing’ and ‘AM_MAINTAINER_MODE’
=======================================
‘missing’
---------
The ‘missing’ script is a wrapper around several maintainer tools,
designed to warn users if a maintainer tool is required but missing.
Typical maintainer tools are ‘autoconf’, ‘automake’, ‘bison’, etc.
Because files generated by these tools are shipped with the other
sources of a package, these tools shouldn’t be required during a user
build and they are not checked for in ‘configure’.
However, if for some reason a rebuild rule is triggered and involves
a missing tool, ‘missing’ will notice it and warn the user, even
suggesting how to obtain such a tool (at least in case it is a
well-known one, like ‘makeinfo’ or ‘bison’). This is more helpful and
user-friendly than just having the rebuild rules spewing out a terse
error message like ‘sh: TOOL: command not found’. Similarly, ‘missing’
will warn the user if it detects that a maintainer tool it attempted to
use seems too old (be warned that diagnosing this correctly is typically
more difficult than detecting missing tools, and requires cooperation
from the tool itself, so it won’t always work).
If the required tool is installed, ‘missing’ will run it and won’t
attempt to continue after failures. This is correct behavior during
development: developers love fixing failures. However, users with
missing or too old maintainer tools may get an error when the rebuild
rule is spuriously triggered, halting the build. This failure to let
the build continue is one of the arguments of the ‘AM_MAINTAINER_MODE’
advocates.
‘AM_MAINTAINER_MODE’
--------------------
‘AM_MAINTAINER_MODE’ allows you to choose whether the so called "rebuild
rules" should be enabled or disabled. With
‘AM_MAINTAINER_MODE([enable])’, they are enabled by default; otherwise
they are disabled by default. In the latter case, if you have
‘AM_MAINTAINER_MODE’ in ‘configure.ac’, and run ‘./configure && make’,
then ‘make’ will *never* attempt to rebuild ‘configure’, ‘Makefile.in’s,
Lex or Yacc outputs, etc. That is, this disables build rules for files
that are usually distributed and that users should normally not have to
update.
The user can override the default setting by passing either
‘--enable-maintainer-mode’ or ‘--disable-maintainer-mode’ to
‘configure’.
People use ‘AM_MAINTAINER_MODE’ either because they do not want their
users (or themselves) annoyed by timestamp lossage (⇒CVS), or
because they simply can’t stand the rebuild rules and prefer running
maintainer tools explicitly.
‘AM_MAINTAINER_MODE’ also allows you to disable some custom build
rules conditionally. Some developers use this feature to disable rules
that need exotic tools that users may not have available.
Several years ago François Pinard pointed out several arguments
against this ‘AM_MAINTAINER_MODE’ macro. Most of them relate to
insecurity. By removing dependencies you get non-dependable builds:
changes to source files can have no effect on generated files and this
can be very confusing when unnoticed. He adds that security shouldn’t
be reserved to maintainers (what ‘--enable-maintainer-mode’ suggests),
on the contrary. If one user has to modify a ‘Makefile.am’, then either
‘Makefile.in’ should be updated or a warning should be output (this is
what Automake uses ‘missing’ for) but the last thing you want is that
nothing happens and the user doesn’t notice it (this is what happens
when rebuild rules are disabled by ‘AM_MAINTAINER_MODE’).
Jim Meyering, the inventor of the ‘AM_MAINTAINER_MODE’ macro, was
swayed by François’ arguments, and got rid of ‘AM_MAINTAINER_MODE’ in
all of his packages.
Still many people continue to use ‘AM_MAINTAINER_MODE’, because it
helps them working on projects where all files are kept under version
control, and because ‘missing’ isn’t enough if you have the wrong
version of the tools.