automake.texi

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

@node Invoking Automake, configure, Examples, Top
@chapter Creating a @file{Makefile.in}

@cindex Multiple configure.in files
@cindex Invoking Automake
@cindex Automake, invoking

To create all the @file{Makefile.in}s for a package, run the
@code{automake} program in the top level directory, with no arguments.
@code{automake} will automatically find each appropriate
@file{Makefile.am} (by scanning @file{configure.in}; @pxref{configure})
and generate the corresponding @file{Makefile.in}.  Note that
@code{automake} has a rather simplistic view of what constitutes a
package; it assumes that a package has only one @file{configure.in}, at
the top.  If your package has multiple @file{configure.in}s, then you
must run @code{automake} in each directory holding a
@file{configure.in}.

You can optionally give @code{automake} an argument; @file{.am} is
appended to the argument and the result is used as the name of the input
file.  This feature is generally only used to automatically rebuild an
out-of-date @file{Makefile.in}.  Note that @code{automake} must always
be run from the topmost directory of a project, even if being used to
regenerate the @file{Makefile.in} in some subdirectory.  This is
necessary because @code{automake} must scan @file{configure.in}, and
because @code{automake} uses the knowledge that a @file{Makefile.in} is
in a subdirectory to change its behavior in some cases.

@cindex Automake options
@cindex Options, Automake

@code{automake} accepts the following options:

@cindex Extra files distributed with Automake
@cindex Files distributed with Automake
@cindex config.guess

@table @samp
@item -a
@itemx --add-missing
@opindex -a
@opindex --add-missing
Automake requires certain common files to exist in certain situations;
for instance @file{config.guess} is required if @file{configure.in} runs
@code{AC_CANONICAL_HOST}.  Automake is distributed with several of these
files; this option will cause the missing ones to be automatically added
to the package, whenever possible.  In general if Automake tells you a
file is missing, try using this option.  By default Automake tries to
make a symbolic link pointing to its own copy of the missing file; this
can be changed with @code{--copy}.

@item --amdir=@var{dir}
@opindex --amdir
Look for Automake data files in directory @var{dir} instead of in the
installation directory.  This is typically used for debugging.

@item --build-dir=@var{dir}
@opindex --build-dir
Tell Automake where the build directory is.  This option is used when
including dependencies into a @file{Makefile.in} generated by @code{make
dist}; it should not be used otherwise.

@item -c
@item --copy
When used with @code{--add-missing}, causes installed files to be
copied.  The default is to make a symbolic link.

@item --cygnus
@opindex --cygnus
Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
of GNU or Gnits rules.  For more information, see @ref{Cygnus}.

@item --foreign
@opindex --foreign
Set the global strictness to @samp{foreign}.  For more information, see
@ref{Strictness}.

@item --gnits
@opindex --gnits
Set the global strictness to @samp{gnits}.  For more information, see
@ref{Gnits}.

@item --gnu
@opindex --gnu
Set the global strictness to @samp{gnu}.  For more information, see
@ref{Gnits}.  This is the default strictness.

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

@item -i
@itemx --include-deps
@opindex -i
@opindex --include-deps
Include all automatically generated dependency information
(@pxref{Dependencies}) in the generated
@file{Makefile.in}.  This is generally done when making a distribution;
see @ref{Dist}.

@item --generate-deps
@opindex --generate-deps
Generate a file concatenating all automatically generated dependency
information (@pxref{Dependencies}) into one file, @file{.dep_segment}.
This is generally done when making a distribution; see @ref{Dist}.  It
is useful when maintaining a @file{SMakefile} or makefiles for other
platforms (@file{Makefile.DOS}, etc.)  It can only be used in
conjunction with @samp{--include-deps}, @samp{--srcdir-name}, and
@samp{--build-dir}.  Note that if this option is given, no other
processing is done.

@item --no-force
@opindex --no-force
Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
@file{configure.in}.  This option causes it to only update those
@file{Makefile.in}s which are out of date with respect to one of their
dependents.

@item -o @var{dir}
@itemx --output-dir=@var{dir}
@opindex -o
@opindex --output-dir
Put the generated @file{Makefile.in} in the directory @var{dir}.
Ordinarily each @file{Makefile.in} is created in the directory of the
corresponding @file{Makefile.am}.  This option is used when making
distributions.

@item --srcdir-name=@var{dir}
@opindex --srcdir-name
Tell Automake the name of the source directory associated with the
current build.  This option is used when including dependencies into a
@file{Makefile.in} generated by @code{make dist}; it should not be used
otherwise.

@item -v
@itemx --verbose
@opindex -v
@opindex --verbose
Cause Automake to print information about which files are being read or
created.

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


@node configure, Top level, Invoking Automake, Top
@chapter Scanning @file{configure.in}

@cindex configure.in, scanning
@cindex Scanning configure.in

Automake scans the package's @file{configure.in} to determine certain
information about the package.  Some @code{autoconf} macros are required
and some variables must be defined in @file{configure.in}.  Automake
will also use information from @file{configure.in} to further tailor its
output.

Automake also supplies some Autoconf macros to make the maintenance
easier.  These macros can automatically be put into your
@file{aclocal.m4} using the @code{aclocal} program.

@menu
* Requirements::                Configuration requirements
* Optional::                    Other things Automake recognizes
* Invoking aclocal::            Auto-generating aclocal.m4
* Macros::                      Autoconf macros supplied with Automake
* Extending aclocal::           Writing your own aclocal macros
@end menu


@node Requirements, Optional, configure, configure
@section Configuration requirements

@cindex Automake requirements
@cindex Requirements of Automake

The simplest way to meet the basic Automake requirements is to use the
macro @code{AM_INIT_AUTOMAKE} (@pxref{Macros}).  But if you prefer, you
can do the required steps by hand:
@cvindex AM_INIT_AUTOMAKE

@itemize @bullet
@item
Define the variables @code{PACKAGE} and @code{VERSION} with
@code{AC_SUBST}.
@cvindex PACKAGE
@cvindex VERSION
@code{PACKAGE} should be the name of the package as it appears when
bundled for distribution.  For instance, Automake defines @code{PACKAGE}
to be @samp{automake}.  @code{VERSION} should be the version number of
the release that is being developed.  We recommend that you make
@file{configure.in} the only place in your package where the version
number is defined; this makes releases simpler.

Automake doesn't do any interpretation of @code{PACKAGE} or
@code{VERSION}, except in @samp{Gnits} mode (@pxref{Gnits}).

@item
Use the macro @code{AC_ARG_PROGRAM} if a program or script is installed.
@xref{Transforming Names, , Transforming Program Names When Installing,
autoconf, The Autoconf}.
@cvindex AC_ARG_PROGRAM

@item
Use @code{AC_PROG_MAKE_SET} if the package is not flat.  @xref{Output, ,
Creating Output Files, autoconf, The Autoconf Manual}.
@cvindex AC_PROG_MAKE_SET

@item
Use @code{AM_SANITY_CHECK} to make sure the build environment is sane.

@item
Call @code{AC_PROG_INSTALL}
(@pxref{Particular Programs, , Particular Program Checks, autoconf, The
Autoconf Manual}).
@cvindex AC_PROG_INSTALL

@item
Use @code{AM_MISSING_PROG} to see whether the programs @code{aclocal},
@code{autoconf}, @code{automake}, @code{autoheader}, and @code{makeinfo}
are in the build environment.  Here is how this is done:
@example
missing_dir=`cd $ac_aux_dir && pwd`
AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir)
AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir)
AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)
@end example
@end itemize


Here are the other macros which Automake requires but which are not run
by @code{AM_INIT_AUTOMAKE}:

@cindex AC_OUTPUT, scanning

@table @code
@item AC_OUTPUT
Automake uses this to determine which files to create (@pxref{Output, ,
Creating Output Files, autoconf, The Autoconf Manual}).  Listed files
named @code{Makefile} are treated as @file{Makefile}s.  Other listed
files are treated differently.  Currently the only difference is that a
@file{Makefile} is removed by @code{make distclean}, while other files
are removed by @code{make clean}.
@c FIXME: this is in violation of standards!
@cvindex AC_OUTPUT
@end table


@node Optional, Invoking aclocal, Requirements, configure
@section Other things Automake recognizes

@cindex Macros Automake recognizes
@cindex Recognized macros by Automake

Automake will also recognize the use of certain macros and tailor the
generated @file{Makefile.in} appropriately.  Currently recognized macros
and their effects are:

@table @code
@item AC_CONFIG_HEADER
Automake requires the use of @code{AM_CONFIG_HEADER}, which is similar
to @code{AC_CONFIG_HEADER} (@pxref{Configuration Headers, ,
Configuration Header Files, autoconf, The Autoconf Manual}), but does
some useful Automake-specific work.
@cvindex AC_CONFIG_HEADER

@item AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as
@file{mkinstalldirs}, in the directory named in this macro invocation.
If not seen, the scripts are looked for in their @samp{standard}
locations (either the top source directory, or in the source directory
corresponding to the current @file{Makefile.am}, whichever is
appropriate).  @xref{Input, , Finding `configure' Input, autoconf, The
Autoconf Manual}.
@cvindex AC_CONFIG_AUX_DIR
FIXME: give complete list of things looked for in this directory

@item AC_PATH_XTRA
Automake will insert definitions for the variables defined by
@code{AC_PATH_XTRA} into each @file{Makefile.in} that builds a C program
or library.  @xref{System Services, , System Services, autoconf, The
Autoconf Manual}.
@cvindex AC_PATH_XTRA

@item AC_CANONICAL_HOST
@itemx AC_CHECK_TOOL
Automake will ensure that @file{config.guess} and @file{config.sub}
exist.  Also, the @file{Makefile} variables @samp{host_alias} and
@samp{host_triplet} are introduced.  See both @ref{Canonicalizing, ,
Getting the Canonical System Type, autoconf, The Autoconf Manual}, and
@ref{Generic Programs, , Generic Program Checks, autoconf, The Autoconf
Manual}.
@c fixme xref autoconf docs.
@cvindex AC_CANONICAL_HOST
@cvindex AC_CHECK_TOOL
@vindex host_alias
@vindex host_triplet

@item AC_CANONICAL_SYSTEM
This is similar to @code{AC_CANONICAL_HOST}, but also defines the
@file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
@xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
Autoconf Manual}.
@cvindex AC_CANONICAL_SYSTEM
@vindex build_alias
@vindex target_alias

@item AC_FUNC_ALLOCA
@itemx AC_FUNC_GETLOADAVG
@itemx AC_FUNC_MEMCMP
@itemx AC_STRUCT_ST_BLOCKS
@itemx AC_FUNC_FNMATCH
@itemx AM_FUNC_STRTOD
@itemx AC_REPLACE_FUNCS
@itemx AC_REPLACE_GNU_GETOPT
@itemx AM_WITH_REGEX
Automake will ensure that the appropriate dependencies are generated for
the objects corresponding to these macros.  Also, Automake will verify
that the appropriate source files are part of the distribution.  Note
that Automake does not come with any of the C sources required to use
these macros, so @code{automake -a} will not install the sources.
@xref{A Library}, for more information.  Also, see @ref{Particular
Functions, , Particular Function Checks, autoconf, The Autoconf Manual}.
@cvindex AC_FUNC_ALLOCA
@cvindex AC_FUNC_GETLOADAVG
@cvindex AC_FUNC_MEMCMP
@cvindex AC_STRUCT_ST_BLOCKS
@cvindex AC_FUNC_FNMATCH
@cvindex AC_FUNC_FNMATCH
@cvindex AC_REPLACE_FUNCS
@cvindex AC_REPLACE_GNU_GETOPT
@cvindex AM_FUNC_STRTOD
@cvindex AM_WITH_REGEX

@item LIBOBJS
Automake will detect statements which put @file{.o} files into
@code{LIBOBJS}, and will treat these additional files as if they were
discovered via @code{AC_REPLACE_FUNCS}.  @xref{Generic Functions, ,
Generic Function Checks, autoconf, The Autoconf Manual}.
@cvindex LIBOBJS

@item AC_PROG_RANLIB
This is required if any libraries are built in the package.
@xref{Particular Programs, , Particular Program Checks, autoconf, The
Autoconf Manual}.
@cvindex AC_PROG_RANLIB

@item AC_PROG_CXX
This is required if any C++ source is included.  @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@cvindex AC_PROG_CXX

@item AC_PROG_F77
This is required if any Fortran 77 source is included.  This macro is
distributed with Autoconf version 2.13 and later.  @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@cvindex AC_PROG_F77

@item AC_F77_LIBRARY_LDFLAGS
This is required for programs and shared libraries that are a mixture of
languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
C++}).  @xref{Macros, , Autoconf macros supplied with Automake}.
@cvindex AC_F77_LIBRARY_LDFLAGS

@item AM_PROG_LIBTOOL
Automake will turn on processing for @code{libtool} (@pxref{Top, ,
Introduction, libtool, The Libtool Manual}).