automake.texi

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

@cvindex AM_PROG_LIBTOOL

@item AC_PROG_YACC
If a Yacc source file is seen, then you must either use this macro or
define the variable @samp{YACC} in @file{configure.in}.  The former is
preferred (@pxref{Particular Programs, , Particular Program Checks,
autoconf, The Autoconf Manual}).
@cvindex AC_PROG_YACC
@cvindex YACC

@item AC_DECL_YYTEXT
This macro is required if there is Lex source in the package.
@xref{Particular Programs, , Particular Program Checks, autoconf, The
Autoconf Manual}.
@cvindex AC_DECL_YYTEXT

@item AC_PROG_LEX
If a Lex source file is seen, then this macro must be used.
@xref{Particular Programs, , Particular Program Checks, autoconf, The
Autoconf Manual}.
@cvindex AC_PROG_LEX

@item ALL_LINGUAS
If Automake sees that this variable is set in @file{configure.in}, it
will check the @file{po} directory to ensure that all the named
@samp{.po} files exist, and that all the @samp{.po} files that exist are
named.
@cvindex ALL_LINGUAS

@item AM_C_PROTOTYPES
This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
@cvindex AM_C_PROTOTYPES

@item AM_GNU_GETTEXT
This macro is required for packages which use GNU gettext
(@pxref{gettext}).  It is distributed with gettext.  If Automake sees
this macro it ensures that the package meets some of gettext's
requirements.
@cvindex AM_GNU_GETTEXT

@item AM_MAINTAINER_MODE
@opindex --enable-maintainer-mode
This macro adds a @samp{--enable-maintainer-mode} option to
@code{configure}.  If this is used, @code{automake} will cause
@samp{maintainer-only} rules to be turned off by default in the
generated @file{Makefile.in}s.  This macro is disallowed in @samp{Gnits}
mode (@pxref{Gnits}).  This macro defines the @samp{MAINTAINER_MODE}
conditional, which you can use in your own @file{Makefile.am}.
@cvindex AM_MAINTAINER_MODE

@item AC_SUBST
@itemx AC_CHECK_TOOL
@itemx AC_CHECK_PROG
@itemx AC_CHECK_PROGS
@itemx AC_PATH_PROG
@itemx AC_PATH_PROGS
For each of these macros, the first argument is automatically defined as
a variable in each generated @file{Makefile.in}.  @xref{Setting Output
Variables, , Setting Output Variables, autoconf, The Autoconf Manual},
and @ref{Generic Programs, , Generic Program Checks, autoconf, The
Autoconf Manual}.
@cvindex AC_SUBST
@cvindex AC_CHECK_TOOL
@cvindex AC_CHECK_PROG
@cvindex AC_CHECK_PROGS
@cvindex AC_PATH_PROG
@cvindex AC_PATH_PROGS

@end table


@node Invoking aclocal, Macros, Optional, configure
@section Auto-generating aclocal.m4

@cindex Invoking aclocal
@cindex aclocal, Invoking

Automake includes a number of Autoconf macros which can be used in your
package; some of them are actually required by Automake in certain
situations.  These macros must be defined in your @file{aclocal.m4};
otherwise they will not be seen by @code{autoconf}.

The @code{aclocal} program will automatically generate @file{aclocal.m4}
files based on the contents of @file{configure.in}.  This provides a
convenient way to get Automake-provided macros, without having to
search around.  Also, the @code{aclocal} mechanism is extensible for use
by other packages.

At startup, @code{aclocal} scans all the @file{.m4} files it can find,
looking for macro definitions.  Then it scans @file{configure.in}.  Any
mention of one of the macros found in the first step causes that macro,
and any macros it in turn requires, to be put into @file{aclocal.m4}.

The contents of @file{acinclude.m4}, if it exists, are also
automatically included in @file{aclocal.m4}.  This is useful for
incorporating local macros into @file{configure}.

@code{aclocal} accepts the following options:

@table @code
@item --acdir=@var{dir}
@opindex --acdir
Look for the macro files in @var{dir} instead of the installation
directory.  This is typically used for debugging.

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

@item -I @var{dir}
@opindex -I
Add the directory @var{dir} to the list of directories searched for
@file{.m4} files.

@item --output=@var{file}
@opindex --output
Cause the output to be put into @var{file} instead of @file{aclocal.m4}.

@item --print-ac-dir
@opindex --print-ac-dir
Prints the name of the directory which @code{aclocal} will search to
find the @file{.m4} files.  When this option is given, normal processing
is suppressed.  This option can be used by a package to determine where
to install a macro file.

@item --verbose
@opindex --verbose
Print the names of the files it examines.

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


@node Macros, Extending aclocal, Invoking aclocal, configure
@section Autoconf macros supplied with Automake

@c consider generating this node automatically from m4 files.

@table @code
@item AM_CONFIG_HEADER
Automake will generate rules to automatically regenerate the config
header.  If you do use this macro, you must create the file
@file{stamp-h.in} in your source directory.  It can be empty.
@cvindex AM_CONFIG_HEADER

@item AM_ENABLE_MULTILIB
This is used when a ``multilib'' library is being built.  A
@dfn{multilib} library is one that is built multiple times, once per
target flag combination.  This is only useful when the library is
intended to be cross-compiled.  The first optional argument is the name
of the @file{Makefile} being generated; it defaults to @samp{Makefile}.
The second option argument is used to find the top source directory; it
defaults to the empty string (generally this should not be used unless
you are familiar with the internals).

@item AM_FUNC_STRTOD
If the @code{strtod} function is not available, or does not work
correctly (like the one on SunOS 5.4), add @file{strtod.o} to output
variable @code{LIBOBJS}.
@cvindex AM_FUNC_STRTOD

@item AM_FUNC_ERROR_AT_LINE
If the function @code{error_at_line} is not found, then add
@file{error.o} to @code{LIBOBJS}.
@cvindex AM_FUNC_ERROR_AT_LINE

@item AM_FUNC_MKTIME
Check for a working @code{mktime} function.  If not found, add
@file{mktime.o} to @samp{LIBOBJS}.
@cvindex AM_FUNC_MKTIME

@item AM_FUNC_OBSTACK
Check for the GNU obstacks code; if not found, add @file{obstack.o} to
@samp{LIBOBJS}.
@cvindex AM_FUNC_OBSTACK

@item AM_C_PROTOTYPES
Check to see if function prototypes are understood by the compiler.  If
so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
@samp{ANSI2KNR} to the empty string.  Otherwise, set @samp{U} to
@samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}.  Automake uses these
values to implement automatic de-ANSI-fication.
@cvindex AM_C_PROTOTYPES

@item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
define @code{GWINSZ_IN_SYS_IOCTL}.  Otherwise @code{TIOCGWINSZ} can be
found in @file{<termios.h>}.
@cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL

@item AM_INIT_AUTOMAKE
Runs many macros that most @file{configure.in}'s need.  This macro has
two required arguments, the package and the version number.  By default
this macro @code{AC_DEFINE}'s @samp{PACKAGE} and @samp{VERSION}.  This
can be avoided by passing in a non-empty third argument.

@item AM_PATH_LISPDIR
Searches for the program @code{emacs}, and, if found, sets the output
variable @code{lispdir} to the full path to Emacs' site-lisp directory.
@cvindex AM_PATH_LISPDIR

@item AM_PROG_CC_STDC
If the C compiler in not in ANSI C mode by default, try to add an option
to output variable @code{CC} to make it so.  This macro tries various
options that select ANSI C on some system or another.  It considers the
compiler to be in ANSI C mode if it handles function prototypes correctly.

If you use this macro, you should check after calling it whether the C
compiler has been set to accept ANSI C; if not, the shell variable
@code{am_cv_prog_cc_stdc} is set to @samp{no}.  If you wrote your source
code in ANSI C, you can make an un-ANSIfied copy of it by using the
@code{ansi2knr} option (@pxref{ANSI}).

@item AM_PROG_LEX
@cindex HP-UX 10, lex problems
@cindex lex problems with HP-UX 10
Like @code{AC_PROG_LEX} with @code{AC_DECL_YYTEXT} (@pxref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}),
but uses the @code{missing} script on systems that do not have
@code{lex}.  @samp{HP-UX 10} is one such system.

@item AM_SANITY_CHECK
This checks to make sure that a file created in the build directory is
newer than a file in the source directory.  This can fail on systems
where the clock is set incorrectly.  This macro is automatically run
from @code{AM_INIT_AUTOMAKE}.

@item AM_SYS_POSIX_TERMIOS
@cvindex am_cv_sys_posix_termios
@cindex POSIX termios headers
@cindex termios POSIX headers
Check to see if POSIX termios headers and functions are available on the
system.  If so, set the shell variable @code{am_cv_sys_posix_termios} to
@samp{yes}.  If not, set the variable to @samp{no}.

@item AM_TYPE_PTRDIFF_T
@cvindex HAVE_PTRDIFF_T
@vindex ptrdiff_t
Define @samp{HAVE_PTRDIFF_T} if the type @samp{ptrdiff_t} is defined in
@file{<stddef.h>}.

@item AM_WITH_DMALLOC
@cvindex WITH_DMALLOC
@cindex dmalloc, support for
@opindex --with-dmalloc
Add support for the
@uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
package.  If the user configures with @samp{--with-dmalloc}, then define
@code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.

@item AM_WITH_REGEX
@cvindex WITH_REGEX
@opindex --with-regex
@cindex regex package
@cindex rx package
Adds @samp{--with-regex} to the @code{configure} command line.  If
specified (the default), then the @samp{regex} regular expression
library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
@samp{WITH_REGEX} is defined..  If @samp{--without-regex} is given, then
the @samp{rx} regular expression library is used, and @file{rx.o} is put
into @samp{LIBOBJS}.

@end table


@node Extending aclocal,  , Macros, configure
@section Writing your own aclocal macros

@cindex aclocal, extending
@cindex Extending aclocal

The @code{aclocal} program doesn't have any built-in knowledge of any
macros, so it is easy to extend it with your own macros.

This is mostly used for libraries which want to supply their own
Autoconf macros for use by other programs.  For instance the
@code{gettext} library supplies a macro @code{AM_GNU_GETTEXT} which
should be used by any package using @code{gettext}.  When the library is
installed, it installs this macro so that @code{aclocal} will find it.

A file of macros should be a series of @code{AC_DEFUN}'s.  The
@code{aclocal} programs also understands @code{AC_REQUIRE}, so it is
safe to put each macro in a separate file.  @xref{Prerequisite Macros, ,
, autoconf, The Autoconf Manual}, and @ref{Macro Definitions, , ,
autoconf, The Autoconf Manual}.

A macro file's name should end in @file{.m4}.  Such files should be
installed in @file{$(datadir)/aclocal}.


@node Top level, Programs, configure, Top
@chapter The top-level @file{Makefile.am}

@cindex SUBDIRS, explained

In non-flat packages, the top level @file{Makefile.am} must tell
Automake which subdirectories are to be built.  This is done via the
@code{SUBDIRS} variable.
@vindex SUBDIRS

The @code{SUBDIRS} macro holds a list of subdirectories in which
building of various sorts can occur.  Many targets (e.g. @code{all}) in
the generated @file{Makefile} will run both locally and in all specified
subdirectories.  Note that the directories listed in @code{SUBDIRS} are
not required to contain @file{Makefile.am}s; only @file{Makefile}s
(after configuration).  This allows inclusion of libraries from packages
which do not use Automake (such as @code{gettext}).  The directories
mentioned in @code{SUBDIRS} must be direct children of the current
directory.  For instance, you cannot put @samp{src/subdir} into
@code{SUBDIRS}.

In a deep package, the top-level @file{Makefile.am} is often very short.
For instance, here is the @file{Makefile.am} from the GNU Hello
distribution:

@example
EXTRA_DIST = BUGS ChangeLog.O README-alpha
SUBDIRS = doc intl po src tests
@end example

@cindex SUBDIRS, overriding
@cindex Overriding SUBDIRS

It is possible to override the @code{SUBDIRS} variable if, like in the
case of GNU @code{Inetutils}, you want to only build a subset of the
entire package.  In your @file{Makefile.am} include:

@example
SUBDIRS = @@SUBDIRS@@
@end example

Then in your @file{configure.in} you can specify:

@example
SUBDIRS = "src doc lib po"
AC_SUBST(SUBDIRS)
@end example

The upshot of this is that Automake is tricked into building the package
to take the subdirs, but doesn't actually bind that list until
@code{configure} is run.

Although the @code{SUBDIRS} macro can contain configure substitutions
(e.g. @samp{@@DIRS@@}); Automake itself does not actually examine the
contents of this variable.

If @code{SUBDIRS} is defined, then your @file{configure.in} must include
@code{AC_PROG_MAKE_SET}.

The use of @code{SUBDIRS} is not restricted to just the top-level
@file{Makefile.am}.  Automake can be used to construct packages of
arbitrary depth.

By default, Automake generates @file{Makefiles} which work depth-first
(@samp{postfix}).  However, it is possible to change this ordering.  You
can do this by putting @samp{.} into @code{SUBDIRS}.  For instance,
putting @samp{.}  first will cause a @samp{prefix} ordering of
directories.


@node Programs, Other objects, Top level, Top
@chapter Building Programs and Libraries

A large part of Automake's functionality is dedicated to making it easy
to build programs and libraries.

@menu
* A Program::                   Building a program
* A Library::                   Building a library
* LIBOBJS::                     Special handling for LIBOBJS and ALLOCA