General ideas

There are a few basic ideas that will help understand how Automake works.

General Operation

Automake works by reading a `Makefile.am' and generating a `Makefile.in'. Certain macros and targets defined in the `Makefile.am' instruct automake to generate more specialized code; for instances a `bin_PROGRAMS' macro definition will cause targets for compiling and linking to be generated.

The macro definitions and targets in the `Makefile.am' are copied into the generated file. This allows you to add arbitrary code into the generated `Makefile.in'. For instance the Automake distribution includes a non-standard cvs-dist target, which the Automake maintainer uses to make distributions from his source control system.

Note that GNU make extensions are not recognized by Automake. Using such extensions in a `Makefile.am' will lead to errors or confusing behavior.

Automake tries to group comments with adjoining targets (or variable definitions) in an intelligent way.

A target defined in `Makefile.am' generally overrides any such target 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' will override any definition of the variable that automake would ordinarily create. This feature is more often useful than the ability to override a target definition. 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. E.g., 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 which is not copied into the output; all lines beginning with `##' 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

Depth

automake supports three kinds of directory hierarchy: "flat", "shallow", and "deep".

A flat package is one in which all the files are in a single directory. The `Makefile.am' for such a package by definition lacks a SUBDIRS macro. An example of such a package is termutils.

A deep package is one in which all the source lies in subdirectories; the top level directory contains mainly configuration information. GNU cpio is a good example of such a package, as is GNU tar. The top level `Makefile.am' for a deep package will contain a SUBDIRS macro, but no other macros to define objects which are built.

A shallow package is one in which the primary source resides in the top-level directory, while various parts (typically libraries) reside in subdirectories. Automake is one such package (as is GNU make, which does not currently use automake).

Strictness

While Automake is intended to be used by maintainers of GNU packages, it does make some effort to accommodate those who wish to use it, but do not want to use all the GNU conventions.

To this end, Automake supports three levels of strictness---the strictness indicating how stringently Automake should check standards conformance.

The valid strictness levels are:

`foreign'

Automake will check for only those things which are absolutely required for proper operations. For instance, whereas GNU standards dictate the existence of a `NEWS' file, it will not be required in this mode. The name comes from the fact that Automake is intended to be used for GNU programs; these relaxed rules are not the standard mode of operation.

`gnu'

Automake will check--as much as possible--for compliance to the GNU standards for packages. This is the default.

`gnits'

Automake will check for compliance to the as-yet-unwritten Gnits standards. These are based on the GNU standards, but are even more detailed. Unless you are a Gnits standards contributor, it is recommended that you avoid this option until such time as the Gnits standard is actually published.

For more information on the precise implications of the strictness level, see See section The effect of --gnu and --gnits.

The Uniform Naming Scheme

Automake variables generally follow a uniform naming scheme that makes it easy to decide how programs (and other derived objects) are built, and how they are installed. This scheme also supports configure time determination of what should be built.

At make time, certain variables are used to determine which objects are to be built. These variables are called primary variables. For instance, the primary variable PROGRAMS holds a list of programs which are to be compiled and linked.

A different set of variables is used to decide where the built objects should be installed. These variables are named after the primary variables, but have a prefix indicating which standard directory should be used as the installation directory. The standard directory names are given in the GNU standards (see section `Directory Variables' in The GNU Coding Standards). Automake extends this list with pkglibdir, pkgincludedir, and pkgdatadir; these are the same as the non-`pkg' versions, but with `@PACKAGE@' appended. For instance, pkglibdir is defined as $(datadir)/@PACKAGE@.

For each primary, there is one additional variable named by prepending `EXTRA_' to the primary name. This variable is used to list objects which may or may not be built, depending on what configure decides. This variable is required because Automake must statically know the entire list of objects to be built in order to generate a `Makefile.in' that will work in all cases.

For instance, cpio decides at configure time which programs are built. Some of the programs are installed in bindir, and some are installed in sbindir:

EXTRA_PROGRAMS = mt rmt
bin_PROGRAMS = cpio pax
sbin_PROGRAMS = @PROGRAMS@

Defining a primary variable without a prefix (eg PROGRAMS) is an error.

Note that the common `dir' suffix is left off when constructing the variable names; thus one writes `bin_PROGRAMS' and not `bindir_PROGRAMS'.

Not every sort of object can be installed in every directory. Automake will flag those attempts it finds in error. Automake will also diagnose obvious misspellings in directory names.

Sometimes the standard directories--even as augmented by Automake--- are not enough. In particular it is sometimes useful, for clarity, to install objects in a subdirectory of some predefined directory. To this end, Automake allows you to extend the list of possible installation directories. A given prefix (eg `zar') is valid if a variable of the same name with `dir' appended is defined (eg `zardir').

For instance, until HTML support is part of Automake, you could use this to install raw HTML documentation:

htmldir = $(prefix)/html
html_DATA = automake.html

The special prefix `noinst' indicates that the objects in question should not be installed at all.

The special prefix `check' indicates that the objects in question should not be built until the make check command is run.

Possible primary names are `PROGRAMS', `LIBRARIES', `LISP', `SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'.

How derived variables are named

Sometimes a Makefile variable name is derived from some text the user supplies. For instance program names are rewritten into Makefile macro names. Automake canonicalizes this text, so that it does not have to follow Makefile variable naming rules. All characters in the name except for letters, numbers, and the underscore are turned into underscores when making macro references. E.g., if your program is named sniff-glue, the derived variable name would be sniff_glue_SOURCES, not sniff-glue_SOURCES.

Go to the first, previous, next, last section, table of contents.