Next: Scanning configure.in, Previous: Creating a Makefile.in, Up: GNU Automake [Index]
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
).
While Automake is intended to be used by maintainers of GNU packages, it does make some effort to accomodate 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:
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.
Automake will check – as much as possible – for compliance to the GNU standards for packages. This is the default.
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.
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 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 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 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 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’, ‘SCRIPTS’, ‘DATA’, ‘HEADERS’, ‘MANS’, and ‘TEXINFOS’.
Automake essentially works by reading a Makefile.am and generating a Makefile.in. The macro definitions and targets in the Makefile.am are copied into the generated file.
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.
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
Next: Scanning configure.in, Previous: Creating a Makefile.in, Up: GNU Automake [Index]