Autoconf, Automake, and Libtool: General Automake principles

- | ## 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 19. 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 Gary V. Vaughan on February, 8 2006 using texi2html