autoconf.texi

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

@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 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 differs from many other computer
languages because it treats actual code the same as plain text.  Whereas
in C, for instance, data and instructions have 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 white
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 blanks or newlines in arguments are ignored,
unless they are quoted.  You should always quote an argument that
might contain a macro name, comma, parenthesis, or a leading blank or
newline.  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], [1],
                   [Define to 1 if you 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], 1,
                   [Define to 1 if you have <stdio.h>.])],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])
@end example

@noindent
because @samp{1} cannot contain a macro call.  Here, the argument of
@code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
interpreted as an argument separator.  Also, the second and third arguments
of @samp{AC_CHECK_HEADER} must be quoted, since they contain
macro calls.  The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
if you unwisely defined a macro with a name like @samp{Define} or
@samp{stdio} then they would need quoting.  Cautious Autoconf users
would keep the quotes, but many Autoconf users find such precautions
annoying, and would rewrite the example as follows:

@example
AC_CHECK_HEADER(stdio.h,
                [AC_DEFINE(HAVE_STDIO_H, 1,
                   [Define to 1 if you have <stdio.h>.])],
                [AC_MSG_ERROR([Sorry, can't do anything for you])])
@end example

@noindent
This is safe, so long as you adopt good naming conventions and do not
define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
@samp{h}.  Though it is also safe here to omit the quotes around
@samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
message strings are more likely to inadvertently contain commas.

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

@example
AC_CHECK_HEADER(stdio.h,
                AC_DEFINE(HAVE_STDIO_H, 1,
                   Define to 1 if you 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 results 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 is 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!

On the other hand, descriptions (e.g., the last parameter of
@code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
are subject to line breaking, for example---and should not be double quoted.
Even if these descriptions are short and are not actually broken, double
quoting them yields weird results.

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
with the @samp{#}.  For example, it is helpful to begin
@file{configure.ac} files with a line like this:

@example
# Process this file with autoconf to produce a configure script.
@end example

@node configure.ac Layout
@subsection Standard @file{configure.ac} Layout

The order in which @file{configure.ac} calls the Autoconf macros is not
important, with a few exceptions.  Every @file{configure.ac} must
contain a call to @code{AC_INIT} before the checks, and a call to
@code{AC_OUTPUT} at the end (@pxref{Output}).  Additionally, some macros
rely on other macros having been called first, because they check
previously set values of some variables to decide what to do.  These
macros are noted in the individual descriptions (@pxref{Existing
Tests}), and they also warn you when @command{configure} is created if they
are called out of order.

To encourage consistency, here is a suggested order for calling the
Autoconf macros.  Generally speaking, the things near the end of this
list are those that could depend on things earlier in it.  For example,
library functions could be affected by types and libraries.

@display
@group
Autoconf requirements
@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
information on the package
checks for programs
checks for libraries
checks for header files
checks for types
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
@code{AC_OUTPUT}
@end group
@end display


@node autoscan Invocation
@section Using @command{autoscan} to Create @file{configure.ac}
@cindex @command{autoscan}

The @command{autoscan} program can help you create and/or maintain a
@file{configure.ac} file for a software package.  @command{autoscan}
examines source files in the directory tree rooted at a directory given
as a command line argument, or the current directory if none is given.
It searches the source files for common portability problems and creates
a file @file{configure.scan} which is a preliminary @file{configure.ac}
for that package, and checks a possibly existing @file{configure.ac} for
completeness.

When using @command{autoscan} to create a @file{configure.ac}, you
should manually examine @file{configure.scan} before renaming it to
@file{configure.ac}; it probably needs some adjustments.
Occasionally, @command{autoscan} outputs a macro in the wrong order
relative to another macro, so that @command{autoconf} produces a warning;
you need to move such macros manually.  Also, if you want the package to
use a configuration header file, you must add a call to
@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}).  You might
also have to change or add some @code{#if} directives to your program in
order to make it work with Autoconf (@pxref{ifnames Invocation}, for
information about a program that can help with that job).

When using @command{autoscan} to maintain a @file{configure.ac}, simply
consider adding its suggestions.  The file @file{autoscan.log}
contains detailed information on why a macro is requested.

@command{autoscan} uses several data files (installed along with Autoconf)
to determine which macros to output when it finds particular symbols in
a package's source files.  These data files all have the same format:
each line consists of a symbol, one or more blanks, and the Autoconf macro to
output if that symbol is encountered.  Lines starting with @samp{#} are
comments.

@command{autoscan} accepts the following options:

@table @option
@item --help
@itemx -h
Print a summary of the command line options and exit.

@item --version
@itemx -V
Print the version number of Autoconf and exit.

@item --verbose
@itemx -v
Print the names of the files it examines and the potentially interesting
symbols it finds in them.  This output can be voluminous.

@item --include=@var{dir}
@itemx -I @var{dir}
Append @var{dir} to the include path.  Multiple invocations accumulate.

@item --prepend-include=@var{dir}
@item -B @var{dir}
Prepend @var{dir} to the include path.  Multiple invocations accumulate.
@end table

@node ifnames Invocation
@section Using @command{ifnames} to List Conditionals
@cindex @command{ifnames}

@command{ifnames} can help you write @file{configure.ac} for a software
package.  It prints the identifiers that the package already uses in C
preprocessor conditionals.  If a package has already been set up to have
some portability, @command{ifnames} can thus help you figure out what its
@command{configure} needs to check for.  It may help fill in some gaps in a
@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
Invocation}).

@command{ifnames} scans all of the C source files named on the command line
(or the standard input, if none are given) and writes to the standard
output a sorted list of all the identifiers that appear in those files
in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
directives.  It prints each identifier on a line, followed by a
space-separated list of the files in which that identifier occurs.

@noindent
@command{ifnames} accepts the following options:

@table @option
@item --help
@itemx -h
Print a summary of the command line options and exit.

@item --version
@itemx -V
Print the version number of Autoconf and exit.
@end table

@node autoconf Invocation