Go to the first, previous, next, last section, table of contents.
The following sections cover a few basic ideas that will help you understand how Automake works.
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 instance, a `bin_PROGRAMS' macro definition will cause targets for compiling and linking programs to be generated.
The macro 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 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 and macro 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 macro defined in `Makefile.am' will override any
definition of the macro 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 macros generated by
automake are considered to be for internal use only, and their
names might change in future releases.
When examining a macro definition, Automake will recursively examine
macros 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
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:
For more information on the precise implications of the strictness
level, see section 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 section The effect of --cygnus.
Automake macros (from here on referred to as 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 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.
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.
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 macro naming rules. All characters in the name except for letters, numbers, the strudel (@), and the underscore are turned into underscores when making macro references.
For example, if your program is named sniff-glue, the derived
variable name would be sniff_glue_SOURCES, not
sniff-glue_SOURCES.
The strudel is an addition, to make the use of Autoconf substitutions in macro names less obfuscating.
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.
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
compile
config.guess
config.sub
depcomp
elisp-comp
install-sh
install program which works on
platforms where install is unavailable or unusable.
mdate-sh
missing
missing
prints an informative warning and attempts to fix things so that the
build can continue.
mkinstalldirs
mkdir -p is not portable.
py-compile
texinfo.tex
make dvi to work when
Texinfo sources are in the package.
ylwrap
lex and yacc and ensures that, for
instance, multiple yacc instances can be invoked in a single
directory in parallel.
Go to the first, previous, next, last section, table of contents.