autoconf.texi

LINUX下的源码工具,可自己分析,或者直接装在系统上作为应用

* Redefined M4 Macros::         M4 builtins changed in M4sugar
* Evaluation Macros::           More quotation and evaluation control
* Forbidden Patterns::          Catching unexpanded macros

Writing Autoconf Macros

* Macro Definitions::           Basic format of an Autoconf macro
* Macro Names::                 What to call your new macros
* Reporting Messages::          Notifying @command{autoconf} users
* Dependencies Between Macros::  What to do when macros depend on other macros
* Obsoleting Macros::           Warning about old ways of doing things
* Coding Style::                Writing Autoconf macros @`a la Autoconf

Dependencies Between Macros

* Prerequisite Macros::         Ensuring required information
* Suggested Ordering::          Warning about possible ordering problems

Portable Shell Programming

* Shellology::                  A zoology of shells
* Here-Documents::              Quirks and tricks
* File Descriptors::            FDs and redirections
* File System Conventions::     File- and pathnames
* Shell Substitutions::         Variable and command expansions
* Assignments::                 Varying side effects of assignments
* Special Shell Variables::     Variables you should not change
* Limitations of Builtins::     Portable use of not so portable /bin/sh
* Limitations of Usual Tools::  Portable use of portable tools
* Limitations of Make::         Portable Makefiles

Manual Configuration

* Specifying Names::            Specifying the system type
* Canonicalizing::              Getting the canonical system type
* Using System Type::           What to do with the system type

Site Configuration

* External Software::           Working with other optional software
* Package Options::             Selecting optional features
* Pretty Help Strings::         Formatting help string
* Site Details::                Configuring site details
* Transforming Names::          Changing program names when installing
* Site Defaults::               Giving @command{configure} local defaults

Transforming Program Names When Installing

* Transformation Options::      @command{configure} options to transform names
* Transformation Examples::     Sample uses of transforming names
* Transformation Rules::        @file{Makefile} uses of transforming names

Running @command{configure} Scripts

* Basic Installation::          Instructions for typical cases
* Compilers and Options::       Selecting compilers and optimization
* Multiple Architectures::      Compiling for multiple architectures at once
* Installation Names::          Installing in different directories
* Optional Features::           Selecting optional features
* System Type::                 Specifying the system type
* Sharing Defaults::            Setting site-wide defaults for @command{configure}
* Defining Variables::          Specifying the compiler etc.
* configure Invocation::        Changing how @command{configure} runs

Obsolete Constructs

* Obsolete config.status Use::  Different calling convention
* acconfig.h::                  Additional entries in @file{config.h.in}
* autoupdate Invocation::       Automatic update of @file{configure.ac}
* Obsolete Macros::             Backward compatibility macros
* Autoconf 1::                  Tips for upgrading your files
* Autoconf 2.13::               Some fresher tips

Upgrading From Version 1

* Changed File Names::          Files you might rename
* Changed Makefiles::           New things to put in @file{Makefile.in}
* Changed Macros::              Macro calls you might replace
* Changed Results::             Changes in how to check test results
* Changed Macro Writing::       Better ways to write your own macros

Upgrading From Version 2.13

* Changed Quotation::           Broken code which used to work
* New Macros::                  Interaction with foreign macros
* Hosts and Cross-Compilation::  Bugward compatibility kludges
* AC_LIBOBJ vs LIBOBJS::        LIBOBJS is a forbidden token
* AC_FOO_IFELSE vs AC_TRY_FOO::  A more generic scheme for testing sources

Generating Test Suites with Autotest

* Using an Autotest Test Suite::  Autotest and the user
* Writing testsuite.at::        Autotest macros
* testsuite Invocation::        Running @command{testsuite} scripts
* Making testsuite Scripts::    Using autom4te to create @command{testsuite}

Using an Autotest Test Suite

* testsuite Scripts::           The concepts of Autotest
* Autotest Logs::               Their contents

Frequent Autoconf Questions, with answers

* Distributing::                Distributing @command{configure} scripts
* Why GNU m4::                  Why not use the standard M4?
* Bootstrapping::               Autoconf and @acronym{GNU} M4 require each other?
* Why Not Imake::               Why @acronym{GNU} uses @command{configure} instead of Imake
* Defining Directories::        Passing @code{datadir} to program
* autom4te.cache::              What is it?  Can I remove it?

History of Autoconf

* Genesis::                     Prehistory and naming of @command{configure}
* Exodus::                      The plagues of M4 and Perl
* Leviticus::                   The priestly code of portability arrives
* Numbers::                     Growth and contributors
* Deuteronomy::                 Approaching the promises of easy configuration

Copying This Manual

* GNU Free Documentation License::  License for copying this manual

Indices

* Environment Variable Index::  Index of environment variables used
* Output Variable Index::       Index of variables set in output files
* Preprocessor Symbol Index::   Index of C preprocessor symbols defined
* Autoconf Macro Index::        Index of Autoconf macros
* M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
* Autotest Macro Index::        Index of Autotest macros
* Program & Function Index::    Index of those with portability problems
* Concept Index::               General index

@end detailmenu
@end menu

@c ============================================================= Introduction.

@node Introduction
@chapter Introduction

@flushright
A physicist, an engineer, and a computer scientist were discussing the
nature of God.  ``Surely a Physicist,'' said the physicist, ``because
early in the Creation, God made Light; and you know, Maxwell's
equations, the dual nature of electromagnetic waves, the relativistic
consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
before making Light, God split the Chaos into Land and Water; it takes a
hell of an engineer to handle that big amount of mud, and orderly
separation of solids from liquids@dots{}'' The computer scientist
shouted: ``And the Chaos, where do you think it was coming from, hmm?''

---Anonymous
@end flushright
@c (via Franc,ois Pinard)

Autoconf is a tool for producing shell scripts that automatically
configure software source code packages to adapt to many kinds of
@sc{unix}-like systems.  The configuration scripts produced by Autoconf
are independent of Autoconf when they are run, so their users do not
need to have Autoconf.

The configuration scripts produced by Autoconf require no manual user
intervention when run; they do not normally even need an argument
specifying the system type.  Instead, they individually test for the
presence of each feature that the software package they are for might need.
(Before each check, they print a one-line message stating what they are
checking for, so the user doesn't get too bored while waiting for the
script to finish.)  As a result, they deal well with systems that are
hybrids or customized from the more common @sc{unix} variants.  There is
no need to maintain files that list the features supported by each
release of each variant of @sc{unix}.

For each software package that Autoconf is used with, it creates a
configuration script from a template file that lists the system features
that the package needs or can use.  After the shell code to recognize
and respond to a system feature has been written, Autoconf allows it to
be shared by many software packages that can use (or need) that feature.
If it later turns out that the shell code needs adjustment for some
reason, it needs to be changed in only one place; all of the
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 @file{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 @sc{unix} versions of M4, including @acronym{GNU} M4 1.3,
do not have.  You must use version 1.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 @href{http://www.gnu.org/software/autoconf/autoconf.html,
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}.

Bug reports should be preferably submitted to the
@href{http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=autoconf,
Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the
Autoconf Bugs mailing list}.  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 @acronym{CVS}; see the Autoconf
web page for details.  There is also a
@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @acronym{CVS}web
interface to the Autoconf development tree}.  Patches relative to the
current @acronym{CVS} version can be sent for review to the
@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.

Because of its mission, Autoconf 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
@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
Archive}, which is kindly run by @email{simons@@computer.org,
Peter Simons}.


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

@node The GNU Build System
@chapter The @acronym{GNU} Build System

Autoconf solves an important problem---reliable discovery of
system-specific build and run-time 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
* 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 @file{Makefile} is almost the
only viable way to distribute automatic build rules for software, but
one quickly runs into @command{make}'s numerous limitations.  Its lack of
support for automatic dependency tracking, recursive builds in
subdirectories, reliable timestamps (e.g., for network filesystems), 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
@code{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} will
build the @code{hello} program, and @code{make install} will install it
in @file{/usr/local/bin} (or whatever prefix was given to
@command{configure}, if not @file{/usr/local}).

Automake may require that additional tools be present on the
@emph{developer's} machine.  For example, the @code{Makefile.in} that
the developer works with may not be portable (e.g., it might use special
features of your compiler to automatically generate dependency
information).  Running @code{make dist}, however, produces a
@file{hello-1.0.tar.gz} package (or whatever the program/version is)
with a @code{Makefile.in} that will work on any system.

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 Libtool
@section Libtool

Very 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 @code{Makefile} 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 on its own, 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.