3. General ideas

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

3.1 General Operation

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 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 rule for the git-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.

Further note that variable assignments should not be indented with TAB characters, use spaces if necessary. On the other hand, rule commands should be indented with a leading TAB character.

Automake tries to keep comments grouped with any adjoining rules or variable definitions.

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

3.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 that 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).

See section The effect of `--gnu' and `--gnits', for more information on the precise implications of the strictness level.

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

3.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 that are concatenated together.

The piece that tells automake what is being built is commonly called the primary. For instance, the primary PROGRAMS holds a list of programs that 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, and they indicate which standard directory should be used as the installation directory. The standard directory names are given in the GNU standards (see (standards)Directory Variables section `Directory Variables' in The GNU Coding Standards). Automake extends this list with pkgdatadir, pkgincludedir, pkglibdir, and pkglibexecdir; 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 that 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 should be 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, the following snippet will install `file.xml' into `$(datadir)/xml'.

xmldir = $(datadir)/xml
xml_DATA = file.xml

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 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 that control other aspects of automake's behavior. The currently defined prefixes are `dist_', `nodist_', `nobase_', and `notrans_'. These prefixes are explained later (see section Program and Library Variables) (see section Man Pages).

3.4 Staying below the command line length limit

Traditionally, most unix-like systems have a length limitation for the command line arguments and environment contents when creating new processes (see for example http://www.in-ulm.de/~mascheck/various/argmax/ for an overview on this issue), which of course also applies to commands spawned by make. POSIX requires this limit to be at least 4096 bytes, and most modern systems have quite high limits (or are unlimited).

In order to create portable Makefiles that do not trip over these limits, it is necessary to keep the length of file lists bounded. Unfortunately, it is not possible to do so fully transparently within Automake, so your help may be needed. Typically, you can split long file lists manually and use different installation directory names for each list. For example,

data_DATA = file1 … fileN fileN+1 … file2N

may also be written as

data_DATA = file1 … fileN
data2dir = $(datadir)
data2_DATA = fileN+1 … file2N

and will cause Automake to treat the two lists separately during make install. See The Two Parts of Install for choosing directory names that will keep the ordering of the two parts of installation Note that make dist may still only work on a host with a higher length limit in this example.

Automake itself employs a couple of strategies to avoid long command lines. For example, when `${srcdir}/' is prepended to file names, as can happen with above $(data_DATA) lists, it limits the amount of arguments passed to external commands.

Unfortunately, some system's make commands may prepend VPATH prefixes like `${srcdir}/' to file names from the source tree automatically (see (autoconf)Automatic Rule Rewriting section `Automatic Rule Rewriting' in The Autoconf Manual). In this case, the user may have to switch to use GNU Make, or refrain from using VPATH builds, in order to stay below the length limit.

For libraries and programs built from many sources, convenience archives may be used as intermediates in order to limit the object list length (see section Libtool Convenience Libraries).

3.5 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.

3.6 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. However, the package itself should never set a user variable, particularly not to include switches that 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. The package maintainer--that is, the author(s) of the `Makefile.am' and `configure.ac' files--may adjust these shadow variables however necessary.

See section Flag Variables Ordering, for more discussion about these variables and how they interact with per-target variables.

3.7 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.

Although all of these files are distributed and installed with Automake, a couple of them are maintained separately. The Automake copies are updated before each release, but we mention the original source in case you need more recent versions.

ansi2knr.c

ansi2knr.1

These two files are used for de-ANSI-fication support (obsolete see section Automatic de-ANSI-fication).

compile

This is a wrapper for compilers that do not accept options `-c' and `-o' at the same time. It is only used when absolutely required. Such compilers are rare.

config.guess

config.sub

These two 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. Each new release of Automake comes with up-to-date copies of these programs. If your copy of Automake is getting old, you are encouraged to fetch the latest versions of these files from http://savannah.gnu.org/git/?group=config before making a release.

config-ml.in

This file is not a program, it is a `configure' fragment used for multilib support (see section Support for Multilibs). This file is maintained in the GCC tree at http://gcc.gnu.org/svn.html.

depcomp

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

elisp-comp

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

install-sh

This is a replacement for the install program that 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 that 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 script used to be a wrapper around `mkdir -p', which is not portable. Now we prefer to use `install-sh -d' when configure finds that `mkdir -p' does not work, this makes one less script to distribute.

For backward compatibility `mkinstalldirs' is still used and distributed when automake finds it in a package. But it is no longer installed automatically, and it should be safe to remove it.

py-compile

This is used to byte-compile Python scripts.

symlink-tree

This program duplicates a tree of directories, using symbolic links instead of copying files. Such an operation is performed when building multilibs (see section Support for Multilibs). This file is maintained in the GCC tree at http://gcc.gnu.org/svn.html.

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. The latest version can be downloaded from http://www.gnu.org/software/texinfo/.

ylwrap

This program wraps lex and yacc to rename their output files. It also ensures that, for instance, multiple yacc instances can be invoked in a single directory in parallel.

This document was generated on July, 20 2009 using texi2html 1.76.