automake: maintainer-mode

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