autoconf.texi

autoconf是一个产生可以自动配置源代码包

configuration scripts can be regenerated automatically to take advantage
of the updated code.

The Metaconfig package is similar in purpose to Autoconf, but the
scripts it produces require manual user intervention, which is quite
inconvenient when configuring large source trees.  Unlike Metaconfig
scripts, Autoconf scripts can support cross-compiling, if some care is
taken in writing them.

Autoconf does not solve all problems related to making portable
software packages---for a more complete solution, it should be used in
concert with other @acronym{GNU} build tools like Automake and
Libtool.  These other tools take on jobs like the creation of a
portable, recursive makefile with all of the standard targets,
linking of shared libraries, and so on.  @xref{The GNU Build System},
for more information.

Autoconf imposes some restrictions on the names of macros used with
@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).

Autoconf requires @acronym{GNU} M4 in order to generate the scripts.  It uses
features that some versions of M4, including @acronym{GNU} M4 1.3,
do not have.  You should use version 1.4.4 or later of @acronym{GNU} M4.

@xref{Autoconf 1}, for information about upgrading from version 1.
@xref{History}, for the story of Autoconf's development.  @xref{FAQ},
for answers to some common questions about Autoconf.

See the @uref{http://www.gnu.org/software/autoconf/,
Autoconf web page} for up-to-date information, details on the mailing
lists, pointers to a list of known bugs, etc.

Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
list}.  Past suggestions are
@uref{http://lists.gnu.org/archive/html/autoconf/, archived}.

Mail bug reports to @email{bug-autoconf@@gnu.org, the
Autoconf Bugs mailing list}.  Past bug reports are
@uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.

If possible, first check that your bug is
not already solved in current development versions, and that it has not
been reported yet.  Be sure to include all the needed information and a
short @file{configure.ac} that demonstrates the problem.

Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
@uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
Summary} for details.  Patches relative to the
current @acronym{CVS} version can be sent for review to the
@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
Past patches are
@uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.

Because of its mission, the Autoconf package itself
includes only a set of often-used
macros that have already demonstrated their usefulness.  Nevertheless,
if you wish to share your macros, or find existing ones, see the
@uref{http://autoconf-archive.cryp.to/, Autoconf Macro
Archive}, which is kindly run by @email{simons@@cryp.to,
Peter Simons}.


@c ================================================= The GNU Build System

@node The GNU Build System
@chapter The @acronym{GNU} Build System
@cindex @acronym{GNU} build system

Autoconf solves an important problem---reliable discovery of
system-specific build and runtime information---but this is only one
piece of the puzzle for the development of portable software.  To this
end, the @acronym{GNU} project has developed a suite of integrated
utilities to finish the job Autoconf started: the @acronym{GNU} build
system, whose most important components are Autoconf, Automake, and
Libtool.  In this chapter, we introduce you to those tools, point you
to sources of more information, and try to convince you to use the
entire @acronym{GNU} build system for your software.

@menu
* Automake::                    Escaping makefile hell
* Gnulib::                      The @acronym{GNU} portability library
* Libtool::                     Building libraries portably
* Pointers::                    More info on the @acronym{GNU} build system
@end menu

@node Automake
@section Automake

The ubiquity of @command{make} means that a makefile is almost the
only viable way to distribute automatic build rules for software, but
one quickly runs into its numerous limitations.  Its lack of
support for automatic dependency tracking, recursive builds in
subdirectories, reliable timestamps (e.g., for network file systems), and
so on, mean that developers must painfully (and often incorrectly)
reinvent the wheel for each project.  Portability is non-trivial, thanks
to the quirks of @command{make} on many systems.  On top of all this is the
manual labor required to implement the many standard targets that users
have come to expect (@code{make install}, @code{make distclean},
@code{make uninstall}, etc.).  Since you are, of course, using Autoconf,
you also have to insert repetitive code in your @code{Makefile.in} to
recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
provided by @command{configure}.  Into this mess steps @dfn{Automake}.
@cindex Automake

Automake allows you to specify your build needs in a @code{Makefile.am}
file with a vastly simpler and more powerful syntax than that of a plain
makefile, and then generates a portable @code{Makefile.in} for
use with Autoconf.  For example, the @code{Makefile.am} to build and
install a simple ``Hello world'' program might look like:

@example
bin_PROGRAMS = hello
hello_SOURCES = hello.c
@end example

@noindent
The resulting @code{Makefile.in} (~400 lines) automatically supports all
the standard targets, the substitutions provided by Autoconf, automatic
dependency tracking, @code{VPATH} building, and so on.  @command{make}
builds the @code{hello} program, and @code{make install} installs it
in @file{/usr/local/bin} (or whatever prefix was given to
@command{configure}, if not @file{/usr/local}).

The benefits of Automake increase for larger packages (especially ones
with subdirectories), but even for small programs the added convenience
and portability can be substantial.  And that's not all@enddots{}

@node Gnulib
@section Gnulib

@acronym{GNU} software has a well-deserved reputation for running on
many different types of systems.  While our primary goal is to write
software for the @acronym{GNU} system, many users and developers have
been introduced to us through the systems that they were already using.

@cindex Gnulib
Gnulib is a central location for common @acronym{GNU} code, intended to
be shared among free software packages.  Its components are typically
shared at the source level, rather than being a library that gets built,
installed, and linked against.  The idea is to copy files from Gnulib
into your own source tree.  There is no distribution tarball; developers
should just grab source modules from the repository.  The source files
are available online, under various licenses, mostly @acronym{GNU}
@acronym{GPL} or @acronym{GNU} @acronym{LGPL}.

Gnulib modules typically contain C source code along with Autoconf
macros used to configure the source code.  For example, the Gnulib
@code{stdbool} module implements a @file{stdbool.h} header that nearly
conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
This module contains a source file for the replacement header, along
with an Autoconf macro that arranges to use the replacement header on
old-fashioned systems.

@node Libtool
@section Libtool

Often, one wants to build not only programs, but libraries, so that
other programs can benefit from the fruits of your labor.  Ideally, one
would like to produce @emph{shared} (dynamically linked) libraries,
which can be used by multiple programs without duplication on disk or in
memory and can be updated independently of the linked programs.
Producing shared libraries portably, however, is the stuff of
nightmares---each system has its own incompatible tools, compiler flags,
and magic incantations.  Fortunately, @acronym{GNU} provides a solution:
@dfn{Libtool}.
@cindex Libtool

Libtool handles all the requirements of building shared libraries for
you, and at this time seems to be the @emph{only} way to do so with any
portability.  It also handles many other headaches, such as: the
interaction of Make rules with the variable suffixes of
shared libraries, linking reliably with shared libraries before they are
installed by the superuser, and supplying a consistent versioning system
(so that different versions of a library can be installed or upgraded
without breaking binary compatibility).  Although Libtool, like
Autoconf, can be used without Automake, it is most simply utilized in
conjunction with Automake---there, Libtool is used automatically
whenever shared libraries are needed, and you need not know its syntax.

@node Pointers
@section Pointers

Developers who are used to the simplicity of @command{make} for small
projects on a single system might be daunted at the prospect of
learning to use Automake and Autoconf.  As your software is
distributed to more and more users, however, you otherwise
quickly find yourself putting lots of effort into reinventing the
services that the @acronym{GNU} build tools provide, and making the
same mistakes that they once made and overcame.  (Besides, since
you're already learning Autoconf, Automake is a piece of cake.)

There are a number of places that you can go to for more information on
the @acronym{GNU} build tools.

@itemize @minus

@item Web

The home pages for
@uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
@uref{http://www.gnu.org/@/software/@/automake/, Automake},
@uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
@uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.

@item Automake Manual

@xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
information on Automake.

@item Books

The book @cite{@acronym{GNU} Autoconf, Automake and
Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor.  SAMS (originally
New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
build environment.  You can also find
@uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.

@end itemize

@c ================================================= Making configure Scripts.

@node Making configure Scripts
@chapter Making @command{configure} Scripts
@cindex @file{aclocal.m4}
@cindex @command{configure}

The configuration scripts that Autoconf produces are by convention
called @command{configure}.  When run, @command{configure} creates several
files, replacing configuration parameters in them with appropriate
values.  The files that @command{configure} creates are:

@itemize @minus
@item
one or more @file{Makefile} files, usually one in each subdirectory of the
package (@pxref{Makefile Substitutions});

@item
optionally, a C header file, the name of which is configurable,
containing @code{#define} directives (@pxref{Configuration Headers});

@item
a shell script called @file{config.status} that, when run, recreates
the files listed above (@pxref{config.status Invocation});

@item
an optional shell script normally called @file{config.cache}
(created when using @samp{configure --config-cache}) that
saves the results of running many of the tests (@pxref{Cache Files});

@item
a file called @file{config.log} containing any messages produced by
compilers, to help debugging if @command{configure} makes a mistake.
@end itemize

@cindex @file{configure.in}
@cindex @file{configure.ac}
To create a @command{configure} script with Autoconf, you need to write an
Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
@command{autoconf} on it.  If you write your own feature tests to
supplement those that come with Autoconf, you might also write files
called @file{aclocal.m4} and @file{acsite.m4}.  If you use a C header
file to contain @code{#define} directives, you might also run
@command{autoheader}, and you can distribute the generated file
@file{config.h.in} with the package.

Here is a diagram showing how the files that can be used in
configuration are produced.  Programs that are executed are suffixed by
@samp{*}.  Optional files are enclosed in square brackets (@samp{[]}).
@command{autoconf} and @command{autoheader} also read the installed Autoconf
macro files (by reading @file{autoconf.m4}).

@noindent
Files used in preparing a software package for distribution:
@example
your source files --> [autoscan*] --> [configure.scan] --> configure.ac

@group
configure.ac --.
               |   .------> autoconf* -----> configure
[aclocal.m4] --+---+
               |   `-----> [autoheader*] --> [config.h.in]
[acsite.m4] ---'
@end group

Makefile.in -------------------------------> Makefile.in
@end example

@noindent
Files used in configuring a software package:
@example
@group
                       .-------------> [config.cache]
configure* ------------+-------------> config.log
                       |
[config.h.in] -.       v            .-> [config.h] -.
               +--> config.status* -+               +--> make*
Makefile.in ---'                    `-> Makefile ---'
@end group
@end example

@menu
* Writing configure.ac::        What to put in an Autoconf input file
* autoscan Invocation::         Semi-automatic @file{configure.ac} writing
* ifnames Invocation::          Listing the conditionals in source code
* autoconf Invocation::         How to create configuration scripts
* autoreconf Invocation::       Remaking multiple @command{configure} scripts
@end menu

@node Writing configure.ac
@section Writing @file{configure.ac}

To produce a @command{configure} script for a software package, create a
file called @file{configure.ac} that contains invocations of the
Autoconf macros that test the system features your package needs or can
use.  Autoconf macros already exist to check for many features; see
@ref{Existing Tests}, for their descriptions.  For most other features,
you can use Autoconf template macros to produce custom checks; see
@ref{Writing Tests}, for information about them.  For especially tricky
or specialized features, @file{configure.ac} might need to contain some
hand-crafted shell commands; see @ref{Portable Shell}.  The
@command{autoscan} program can give you a good start in writing
@file{configure.ac} (@pxref{autoscan Invocation}, for more information).

Previous versions of Autoconf promoted the name @file{configure.in},
which is somewhat ambiguous (the tool needed to process this file is not
described by its extension), and introduces a slight confusion with
@file{config.h.in} and so on (for which @samp{.in} means ``to be
processed by @command{configure}'').  Using @file{configure.ac} is now
preferred.

@menu
* Shell Script Compiler::       Autoconf as solution of a problem
* Autoconf Language::           Programming in Autoconf
* configure.ac Layout::         Standard organization of @file{configure.ac}