@value{UPDATED}), a program that creates GNU standards-compliant
Makefiles from template files.
-Copyright @copyright{} 1995-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 1995-2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@author David MacKenzie
@author Tom Tromey
@author Alexandre Duret-Lutz
+@author Ralf Wildenhues
+@author Stefano Lattarini
@page
@vskip 0pt plus 1filll
@insertcopying
Simple Tests
* Scripts-based Testsuites:: Automake-specific concepts and terminology
-* Serial Test Harness:: Older (and obsolescent) serial test harness
+* Serial Test Harness:: Older (and discouraged) serial test harness
* Parallel Test Harness:: Generic concurrent test harness
Using the TAP test protocol
~/amhello % @kbd{autoreconf --install}
configure.ac: installing './install-sh'
configure.ac: installing './missing'
+configure.ac: installing './compile'
src/Makefile.am: installing './depcomp'
@end example
The second possibility, which we do recommend, is to write each macro
in its own file and gather all these files in a directory. This
directory is usually called @file{m4/}. Then it's enough to update
-@file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIR}:
+@file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIRS}:
@example
-AC_CONFIG_MACRO_DIR([m4])
+AC_CONFIG_MACRO_DIRS([m4])
@end example
@command{aclocal} will then take care of automatically adding @file{m4/}
explained in @ref{Local Macros}, and has
@example
-AC_CONFIG_MACRO_DIR([m4])
+AC_CONFIG_MACRO_DIRS([m4])
@end example
@noindent
Runs many macros required for proper operation of the generated Makefiles.
@vindex AUTOMAKE_OPTIONS
-@code{AM_INIT_AUTOMAKE} is called with a single argument: a space-separated
-list of Automake options that should be applied to every @file{Makefile.am}
-in the tree. The effect is as if each option were listed in
-@code{AUTOMAKE_OPTIONS} (@pxref{Options}).
-
-@c FIXME: Remove this "modernization advice" in Automake 1.14 (and adjust
-@c FIXME: the error message in m4/init.m4:AM_INIT_AUTOMAKE accordingly).
+Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
+space-separated list of Automake options that should be applied to
+every @file{Makefile.am} in the tree. The effect is as if
+each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
@acindex AC_INIT
-This macro could once (before Automake 1.13) also be called in the
-@emph{now obsolete and completely unsupported} form
+This macro can also be called in another, @emph{deprecated} form:
@code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
-there were two required arguments: the package and the version number.
+there are two required arguments: the package and the version number.
+This usage is mostly obsolete because the @var{package} and @var{version}
+can be obtained from Autoconf's @code{AC_INIT} macro. However,
+differently from what happens for @code{AC_INIT} invocations, this
+@code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions
+in the @code{PACKAGE} and @code{VERSION} arguments, and this can be
+still be useful in some selected situations. Our hope is that future
+Autoconf versions will improve their support for package versions
+defined dynamically at configure runtime; when (and if) this happens,
+support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely
+be removed from Automake.
@anchor{Modernize AM_INIT_AUTOMAKE invocation}
If your @file{configure.ac} has:
@end example
@noindent
-you must modernize it as follows in order to make it work with Automake
-1.13 or later:
+you should modernize it as follows:
@example
AC_INIT([mumble], [1.5])
@opindex no-define
By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
@code{VERSION}. This can be avoided by passing the @option{no-define}
-option:
+option (@pxref{List of Automake options}):
@example
-AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
+AM_INIT_AUTOMAKE([no-define ...])
@end example
@item AM_PATH_LISPDIR
@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.
+This is an obsolescent macro that checks that the C compiler supports
+the @option{-c} and @option{-o} options together. Note that, since
+Automake 1.14, the @code{AC_PROG_CC} is rewritten to implement such
+checks itself, and thus the explicit use of @code{AM_PROG_CC_C_O}
+should no longer be required.
@item AM_PROG_LEX
@acindex AM_PROG_LEX
using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
you are advised to switch ASAP to the more modern Autoconf-provided
-interface instead; both the macro and the variable @emph{will be
-removed} in the next major Automake release.
+interface instead; both the macro and the variable might be removed
+in a future major Automake release.
@end table
like @file{sample.c} will be compiled to produce @file{sample.o}.
However, if the program's @code{_CFLAGS} variable is set, then the
object file will be named, for instance, @file{maude-sample.o}. (See
-also @ref{Renamed Objects}.) The use of per-target compilation flags
-with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
-from @file{configure.ac}.
+also @ref{Renamed Objects}).
In compilations with per-target flags, the ordinary @samp{AM_} form of
the flags variable is @emph{not} automatically included in the
@item AM_CFLAGS
This is the variable the @file{Makefile.am} author can use to pass
-in additional C compiler flags. It is more fully documented elsewhere.
-In some situations, this is not used, in preference to the
-per-executable (or per-library) @code{_CFLAGS}.
+in additional C compiler flags. In some situations, this is
+not used, in preference to the per-executable (or per-library)
+@code{_CFLAGS}.
@item COMPILE
This is the command used to actually compile a C source file. The
@cindex Multiple @command{lex} lexers
@cindex @command{lex}, multiple lexers
-When @command{lex} or @command{yacc} sources are used, @code{automake
--i} automatically installs an auxiliary program called
-@command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
-program is used by the build rules to rename the output of these
+When @command{lex} or @command{yacc} sources are used, @code{automake -a}
+automatically installs an auxiliary program called @command{ylwrap} in
+your package (@pxref{Auxiliary Programs}).
+This program is used by the build rules to rename the output of these
tools, and makes it possible to include multiple @command{yacc} (or
@command{lex}) source files in a single directory. (This is necessary
because yacc's output file name is fixed, and a parallel make could
@end example
Any @file{.vala} file listed in a @code{_SOURCES} variable will be
-compiled into C code by the Vala compiler. The generated @file{.c} files are
-distributed. The end user does not need to have a Vala compiler installed.
+compiled into C code by the Vala compiler. The generated @file{.c} files
+are distributed. The end user does not need to have a Vala compiler installed.
Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
that will locate the Vala compiler and optionally check its version
number.
-@defmac AM_PROG_VALAC (@ovar{minimum-version})
-Try to find a Vala compiler in @env{PATH}. If it is found, the variable
-@code{VALAC} is set. Optionally a minimum release number of the compiler
-can be requested:
-
-@example
-AM_PROG_VALAC([0.7.0])
-@end example
+@defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
+ @ovar{action-if-not-found})
+Search for a Vala compiler in @env{PATH}. If it is found, the variable
+@code{VALAC} is set to point to it (see below for more details). This
+macro takes three optional arguments. The first argument, if present,
+is the minimum version of the Vala compiler required to compile this
+package. If a compiler is found and satisfies @var{minimum-version},
+then @var{action-if-found} is run (this defaults to do nothing).
+Otherwise, @var{action-if-not-found} is run. If @var{action-if-not-found}
+is not specified, the default value is to print a warning in case no
+compiler is found, or if a too-old version of the compiler is found.
@end defmac
There are a few variables that are used when compiling Vala sources:
@vtable @code
@item VALAC
-Path to the Vala compiler.
+Absolute path to the Vala compiler, or simply @samp{valac} if no
+suitable compiler Vala could be found at configure runtime.
@item VALAFLAGS
Additional arguments for the Vala compiler.
Automake provides some minimal support for Java bytecode compilation with
the @code{JAVA} primary (in addition to the support for compiling Java to
native machine code; @pxref{Java Support with gcj}). Note however that
-@emph{the interface and most features described here are deprecated}; the
-next automake release will strive to provide a better and cleaner
+@emph{the interface and most features described here are deprecated}.
+Future Automake releases will strive to provide a better and cleaner
interface, which however @emph{won't be backward-compatible}; the present
-interface will probably be removed altogether in future automake releases
-(1.13 or later), so don't use it in new code.
+interface will probably be removed altogether some time after the
+introduction of the new interface (if that ever materializes).
Any @file{.java} files listed in a @code{_JAVA} variable will be
compiled with @code{JAVAC} at build time. By default, @file{.java}
If the current directory contains Texinfo source, you must declare it
with the @code{TEXINFOS} primary. Generally Texinfo files are converted
into info, and thus the @code{info_TEXINFOS} variable is most commonly used
-here. Any Texinfo source file must end in the @file{.texi},
-@file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
-for new manuals.
+here. Any Texinfo source file should have the @file{.texi} extension.
+Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their
+use is discouraged now, and will elicit runtime warnings.
Automake generates rules to build @file{.info}, @file{.dvi},
@file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
Furthermore, @file{.info} files are automatically distributed so that
Texinfo is not a prerequisite for installing your package.
+It is worth noting that, contrary to what happens with the other formats,
+the generated @file{.info} files are by default placed in @code{srcdir}
+rather than in the @code{builddir}. This can be changed with the
+@option{info-in-builddir} option.
+
@trindex dvi
@trindex html
@trindex pdf
@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
files.
-@c Keep in sync with txinfo21.sh
+@c Keep in sync with txinfo-many-output-formats.sh
For instance, the following setting can be used to obtain one single
@file{.html} file per manual, without node separators.
@example
entire directory will be recursively copied into the distribution.
Please note that this will also copy @emph{everything} in the directory,
including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
-version control files. We recommend against using this feature.
+version control files; thus we recommend against using this feature
+as-is. However, you can use the @code{dist-hook} feature to
+ameliorate the problem; @pxref{The dist Hook}.
@vindex SUBDIRS
@vindex DIST_SUBDIRS
distributions in various formats. Their targets are:
@table @asis
+@item @code{dist-gzip}
+Generate a @samp{gzip} tar archive of the distribution. This is the
+only format enabled by default.
+@trindex dist-gzip
+
@vindex BZIP2
@item @code{dist-bzip2}
-Generate a bzip2 tar archive of the distribution. bzip2 archives are
-frequently smaller than gzipped archives.
+Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives
+are frequently smaller than gzipped archives.
By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
To make it use a different one, set the @env{BZIP2} environment variable.
For example, @samp{make dist-bzip2 BZIP2=-7}.
@trindex dist-bzip2
-@item @code{dist-gzip}
-Generate a gzip tar archive of the distribution.
-@trindex dist-gzip
-
@item @code{dist-lzip}
Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
archives are frequently smaller than @command{bzip2}-compressed archives.
@trindex dist-lzip
-@item @code{dist-shar}
-Generate a shar archive of the distribution.
-@trindex dist-shar
-
@vindex XZ_OPT
@item @code{dist-xz}
Generate an @samp{xz} tar archive of the distribution. @command{xz}
@option{-e}. To make it use a different one, set the @env{XZ_OPT}
environment variable. For example, run this command to use the
default compression ratio, but with a progress indicator:
-@samp{make dist-xz XZ_OPT=-7e}.
+@samp{make dist-xz XZ_OPT=-ve}.
@trindex dist-xz
@item @code{dist-zip}
-Generate a zip archive of the distribution.
+Generate a @samp{zip} archive of the distribution.
@trindex dist-zip
@item @code{dist-tarZ}
-Generate a compressed tar archive of
-the distribution.
+Generate a tar archive of the distribution, compressed with the
+historical (and obsolescent) program @command{compress}. This
+option is deprecated, and it and the corresponding functionality
+will be removed altogether in Automake 2.0.
@trindex dist-tarZ
+
+@item @code{dist-shar}
+Generate a @samp{shar} archive of the distribution. This format
+archive is obsolescent, and use of this option is deprecated.
+It and the corresponding functionality will be removed altogether
+in Automake 2.0.
+@trindex dist-shar
+
@end table
-The rule @code{dist} (and its historical synonym @code{dist-all}) will
-create archives in all the enabled formats, @ref{Options}. By
-default, only the @code{dist-gzip} target is hooked to @code{dist}.
+The rule @code{dist} (and its historical synonym @code{dist-all})
+will create archives in all the enabled formats (@pxref{List of
+Automake options} for how to change this list). By default, only
+the @code{dist-gzip} target is hooked to @code{dist}.
@node Tests
@menu
* Scripts-based Testsuites:: Automake-specific concepts and terminology
-* Serial Test Harness:: Older (and obsolescent) serial test harness
+* Serial Test Harness:: Older (and discouraged) serial test harness
* Parallel Test Harness:: Generic concurrent test harness
@end menu
results and the summary are colored appropriately. The developer and the
user can disable colored output by setting the @command{make} variable
@samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
-even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
+even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
It's also worth noting that some @command{make} implementations,
when used in parallel mode, have slightly different semantics
(@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
@node Serial Test Harness
-@subsection Older (and obsolescent) serial test harness
+@subsection Older (and discouraged) serial test harness
@cindex @option{serial-tests}, Using
-@emph{This harness is obsolescent}, and kept for backward-compatibility
-reasons only. The user is strongly advised to just use the parallel test
-harness instead (@pxref{Parallel Test Harness}).
+First, note that today the use of this harness is strongly discouraged in
+favour of the parallel test harness (@pxref{Parallel Test Harness}).
+Still, there are @emph{few} situations when the advantages offered by
+the parallel harness are irrelevant, and when test concurrency can
+even cause tricky problems. In those cases, it might make sense to
+still use the serial harness, for simplicity and reliability (we still
+suggest trying to give the parallel harness a shot though).
The serial test harness is enabled by the Automake option
@option{serial-tests}. It operates by simply running the tests serially,
of inter-test dependencies, lazy reruns of tests that have not completed
in a prior run, and hard errors for exceptional failures.
-This harness is still somewhat experimental and may undergo changes in
-order to satisfy additional portability requirements.
-
@anchor{Basics of test metadata}
@vindex TEST_SUITE_LOG
@vindex TESTS
For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
+@cindex Configure substitutions in @code{TESTS}
+It is important to note that, due to current limitations (unlikely to be
+lifted), configure substitutions in the definition of @code{TESTS} can
+only work if they will expand to a list of tests that have a suffix listed
+in @code{TEST_EXTENSIONS}.
+
@vindex _LOG_COMPILE
@vindex _LOG_COMPILER
@vindex _LOG_FLAGS
cause @file{configure} to be rerun each time @file{version.sh} is
changed.
+@c Keep in sync with remake-config-status-dependencies.sh
@example
AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
@end example
Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
@code{CONFIG_STATUS_DEPENDENCIES}.
+@c Keep in sync with remake-configure-dependencies.sh
@code{CONFIGURE_DEPENDENCIES} adds dependencies to the
@file{configure} rule, whose effect is to run @command{autoconf}. This
variable should be seldom used, because @command{automake} already tracks
@code{m4_include}d files. However it can be useful when playing
tricky games with @code{m4_esyscmd} or similar non-recommendable
-macros with side effects.
+macros with side effects. Be also aware that interactions of this
+variable with the @ref{Autom4te Cache, , autom4te cache, autoconf,
+The Autoconf Manual} are quite problematic and can cause subtle
+breakage, so you might want to disable the cache if you want to use
+@code{CONFIGURE_DEPENDENCIES}.
@code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
@file{config.status} rule, whose effect is to run @file{configure}.
in the example above.
Speaking of @file{version.sh} scripts, we recommend against them
-today. We recommend that @file{version.sh} be replaced by an M4 file
-that is included by @file{configure.ac}:
+today. They are mainly used when the version of a package is updated
+automatically by a script (e.g., in daily builds). Here is what some
+old-style @file{configure.ac}s may look like:
+
+@example
+AC_INIT
+. $srcdir/version.sh
+AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
+@dots{}
+@end example
+
+@noindent
+Here, @file{version.sh} is a shell fragment that sets
+@code{VERSION_NUMBER}. The problem with this example is that
+@command{automake} cannot track dependencies (listing @file{version.sh}
+in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
+to the user), and that it uses the obsolete form of @code{AC_INIT} and
+@code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
+straightforward, because shell variables are not allowed in
+@code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
+replaced by an M4 file that is included by @file{configure.ac}:
@example
m4_include([version.m4])
@samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
second form is that @command{automake} will take care of the
dependencies when defining the rebuild rule, and will also distribute
-the file automatically.
+the file automatically. An inconvenience is that @command{autoconf}
+will now be rerun each time the version number is bumped, when only
+@file{configure} had to be rerun in the previous setup.
@node Options
Hook @code{dist-lzip} to @code{dist}.
@trindex dist-lzip
-@item @option{dist-shar}
-@cindex Option, @option{dist-shar}
-@opindex dist-shar
-Hook @code{dist-shar} to @code{dist}.
-@trindex dist-shar
+@item @option{dist-xz}
+@cindex Option, @option{dist-xz}
+@opindex dist-xz
+Hook @code{dist-xz} to @code{dist}.
+@trindex dist-xz
@item @option{dist-zip}
@cindex Option, @option{dist-zip}
Hook @code{dist-zip} to @code{dist}.
@trindex dist-zip
+@item @option{dist-shar}
+@cindex Option, @option{dist-shar}
+@opindex dist-shar
+Hook @code{dist-shar} to @code{dist}. Use of this option
+is deprecated, as the @samp{shar} format is obsolescent and
+problematic. Support for it will be removed altogether in
+Automake 2.0.
+@trindex dist-shar
+
@item @option{dist-tarZ}
@cindex Option, @option{dist-tarZ}
@opindex dist-tarZ
-Hook @code{dist-tarZ} to @code{dist}.
+Hook @code{dist-tarZ} to @code{dist}. Use of this option
+is deprecated, as the @samp{compress} program is obsolete.
+Support for it will be removed altogether in Automake 2.0.
@trindex dist-tarZ
@item @option{filename-length-max=99}
@file{configure.ac}, it will be ignored otherwise. It will also be
ignored in sub-packages of nested packages (@pxref{Subpackages}).
+@item @option{info-in-builddir}
+@cindex Option, @option{info-in-builddir}
+@opindex info-in-builddir
+Instruct Automake to place the generated @file{.info} files in the
+@code{builddir} rather than in the @code{srcdir}. Note that this
+might make VPATH builds with some non-GNU make implementations more
+brittle.
+
@item @option{no-define}
@cindex Option, @option{no-define}
@opindex no-define
@file{subdir/file.cxx}, then the output file would be
@file{subdir/file.o}.
-In order to use this option with C sources, you should add
-@code{AM_PROG_CC_C_O} to @file{configure.ac}.
-
@anchor{tar-formats}
@item @option{tar-v7}
@itemx @option{tar-ustar}
Makefile fragments included this way are always distributed because
they are needed to rebuild @file{Makefile.in}.
+Inside a fragment, the construct @code{%reldir%} is replaced with the
+directory of the fragment relative to the base @file{Makefile.am}.
+Similarly, @code{%canon_reldir%} is replaced with the canonicalized
+(@pxref{Canonicalization}) form of @code{%reldir%}. As a convenience,
+@code{%D%} is a synonym for @code{%reldir%}, and @code{%C%}
+is a synonym for @code{%canon_reldir%}.
+
+A special feature is that if the fragment is in the same directory as
+the base @file{Makefile.am} (i.e., @code{%reldir%} is @code{.}), then
+@code{%reldir%} and @code{%canon_reldir%} will expand to the empty
+string as well as eat, if present, a following slash or underscore
+respectively.
+
+Thus, a makefile fragment might look like this:
+
+@example
+bin_PROGRAMS += %reldir%/mumble
+%canon_reldir%_mumble_SOURCES = %reldir%/one.c
+@end example
+
@node Conditionals
@chapter Conditionals
projects / platform / upstream / automake.git / blobdiff