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