autoconf.texi

LINUX下的源码工具,可自己分析,或者直接装在系统上作为应用

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 @file{Makefile} 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}}.

@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 where @command{autoreconf} runs
@command{autoconf} (and @command{autoheader}, if appropriate).

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

This option triggers calls to @samp{automake --add-missing},
@samp{libtoolize}, @samp{autopoint}, etc.

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

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

@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 @code{WARNINGS}, a comma separated list of categories, is
honored.  Passing @samp{-W @var{category}} will actually behave as if
you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}.  If
you want to disable the defaults and @code{WARNINGS}, but (for example)
enable the warnings about obsolete constructs, you would use @option{-W
none,obsolete}.
@end table


@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
* Initializing configure::      Option processing etc.
* Notices::                     Copyright, version numbers in @command{configure}
* Input::                       Where Autoconf should find files
* Output::                      Outputting results from the configuration
* Configuration Actions::       Preparing the output based on results
* Configuration Files::         Creating output files
* Makefile Substitutions::      Using output variables in @file{Makefile}s
* Configuration Headers::       Creating a configuration header file
* Configuration Commands::      Running arbitrary instantiation commands
* Configuration Links::         Links depending on the configuration
* Subdirectories::              Configuring independent packages together
* Default Prefix::              Changing the default installation prefix
@end menu

@node Initializing configure
@section Initializing @command{configure}

Every @command{configure} script must call @code{AC_INIT} before doing
anything else.  The only other required macro is @code{AC_OUTPUT}
(@pxref{Output}).

@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
@acindex INIT
Process any command-line arguments and perform various initializations
and verifications.

Set the name of the @var{package} and its @var{version}.  These are
typically used in @option{--version} support, including that of
@command{configure}.  The optional argument @var{bug-report} should be
the email to which users should send bug reports.  The package
@var{tarname} differs from @var{package}: the latter designates the full
package name (e.g., @samp{GNU Autoconf}), while the former is meant for
distribution tar ball names (e.g., @samp{autoconf}).  It defaults to
@var{package} with @samp{GNU } stripped, lower-cased, and all characters
other than alphanumerics and underscores are changed to @samp{-}.

It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
there should not be any shell computation, but they can be computed by
M4.

The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
@code{PACKAGE_NAME}) are defined by @code{AC_INIT}:

@table @asis
@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
@acindex PACKAGE_NAME
@ovindex PACKAGE_NAME
@cvindex PACKAGE_NAME
Exactly @var{package}.

@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
@acindex PACKAGE_TARNAME
@ovindex PACKAGE_TARNAME
@cvindex PACKAGE_TARNAME
Exactly @var{tarname}.

@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
@acindex PACKAGE_VERSION
@ovindex PACKAGE_VERSION
@cvindex PACKAGE_VERSION
Exactly @var{version}.

@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
@acindex PACKAGE_STRING
@ovindex PACKAGE_STRING
@cvindex PACKAGE_STRING
Exactly @samp{@var{package} @var{version}}.

@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
@acindex PACKAGE_BUGREPORT
@ovindex PACKAGE_BUGREPORT
@cvindex PACKAGE_BUGREPORT
Exactly @var{bug-report}.
@end table
@end defmac


@node Notices
@section Notices in @command{configure}

The following macros manage version numbers for @command{configure}
scripts.  Using them is optional.

@c FIXME: AC_PREREQ should not be here
@defmac AC_PREREQ (@var{version})
@acindex PREREQ
@cindex Version
Ensure that a recent enough version of Autoconf is being used.  If the
version of Autoconf being used to create @command{configure} is earlier
than @var{version}, print an error message to the standard error output
and do not create @command{configure}.  For example:

@example
AC_PREREQ(@value{VERSION})
@end example

This macro is the only macro that may be used before @code{AC_INIT}, but
for consistency, you are invited not to do so.
@end defmac

@defmac AC_COPYRIGHT (@var{copyright-notice})
@acindex COPYRIGHT
@cindex Copyright Notice
State that, in addition to the Free Software Foundation's copyright on
the Autoconf macros, parts of your @command{configure} are covered by the
@var{copyright-notice}.

The @var{copyright-notice} will show up in both the head of
@command{configure} and in @samp{configure --version}.
@end defmac


@defmac AC_REVISION (@var{revision-info})
@acindex REVISION
@cindex Revision
Copy revision stamp @var{revision-info} into the @command{configure}
script, with any dollar signs or double-quotes removed.  This macro lets
you put a revision stamp from @file{configure.ac} into @command{configure}
without @acronym{RCS} or @acronym{CVS} changing it when you check in
@command{configure}.  That way, you can determine easily which revision of
@file{configure.ac} a particular @command{configure} corresponds to.

For example, this line in @file{configure.ac}:

@c The asis prevents RCS from changing the example in the manual.
@example
AC_REVISION($@asis{Revision: 1.30 }$)
@end example

@noindent
produces this in @command{configure}:

@example
#! /bin/sh
# From configure.ac Revision: 1.30
@end example
@end defmac


@node Input
@section Finding @command{configure} Input


@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
@acindex CONFIG_SRCDIR
@var{unique-file-in-source-dir} is some file that is in the package's
source directory; @command{configure} checks for this file's existence to
make sure that the directory that it is told contains the source code in
fact does.  Occasionally people accidentally specify the wrong directory
with @option{--srcdir}; this is a safety check.  @xref{configure
Invocation}, for more information.
@end defmac


@c FIXME: Remove definitively once --install explained.
@c
@c Small packages may store all their macros in @code{aclocal.m4}.  As the
@c set of macros grows, or for maintenance reasons, a maintainer may prefer
@c to split the macros in several files.  In this case, Autoconf must be
@c told which files to load, and in which order.
@c
@c @defmac AC_INCLUDE (@var{file}@dots{})
@c @acindex INCLUDE
@c @c FIXME: There is no longer shell globbing.
@c Read the macro definitions that appear in the listed files.  A list of
@c space-separated filenames or shell globbing patterns is expected.  The
@c files will be read in the order they're listed.
@c
@c Because the order of definition of macros is important (only the last
@c definition of a macro is used), beware that it is @code{AC_INIT} that
@c loads @file{acsite.m4} and @file{aclocal.m4}.  Note that
@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
@c the latter case, non-macro lines from included files may end up in the
@c @file{configure} script, whereas in the former case, they'd be discarded
@c just like any text that appear before @code{AC_INIT}.
@c @end defmac

Packages that do manual configuration or use the @code{install} program
might need to tell @command{configure} where to find some other shell
scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
it looks are correct for most cases.

@defmac AC_CONFIG_AUX_DIR (@var{dir})
@acindex CONFIG_AUX_DIR
Use the auxiliary build tools (e.g., @file{install-sh},
@file{config.sub}, @file{config.guess}, Cygnus @command{configure},
Automake and Libtool scripts etc.) that are in directory @var{dir}.
These are auxiliary files used in configuration.  @var{dir} can be
either absolute or relative to @file{@var{srcdir}}.  The default is
@file{@var{srcdir}} or @file{@var{srcdir}/..} or
@file{@var{srcdir}/../..}, whichever is the first that contains
@file{install-sh}.  The other files are not checked for, so that using
@code{AC_PROG_INSTALL} does not automatically require distributing the
other auxiliary files.  It checks for @file{install.sh} also, but that
name is obsolete because some @code{make} have a rule that creates
@file{install} from it if there is no @file{Makefile}.
@end defmac


@node Output
@section Outputting Files

Every Autoconf script, e.g., @file{configure.ac}, should finish by
calling @code{AC_OUTPUT}.  That is the macro that generates
@file{config.status}, which will create the @file{Makefile}s and any
other files resulting from configuration.  This is the only required
macro besides @code{AC_INIT} (@pxref{Input}).

@defmac AC_OUTPUT
@acindex OUTPUT
@cindex Instantiation
Generate @file{con