2. General ideas

The following sections cover a few basic ideas that will help you understand how Automake works.

2.1 General Operation		General operation of Automake
2.2 Strictness		Standards conformance checking
2.3 The Uniform Naming Scheme
2.4 How derived variables are named
2.5 Variables reserved for the user
2.6 Programs automake might require

2.1 General Operation

Automake works by reading a `Makefile.am' and generating a `Makefile.in'. Certain variables and targets defined in the `Makefile.am' instruct Automake to generate more specialized code; for instance, a `bin_PROGRAMS' variable definition will cause targets for compiling and linking programs to be generated.

The variable definitions and targets in the `Makefile.am' are copied verbatim 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 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 targets or variable definitions.

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' or AC_SUBST'ed from `configure.in' 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. 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 which 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

2.2 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 (which may never happen).

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

Automake also has a special "cygnus" mode which is similar to strictness but handled differently. This mode is useful for packages which are put into a "Cygnus" style tree (e.g., the GCC tree). For more information on this mode, see 22. The effect of --cygnus.

2.3 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. The variable names are made of several pieces which are concatenated together.

The piece which tells automake what is being built is commonly called the primary. For instance, the primary PROGRAMS holds a list of programs which are to be compiled and linked.

A different set of names is used to decide where the built objects should be installed. These names are prefixes to the primary which indicate 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 $(libdir)/@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 that may 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 = @MORE_PROGRAMS@

Defining a primary without a prefix as a variable, e.g., 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 (e.g. `zar') is valid if a variable of the same name with `dir' appended is defined (e.g. 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 be built but not installed at all. This is usually used for objects required to build the rest of your package, for instance static libraries (see section 9.2 Building a library), or helper scripts.

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

The current primary names are `PROGRAMS', `LIBRARIES', `LISP', `PYTHON', `JAVA', `SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'.

Some primaries also allow additional prefixes which control other aspects of automake's behavior. The currently defined prefixes are `dist_', `nodist_', and `nobase_'. These prefixes are explained later (see section 9.4 Program and Library Variables).

2.4 How derived variables are named

Sometimes a Makefile variable name is derived from some text the maintainer supplies. For instance, a program name listed in `_PROGRAMS' is rewritten into the name of a `_SOURCES' variable. In cases like this, Automake canonicalizes the text, so that program names and the like do not have to follow Makefile variable naming rules. All characters in the name except for letters, numbers, the strudel (@), and the underscore are turned into underscores when making variable references.

For example, if your program is named sniff-glue, the derived variable name would be sniff_glue_SOURCES, not sniff-glue_SOURCES. Similarly the sources for a library named libmumble++.a should be listed in the libmumble___a_SOURCES variable.

The strudel is an addition, to make the use of Autoconf substitutions in variable names less obfuscating.

2.5 Variables reserved for the user

Some Makefile variables are reserved by the GNU Coding Standards for the use of the "user" -- the person building the package. For instance, CFLAGS is one such variable.

Sometimes package developers are tempted to set user variables such as CFLAGS because it appears to make their job easier -- they don't have to introduce a second variable into every target.

However, the package itself should never set a user variable, particularly not to include switches which are required for proper compilation of the package. Since these variables are documented as being for the package builder, that person rightfully expects to be able to override any of these variables at build time.

To get around this problem, automake introduces an automake-specific shadow variable for each user flag variable. (Shadow variables are not introduced for variables like CC, where they would make no sense.) The shadow variable is named by prepending `AM_' to the user variable's name. For instance, the shadow variable for YFLAGS is AM_YFLAGS.

2.6 Programs automake might require

Automake sometimes requires helper programs so that the generated `Makefile' can do its work properly. There are a fairly large number of them, and we list them here.

ansi2knr.c

ansi2knr.1

These two files are used by the automatic de-ANSI-fication support (see section 9.13 Automatic de-ANSI-fication).

compile

This is a wrapper for compilers which don't accept both `-c' and `-o' at the same time. It is only used when absolutely required. Such compilers are rare.

config.guess

config.sub

These programs compute the canonical triplets for the given build, host, or target architecture. These programs are updated regularly to support new architectures and fix probes broken by changes in new kernel versions. You are encouraged to fetch the latest versions of these files from ftp://ftp.gnu.org/gnu/config/ before making a release.

depcomp

This program understands how to run a compiler so that it will generate not only the desired output but also dependency information which is then used by the automatic dependency tracking feature.

elisp-comp

This program is used to byte-compile Emacs Lisp code.

install-sh

This is a replacement for the install program which works on platforms where install is unavailable or unusable.

mdate-sh

This script is used to generate a `version.texi' file. It examines a file and prints some date information about it.

missing

This wraps a number of programs which are typically only required by maintainers. If the program in question doesn't exist, missing prints an informative warning and attempts to fix things so that the build can continue.

mkinstalldirs

This works around the fact that mkdir -p is not portable.

py-compile

This is used to byte-compile Python scripts.

texinfo.tex

Not a program, this file is required for make dvi, make ps and make pdf to work when Texinfo sources are in the package.

ylwrap

This program wraps lex and yacc and ensures that, for instance, multiple yacc instances can be invoked in a single directory in parallel.