automake: General Operation

1 
1 3.1 General Operation
1 =====================
1 
1 Automake works by reading a ‘Makefile.am’ and generating a
1 ‘Makefile.in’.  Certain variables and rules defined in the ‘Makefile.am’
1 instruct Automake to generate more specialized code; for instance, a
1 ‘bin_PROGRAMS’ variable definition will cause rules for compiling and
1 linking programs to be generated.
1 
1    The variable definitions and rules in the ‘Makefile.am’ are copied
1 mostly verbatim into the generated file, with all variable definitions
1 preceding all rules.  This allows you to add almost arbitrary code into
1 the generated ‘Makefile.in’.  For instance, the Automake distribution
1 includes a non-standard rule for the ‘git-dist’ target, which the
1 Automake maintainer uses to make distributions from the source control
1 system.
1 
1    Note that most GNU make extensions are not recognized by Automake.
1 Using such extensions in a ‘Makefile.am’ will lead to errors or
1 confusing behavior.
1 
1    A special exception is that the GNU make append operator, ‘+=’, is
1 supported.  This operator appends its right hand argument to the
1 variable specified on the left.  Automake will translate the operator
1 into an ordinary ‘=’ operator; ‘+=’ will thus work with any make
1 program.
1 
1    Automake tries to keep comments grouped with any adjoining rules or
1 variable definitions.
1 
1    Generally, Automake is not particularly smart in the parsing of
1 unusual Makefile constructs, so you’re advised to avoid fancy constructs
1 or “creative” use of whitespace.  For example, <TAB> characters cannot
1 be used between a target name and the following “‘:’” character, and
1 variable assignments shouldn’t be indented with <TAB> characters.  Also,
1 using more complex macro in target names can cause trouble:
1 
1      % cat Makefile.am
1      $(FOO:=x): bar
1      % automake
1      Makefile.am:1: bad characters in variable name '$(FOO'
1      Makefile.am:1: ':='-style assignments are not portable
1 
1    A rule defined in ‘Makefile.am’ generally overrides any such rule of
1 a similar name that would be automatically generated by ‘automake’.
1 Although this is a supported feature, it is generally best to avoid
1 making use of it, as sometimes the generated rules are very particular.
1 
1    Similarly, a variable defined in ‘Makefile.am’ or ‘AC_SUBST’ed from
1 ‘configure.ac’ will override any definition of the variable that
1 ‘automake’ would ordinarily create.  This feature is more often useful
1 than the ability to override a rule.  Be warned that many of the
1 variables generated by ‘automake’ are considered to be for internal use
1 only, and their names might change in future releases.
1 
1    When examining a variable definition, Automake will recursively
1 examine variables referenced in the definition.  For example, if
1 Automake is looking at the content of ‘foo_SOURCES’ in this snippet
1 
1      xs = a.c b.c
1      foo_SOURCES = c.c $(xs)
1 
1    it would use the files ‘a.c’, ‘b.c’, and ‘c.c’ as the contents of
1 ‘foo_SOURCES’.
1 
1    Automake also allows a form of comment that is _not_ copied into the
1 output; all lines beginning with ‘##’ (leading spaces allowed) are
1 completely ignored by Automake.
1 
1    It is customary to make the first line of ‘Makefile.am’ read:
1 
1      ## Process this file with automake to produce Makefile.in
1