The autotools as a group help you create software
distributions which will build reliably on a large variety
of platforms. They are most obviously associated with unix
systems, but in fact support the larger class of POSIX
systems which have an implementation of /bin/sh
available -- a class which includes Windows machines,
through the cygwin
environment.
The minimum required contact with the autotools is to
generate the files which will let you configure a freshly
checked-out directory before working on it, since these
configuration files are not checked in to the repository.
The ./bootstrap script (see Section 2.2) will do this for
you, but it can only do this if the autotools are installed
(see Section 3.5).
The aim of the notes below is to give you an overview of autoconf and automake functionality, enough to make it possible for you to roughly understand the existing configuration files, and to make it easier to approach the full autoconf and automake documentation. We start off with a broad overview, and provide a few further details in the subsections which follow.
The two most obvious and important files are
configure.ac and
Makefile.am. The
first tells autoconf how to make the
./configure script which does the actual
configuration work, and which will be distributed with your
package, the second (assuming you're using automake rather
than hand-maintaining the input Makefile) tells automake how
to create the template makefile Makefile.in,
which is also distributed with your package, and which is
edited by the ./configure script to (finally!)
produce the Makefile which (finally!) builds the
code on the user's system.
It's useful to illustrate the inputs and outputs of the various tools. First are autoconf and automake:
 |
| Figure 1: Inputs to, and outputs from, autoconf |
 |
| Figure 2: Inputs to, and outputs from, automake |
As you can see, although configure.ac is most
associated with autoconf, automake reads it, too, to
discover for example whether you have invoked
AC_PROG_LIBTOOL or STAR_MONOLITHS,
and so whether it needs to add the appropriate support in
the generated Makefile.in.
Once the ./configure script is created, it is
able to interrogate the system (the user's system, that is,
not the developer's), and based on that edit the various
.in files to produce their corresponding
outputs.
 |
| Figure 3: Inputs and outputs to configure |
This diagram for ./configure shows a file
config.h.in being
edited. This file -- which
we will have more to say about in Section 2.1.1 -- is a template list of C
preprocessor definitions, which can be
#included in a C source file, and so used to
configure the use of functions and definitions there. Like
any of the other .in files, it is possible to
maintain this by hand, but it is more reliable to maintain
it using another application
autoheader, which
looks as follows.
 |
| Figure 4: Inputs and outputs to autoheader |
The other file we have not mentioned yet is
starconf.m4. This file contains macros (in
the implementation language of autoconf, m4) which are
used to extend autoconf's functionality, supplying the
Starlink-specific autoconf support. You will
not typically have anything to do with this file, and we
mention it only to indicate schematically where (some of)
the Starlink magic comes from. This file is not in your
working directory, but is installed in the place the
autotools expect to find it, by the starconf
application described in Section 2.2. You may also
notice a file aclocal.m4
in your directory.
This is a cache of autoconf macros, maintained by the
autoreconf program; it should not be checked in.
Of the applications mentioned above, automake, autoconf and
(usually implicitly) autoheader are run on the developer's
machine before or while making a distribution; thus the
products of these programs, ./configure,
config.h.in and Makefile.in, are
included in the distribution, and the .in files
edited by the ./configure script into the
config.h and Makefile which
actually control the build.
We have elided some details here, for simplicity, and we
could possibly have elided more, since you generally don't
have to concern yourself with autoheader or
aclocal.m4. You don't even have to worry
about the dependencies between these files and applications,
since the Makefile.in which automake generates
knows about these dependencies and will generally keep
things up to date for you. If you wish to be sure things
are up to date, then you can simply run application
autoreconf (see Section 2.1.4), which
knows enough about the relationships between them to run
each of the required ones in the correct order. This is
likely the only one of the autotools commands which you will
run yourself.
For more details on the relationships between these applications, and fuller diagrams, see the online copy of the book `GNU Autoconf, Automake, and Libtool', and in particular Appendix C of that book, `Generated file dependencies'.
Comprehensive details of the autotools are to be found in their respective manuals, which are available online at
<http://www.gnu.org/software/autoconf/manual/autoconf-2.57/autoconf.html><http://www.gnu.org/software/automake/manual/><http://www.gnu.org/software/libtool/manual.html>It's also worth looking at the `Release Process' section of the GNU Coding Standards document. Though we are not necessarily following these standards, this section both describes what is conventional packaging in the open-source world, and outlines the conventions which the autotools are designed to support.