autoconf.texi

autoconf 2.59版,可用于redhat系统.用于编译原码,编写makefile文件.

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}).

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.

@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 will 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 will be 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
@href{http://www.gnu.org/software/autoconf/,Autoconf},
@href{http://www.gnu.org/software/automake/,Automake}, and
@href{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.  New
Riders, 2000, ISBN 1578701902.}  describes the complete @acronym{GNU}
build environment.  You can also find the entire book on-line at
@href{http://sources.redhat.com/autobook/,``The Goat Book'' home
page}.

@item Tutorials and Examples

The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
maintains links to a number of Autoconf/Automake tutorials online, and
also links to the @href{http://www.gnu.org/software/ac-archive/,
Autoconf Macro Archive}.

@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, will recreate
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 will 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}
@end menu

@node Shell Script Compiler
@subsection A Shell Script Compiler

Just as for any other computer language, in order to properly program
@file{configure.ac} in Autoconf you must understand @emph{what} problem
the language tries to address and @emph{how} it does so.

The problem Autoconf addresses is that the world is a mess.  After all,
you are using Autoconf in order to have your package compile easily on
all sorts of different systems, some of them being extremely hostile.
Autoconf itself bears the price for these differences: @command{configure}
must run on all those systems, and thus @command{configure} must limit itself
to their lowest common denominator of features.

Naturally, you might then think of shell scripts; who needs
@command{autoconf}?  A set of properly written shell functions is enough to
make it easy to write @command{configure} scripts by hand.  Sigh!
Unfortunately, shell functions do not belong to the least common
denominator; therefore, where you would like to define a function and
use it ten times, you would instead need to copy its body ten times.

So, what is really needed is some kind of compiler, @command{autoconf},
that takes an Autoconf program, @file{configure.ac}, and transforms it
into a portable shell script, @command{configure}.

How does @command{autoconf} perform this task?

There are two obvious possibilities: creating a brand new language or
extending an existing one.  The former option is very attractive: all
sorts of optimizations could easily be implemented in the compiler and
many rigorous checks could be performed on the Autoconf program
(e.g., rejecting any non-portable construct).  Alternatively, you can
extend an existing language, such as the @code{sh} (Bourne shell)
language.

Autoconf does the latter: it is a layer on top of @code{sh}.  It was
therefore most convenient to implement @command{autoconf} as a macro
expander: a program that repeatedly performs @dfn{macro expansions} on
text input, replacing macro calls with macro bodies and producing a pure
@code{sh} script in the end.  Instead of implementing a dedicated
Autoconf macro expander, it is natural to use an existing
general-purpose macro language, such as M4, and implement the extensions
as a set of M4 macros.


@node Autoconf Language
@subsection The Autoconf Language
@cindex quotation

The Autoconf language is very different from many other computer
languages because it treats actual code the same as plain text.  Whereas
in C, for instance, data and instructions have very different syntactic
status, in Autoconf their status is rigorously the same.  Therefore, we
need a means to distinguish literal strings from text to be expanded:
quotation.

When calling macros that take arguments, there must not be any blank
space between the macro name and the open parenthesis.  Arguments should
be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
separated by commas.  Any leading spaces in arguments are ignored,
unless they are quoted.  You may safely leave out the quotes when the
argument is simple text, but @emph{always} quote complex arguments such
as other macro calls.  This rule applies recursively for every macro
call, including macros called from other macros.

For instance:

@example
AC_CHECK_HEADER([stdio.h],
                [AC_DEFINE([HAVE_STDIO_H])],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])
@end example

@noindent
is quoted properly.  You may safely simplify its quotation to:

@example
AC_CHECK_HEADER(stdio.h,
                [AC_DEFINE(HAVE_STDIO_H)],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])
@end example

@noindent
Notice that the argument of @code{AC_MSG_ERROR} is still quoted;
otherwise, its comma would have been interpreted as an argument separator.

The following example is wrong and dangerous, as it is underquoted:

@example
AC_CHECK_HEADER(stdio.h,
                AC_DEFINE(HAVE_STDIO_H),
                AC_MSG_ERROR([Sorry, can't do anything for you]))
@end example

In other cases, you may have to use text that also resembles a macro
call.  You must quote that text even when it is not passed as a macro