autoconf.texi

来自「LINUX下的源码工具,可自己分析,或者直接装在系统上作为应用」· TEXI 代码 · 共 1,672 行 · 第 1/5 页

@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
argument:

@example
echo "Hard rock was here!  --[AC_DC]"
@end example

@noindent
which will result in

@example
echo "Hard rock was here!  --AC_DC"
@end example

@noindent
When you use the same text in a macro argument, you must therefore have
an extra quotation level (since one is stripped away by the macro
substitution).  In general, then, it is a good idea to @emph{use double
quoting for all literal string arguments}:

@example
AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
@end example

You are now able to understand one of the constructs of Autoconf that
has been continually misunderstood@dots{}  The rule of thumb is that
@emph{whenever you expect macro expansion, expect quote expansion};
i.e., expect one level of quotes to be lost.  For instance:

@example
AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
@end example

@noindent
is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
@samp{char b[10];} and will be expanded once, which results in
@samp{char b10;}.  (There was an idiom common in Autoconf's past to
address this issue via the M4 @code{changequote} primitive, but do not
use it!)  Let's take a closer look: the author meant the first argument
to be understood as a literal, and therefore it must be quoted twice:

@example
AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
@end example

@noindent
Voil@`a, you actually produce @samp{char b[10];} this time!

The careful reader will notice that, according to these guidelines, the
``properly'' quoted @code{AC_CHECK_HEADER} example above is actually
lacking three pairs of quotes!  Nevertheless, for the sake of readability,
double quotation of literals is used only where needed in this manual.

Some macros take optional arguments, which this documentation represents
as @ovar{arg} (not to be confused with the quote characters).  You may
just leave them empty, or use @samp{[]} to make the emptiness of the
argument explicit, or you may simply omit the trailing commas.  The
three lines below are equivalent:

@example
AC_CHECK_HEADERS(stdio.h, [], [], [])
AC_CHECK_HEADERS(stdio.h,,,)
AC_CHECK_HEADERS(stdio.h)
@end example

It is best to put each macro call on its own line in
@file{configure.ac}.  Most of the macros don't add extra newlines; they
rely on the newline after the macro call to terminate the commands.
This approach makes the generated @command{configure} script a little
easier to read by not inserting lots of blank lines.  It is generally
safe to set shell variables on the same line as a macro call, because
the shell allows assignments without intervening newlines.

You can include comments in @file{configure.ac} files by starting them