autoconf.texi

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

@section Using @command{autoconf} to Create @command{configure}
@cindex @command{autoconf}

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

The Autoconf macros are defined in several files.  Some of the files are
distributed with Autoconf; @command{autoconf} reads them first.  Then it
looks for the optional file @file{acsite.m4} in the directory that
contains the distributed Autoconf macro files, and for the optional file
@file{aclocal.m4} in the current directory.  Those files can contain
your site's or the package's own Autoconf macro definitions
(@pxref{Writing Autoconf Macros}, for more information).  If a macro is
defined in more than one of the files that @command{autoconf} reads, the
last definition it reads overrides the earlier ones.

@command{autoconf} 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
Report processing steps.

@item --debug
@itemx -d
Don't remove the temporary files.

@item --force
@itemx -f
Remake @file{configure} even if newer than its input files.

@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.

@item --output=@var{file}
@itemx -o @var{file}
Save output (script or trace) to @var{file}.  The file @option{-} stands
for the standard output.

@item --warnings=@var{category}
@itemx -W @var{category}
@evindex WARNINGS
Report the warnings related to @var{category} (which can actually be a
comma separated list).  @xref{Reporting Messages}, macro
@code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
values include:

@table @samp
@item all
report all the warnings

@item none
report none

@item error
treats warnings as errors

@item no-@var{category}
disable warnings falling into @var{category}
@end table

Warnings about @samp{syntax} are enabled by default, and the environment
variable @env{WARNINGS}, a comma separated list of categories, is
honored as well.  Passing @option{-W @var{category}} actually behaves as if
you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
you want to disable the defaults and @env{WARNINGS}, but (for example)
enable the warnings about obsolete constructs, you would use @option{-W
none,obsolete}.

@cindex Back trace
@cindex Macro invocation stack
Because @command{autoconf} uses @command{autom4te} behind the scenes, it
displays a back trace for errors, but not for warnings; if you want
them, just pass @option{-W error}.  @xref{autom4te Invocation}, for some
examples.

@item --trace=@var{macro}[:@var{format}]
@itemx -t @var{macro}[:@var{format}]
Do not create the @command{configure} script, but list the calls to
@var{macro} according to the @var{format}.  Multiple @option{--trace}
arguments can be used to list several macros.  Multiple @option{--trace}
arguments for a single macro are not cumulative; instead, you should
just make @var{format} as long as needed.

The @var{format} is a regular string, with newlines if desired, and
several special escape codes.  It defaults to @samp{$f:$l:$n:$%}; see
@ref{autom4te Invocation}, for details on the @var{format}.

@item --initialization
@itemx -i
By default, @option{--trace} does not trace the initialization of the
Autoconf macros (typically the @code{AC_DEFUN} definitions).  This
results in a noticeable speedup, but can be disabled by this option.
@end table


It is often necessary to check the content of a @file{configure.ac}
file, but parsing it yourself is extremely fragile and error-prone.  It
is suggested that you rely upon @option{--trace} to scan
@file{configure.ac}.  For instance, to find the list of variables that
are substituted, use:

@example
@group
$ @kbd{autoconf -t AC_SUBST}
configure.ac:2:AC_SUBST:ECHO_C
configure.ac:2:AC_SUBST:ECHO_N
configure.ac:2:AC_SUBST:ECHO_T
@i{More traces deleted}
@end group
@end example

@noindent
The example below highlights the difference between @samp{$@@},
@samp{$*}, and @samp{$%}.

@example
@group
$ @kbd{cat configure.ac}
AC_DEFINE(This, is, [an
[example]])
$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
*: $*
%: $%'
@@: [This],[is],[an
[example]]
*: This,is,an
[example]
%: This:is:an [example]
@end group
@end example

@noindent
The @var{format} gives you a lot of freedom:

@example
@group
$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
$ac_subst@{"ECHO_C"@} = "configure.ac:2";
$ac_subst@{"ECHO_N"@} = "configure.ac:2";
$ac_subst@{"ECHO_T"@} = "configure.ac:2";
@i{More traces deleted}
@end group
@end example

@noindent
A long @var{separator} can be used to improve the readability of complex
structures, and to ease their parsing (for instance when no single
character is suitable as a separator):

@example
@group
$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
ACLOCAL|:::::|aclocal|:::::|$missing_dir
AUTOCONF|:::::|autoconf|:::::|$missing_dir
AUTOMAKE|:::::|automake|:::::|$missing_dir
@i{More traces deleted}
@end group
@end example

@node autoreconf Invocation
@section Using @command{autoreconf} to Update @command{configure} Scripts
@cindex @command{autoreconf}

Installing the various components of the @acronym{GNU} Build System can be
tedious: running @command{autopoint} for Gettext, @command{automake} for
@file{Makefile.in} etc.@: in each directory.  It may be needed either
because some tools such as @command{automake} have been updated on your
system, or because some of the sources such as @file{configure.ac} have
been updated, or finally, simply in order to install the @acronym{GNU} Build
System in a fresh tree.

@command{autoreconf} runs @command{autoconf}, @command{autoheader},
@command{aclocal}, @command{automake}, @command{libtoolize}, and
@command{autopoint} (when appropriate) repeatedly to update the
@acronym{GNU} Build System in the specified directories and their
subdirectories (@pxref{Subdirectories}).  By default, it only remakes
those files that are older than their sources.

If you install a new version of some tool, you can make
@command{autoreconf} remake @emph{all} of the files by giving it the
@option{--force} option.

@xref{Automatic Remaking}, for Make rules to automatically
remake @command{configure} scripts when their source files change.  That
method handles the timestamps of configuration header templates
properly, but does not pass @option{--autoconf-dir=@var{dir}} or
@option{--localdir=@var{dir}}.

@cindex Gettext
@cindex @command{autopoint}
Gettext supplies the @command{autopoint} command to add translation
infrastructure to a source package.  If you use @command{autopoint},
your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
@code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}.  @xref{autopoint
Invocation, , Invoking the @code{autopoint} Program, gettext,
@acronym{GNU} @code{gettext} utilities}, for further details.

@noindent
@command{autoreconf} 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
Print the name of each directory @command{autoreconf} examines and the
commands it runs.  If given two or more times, pass @option{--verbose}
to subordinate tools that support it.

@item --debug
@itemx -d
Don't remove the temporary files.

@item --force
@itemx -f
Remake even @file{configure} scripts and configuration headers that are
newer than their input files (@file{configure.ac} and, if present,
@file{aclocal.m4}).

@item --install
@itemx -i
Install the missing auxiliary files in the package.  By default, files
are copied; this can be changed with @option{--symlink}.

If deemed appropriate, this option triggers calls to
@samp{automake --add-missing},
@samp{libtoolize}, @samp{autopoint}, etc.

@item --no-recursive
Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
macro @code{AC_CONFIG_SUBDIRS}).

@item --symlink
@itemx -s
When used with @option{--install}, install symbolic links to the missing
auxiliary files instead of copying them.

@item --make
@itemx -m
When the directories were configured, update the configuration by
running @samp{./config.status --recheck && ./config.status}, and then
run @samp{make}.

@item --include=@var{dir}
@itemx -I @var{dir}
Append @var{dir} to the include path.  Multiple invocations accumulate.
Passed on to @command{autoconf} and @command{autoheader} internally.

@item --prepend-include=@var{dir}
@item -B @var{dir}
Prepend @var{dir} to the include path.  Multiple invocations accumulate.
Passed on to @command{autoconf} and @command{autoheader} internally.

@item --warnings=@var{category}
@itemx -W @var{category}
@evindex WARNINGS
Report the warnings related to @var{category} (which can actually be a
comma separated list).

@table @samp
@item cross
related to cross compilation issues.

@item obsolete
report the uses of obsolete constructs.

@item portability
portability issues

@item syntax
dubious syntactic constructs.

@item all
report all the warnings

@item none
report none

@item error
treats warnings as errors

@item no-@var{category}
disable warnings falling into @var{category}
@end table

Warnings about @samp{syntax} are enabled by default, and the environment
variable @env{WARNINGS}, a comma separated list of categories, is
honored as well.  Passing @option{-W @var{category}} actually behaves as if
you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
you want to disable the defaults and @env{WARNINGS}, but (for example)
enable the warnings about obsolete constructs, you would use @option{-W
none,obsolete}.
@end table

If you want @command{autoreconf} to pass flags that are not listed here
on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.

@c ========================================= Initialization and Output Files.

@node Setup
@chapter Initialization and Output Files

Autoconf-generated @command{configure} scripts need some information about
how to initialize, such as how to find the package's source files and
about the output files to produce.  The following sections describe the
initialization and the creation of output files.

@menu