autoconf.texi

这是一个自动生成MAKEFILE的工具。在LINUX工程项目里是很好的帮手。希望对大家有点帮助。

feature that the software package they are for might need individually.
(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 UNIX variants.  There is no
need to maintain files that list the features supported by each release
of each variant of 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.

There are several jobs related to making portable software packages
that Autoconf currently does not do.  Among these are automatically
creating @file{Makefile} files with all of the standard targets, and
supplying replacements for standard library functions and header files on
systems that lack them.  Work is in progress to add those features in
the future.

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

Autoconf requires GNU @code{m4} in order to generate the scripts.  It
uses features that some UNIX versions of @code{m4} do not have.  It also
overflows internal limits of some versions of @code{m4}, including GNU
@code{m4} 1.0.  You must use version 1.1 or later of GNU @code{m4}.
Using version 1.3 or later will be much faster than 1.1 or 1.2.

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

Mail suggestions and bug reports for Autoconf to
@code{bug-gnu-utils@@prep.ai.mit.edu}.  Please include the Autoconf version
number, which you can get by running @samp{autoconf --version}.

@node Making configure Scripts, Setup, Introduction, Top
@chapter Making @code{configure} Scripts

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

@itemize @bullet
@item
one or more @file{Makefile} files, 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{Invoking config.status});

@item
a shell script called @file{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 @code{configure} makes a mistake.
@end itemize

To create a @code{configure} script with Autoconf, you need to write an
Autoconf input file @file{configure.in} and run @code{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 write @file{acconfig.h}, and you will
distribute the Autoconf-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{[]}).
@code{autoconf} and @code{autoheader} also read the installed Autoconf
macro files (by reading @file{autoconf.m4}).

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

configure.in --.   .------> autoconf* -----> configure
               +---+
[aclocal.m4] --+   `---.
[acsite.m4] ---'       |
                       +--> [autoheader*] -> [config.h.in]
[acconfig.h] ----.     |
                 +-----'
[config.h.top] --+
[config.h.bot] --'

Makefile.in -------------------------------> Makefile.in
@end group
@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.in::        What to put in an Autoconf input file.
* Invoking autoscan::           Semi-automatic @file{configure.in} writing.
* Invoking ifnames::            Listing the conditionals in source code.
* Invoking autoconf::           How to create configuration scripts.
* Invoking autoreconf::         Remaking multiple @code{configure} scripts.
@end menu

@node Writing configure.in, Invoking autoscan, Making configure Scripts, Making configure Scripts
@section Writing @file{configure.in}

To produce a @code{configure} script for a software package, create a
file called @file{configure.in} 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.in} might need to
contain some hand-crafted shell commands.  The @code{autoscan}
program can give you a good start in writing @file{configure.in}
(@pxref{Invoking autoscan}, for more information).

The order in which @file{configure.in} calls the Autoconf macros
is not important, with a few exceptions.  Every
@file{configure.in} 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 creating @code{configure} 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 could depend on things earlier in it.  For example, library
functions could be affected by typedefs and libraries.

@display
@group
@code{AC_INIT(@var{file})}
checks for programs
checks for libraries
checks for header files
checks for typedefs
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
@code{AC_OUTPUT(@r{[}@var{file@dots{}}@r{]})}
@end group
@end display

It is best to put each macro call on its own line in
@file{configure.in}.  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 @code{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.

When calling macros that take arguments, there must not be any blank
space between the macro name and the open parenthesis.  Arguments can be
more than one line long if they are enclosed within the @code{m4} quote
characters @samp{[} and @samp{]}.  If you have a long line such as a
list of file names, you can generally use a backslash at the end of a
line to continue it logically on the next line (this is implemented by
the shell, not by anything special that Autoconf does).

Some macros handle two cases: what to do if the given condition is met,
and what to do if the condition is not met.  In some places you might
want to do something if a condition is true but do nothing if it's
false, or vice versa.  To omit the true case, pass an empty value for
the @var{action-if-found} argument to the macro.  To omit the false
case, omit the @var{action-if-not-found} argument to the macro,
including the comma before it.

You can include comments in @file{configure.in} files by starting them
with the @code{m4} builtin macro @code{dnl}, which discards text up
through the next newline.  These comments do not appear in the generated
@code{configure} scripts.  For example, it is helpful to begin
@file{configure.in} files with a line like this:

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

@node Invoking autoscan, Invoking ifnames, Writing configure.in, Making configure Scripts
@section Using @code{autoscan} to Create @file{configure.in}

The @code{autoscan} program can help you create a @file{configure.in}
file for a software package.  @code{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.in} for
that package.

You should manually examine @file{configure.scan} before renaming it to
@file{configure.in}; it will probably need some adjustments.
Occasionally @code{autoscan} outputs a macro in the wrong order relative
to another macro, so that @code{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_HEADER} (@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{Invoking ifnames}, for
information about a program that can help with that job).

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

@code{autoscan} is only installed if you already have Perl installed.
@code{autoscan} accepts the following options:

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

@item --macrodir=@var{dir}
@evindex AC_MACRODIR
Look for the data files in directory @var{dir} instead of the default
installation directory.  You can also set the @code{AC_MACRODIR}
environment variable to a directory; this option overrides the
environment variable.

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

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

@node Invoking ifnames, Invoking autoconf, Invoking autoscan, Making configure Scripts
@section Using @code{ifnames} to List Conditionals

@code{ifnames} can help when writing a @file{configure.in} 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, this program can help you figure out what
its @code{configure} needs to check for.  It may help fill in some gaps
in a @file{configure.in} generated by @code{autoscan} (@pxref{Invoking
autoscan}).

@code{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
@code{ifnames} accepts the following options:

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

@item --macrodir=@var{dir}
@itemx -m @var{dir}
@evindex AC_MACRODIR
Look for the Autoconf macro files in directory @var{dir} instead of the
default installation directory.  Only used to get the version number.
You can also set the @code{AC_MACRODIR}
environment variable to a directory; this option overrides the
environment variable.

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

@node Invoking autoconf, Invoking autoreconf, Invoking ifnames, Making configure Scripts
@section Using @code{autoconf} to Create @code{configure}

To create @code{configure} from @file{configure.in}, run the
@code{autoconf} program with no arguments.  @code{autoconf} processes
@file{configure.in} with the @code{m4} macro processor, using the
Autoconf macros.  If you give @code{autoconf} an argument, it reads that
file instead of @file{configure.in} and writes the configuration script
to the standard output instead of to @code{configure}.  If you give
@code{autoconf} the argument @samp{-}, it reads the standard input
instead of @file{configure.in} and writes the configuration script on
the standard output.