7.1 General Automake principles

Automake at its simplest turns a file called ‘Makefile.am’ into a GNU-compliant ‘Makefile.in’ for use with ‘configure’. Each ‘Makefile.am’ is written according to make syntax; Automake recognizes special macro and target names and generates code based on these.

There are a few Automake rules which differ slightly from make rules:

• Ordinary make comments are passed through to the output, but comments beginning with ‘##’ are Automake comments and are not passed through.
• Automake supports include directives. These directives are not passed through to the ‘Makefile.in’, but instead are processed by automake – files included this way are treated as if they were textually included in ‘Makefile.am’ at that point. This can be used to add boilerplate to each ‘Makefile.am’ in a project via a centrally-maintained file. The filename to include can start with ‘$(top_srcdir)’ to indicate that it should be found relative to the top-most directory of the project; if it is a relative path or if it starts with ‘$(srcdir)’ then it is relative to the current directory. For example, here is how you would reference boilerplate code from the file ‘config/Make-rules’ (where ‘config’ is a top-level directory in the project):

  include $(top_srcdir)/config/Make-rules

• Automake supports conditionals which are not passed directly through to ‘Makefile.in’. This feature is discussed in Advanced GNU Automake Usage.
• Automake supports macro assignment using ‘+=’; these assignments are translated by Automake into ordinary ‘=’ assignments in ‘Makefile.in’.

All macros and targets, including those which Automake does not recognize, are passed through to the generated ‘Makefile.in’ – this is a powerful extension mechanism. Sometimes Automake will define macros or targets internally. If these are also defined in ‘Makefile.am’ then the definition in ‘Makefile.am’ takes precedence. This feature provides an easy way to tailor specific parts of the output in small ways.

Note, however, that it is a mistake to override parts of the generated code that aren’t documented (and thus ‘exported’ by Automake). Overrides like this stand a good chance of not working with future Automake releases.

Automake also scans ‘configure.in’. Sometimes it uses the information it discovers to generate extra code, and sometimes to provide extra error checking. Automake also turns every AC_SUBST into a ‘Makefile’ variable. This is convenient in more ways than one: not only does it mean that you can refer to these macros in ‘Makefile.am’ without extra work, but, since Automake scans ‘configure.in’ before it reads any ‘Makefile.am’, it also means that special variables and overrides Automake recognizes can be defined once in ‘configure.in’.

This document was generated by Ben Elliston on July 10, 2015 using texi2html 1.82.