@insertcopying
@end titlepage
-@c Define an index of configure output variables.
-@defcodeindex ov
-@c Define an index of configure variables.
-@defcodeindex cv
+@c Define an index of configure macros.
+@defcodeindex ac
@c Define an index of options.
@defcodeindex op
@c Define an index of targets.
@c Define an index of commands.
@defcodeindex cm
-@c Put the macros and variables into their own index.
-@c @syncodeindex fn cp
-@syncodeindex ov vr
-@syncodeindex cv vr
-@syncodeindex fn vr
+@c Put the macros in the function index.
+@syncodeindex ac fn
@c Put everything else into one index (arbitrarily chosen to be the concept index).
@syncodeindex op cp
Indices
-* Macro and Variable Index:: Index of Autoconf macros and Automake variables
+* Macro Index:: Index of Autoconf macros
+* Variable Index:: Index of Makefile variables
* General Index:: General index
@end detailmenu
fully GNU standards-compliant, and do not require @code{perl} in order
to be built.
-@cindex BUGS, reporting
-@cindex Reporting BUGS
+@cindex Bugs, reporting
+@cindex Reporting bugs
@cindex E-mail, bug reports
Mail suggestions and bug reports for Automake to
for compiling and linking programs to be generated.
@cindex Non-standard targets
-@cindex cvs-dist, non-standard example
+@cindex @code{cvs-dist}, non-standard example
@trindex cvs-dist
The variable definitions and rules in the @file{Makefile.am} are
behavior.
@cindex Append operator
+@cmindex +=
A special exception is that the GNU make append operator, @samp{+=}, is
supported. This operator appends its right hand argument to the variable
specified on the left. Automake will translate the operator into
it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
contents of @code{foo_SOURCES}.
-@cindex ## (special Automake comment)
+@cindex @code{##} (special Automake comment)
@cindex Special Automake comment
@cindex Comment, special to Automake
not want to use all the GNU conventions.
@cindex Strictness, defined
-@cindex Strictness, foreign
-@cindex foreign strictness
-@cindex Strictness, gnu
-@cindex gnu strictness
-@cindex Strictness, gnits
-@cindex gnits strictness
+@cindex Strictness, @code{foreign}
+@cindex @code{foreign} strictness
+@cindex Strictness, @code{gnu}
+@cindex @code{gnu} strictness
+@cindex Strictness, @code{gnits}
+@cindex @code{gnits} strictness
To this end, Automake supports three levels of @dfn{strictness}---the
strictness indicating how stringently Automake should check standards
built, and how they are installed. This scheme also supports
@code{configure} time determination of what should be built.
-@cindex _PROGRAMS primary variable
-@cindex PROGRAMS primary variable
-@cindex Primary variable, PROGRAMS
+@cindex @code{_PROGRAMS} primary variable
+@cindex @code{PROGRAMS} primary variable
+@cindex Primary variable, @code{PROGRAMS}
@cindex Primary variable, defined
+@vindex _PROGRAMS
At @code{make} time, certain variables are used to determine which
objects are to be built. The variable names are made of several pieces
list of programs which are to be compiled and linked.
@vindex PROGRAMS
-@cindex pkglibdir, defined
-@cindex pkgincludedir, defined
-@cindex pkgdatadir, defined
+@cindex @code{pkglibdir}, defined
+@cindex @code{pkgincludedir}, defined
+@cindex @code{pkgdatadir}, defined
@vindex pkglibdir
@vindex pkgincludedir
@vindex pkgdatadir
+@cindex @code{PACKAGE}, directory
A different set of names is used to decide where the built objects
should be installed. These names are prefixes to the primary which
indicate which standard directory should be used as the installation
and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
versions, but with @samp{$(PACKAGE)} appended. For instance,
@code{pkglibdir} is defined as @code{$(libdir)/$(PACKAGE)}.
-@cvindex PACKAGE, directory
-
-@cindex EXTRA_, prepending
+@cindex @code{EXTRA_}, prepending
For each primary, there is one additional variable named by prepending
@samp{EXTRA_} to the primary name. This variable is used to list
objects which may or may not be built, depending on what
must statically know the entire list of objects that may be built in
order to generate a @file{Makefile.in} that will work in all cases.
-@cindex EXTRA_PROGRAMS, defined
-@cindex Example, EXTRA_PROGRAMS
-@cindex cpio example
+@cindex @code{EXTRA_PROGRAMS}, defined
+@cindex Example, @code{EXTRA_PROGRAMS}
+@cindex @command{cpio} example
For instance, @code{cpio} decides at configure time which programs are
built. Some of the programs are installed in @code{bindir}, and some
html_DATA = automake.html
@end example
-@cindex noinst primary prefix, definition
+@cindex @code{noinst_} primary prefix, definition
+@vindex noinst_
The special prefix @samp{noinst} indicates that the objects in question
should be built but not installed at all. This is usually used for
objects required to build the rest of your package, for instance static
libraries (@pxref{A Library}), or helper scripts.
-@cindex check primary prefix, definition
+@cindex @code{check_} primary prefix, definition
+@vindex check_
The special prefix @samp{check} indicates that the objects in question
should not be built until the @code{make check} command is run. Those
provide a portability framework, but your @file{Makefile.in}s have been
ad-hoc. You want to make them bulletproof, so you turn to Automake.
-@cindex AM_INIT_AUTOMAKE, example use
+@cindex @code{AM_INIT_AUTOMAKE}, example use
The first step is to update your @file{configure.ac} to include the
commands that @code{automake} needs. The way to do this is to add an
doesn't use @code{gettext}, it doesn't want to build a shared library),
you're done with this part. That was easy!
-@cindex aclocal program, introduction
-@cindex aclocal.m4, preexisting
-@cindex acinclude.m4, defined
+@cindex @command{aclocal} program, introduction
+@cindex @file{aclocal.m4}, preexisting
+@cindex @file{acinclude.m4}, defined
Now you must regenerate @file{configure}. But to do that, you'll need
to tell @code{autoconf} how to find the new macro you've used. The
autoconf
@end example
-@cindex zardoz example
+@cindex @command{zardoz} example
Now it is time to write your @file{Makefile.am} for @code{zardoz}.
Since @code{zardoz} is a user program, you want to install it where the
two-liner. GNU Hello is internationalized, does option processing, and
has a manual and a test suite.
-@cindex configure.ac, from GNU Hello
-@cindex GNU Hello, configure.ac
-@cindex Hello, configure.ac
+@cindex @file{configure.ac}, from GNU Hello
+@cindex GNU Hello, @file{configure.ac}
+@cindex Hello, @file{configure.ac}
Here is the @file{configure.ac} from GNU Hello.
@strong{Please note:} The calls to @code{AC_INIT} and @code{AM_INIT_AUTOMAKE}
The script @file{hello} is generated by @code{configure}, and is the
only test case. @code{make check} will run this test.
-@cindex INCLUDES, example usage
+@cindex @code{INCLUDES}, example usage
+@vindex INCLUDES
Last we have @file{src/Makefile.am}, where all the real work is done:
@c FIXME: As all the Hello World excerpts in this manual, this
@node true
@section Building true and false
-@cindex Example, false and true
-@cindex false Example
-@cindex true Example
+@cindex Example, @command{false} and @command{true}
+@cindex @command{false} Example
+@cindex @command{true} Example
Here is another, trickier example. It shows how to generate two
programs (@code{true} and @code{false}) from the same source file
@node Invoking Automake
@chapter Creating a @file{Makefile.in}
-@cindex Multiple configure.ac files
-@cindex Invoking Automake
-@cindex Automake, invoking
+@cindex Multiple @file{configure.ac} files
+@cindex Invoking @command{automake}
+@cindex @command{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.
@file{configure} and you still have to run @code{autoconf} yourself for
this purpose.
-@cindex Automake options
-@cindex Options, Automake
+@cindex @command{automake} options
+@cindex Options, @command{automake}
@cindex Strictness, command line
-@code{automake} accepts the following options:
+@command{automake} accepts the following options:
@cindex Extra files distributed with Automake
@cindex Files distributed with Automake
-@cindex config.guess
+@cindex @file{config.guess}
@table @samp
@item -a
@node configure
@chapter Scanning @file{configure.ac}
-@cindex configure.ac, scanning
-@cindex Scanning configure.ac
+@cindex @file{configure.ac}, scanning
+@cindex Scanning @file{configure.ac}
Automake scans the package's @file{configure.ac} to determine certain
information about the package. Some @code{autoconf} macros are required
@cindex Automake requirements
@cindex Requirements of Automake
+@acindex AM_INIT_AUTOMAKE
The one real requirement of Automake is that your @file{configure.ac}
call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
required for proper Automake operation (@pxref{Macros}).
-@cvindex AM_INIT_AUTOMAKE
Here are the other macros which Automake requires but which are not run
by @code{AM_INIT_AUTOMAKE}:
@table @code
@item AC_CONFIG_FILES
@itemx AC_OUTPUT
+@acindex AC_CONFIG_FILES
+@acindex AC_OUTPUT
Automake uses these to determine which files to create (@pxref{Output, ,
Creating Output Files, autoconf, The Autoconf Manual}). A listed file
is considered to be an Automake generated @file{Makefile} if there
to be Automake generated.
Files created by @code{AC_CONFIG_FILES} are removed by @code{make distclean}.
-@cvindex AC_CONFIG_FILES
-@cvindex AC_OUTPUT
@end table
macros and tailor the generated @file{Makefile.in} appropriately.
Currently recognized macros and their effects are:
-@table @code
+@ftable @code
@item AC_CONFIG_HEADERS
Automake will generate rules to rebuild these headers. Older versions
of Automake required the use of @code{AM_CONFIG_HEADER}
(@pxref{Macros}); this is no longer the case today.
-@cvindex AC_CONFIG_HEADERS
@item AC_CONFIG_LINKS
Automake will generate rules to remove @file{configure} generated links on
@code{make distclean} and to distribute named source files as part of
@code{make dist}.
-@cvindex AC_CONFIG_LINKS
@item AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as
@file{py-compile}, @file{texinfo.tex}, and @file{ylwrap}.) Not all
scripts are always searched for; some scripts will only be sought if the
generated @file{Makefile.in} requires them.
-@cvindex AC_CONFIG_AUX_DIR
If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
-their @samp{standard} locations. For @file{mdate-sh},
+their standard locations. For @file{mdate-sh},
@file{texinfo.tex}, and @file{ylwrap}, the standard location is the
source directory corresponding to the current @file{Makefile.am}. For
the rest, the standard location is the first one of @file{.}, @file{..},
@item AC_CANONICAL_BUILD
@itemx AC_CANONICAL_HOST
@itemx AC_CANONICAL_TARGET
+@vindex build_triplet
+@vindex host_triplet
+@vindex target_triplet
Automake will ensure that @file{config.guess} and @file{config.sub}
exist. Also, the @file{Makefile} variables @samp{build_triplet},
@samp{host_triplet} and @samp{target_triplet} are introduced. See
@ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
The Autoconf Manual}.
-@cvindex AC_CANONICAL_BUILD
-@cvindex AC_CANONICAL_HOST
-@cvindex AC_CANONICAL_TARGET
-@vindex build_triplet
-@vindex host_triplet
-@vindex target_triplet
@item AC_LIBSOURCE
@itemx AC_LIBSOURCES
@itemx AC_LIBOBJ
+@vindex LIBOBJS
Automake will automatically distribute any file listed in
@code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
@file{file.c} will be distributed automatically by Automake. This
encompasses many macros like @code{AC_FUNC_ALLOCA},
@code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
-@cvindex AC_LIBOBJ
-@cvindex AC_LIBSOURCE
-@cvindex AC_LIBSOURCES
By the way, direct assignments to @code{LIBOBJS} are no longer
supported. You should always use @code{AC_LIBOBJ} for this purpose.
@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs. @code{LIBOBJS},
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 AC_PROG_FC
This is required if any Fortran 90/95 source is included. This macro is
distributed with Autoconf version 2.58 and later. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
-@cvindex AC_PROG_FC
@item AC_PROG_LIBTOOL
Automake will turn on processing for @code{libtool} (@pxref{Top, ,
Introduction, libtool, The Libtool Manual}).
-@cvindex AC_PROG_LIBTOOL
@item AC_PROG_YACC
+@vindex YACC
If a Yacc source file is seen, then you must either use this macro or
define the variable @samp{YACC} in @file{configure.ac}. The former is
preferred (@pxref{Particular Programs, , Particular Program Checks,
autoconf, The Autoconf Manual}).
-@cvindex AC_PROG_YACC
-@cvindex YACC
@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 AC_REQUIRE_AUX_FILE
-@cvindex AC_REQUIRE_AUX_FILE
@command{automake} will ensure each file for which this macro is
called exists in the aux directory, and will complain otherwise. It
will also automatically distribute the file. This macro should be
The Autoconf Manual}.
@item AC_SUBST
-@cvindex AC_SUBST
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}.
@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 defines the
+generated @file{Makefile.in}s. This macro defines the
@samp{MAINTAINER_MODE} conditional, which you can use in your own
-@file{Makefile.am}.
-@cvindex AM_MAINTAINER_MODE
+@file{Makefile.am}. @xref{maintainer-mode}.
@item m4_include
-@cvindex m4_include
Files included by @file{configure.ac} using this macro will be
detected by Automake and automatically distributed. They will also
appear as dependencies in @file{Makefile} rules.
opposed to macros installed in a system-wide directory, see
@ref{Invoking aclocal}).
-@end table
+@end ftable
@node Invoking aclocal
@section Auto-generating aclocal.m4
-@cindex Invoking aclocal
-@cindex aclocal, Invoking
+@cindex Invoking @command{aclocal}
+@cindex @command{aclocal}, Invoking
Automake includes a number of Autoconf macros which can be used in
your package (@pxref{Macros}); some of them are actually required by
@node aclocal options
@section aclocal options
-@cindex aclocal, Options
-@cindex Options, aclocal
+@cindex @command{aclocal}, Options
+@cindex Options, @command{aclocal}
@code{aclocal} accepts the following options:
@section Macro search path
@cindex Macro search path
-@cindex aclocal search path
+@cindex @command{aclocal} search path
By default, @command{aclocal} searches for @file{.m4} files in the following
directories, in this order:
@table @code
@item AM_CONFIG_HEADER
+@acindex AM_CONFIG_HEADER
Automake will generate rules to automatically regenerate the config
header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
today (@pxref{Optional}).
-@cvindex AM_CONFIG_HEADER
@item AM_ENABLE_MULTILIB
+@acindex AM_ENABLE_MULTILIB
This is used when a ``multilib'' library is being built. 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
@xref{Multilibs}.
@item AM_C_PROTOTYPES
+@acindex AM_C_PROTOTYPES
+@vindex ANSI2KNR
+@vindex U
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
+@acindex 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
+found in @file{<termios.h>}. This macro is obsolete, you should
+use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
@item AM_INIT_AUTOMAKE([OPTIONS])
@itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
+@acindex AM_INIT_AUTOMAKE
Runs many macros required for proper operation of the generated Makefiles.
+@vindex AUTOMAKE_OPTIONS
This macro has two forms, the first of which is preferred.
In this form, @code{AM_INIT_AUTOMAKE} is called with a
single argument --- a space-separated list of Automake options which should
be applied to every @file{Makefile.am} in the tree. The effect is as if
-each option were listed in @code{AUTOMAKE_OPTIONS}.
+each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
+@acindex AC_INIT
The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
arguments: the package and the version number. This form is
obsolete because the @var{package} and @var{version} can be obtained
form).
If your @file{configure.ac} has:
+
@example
AC_INIT(src/foo.c)
AM_INIT_AUTOMAKE(mumble, 1.5)
@end example
+
+@noindent
you can modernize it as follows:
+
@example
AC_INIT(mumble, 1.5)
AC_CONFIG_SRCDIR(src/foo.c)
four-argument form of @code{AC_INIT} --- supported in Autoconf versions
greater than 2.52g --- to provide the tarball name explicitly).
+@cindex @code{PACKAGE}, prevent definition
+@cindex @code{VERSION}, prevent definition
+@opindex no-define
By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and
@samp{VERSION}. This can be avoided by passing the @samp{no-define}
option, as in:
@end example
or by passing a third non-empty argument to the obsolete form.
-@cvindex PACKAGE, prevent definition
-@cvindex VERSION, prevent definition
-
@item AM_PATH_LISPDIR
+@acindex AM_PATH_LISPDIR
+@vindex EMACS
+@vindex 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.
use the @samp{--with-lispdir} option to @command{configure} to
explicitly set the correct path (if you're sure you have an @code{emacs}
that supports Emacs Lisp.
-@cvindex AM_PATH_LISPDIR
@item AM_PROG_AS
+@acindex AM_PROG_AS
+@vindex CCAS
+@vindex CCASFLAGS
Use this macro when you have assembly code in your project. This will
choose the assembler for you (by default the C compiler) and set
@code{CCAS}, and will also set @code{CCASFLAGS} if required.
@item AM_PROG_CC_C_O
+@acindex AM_PROG_CC_C_O
+@acindex AC_PROG_CC_C_O
This is like @code{AC_PROG_CC_C_O}, but it generates its results in
the manner required by automake. You must use this instead of
@code{AC_PROG_CC_C_O} when you need this functionality, that is, when
using per-target flags or subdir-objects with C sources.
@item AM_PROG_LEX
-@cindex HP-UX 10, lex problems
-@cindex lex problems with HP-UX 10
+@acindex AM_PROG_LEX
+@acindex AC_PROG_LEX
+@cindex HP-UX 10, @command{lex} problems
+@cindex @command{lex} problems with HP-UX 10
Like @code{AC_PROG_LEX} (@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_PROG_GCJ
+@acindex AM_PROG_GCJ
+@vindex GCJ
+@vindex GCJFLAGS
This macro finds the @code{gcj} program or causes an error. It sets
@samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
GNU Compiler Collection.
-@cvindex AM_PROG_GCJ
@item AM_SYS_POSIX_TERMIOS
-@cvindex am_cv_sys_posix_termios
+@acindex AM_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}.
+@samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
+you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
@item AM_WITH_DMALLOC
-@cvindex WITH_DMALLOC
-@cindex dmalloc, support for
+@acindex AM_WITH_DMALLOC
+@cindex @command{dmalloc}, support for
+@vindex WITH_DMALLOC
@opindex --with-dmalloc
Add support for the
@uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
@code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
@item AM_WITH_REGEX
-@cvindex WITH_REGEX
+@acindex AM_WITH_REGEX
+@vindex WITH_REGEX
@opindex --with-regex
@cindex regex package
@cindex rx package
them as implementation details; or better, do not consider them at all:
skip this section!
-@table @code
+@ftable @code
@item _AM_DEPENDENCIES
@itemx AM_SET_DEPDIR
@itemx AM_DEP_TRACK
where the clock is set incorrectly. This macro is automatically run
from @code{AM_INIT_AUTOMAKE}.
-@end table
+@end ftable
@node Extending aclocal
@section Writing your own aclocal macros
-@cindex aclocal, extending
-@cindex Extending aclocal
+@cindex @command{aclocal}, extending
+@cindex Extending @command{aclocal}
The @command{aclocal} program doesn't have any built-in knowledge of any
macros, so it is easy to extend it with your own macros.
Especially, any call to @code{AC_PREREQ} should be done inside the
defined macro, not at the beginning of the file.
-@cindex underquoted AC_DEFUN
-@cvindex AC_DEFUN
-@cvindex AC_PREREQ
+@cindex underquoted @code{AC_DEFUN}
+@acindex AC_DEFUN
+@acindex AC_PREREQ
Starting with Automake 1.8, @command{aclocal} will warn about all
underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
@node Future of aclocal
@section The Future of @command{aclocal}
-@cindex aclocal's scheduled death
+@cindex @command{aclocal}'s scheduled death
@command{aclocal} is expected to disappear. This feature really
should not be offered by Automake. Automake should focus on generating
@node Subdirectories
@section Recursing subdirectories
-@cindex SUBDIRS, explained
+@cindex @code{SUBDIRS}, explained
In packages with subdirectories, the top level @file{Makefile.am} must
tell Automake which subdirectories are to be built. This is done via
include_HEADERS = inc/stdio.h
@end example
-@cindex nobase_
+@vindex nobase_
+@cindex @code{nobase_} prefix
@cindex Path stripping, avoiding
@cindex Avoiding path stripping
nobase_include_HEADERS = sys/types.h
@end example
-@cindex nobase_ and dist_ or nodist_
-@cindex dist_ and nobase_
-@cindex nodist_ and nobase_
+@cindex @code{nobase_} and @code{dist_} or @code{nodist_}
+@cindex @code{dist_} and @code{nobase_}
+@cindex @code{nodist_} and @code{nobase_}
+@vindex dist_
+@vindex nodist_
@samp{nobase_} should be specified first when used in conjunction with
either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
@section Nesting Packages
@cindex Nesting packages
@cindex Subpackages
-@cvindex AC_CONFIG_SUBDIRS
-@cvindex AC_CONFIG_AUX_DIR
+@acindex AC_CONFIG_SUBDIRS
+@acindex AC_CONFIG_AUX_DIR
In the GNU Build System, packages can be nested to arbitrary depth.
@node Program Sources
@subsection Defining program sources
-@cindex PROGRAMS, bindir
+@cindex @code{PROGRAMS}, @code{bindir}
+@vindex _PROGRAMS
@vindex bin_PROGRAMS
@vindex sbin_PROGRAMS
@vindex libexec_PROGRAMS
This causes each mentioned @samp{.c} file to be compiled into the
corresponding @samp{.o}. Then all are linked to produce @file{hello}.
-@cindex _SOURCES primary, defined
-@cindex SOURCES primary, defined
-@cindex Primary variable, SOURCES
+@cindex @code{_SOURCES} primary, defined
+@cindex @code{SOURCES} primary, defined
+@cindex Primary variable, @code{SOURCES}
+@vindex _SOURCES
If @samp{hello_SOURCES} is not specified, then it defaults to the single
file @file{hello.c} (@pxref{Default _SOURCES}).
can share a single source file, which must be listed in each
@samp{_SOURCES} definition.
-@cindex Header files in _SOURCES
-@cindex _SOURCES and header files
+@cindex Header files in @code{_SOURCES}
+@cindex @code{_SOURCES} and header files
Header files listed in a @samp{_SOURCES} definition will be included in
the distribution but otherwise ignored. In case it isn't obvious, you
@vindex LDADD
@vindex AM_LDFLAGS
-@cindex prog_LDADD, defined
+@cindex @code{prog_LDADD}, defined
Sometimes, multiple programs are built in one directory but do not share
the same link-time requirements. In this case, you can use the
written in lowercase) to override the global @code{LDADD}. If this
variable exists for a given program, then that program is not linked
using @code{LDADD}.
-@vindex _LDADD
+@vindex maude_LDADD
For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
linked against the library @file{libcpio.a}. However, @code{rmt} is
rmt_SOURCES = @dots{}
@end example
-@cindex _LDFLAGS, defined
-
+@cindex @code{_LDFLAGS}, defined
+@vindex maude_LDFLAGS
@samp{@var{prog}_LDADD} is inappropriate for passing program-specific
linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
@samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
this purpose.
-@vindex _LDFLAGS
-
-@cindex _DEPENDENCIES, defined
+@cindex @code{_DEPENDENCIES}, defined
+@vindex maude_DEPENDENCIES
It is also occasionally useful to have a program depend on some other
target which is not actually part of that program. This can be done
using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
@subsubsection Conditional compilation using @code{_LDADD} substitutions
-@cindex EXTRA_prog_SOURCES, defined
+@cindex @code{EXTRA_prog_SOURCES}, defined
Automake must know all the source files that could possibly go into a
program, even if not all the files are built in every circumstance. Any
@subsubsection Conditional programs using @code{configure} substitutions
+@vindex EXTRA_PROGRAMS
+@cindex @code{EXTRA_PROGRAMS}, defined
In this case, you must notify Automake of all the programs that can
possibly be built, but at the same time cause the generated
@file{Makefile.in} to use the programs specified by @code{configure}.
This is done by having @code{configure} substitute values into each
@samp{_PROGRAMS} definition, while listing all optionally built programs
in @code{EXTRA_PROGRAMS}.
-@vindex EXTRA_PROGRAMS
-@cindex EXTRA_PROGRAMS, defined
@example
bin_PROGRAMS = cpio pax $(MT)
@node A Library
@section Building a library
-@cindex _LIBRARIES primary, defined
-@cindex LIBRARIES primary, defined
-@cindex Primary variable, LIBRARIES
+@cindex @code{_LIBRARIES} primary, defined
+@cindex @code{LIBRARIES} primary, defined
+@cindex Primary variable, @code{LIBRARIES}
+@vindex _LIBRARIES
@vindex lib_LIBRARIES
@vindex pkglib_LIBRARIES
variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
not @samp{liblob.a_SOURCES}.
-@cindex _LIBADD primary, defined
-@cindex LIBADD primary, defined
-@cindex Primary variable, LIBADD
-
+@vindex maude_LIBADD
Extra objects can be added to a library using the
@samp{@var{library}_LIBADD} variable. This should be used for objects
determined by @code{configure}. Again from @code{cpio}:
-@vindex _LIBADD
-@vindex LIBADD
@example
libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
@node Libtool Concept
@subsection The Libtool Concept
-@cindex libtool, introduction
+@cindex @command{libtool}, introduction
@cindex libtool library, definition
-@cindex suffix .la, defined
-@cindex .la suffix, defined
+@cindex suffix @file{.la}, defined
+@cindex @file{.la} suffix, defined
Libtool abstracts shared and static libraries into a unified
concept henceforth called @dfn{libtool libraries}. Libtool libraries
tune the default, @xref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
macro, libtool, The Libtool Manual}.)
-@cindex suffix .lo, defined
+@cindex suffix @file{.lo}, defined
Because object files for shared and static libraries must be compiled
differently, libtool is also used during compilation. Object files
built by libtool are called @dfn{libtool objects}: these are files
building source files conditionally (@pxref{Conditional Libtool
Sources}).
-@cindex libltdl, introduction
+@cindex @file{libltdl}, introduction
People considering writing a plug-in system, with dynamically loaded
modules, should look into @file{libltdl}: libtool's dlopening library
@node Libtool Libraries
@subsection Building Libtool Libraries
-@cindex _LTLIBRARIES primary, defined
-@cindex LTLIBRARIES primary, defined
-@cindex Primary variable, LTLIBRARIES
+@cindex @code{_LTLIBRARIES} primary, defined
+@cindex @code{LTLIBRARIES} primary, defined
+@cindex Primary variable, @code{LTLIBRARIES}
@cindex Example of shared libraries
@vindex lib_LTLIBRARIES
@vindex pkglib_LTLIBRARIES
+@vindex _LTLIBRARIES
Automake uses libtool to build libraries declared with the
@samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a
@subsection Libtool Modules
@cindex modules, libtool
@cindex libtool modules
-@cindex -module, libtool
+@cindex @code{-module}, libtool
These are libtool libraries meant to be dlopened. They are
indicated to libtool by passing @code{-module} at link-time.
@node Libtool Flags
@subsection _LIBADD and _LDFLAGS
-@cindex _LIBADD, libtool
-@cindex _LDFLAGS, libtool
+@cindex @code{_LIBADD}, libtool
+@cindex @code{_LDFLAGS}, libtool
As shown in previous sections, the @samp{@var{library}_LIBADD}
variable should be used to list extra libtool objects (@file{.lo}
@vindex LIBOBJS
@vindex LTALLOCA
@vindex ALLOCA
-@cvindex AC_LIBOBJ
+@acindex AC_LIBOBJ
Where an ordinary library might include @code{$(LIBOBJS)} or
@code{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
@subsection Common Issues Related to Libtool's Use
@subsubsection @code{required file `./ltmain.sh' not found}
-@cindex ltmain.sh not found
-@cindex libtoolize, no longer run by Automake
-@cindex libtoolize and autoreconf
-@cindex autoreconf and libtoolize
-@cindex bootstrap.sh and autoreconf
-@cindex autogen.sh and autoreconf
+@cindex @file{ltmain.sh} not found
+@cindex @command{libtoolize}, no longer run by @command{automake}
+@cindex @command{libtoolize} and @command{autoreconf}
+@cindex @command{autoreconf} and @command{libtoolize}
+@cindex @file{bootstrap.sh} and @command{autoreconf}
+@cindex @file{autogen.sh} and @command{autoreconf}
Libtool comes with a tool called @command{libtoolize} that will
install libtool's supporting files into a package. Running this
libraries; the documentation below notes situations where programs and
libraries differ.
-@table @samp
+@vtable @samp
@item maude_SOURCES
This variable, if it exists, lists all the source files which are
compiled to build the program. These files are added to the
This facility is rarely needed in practice,
and we recommend avoiding it until you find it is required.
-@end table
+@end vtable
@node Default _SOURCES
@section Default @code{_SOURCES}
implementation for functions that are missing or broken on the host
system. They are substituted by @file{configure}.
-@cvindex AC_LIBOBJ
+@acindex AC_LIBOBJ
These variables are defined by Autoconf macros such as
@code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
populate @code{$(LIBOBJS)}.
-@cvindex AC_LIBSOURCE
+@acindex AC_LIBSOURCE
Using these variables is very similar to doing conditional compilation
using @code{AC_SUBST} variables, as described in @ref{Conditional
AC_OUTPUT
@end example
-@cvindex AC_CONFIG_LIBOBJ_DIR
+@acindex AC_CONFIG_LIBOBJ_DIR
The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
of these object files are to be found in the @file{lib/} directory.
the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}).
+@vindex YFLAGS
+@vindex AM_YFLAGS
When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
@samp{AM_YFLAGS}. The former is a user variable and the latter is
intended for the @file{Makefile.am} author.
autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
(@pxref{Macros}) is recommended.
+@vindex LFLAGS
+@vindex AM_LFLAGS
When @code{lex} is invoked, it is passed @samp{LFLAGS} and
@samp{AM_LFLAGS}. The former is a user variable and the latter is
intended for the @file{Makefile.am} author.
@code{maintainer-mode} is enabled, or when the files have been erased.
-@cindex ylwrap
-@cindex yacc, multiple parsers
-@cindex Multiple yacc parsers
-@cindex Multiple lex lexers
-@cindex lex, multiple lexers
+@cindex @command{ylwrap}
+@cindex @command{yacc}, multiple parsers
+@cindex Multiple @command{yacc} parsers
+@cindex Multiple @command{lex} lexers
+@cindex @command{lex}, multiple lexers
Automake makes it possible to include multiple @code{yacc} (or
of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
(@file{*.S}).
-The variable @code{CCAS} holds the name of the compiler used to build
-assembly code. This compiler must work a bit like a C compiler; in
-particular it must accept @samp{-c} and @samp{-o}. The value of
-@code{CCASFLAGS} (and @code{CPPFLAGS} for preprocessed files) is passed
-to the compilation.
@vindex CCAS
@vindex CCASFLAGS
@vindex CPPFLAGS
+@vindex AM_CCASFLAGS
+@vindex AM_CPPFLAGS
+The variable @code{CCAS} holds the name of the compiler used to build
+assembly code. This compiler must work a bit like a C compiler; in
+particular it must accept @samp{-c} and @samp{-o}. The values of
+@code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
+definition) is passed to the compilation. For preprocessed files,
+@code{CPPFLAGS} and @code{AM_CPPFLAGS} are also used.
-You are required to set @code{CCAS} and @code{CCASFLAGS} via
-@file{configure.ac}. The autoconf macro @code{AM_PROG_AS} will do this
-for you. Unless they are already set, it simply sets @code{CCAS} to the
-C compiler and @code{CCASFLAGS} to the C compiler flags.
+The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
+@code{CCASFLAGS} for you (unless they are already set, it simply sets
+@code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
+flags), but you are free to define these variables by other means.
Only the suffixes @file{.s} and @file{.S} are recognized by
@code{automake} as being files containing assembly code.
@samp{-l}) to pass to the automatically selected linker in order to link
in the appropriate Fortran 77 intrinsic and run-time libraries.
-@cindex FLIBS, defined
+@cindex @code{FLIBS}, defined
+@vindex FLIBS
These extra Fortran 77 linker flags are supplied in the output variable
@code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
supplied with newer versions of Autoconf (Autoconf version 2.13 and
code will be formatted in a particular way; see the @code{ansi2knr} man
page for details.
+@acindex AM_C_PROTOTYPES
Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
and @file{ansi2knr.1} to be in the same package as the ANSI C source;
these files are distributed with Automake. Also, the package
@file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
(@pxref{Macros}).
-@cvindex AM_C_PROTOTYPES
Automake also handles finding the @code{ansi2knr} support files in some
other directory in the current package. This is done by prepending the
invoke your compiler, dependency tracking will simply be disabled for
your build.
-@cindex depcomp
+@cindex @command{depcomp}
Experience with earlier versions of Automake (@pxref{Dependency
Tracking Evolution}) taught us that it is not reliable to generate
@node Scripts
@section Executable Scripts
-@cindex _SCRIPTS primary, defined
-@cindex SCRIPTS primary, defined
-@cindex Primary variable, SCRIPTS
+@cindex @code{_SCRIPTS} primary, defined
+@cindex @code{SCRIPTS} primary, defined
+@cindex Primary variable, @code{SCRIPTS}
+@vindex _SCRIPTS
It is possible to define and install programs which are scripts. Such
programs are listed using the @samp{SCRIPTS} primary name. Automake
dist_sbin_SCRIPTS = my_script
@end example
-@cindex SCRIPTS, installation directories
+@cindex @code{SCRIPTS}, installation directories
@cindex Installing scripts
@vindex bin_SCRIPTS
@node Headers
@section Header files
-@cindex _HEADERS primary, defined
-@cindex HEADERS primary, defined
-@cindex Primary variable, HEADERS
-
+@cindex @code{_HEADERS} primary, defined
+@cindex @code{HEADERS} primary, defined
+@cindex Primary variable, @code{HEADERS}
+@vindex _HEADERS
@vindex noinst_HEADERS
-@cindex HEADERS, installation directories
+@cindex @code{HEADERS}, installation directories
@cindex Installing headers
@vindex include_HEADERS
@vindex oldinclude_HEADERS
@node Data
@section Architecture-independent data files
-@cindex _DATA primary, defined
-@cindex DATA primary, defined
-@cindex Primary variable, DATA
+@cindex @code{_DATA} primary, defined
+@cindex @code{DATA} primary, defined
+@cindex Primary variable, @code{DATA}
+@vindex _DATA
Automake supports the installation of miscellaneous data files using the
@samp{DATA} family of variables.
rule to build @file{foo.h} first by lack of dependency information.
@vindex BUILT_SOURCES
-@cindex BUILT_SOURCES, defined
+@cindex @code{BUILT_SOURCES}, defined
The @code{BUILT_SOURCES} variable is a workaround for this problem. A
source file listed in @code{BUILT_SOURCES} is made on @code{make all}
@node Emacs Lisp
@section Emacs Lisp
-@cindex _LISP primary, defined
-@cindex LISP primary, defined
-@cindex Primary variable, LISP
+@cindex @code{_LISP} primary, defined
+@cindex @code{LISP} primary, defined
+@cindex Primary variable, @code{LISP}
-@vindex LISP
+@vindex _LISP
@vindex lisp_LISP
@vindex noinst_LISP
@node Java
@section Java
-@cindex _JAVA primary, defined
-@cindex JAVA primary, defined
-@cindex Primary variable, JAVA
+@cindex @code{_JAVA} primary, defined
+@cindex @code{JAVA} primary, defined
+@cindex Primary variable, @code{JAVA}
Automake provides some minimal support for Java compilation with the
@samp{JAVA} primary.
compiled with @code{JAVAC} at build time. By default, @file{.class}
files are not included in the distribution.
-@cindex JAVA restrictions
-@cindex Restrictions for JAVA
+@cindex @code{JAVA} restrictions
+@cindex Restrictions for @code{JAVA}
Currently Automake enforces the restriction that only one @samp{_JAVA}
primary can be used in a given @file{Makefile.am}. The reason for this
@node Python
@section Python
-@cindex _PYTHON primary, defined
-@cindex PYTHON primary, defined
-@cindex Primary variable, PYTHON
-
+@cindex @code{_PYTHON} primary, defined
+@cindex @code{PYTHON} primary, defined
+@cindex Primary variable, @code{PYTHON}
+@vindex _PYTHON
Automake provides support for Python compilation with the @samp{PYTHON}
primary.
@node Texinfo
@section Texinfo
-@cindex _TEXINFOS primary, defined
-@cindex TEXINFOS primary, defined
-@cindex Primary variable, TEXINFOS
+@cindex @code{_TEXINFOS} primary, defined
+@cindex @code{TEXINFOS} primary, defined
+@cindex Primary variable, @code{TEXINFOS}
@cindex HTML output using Texinfo
@cindex PDF output using Texinfo
@cindex PS output using Texinfo
@cindex DVI output using Texinfo
+@vindex _TEXINFOS
+@vindex info_TEXINFOS
If the current directory contains Texinfo source, you must declare it
with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
here. Any Texinfo source file must end in the @file{.texi},
@file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
for new manuals.
-@vindex TEXINFOS
-@vindex info_TEXINFOS
Automake generates rules to build @file{.info}, @file{.dvi}, @file{.ps},
@file{.pdf} and @file{.html} files from your Texinfo sources.
The other files can be built on request by @code{make dvi}, @code{make ps},
@code{make pdf} and @code{make html}.
-@cindex Texinfo flag, VERSION
-@cindex Texinfo flag, UPDATED
-@cindex Texinfo flag, EDITION
-@cindex Texinfo flag, UPDATED-MONTH
+@cindex Texinfo flag, @code{VERSION}
+@cindex Texinfo flag, @code{UPDATED}
+@cindex Texinfo flag, @code{EDITION}
+@cindex Texinfo flag, @code{UPDATED-MONTH}
-@cindex VERSION Texinfo flag
-@cindex UPDATED Texinfo flag
-@cindex EDITION Texinfo flag
-@cindex UPDATED-MONTH Texinfo flag
+@cindex @code{VERSION} Texinfo flag
+@cindex @code{UPDATED} Texinfo flag
+@cindex @code{EDITION} Texinfo flag
+@cindex @code{UPDATED-MONTH} Texinfo flag
-@cindex mdate-sh
+@cindex @file{mdate-sh}
If the @file{.texi} file @code{@@include}s @file{version.texi}, then
that file will be automatically generated. The file @file{version.texi}
hello_TEXINFOS = gpl.texi
@end example
-@cindex texinfo.tex
+@cindex @file{texinfo.tex}
By default, Automake requires the file @file{texinfo.tex} to appear in
the same directory as the Texinfo source (this can be changed using the
@code{TEXINFO_TEX} is preferable, however, because that allows the
@code{dvi}, @code{ps}, and @code{pdf} targets to still work.
-@cindex Rule, install-info
-@cindex Rule, noinstall-info
-@cindex Target, install-info
-@cindex Target, noinstall-info
-@cindex install-info target
-@cindex noinstall-info target
+@cindex Option, @code{noinstall-info}
+@cindex Target, @code{install-info}
+@cindex @code{install-info} target
+@cindex @code{noinstall-info} option
@opindex no-installinfo
@trindex install-info
@node Man pages
@section Man pages
-@cindex _MANS primary, defined
-@cindex MANS primary, defined
-@cindex Primary variable, MANS
+@cindex @code{_MANS} primary, defined
+@cindex @code{MANS} primary, defined
+@cindex Primary variable, @code{MANS}
+@vindex _MANS
+@vindex man_MANS
A package can also include man pages (but see the GNU standards on this
matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
pages are declared using the @samp{MANS} primary. Generally the
@code{man_MANS} variable is used. Man pages are automatically installed in
the correct subdirectory of @code{mandir}, based on the file extension.
-@vindex MANS
-@vindex man_MANS
File extensions such as @samp{.1c} are handled by looking for the valid
part of the extension and using that to determine the correct
In this case, @file{rename.man} will be renamed to @file{rename.1} when
installed, but the other files will keep their names.
-@cindex Rule, install-man
-@cindex Rule, noinstall-man
-@cindex Target, install-man
-@cindex Target, noinstall-man
-@cindex install-man target
-@cindex noinstall-man target
+@cindex Target, @code{install-man}
+@cindex Option, @code{noinstall-man}
+@cindex @code{install-man} target
+@cindex @code{noinstall-man} option
+@opindex no-installman
+@trindex install-man
@c Use @samp{make install} per documentation: (texi)code.
By default, man pages are installed by @samp{make install}. However,
@code{no-installman} option will prevent the man pages from being
installed by default. The user can still explicitly install them via
@samp{make install-man}.
-@opindex no-installman
-@trindex install-man
-Here is how the man pages are handled in GNU @code{cpio} (which includes
-both Texinfo documentation and man pages):
+Here is how the man pages are handled in GNU @command{cpio} (which
+includes both Texinfo documentation and man pages):
@example
man_MANS = cpio.1 mt.1
@chapter What Gets Installed
@cindex Installation support
-@cindex make install support
+@cindex @code{make install} support
@section Basics of installation
@node Clean
@chapter What Gets Cleaned
-@cindex make clean support
+@cindex @code{make clean} support
The GNU Makefile Standards specify a number of different clean rules.
See @xref{Standard Targets, , Standard Targets for Users, standards,
@section Basics of distribution
-@cindex make dist
+@cindex @code{make dist}
+@vindex PACKAGE
+@vindex VERSION
+@trindex dist
The @code{dist} rule in the generated @file{Makefile.in} can be used
to generate a gzip'd @code{tar} file and other flavors of archive for
distribution. The files is named based on the @samp{PACKAGE} and
@samp{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
(@pxref{Macros}); more precisely the gzip'd @code{tar} file is named
@samp{@var{package}-@var{version}.tar.gz}.
-@cvindex PACKAGE
-@cvindex VERSION
-@trindex dist
+@vindex GZIP_ENV
You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
is run. The default setting is @samp{--best}.
+@cindex @code{m4_include}, distribution
+@cindex @code{include}, distribution
+@acindex m4_include
+@cmindex include
For the most part, the files to distribute are automatically found by
Automake: all source files are automatically included in a distribution,
as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
helper scripts installed with @samp{automake --add-missing} are also
distributed.
-@cvindex m4_include, distribution
-
+@vindex EXTRA_DIST
Still, sometimes there are files which must be distributed, but which
are not covered in the automatic rules. These files should be listed in
the @code{EXTRA_DIST} variable. You can mention files from
Please note that this will also copy @emph{everything} in the directory,
including CVS/RCS version control files. We recommend against using
this feature.
-@vindex EXTRA_DIST
+@vindex SUBDIRS
+@vindex DIST_SUBDIRS
If you define @code{SUBDIRS}, Automake will recursively include the
subdirectories in the distribution. If @code{SUBDIRS} is defined
conditionally (@pxref{Conditionals}), Automake will normally include
conditionally, you can set the variable @code{DIST_SUBDIRS} to the
exact list of subdirectories to include in the distribution
(@pxref{Conditional Subdirectories}).
-@vindex DIST_SUBDIRS
@section Fine-grained distribution control
+@vindex dist_
+@vindex nodist_
Sometimes you need tighter control over what does @emph{not} go into the
distribution; for instance you might have source files which are
generated and which you do not want to distribute. In this case
prefixed with @samp{dist_} to add the listed files to the distribution.
Similarly, @samp{nodist_} can be used to omit the files from the
distribution.
-@vindex dist_
-@vindex nodist_
As an example, here is how you would cause some data to be distributed
while leaving some source code out of the distribution:
@section Checking the distribution
-@cindex make distcheck
-@cindex make distcleancheck
+@cindex @code{make distcheck}
+@cindex @code{make distcleancheck}
@vindex distcleancheck_listfiles
-@cindex make distuninstallcheck
+@cindex @code{make distuninstallcheck}
@vindex distuninstallcheck_listfiles
+@trindex distcheck
Automake also generates a @code{distcheck} rule which can be of help
to ensure that a given distribution will actually work.
@code{distcheck} makes a distribution, then tries to do a @code{VPATH}
build, run the test suite, and finally make another tarfile to ensure the
distribution is self-contained.
-@trindex distcheck
+@vindex DISTCHECK_CONFIGURE_FLAGS
Building the package involves running @code{./configure}. If you need
to supply additional flags to @code{configure}, define them in the
@code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
@file{Makefile.am}, or on the command line when invoking @code{make}.
-@vindex DISTCHECK_CONFIGURE_FLAGS
+@trindex distcheck-hook
If the @code{distcheck-hook} rule is defined in your top-level
@file{Makefile.am}, then it will be invoked by @code{distcheck} after
the new distribution has been unpacked, but before the unpacked copy
@file{Makefile.am}, but the @code{DISTCHECK_CONFIGURE_FLAGS} are
passed down to the @code{configure} script of the subpackage.
-
+@trindex distcleancheck
+@vindex DISTCLEANFILES
+@vindex distcleancheck_listfiles
Speaking about potential distribution errors, @code{distcheck} will also
ensure that the @code{distclean} rule actually removes all built
files. This is done by running @code{make distcleancheck} at the end of
running @code{$(distcleancheck_listfiles)}. Usually this check will
find generated files that you forgot to add to the @code{DISTCLEANFILES}
variable (@pxref{Clean}).
-@trindex distcleancheck
The @code{distcleancheck} behavior should be OK for most packages,
otherwise you have the possibility to override the definition of
@code{$(distcleancheck_listfiles)} variable. For instance to disable
@code{distcleancheck} completely, add the following rule to your
top-level @file{Makefile.am}:
-@vindex distcleancheck_listfiles
@example
distcleancheck:
@chapter Support for test suites
@cindex Test suites
-@cindex make check
+@cindex @code{make check}
+@trindex check
Automake supports two forms of test suites.
Automake generates rules to automatically rebuild @file{Makefile}s,
@file{configure}, and other derived files like @file{Makefile.in}.
-@cvindex AM_MAINTAINER_MODE
+@acindex AM_MAINTAINER_MODE
If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
these automatic rebuilding rules are only enabled in maintainer mode.
@itemx @code{gnu}
@itemx @code{foreign}
@itemx @code{cygnus}
-@cindex Option, gnits
-@cindex Option, gnu
-@cindex Option, foreign
-@cindex Option, cygnus
+@cindex Option, @code{gnits}
+@cindex Option, @code{gnu}
+@cindex Option, @code{foreign}
+@cindex Option, @code{cygnus}
+@opindex gnits
+@opindex gnu
+@opindex foreign
+@opindex cygnus
Set the strictness as appropriate. The @code{gnits} option also implies
@code{readme-alpha} and @code{check-news}.
@item @code{ansi2knr}
@itemx @code{@var{path}/ansi2knr}
-@cindex Option, ansi2knr
+@cindex Option, @code{ansi2knr}
+@opindex ansi2knr
Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
path, the generated @file{Makefile.in} will look in the specified
directory to find the @file{ansi2knr} program. The path should be a
currently does not check this).
@item @code{check-news}
-@cindex Option, check-news
+@cindex Option, @code{check-news}
+@opindex check-news
Cause @code{make dist} to fail unless the current version number appears
in the first few lines of the @file{NEWS} file.
@item @code{dejagnu}
-@cindex Option, dejagnu
+@cindex Option, @code{dejagnu}
+@opindex dejagnu
Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
@item @code{dist-bzip2}
-@cindex Option, dist-bzip2
+@cindex Option, @code{dist-bzip2}
+@opindex dist-bzip2
Hook @code{dist-bzip2} to @code{dist}.
@trindex dist-bzip2
@item @code{dist-shar}
-@cindex Option, dist-shar
+@cindex Option, @code{dist-shar}
+@opindex dist-shar
Hook @code{dist-shar} to @code{dist}.
@trindex dist-shar
@item @code{dist-zip}
-@cindex Option, dist-zip
+@cindex Option, @code{dist-zip}
+@opindex dist-zip
Hook @code{dist-zip} to @code{dist}.
@trindex dist-zip
@item @code{dist-tarZ}
-@cindex Option, dist-tarZ
+@cindex Option, @code{dist-tarZ}
+@opindex dist-tarZ
Hook @code{dist-tarZ} to @code{dist}.
@trindex dist-tarZ
@item @code{filename-length-max=99}
-@cindex Option, filename-length-max=99
-@trindex filename-length-max=99
+@cindex Option, @code{filename-length-max=99}
+@opindex filename-length-max=99
Abort if filenames longer than 99 characters are found during
@code{make dist}. Such long filenames are generally considered not to
be portable in tarballs. See the @code{tar-v7} and @code{tar-ustar}
@file{configure.ac}, it will be ignored otherwise.
@item @code{no-define}
-@cindex Option, no-define
+@cindex Option, @code{no-define}
+@opindex no-define
This options is meaningful only when passed as an argument to
@code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
@code{VERSION} variables to be @code{AC_DEFINE}d.
@item @code{no-dependencies}
-@cindex Option, no-dependencies
+@cindex Option, @code{no-dependencies}
+@opindex no-dependencies
This is similar to using @samp{--include-deps} on the command line, but
is useful for those situations where you don't have the necessary bits
to make automatic dependency tracking work @xref{Dependencies}. In this
case the effect is to effectively disable automatic dependency tracking.
@item @code{no-dist}
-@cindex Option, no-dist
+@cindex Option, @code{no-dist}
+@opindex no-dist
Don't emit any code related to @code{dist} target. This is useful
when a package has its own method for making distributions.
@item @code{no-dist-gzip}
-@cindex Option, no-dist-gzip
+@cindex Option, @code{no-dist-gzip}
+@opindex no-dist-gzip
Do not hook @code{dist-gzip} to @code{dist}.
@trindex no-dist-gzip
@item @code{no-exeext}
-@cindex Option, no-exeext
+@cindex Option, @code{no-exeext}
+@opindex no-exeext
If your @file{Makefile.am} defines a rule for target @samp{foo}, it
will override a rule for a target named @samp{foo$(EXEEXT)}. This is
necessary when @code{EXEEXT} is found to be empty. However, by
executables.
@item @code{no-installinfo}
-@cindex Option, no-installinfo
+@cindex Option, @code{no-installinfo}
+@opindex no-installinfo
The generated @file{Makefile.in} will not cause info pages to be built
or installed by default. However, @code{info} and @code{install-info}
targets will still be available. This option is disallowed at
@trindex install-info
@item @code{no-installman}
-@cindex Option, no-installman
+@cindex Option, @code{no-installman}
+@opindex no-installman
The generated @file{Makefile.in} will not cause man pages to be
installed by default. However, an @code{install-man} target will still
be available for optional installation. This option is disallowed at
@trindex install-man
@item @code{nostdinc}
-@cindex Option, nostdinc
+@cindex Option, @code{nostdinc}
+@opindex nostdinc
This option can be used to disable the standard @samp{-I} options which
are ordinarily automatically provided by Automake.
@item @code{no-texinfo.tex}
-@cindex Option, no-texinfo
+@cindex Option, @code{no-texinfo.tex}
+@opindex no-texinfo.tex
Don't require @file{texinfo.tex}, even if there are texinfo files in
this directory.
@item @code{readme-alpha}
-@cindex Option, readme-alpha
+@cindex Option, @code{readme-alpha}
+@opindex readme-alpha
If this release is an alpha release, and the file @file{README-alpha}
exists, then it will be added to the distribution. If this option is
given, version numbers are expected to follow one of two forms. The
letter; it should be omitted for non-alpha releases.
@item @code{std-options}
-@cindex Options, std-options
-@cindex make installcheck
+@cindex Options, @code{std-options}
+@cindex @code{make installcheck}, testing @code{--help} and @code{--version}
+@cindex @code{--help} check
+@cindex @code{--version} check
+@opindex std-options
+
Make the @code{installcheck} rule check that installed scripts and
programs support the @code{--help} and @code{--version} options.
This also provides a basic check that the program's
@end example
@item @code{subdir-objects}
+@cindex Options, @code{subdir-objects}
+@opindex subdir-objects
If this option is specified, then objects are placed into the
subdirectory of the build directory corresponding to the subdirectory of
the source file. For instance if the source file is
@item @code{tar-v7}
@itemx @code{tar-ustar}
@itemx @code{tar-pax}
-@cindex Option, tar-v7
-@cindex Option, tar-ustar
-@cindex Option, tar-pax
-@cindex tar formats
-@cindex v7 tar format
+@cindex Option, @code{tar-v7}
+@cindex Option, @code{tar-ustar}
+@cindex Option, @code{tar-pax}
+@cindex @command{tar} formats
+@cindex v7 @command{tar} format
@cindex ustar format
@cindex pax format
-@trindex tar-v7
-@trindex tar-ustar
-@trindex tar-pax
+@opindex tar-v7
+@opindex tar-ustar
+@opindex tar-pax
These three mutually exclusive options select the tar format to use
when generating tarballs with @code{make dist}. (The tar file created
package can still be built), but @code{make dist} will fail.
@item @var{version}
-@cindex Option, version
+@cindex Option, @var{version}
A version number (e.g. @samp{0.30}) can be specified. If Automake is not
newer than the version specified, creation of the @file{Makefile.in}
will be suppressed.
@item @code{-W@var{category}} or @code{--warnings=@var{category}}
@cindex Option, warnings
+@cindex Option, @code{-W@var{category}}
+@cindex Option, @code{--warnings=@var{category}}
These options behave exactly like their command-line counterpart
(@pxref{Invoking Automake}). This allows you to enable or disable some
warning categories on a per-file basis. You can also setup some warnings
@node Tags
@section Interfacing to @code{etags}
-@cindex TAGS support
+@cindex @file{TAGS} support
Automake will generate rules to generate @file{TAGS} files for use with
GNU Emacs under some circumstances.
@node Suffixes
@section Handling new file extensions
-@cindex Adding new SUFFIXES
-@cindex SUFFIXES, adding
+@cindex Adding new @code{SUFFIXES}
+@cindex @code{SUFFIXES}, adding
@vindex SUFFIXES
It is sometimes useful to introduce a new implicit rule to handle a file
@chapter Include
@cmindex include
-@cindex Including Makefile fragment
-@cindex Makefile fragment, including
+@cindex Including @file{Makefile} fragment
+@cindex @file{Makefile} fragment, including
Automake supports an @code{include} directive which can be used to
include other @file{Makefile} fragments when @code{automake} is run.
Automake supports a simple type of conditionals.
-@cvindex AM_CONDITIONAL
+@acindex AM_CONDITIONAL
Before using a conditional, you must define it by using
@code{AM_CONDITIONAL} in the @code{configure.ac} file (@pxref{Macros}).
will confuse automake.
@end defmac
-@cindex --enable-debug, example
-@cindex Example conditional --enable-debug
-@cindex Conditional example, --enable-debug
+@cindex @code{--enable-debug}, example
+@cindex Example conditional @code{--enable-debug}
+@cindex Conditional example, @code{--enable-debug}
Conditionals typically depend upon options which the user provides to
the @code{configure} script. Here is an example of how to write a
@node Gnits
@chapter The effect of @code{--gnu} and @code{--gnits}
-@cindex --gnu, required files
-@cindex --gnu, complete description
+@cindex @code{--gnu}, required files
+@cindex @code{--gnu}, complete description
The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
variable) causes @code{automake} to check the following:
rules; for instance in the future @code{pathchk} might be required for
@samp{make dist}.
-@cindex --gnits, complete description
+@cindex @code{--gnits}, complete description
The @samp{--gnits} option does everything that @samp{--gnu} does, and
checks the following as well:
@c FIXME xref when standards are finished
@item
-@cindex README-alpha
+@cindex @file{README-alpha}
If @samp{VERSION} indicates that this is an alpha release, and the file
@file{README-alpha} appears in the topmost directory of a package, then
it is included in the distribution. This is done in @samp{--gnits}
@node Cygnus
@chapter The effect of @code{--cygnus}
-@cindex Cygnus strictness
+@cindex @code{cygnus} strictness
Some packages, notably GNU GCC and GNU gdb, have a build environment
originally written at Cygnus Support (subsequently renamed Cygnus
possible to append new dependencies to an @code{automake}-defined
target without redefining the entire rule.
-@cindex -local targets
+@cindex @code{-local} targets
@cindex local targets
However, various useful targets have a @samp{-local} version you can
$(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
@end example
-@cindex -hook targets
+@cindex @code{-hook} targets
@cindex hook targets
Some rule also have a way to run another rule, called a @dfn{hook},
@cindex versioned binaries, installing
@cindex installing versioned binaries
-@cindex LN_S example
+@cindex @code{LN_S} example
For instance, here is how you could install a versioned copy of a
program using @code{$(LN_S)}:
subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
subdirectory project one directory deeper). The good news is that
this proxy @file{Makefile} can be generated with Automake. All we
-need are -local targets (@pxref{Extending}) that perform the dispatch.
-Of course the other Automake features are available, so you could
-decide to let Automake perform distribution or installation. Here is
-a possible @file{Makefile.am}:
+need are @code{-local} targets (@pxref{Extending}) that perform the
+dispatch. Of course the other Automake features are available, so you
+could decide to let Automake perform distribution or installation.
+Here is a possible @file{Makefile.am}:
@example
all-local:
@section @command{missing} and @code{AM_MAINTAINER_MODE}
@subsection @command{missing}
-@cindex missing, purpose
+@cindex @command{missing}, purpose
The @command{missing} script is a wrapper around several maintainer
tools, designed to warn users if a maintainer tool is required but
@code{AM_MAINTAINER_MODE} advocates.
@subsection @code{AM_MAINTAINER_MODE}
-@cindex AM_MAINTAINER_MODE, purpose
-@cvindex AM_MAINTAINER_MODE
+@cindex @code{AM_MAINTAINER_MODE}, purpose
+@acindex AM_MAINTAINER_MODE
@code{AM_MAINTAINER_MODE} disables the so called "rebuild rules" by
default. If you have @code{AM_MAINTAINER_MODE} in
@node distcleancheck
@section Files left in build directory after distclean
-@cindex distclean, diagnostic
+@cindex @code{distclean}, diagnostic
+@cindex @code{make distclean}, diagnostic
@cindex dependencies and distributed files
@trindex distclean
@trindex distcleancheck
@end display
@subsection Compile Flag Variables
+@cindex Flag Variables, Ordering
+@cindex Compile Flag Variables
@cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
@cindex @code{AM_CFLAGS} and @code{CFLAGS}
@cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
@appendix Indices
@menu
-* Macro and Variable Index:: Index of Autoconf macros and Automake variables
+* Macro Index:: Index of Autoconf macros
+* Variable Index:: Index of Makefile variables
* General Index:: General index
@end menu
-@node Macro and Variable Index
-@appendixsec Macro and Variable Index
+@node Macro Index
+@appendixsec Macro Index
+
+@printindex fn
+
+@node Variable Index
+@appendixsec Variable Index
@printindex vr
@c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
@c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
@c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
-@c LocalWords: pkg libdir cvindex cpio bindir sbindir rmt pax sbin zar zardir
+@c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
@c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
@c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
@c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
@c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
@c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
@c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
-@c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS
+@c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable maintainerclean testSubDir
+@c LocalWords: barexec Pinard's
projects / platform / upstream / automake.git / commitdiff