* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
+* Objective C++ Support:: Compiling Objective C++ sources
* Unified Parallel C Support:: Compiling Unified Parallel C sources
* Assembly Support:: Compiling assembly sources
* Fortran 77 Support:: Compiling Fortran 77 sources
maintainers).
The typical Automake input file is simply a series of variable definitions.
-Each such file is processed to create a @file{Makefile.in}. There
-should generally be one @file{Makefile.am} per directory of a project.
+Each such file is processed to create a @file{Makefile.in}.
@cindex Constraints of Automake
@cindex Automake constraints
@cindex @file{amhello-1.0.tar.gz}, use cases
In this section we explore several use cases for the GNU Build System.
-You can replay all these examples on the @file{amhello-1.0.tar.gz}
+You can replay all of these examples on the @file{amhello-1.0.tar.gz}
package distributed with Automake. If Automake is installed on your
system, you should find a copy of this file in
@file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
@example
~/amhello % @kbd{cat README}
This is a demonstration package for GNU Automake.
-Type `info Automake' to read the Automake manual.
+Type 'info Automake' to read the Automake manual.
@end example
@item
@example
~/amhello % @kbd{autoreconf --install}
-configure.ac: installing `./install-sh'
-configure.ac: installing `./missing'
-src/Makefile.am: installing `./depcomp'
+configure.ac: installing './install-sh'
+configure.ac: installing './missing'
+src/Makefile.am: installing './depcomp'
@end example
At this point the build system is complete.
@command{autoreconf} is a script that calls @command{autoconf},
@command{automake}, and a bunch of other commands in the right order.
If you are beginning with these tools, it is not important to figure
-out in which order all these tools should be invoked and why. However,
+out in which order all of these tools should be invoked and why. However,
because Autoconf and Automake have separate manuals, the important
point to understand is that @command{autoconf} is in charge of
creating @file{configure} from @file{configure.ac}, while
% @kbd{cat Makefile.am}
$(FOO:=x): bar
% @kbd{automake}
-Makefile.am:1: bad characters in variable name `$(FOO'
-Makefile.am:1: `:='-style assignments are not portable
+Makefile.am:1: bad characters in variable name '$(FOO'
+Makefile.am:1: ':='-style assignments are not portable
@end example
@cindex Make targets, overriding
that is then used by the automatic dependency tracking feature
(@pxref{Dependencies}).
-@item elisp-comp
-This program is used to byte-compile Emacs Lisp code.
-
@item install-sh
This is a replacement for the @command{install} program that works on
platforms where @command{install} is unavailable or unusable.
@item missing
This wraps a number of programs that are typically only required by
-maintainers. If the program in question doesn't exist,
-@command{missing} prints an informative warning and attempts to fix
-things so that the build can continue.
+maintainers. If the program in question doesn't exist, or seems to old,
+@command{missing} will print an informative warning before failing out,
+to provide the user with more context and information.
@item mkinstalldirs
This script used to be a wrapper around @samp{mkdir -p}, which is not
instance, @option{-Wno-syntax} will hide the warnings about unused
variables.
-The categories output by default are @samp{syntax} and
+The categories output by default are @samp{obsolete}, @samp{syntax} and
@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
are enabled in @option{--gnu} and @option{--gnits} strictness.
that is compatible with @command{make}'s syntax) and furthermore use
@code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
@file{Makefile}, then @command{automake} will be able to use
-@samp{$@{file@}} to generate all these rules. For instance, here is
+@samp{$@{file@}} to generate all of these rules. For instance, here is
how the Automake package itself generates versioned scripts for its
test suite:
@file{config.guess},
@file{config.sub},
@file{depcomp},
-@file{elisp-comp},
@file{compile},
@file{install-sh},
@file{ltmain.sh},
This is required if any Objective C source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+@item AC_PROG_OBJCXX
+This is required if any Objective C++ source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
@item AC_PROG_F77
This is required if any Fortran 77 source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
and many third party macros are underquoted; and we have to apologize
for this temporary inconvenience. The reason we have to be stricter
is that a future implementation of @command{aclocal} (@pxref{Future of
-aclocal}) will have to temporarily include all these third party
+aclocal}) will have to temporarily include all of these third party
@file{.m4} files, maybe several times, including even files that are
not actually needed. Doing so should alleviate many problems of the
current implementation, however it requires a stricter style from the
numerous macros, it will rapidly become difficult to maintain, and it
will be almost impossible to share macros between packages.
-@vindex ACLOCAL_AMFLAGS
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/}. To build @file{aclocal.m4},
-one should therefore instruct @command{aclocal} to scan @file{m4/}.
-From the command line, this is done with @samp{aclocal -I m4}. The
-top-level @file{Makefile.am} should also be updated to define
+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}:
@example
-ACLOCAL_AMFLAGS = -I m4
+AC_CONFIG_MACRO_DIR([m4])
@end example
-@code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
-when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
-also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
-Using @command{autoreconf} to Update @file{configure} Scripts,
-autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
-options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
-Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
-and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
-@command{gettextize} Program, gettext, GNU gettext tools}) to locate
-the place where Gettext's macros should be installed. So even if you
-do not really care about the rebuild rules, you should define
-@code{ACLOCAL_AMFLAGS}.
+@command{aclocal} will then take care of automatically adding @file{m4/}
+to its search path for m4 files.
-When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
+When @samp{aclocal} is run, it will build an @file{aclocal.m4}
that @code{m4_include}s any file from @file{m4/} that defines a
required macro. Macros not found locally will still be searched in
system-wide directories, as explained in @ref{Macro Search Path}.
such third-party macros in your local @file{m4/} directory so they get
distributed.
-Since Automake 1.10, @command{aclocal} offers an option to copy these
-system-wide third-party macros in your local macro directory, solving
-the above problem. Simply use:
+Since Automake 1.10, @command{aclocal} offers the option @code{--install}
+to copy these system-wide third-party macros in your local macro directory,
+helping to solve the above problem.
-@example
-ACLOCAL_AMFLAGS = -I m4 --install
-@end example
-
-@noindent
With this setup, system-wide macros will be copied to @file{m4/}
-the first time you run @command{autoreconf}. Then the locally
-installed macros will have precedence over the system-wide installed
-macros each time @command{aclocal} is run again.
+the first time you run @command{aclocal}. Then the locally installed
+macros will have precedence over the system-wide installed macros
+each time @command{aclocal} is run again.
One reason why you should keep @option{--install} in the flags even
after the first run is that when you later edit @file{configure.ac}
explained in @ref{Local Macros}, and has
@example
-ACLOCAL_AMFLAGS = -I m4 --install
+AC_CONFIG_MACRO_DIR([m4])
@end example
@noindent
-in its top-level @file{Makefile.am}.
+in its @file{configure.ac}.
Initially the @file{m4/} directory is empty. The first time we run
-@command{autoreconf}, it will fetch the options to pass to
-@command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
---install}. @command{aclocal} will notice that
+@command{aclocal --install}, it will notice that
@itemize @bullet
@item
copy this file in @file{m4/thirdparty.m4}, and output an
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
-The next time @samp{aclocal -I m4 --install} is run (either via
-@command{autoreconf}, by hand, or from the @file{Makefile} rebuild
-rules) something different happens. @command{aclocal} notices that
+The next time @samp{aclocal --install} is run, something different
+happens. @command{aclocal} notices that
@itemize @bullet
@item
Now suppose the system-wide third-party macro is changed. This can
happen if the package installing this macro is updated. Let's suppose
-the new macro has serial number 2. The next time @samp{aclocal -I m4
---install} is run the situation is the following:
+the new macro has serial number 2. The next time @samp{aclocal --install}
+is run the situation is the following:
@itemize @bullet
@item
version. MyPackage just had its macro updated as a side effect of
running @command{aclocal}.
-If you are leery of letting @command{aclocal} update your local macro,
-you can run @samp{aclocal -I m4 --diff} to review the changes
-@samp{aclocal -I m4 --install} would perform on these macros.
+If you are leery of letting @command{aclocal} update your local
+macro, you can run @samp{aclocal --diff} to review the changes
+@samp{aclocal --install} would perform on these macros.
Finally, note that the @option{--force} option of @command{aclocal} has
absolutely no effect on the files installed by @option{--install}. For
instance, if you have modified your local macros, do not expect
@option{--install --force} to replace the local macros by their
system-wide versions. If you want to do so, simply erase the local
-macros you want to revert, and run @samp{aclocal -I m4 --install}.
+macros you want to revert, and run @samp{aclocal --install}.
@node Future of aclocal
Runs many macros required for proper operation of the generated Makefiles.
@vindex AUTOMAKE_OPTIONS
-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}).
+@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).
@acindex AC_INIT
-This macro can also be called in @emph{another, deprecated form} (support
-for which will be @emph{removed in the next major Automake release}):
+This macro could once (before Automake 1.13) also be called in the
+@emph{now obsolete and completely unsupported} form
@code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
-there are two required arguments: the package and the version number.
-This form is obsolete because the @var{package} and @var{version} can
-be obtained from Autoconf's @code{AC_INIT} macro (which itself has an
-old and a new form).
+there were two required arguments: the package and the version number.
+@anchor{Modernize AM_INIT_AUTOMAKE invocation}
If your @file{configure.ac} has:
@example
@end example
@noindent
-you should modernize it as follows:
+you must modernize it as follows in order to make it work with Automake
+1.13 or later:
@example
AC_INIT([mumble], [1.5])
This macro will abort @command{configure} if no Unified Parallel C
compiler is found.
+@item AM_MISSING_PROG(@var{name}, @var{program})
+@acindex AM_MISSING_PROG
+@vindex MISSING
+Find a maintainer tool @var{program} and define the @var{name}
+environment variable with its location. If @var{program} is not
+detected, then @var{name} will instead invoke the @command{missing}
+script, in order to give useful advice to the user about the missing
+maintainer tool. @xref{maintainer-mode}, for more information on when
+the @command{missing} script is appropriate.
+
@item AM_SILENT_RULES
@acindex AM_SILENT_RULES
Control the machinery for less verbose build output
it is enough to have a single @file{Makefile.am} that builds
everything in place.
-In larger projects it is common to organize files in different
-directories, in a tree. For instance one directory per program, per
-library or per module. The traditional approach is to build these
-subdirectories recursively: each directory contains its @file{Makefile}
-(generated from @file{Makefile.am}), and when @command{make} is run
-from the top level directory it enters each subdirectory in turn to
-build its contents.
+In larger projects, it is common to organize files in different
+directories, in a tree. For example, there could be a directory
+for the program's source, one for the testsuite, and one for the
+documentation; or, for very large projects, there could be one
+directory per program, per library or per module.
+
+The traditional approach is to build these subdirectories recursively,
+employing @emph{make recursion}: each directory contains its
+own @file{Makefile}, and when @command{make} is run from the top-level
+directory, it enters each subdirectory in turn, and invokes there a
+new @command{make} instance to build the directory's contents.
+
+Because this approach is very widespread, Automake offers built-in
+support for it. However, it is worth nothing that the use of make
+recursion has its own serious issues and drawbacks, and that it's
+well possible to have packages with a multi directory layout that
+make little or no use of such recursion (examples of such packages
+are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
+section below.
@menu
* Subdirectories:: Building subdirectories recursively
@cindex @code{SUBDIRS}, explained
-In packages with subdirectories, the top level @file{Makefile.am} must
+In packages using make recursion, 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
built after everything else since they are meant to test what has
been constructed.
-All @code{clean} rules are run in reverse order of build rules.
+In addition to the built-in recursive targets defined by Automake
+(@code{all}, @code{check}, etc.), the developer can also define his
+own recursive targets. That is done by passing the names of such
+targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS}
+in @file{configure.ac}. Automake generates rules to handle the
+recursion for such targets; and the developer can define real actions
+for them by defining corresponding @code{-local} targets.
+
+@example
+% @kbd{cat configure.ac}
+AC_INIT([pkg-name], [1.0]
+AM_INIT_AUTOMAKE
+AM_EXTRA_RECURSIVE_TARGETS([foo])
+AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
+AC_OUTPUT
+% @kbd{cat Makefile.am}
+SUBDIRS = sub
+foo-local:
+ @@echo This will be run by "make foo".
+% @kbd{cat sub/Makefile.am}
+SUBDIRS = src
+% @kbd{cat sub/src/Makefile.am}
+foo-local:
+ @@echo This too will be run by a "make foo" issued either in
+ @@echo the 'sub/src/' directory, the 'sub/' directory, or the
+ @@echo top-level directory.
+@end example
@node Conditional Subdirectories
@section Conditional Subdirectories
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
-@c Keep in sync with subcond2.sh
+@c Keep in sync with subdir-am-cond.sh
@file{configure} should output the @file{Makefile} for each directory
and define a condition into which @file{opt/} should be built.
@cindex @code{SUBDIRS} and @code{AC_SUBST}
@cindex @code{AC_SUBST} and @code{SUBDIRS}
-@c Keep in sync with subcond3.sh
+@c Keep in sync with subdir-ac-subst.sh
Another possibility is to define @code{MAYBE_OPT} from
@file{./configure} using @code{AC_SUBST}:
If you've ever read Peter Miller's excellent paper,
@uref{http://miller.emu.id.au/pmiller/books/rmch/,
Recursive Make Considered Harmful}, the preceding sections on the use of
-subdirectories will probably come as unwelcome advice. For those who
+make recursion will probably come as unwelcome advice. For those who
haven't read the paper, Miller's main thesis is that recursive
@command{make} invocations are both slow and error-prone.
to write a single @file{Makefile.am} for a complex multi-directory
package.
-
By default an installable file specified in a subdirectory will have its
directory name stripped before installation. For instance, in this
example, the header file will be installed as
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
+* Objective C++ Support:: Compiling Objective C++ sources
* Unified Parallel C Support:: Compiling Unified Parallel C sources
* Assembly Support:: Compiling assembly sources
* Fortran 77 Support:: Compiling Fortran 77 sources
Therefore, when Automake detects this situation it will complain
with a message such as
@example
-object `foo.$(OBJEXT)' created both with libtool and without
+object 'foo.$(OBJEXT)' created both with libtool and without
@end example
A workaround for this issue is to ensure that these two objects get
@itemx maude_GCJFLAGS
@itemx maude_LFLAGS
@itemx maude_OBJCFLAGS
+@itemx maude_OBJCXXFLAGS
@itemx maude_RFLAGS
@itemx maude_UPCFLAGS
@itemx maude_YFLAGS
@samp{_GCJFLAGS},
@samp{_LFLAGS},
@samp{_OBJCFLAGS},
+@samp{_OBJCXXFLAGS},
@samp{_RFLAGS},
@samp{_UPCFLAGS}, and
@samp{_YFLAGS}.
separate variable that is also passed to every compilation that invokes
the C preprocessor. In particular it generates @samp{-I.},
@samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
-@file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
-@code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
-options using the @option{nostdinc} option.
+@file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can
+disable the default @option{-I} options using the @option{nostdinc}
+option.
When a file to be included is generated during the build and not part
of a distribution tarball, its location is under @code{$(builddir)},
@end vtable
+@node Objective C++ Support
+@section Objective C++ Support
+
+@cindex Objective C++ support
+@cindex Support for Objective C++
+
+Automake includes some support for Objective C++.
+
+Any package including Objective C++ code must define the output variable
+@code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when an Objective C++ source file
+is seen:
+
+@vtable @code
+@item OBJCXX
+The name of the Objective C++ compiler.
+
+@item OBJCXXFLAGS
+Any flags to pass to the Objective C++ compiler.
+
+@item AM_OBJCXXFLAGS
+The maintainer's variant of @code{OBJCXXFLAGS}.
+
+@item OBJCXXCOMPILE
+The command used to actually compile an Objective C++ source file. The
+file name is appended to form the complete command line.
+
+@item OBJCXXLINK
+The command used to actually link an Objective C++ program.
+@end vtable
+
+
@node Unified Parallel C Support
@section Unified Parallel C Support
@vindex GCJLINK
Native Java (@code{GCJLINK})
@item
+@vindex OBJCXXLINK
+Objective C++ (@code{OBJCXXLINK})
+@item
@vindex CXXLINK
C++ (@code{CXXLINK})
@item
@section Support for Other Languages
Automake currently only includes full support for C, C++ (@pxref{C++
-Support}), Objective C (@pxref{Objective C Support}), Fortran 77
+Support}), Objective C (@pxref{Objective C Support}),
+Objective C++ (@pxref{Objective C++ Support}),
+Fortran 77
(@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
and Java (@pxref{Java Support with gcj}). There is only rudimentary
support for other languages, support for which will be improved based
distributed.
Automake will byte-compile all Emacs Lisp source files using the Emacs
-found by @code{AM_PATH_LISPDIR}, if any was found.
+found by @code{AM_PATH_LISPDIR}, if any was found. When performing such
+byte-compilation, the flags specified in the (developer-reserved)
+@code{AM_ELCFLAGS} and (user-reserved) @code{ELCFLAGS} make variables
+will be passed to the Emacs invocation.
Byte-compiled Emacs Lisp files are not portable among all versions of
Emacs, so it makes sense to turn this off if you expect sites to have
@samp{$(pyexecdir)/$(PACKAGE)}.
@end vtable
-All these directory variables have values that start with either
+All of these directory variables have values that start with either
@samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
fine in @file{Makefiles}, but it makes these variables hard to use in
@file{configure}. This is mandated by the GNU coding standards, so
documentation installed by default as well as all the above optional
formats.
-All these targets can be extended using @samp{-local} rules
+All of these targets can be extended using @samp{-local} rules
(@pxref{Extending}).
@cindex Texinfo flag, @code{VERSION}
request this explicitly using @samp{make install-info}.
@vindex AM_UPDATE_INFO_DIR
-By default, @code{make install-info} and @code{make install-info}
-will try to run the @command{install-info} program (if available)
-to update (or create) the @file{@code{$@{infodir@}}/dir} index.
+By default, @code{make install-info} and @code{make uninstall-info}
+will try to run the @command{install-info} program (if available) to
+update (or create/remove) the @file{@code{$@{infodir@}}/dir} index.
If this is undesired, it can be prevented by exporting the
@code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
rm -rf `find $(distdir)/doc -type d -name .svn`
@end example
-@c The caveates described here should be documented in 'disthook.test'.
+@c The caveates described here should be documented in 'disthook.sh'.
@noindent
Note that the @code{dist-hook} recipe shouldn't assume that the regular
files in the distribution directory are writable; this might not be the
different means (the so-called ``log compilers'', @pxref{Parallel Test
Harness}).
-Test scripts can be executed serially or concurrently. Automake
-supports both these kinds of test execution, with the serial test harness
-being the default (for backward-compatibility reasons only, as its use
-is nowadays discouraged). The concurrent test harness relies on the
-concurrence capabilities (if any) offered by the underlying @command{make}
+Test scripts can be executed serially or concurrently. Automake supports
+both these kinds of test execution, with the parallel test harness being
+the default. The concurrent test harness relies on the concurrence
+capabilities (if any) offered by the underlying @command{make}
implementation, and can thus only be as good as those are.
By default, only the exit statuses of the test scripts are considered when
determining the testsuite outcome. But Automake allows also the use of
more complex test protocols, either standard (@pxref{Using the TAP test
-protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
-enable such protocols only when the parallel harness is used: they won't
-work with the serial test harness. In the rest of this section we are
-going to concentrate mostly on protocol-less tests, since we'll have later
-a whole section devoted to the use of test protocols (again, @pxref{Custom
-Test Drivers}).
+protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't
+enable such protocols when the serial harness is used, though.
+In the rest of this section we are going to concentrate mostly on
+protocol-less tests, since we cover test protocols in a later section
+(again, @pxref{Custom Test Drivers}).
@cindex Exit status 77, special interpretation
@cindex Exit status 99, special interpretation
@anchor{Simple tests and color-tests}
@vindex AM_COLOR_TESTS
@cindex Colorized testsuite output
-If the Automake option @code{color-tests} is used (@pxref{Options})
-and standard output is connected to a capable terminal, then the test
-results and the summary are colored appropriately. The user can disable
-colored output by setting the @command{make} variable
-@samp{AM_COLOR_TESTS=no}, or force colored output 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 break the automatic detection of a
-connection to a capable terminal. If this is the case, you'll have to
-resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
-testsuite output colorized.
+If the standard output is connected to a capable terminal, then the test
+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}.
+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
+break the automatic detection of a connection to a capable terminal.
+If this is the case, the user will have to resort to the use of
+@samp{AM_COLOR_TESTS=always} in order to have the testsuite output
+colorized.
Test programs that need data files should look for them in @code{srcdir}
(which is both a make variable and an environment variable made available
@example
AM_TESTS_ENVIRONMENT = \
## Some environment initializations are kept in a separate shell
-## file `tests-env.sh', which can make it easier to also run tests
+## file 'tests-env.sh', which can make it easier to also run tests
## from the command line.
. $(srcdir)/tests-env.sh; \
## On Solaris, prefer more POSIX-compliant versions of the standard
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
@node Serial Test Harness
-@subsection Serial Test Harness
+@subsection Older (and obsolescent) serial test harness
@cindex @option{serial-tests}, Using
-@emph{NOTE:} This harness, while still being the default one, is
-obsolescent, and kept mostly for backward-compatibility reasons. The user
-is advised to use the parallel test harness instead (@pxref{Parallel Test
-Harness}). Be warned that future Automake versions might switch to use
-that more modern and feature-rich harness by default.
+@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}).
The serial test harness is enabled by the Automake option
@option{serial-tests}. It operates by simply running the tests serially,
@node Parallel Test Harness
@subsection Parallel Test Harness
-@cindex @option{parallel-tests}, Using
-The parallel (or concurrent) test harness is enabled by the Automake option
-@option{parallel-tests}. It features automatic collection of the test
-scripts output in @file{.log} files, concurrent execution of tests with
-@code{make -j}, specification of inter-test dependencies, lazy reruns of
-tests that have not completed in a prior run, and hard errors for exceptional
-failures.
+By default, Automake generated a parallel (concurrent) test harness. It
+features automatic collection of the test scripts output in @file{.log}
+files, concurrent execution of tests with @code{make -j}, specification
+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.
such script, save its output in a corresponding @file{.log} file and
its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
-@c We choose the `.trs' extension also because, at the time of writing,
+@c We choose the '.trs' extension also because, at the time of writing,
@c it isn't already used for other significant purposes; see e.g.:
@c - http://filext.com/file-extension/trs
@c - http://www.file-extensions.org/search/?searchstring=trs
concurrent execution.
@cindex Unit tests
-@c Keep in sync with 'parallel-tests-extra-programs.test'.
+@c Keep in sync with 'parallel-tests-extra-programs.sh'.
The combination of lazy test execution and correct dependencies between
tests and their sources may be exploited for efficient unit testing
during development. To further speed up the edit-compile-test cycle, it
@end itemize
@noindent
-On the other hand, the exact semantics of how (and if)
-@option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
-and handled is left to the individual test drivers.
+On the other hand, the exact semantics of how (and if) testsuite output
+colorization, @code{XFAIL_TESTS}, and hard errors are supported and
+handled is left to the individual test drivers.
@c TODO: We should really add a working example in the doc/ directory,
@c TODO: and reference if from here.
@subsubsection Command-line arguments for test drivers
A custom driver can rely on various command-line options and arguments
-being passed to it automatically by the Automake's @option{parallel-tests}
-harness. It is @emph{mandatory} that it understands all of them (even
-if the exact interpretation of the associated semantics can legitimately
-change between a test driver and another, and even be a no-op in some
-drivers).
+being passed to it automatically by the Automake-generated test harness.
+It is @emph{mandatory} that it understands all of them (even if the exact
+interpretation of the associated semantics can legitimately change
+between a test driver and another, and even be a no-op in some drivers).
@noindent
Here is the list of options:
Note that the exact semantics attached to the @option{--color-tests},
@option{--expect-failure} and @option{--enable-hard-errors} options are
left up to the individual test drivers. Still, having a behaviour
-compatible or at least similar to that provided by the default
-@option{parallel-tests} driver is advised, as that would offer a better
-consistency and a more pleasant user experience.
+compatible or at least similar to that provided by the default driver
+is advised, as that would offer a better consistency and a more pleasant
+user experience.
@node Log files generation and test results recording
@subsubsection Log files generation and test results recording
@code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
when declared with @code{:test-result:}, can be optionally followed by
text holding the name and/or a brief description of the corresponding
-test; the @option{parallel-tests} harness will ignore such extra text when
-generating @file{test-suite.log} and preparing the testsuite summary.
+test; the harness will ignore such extra text when generating
+@file{test-suite.log} and preparing the testsuite summary.
-@c Keep in sync with 'test-metadata-recheck.test'.
+@c Keep in sync with 'test-metadata-recheck.sh'.
@item @code{:recheck:}
@cindex :recheck:
@cindex reStructuredText field, @code{:recheck:}
happens when two or more @code{:recheck:} fields are present in the same
@file{.trs} file is undefined behaviour.
-@c Keep in sync with 'test-metadata-global-log.test'.
+@c Keep in sync with 'test-metadata-global-log.sh'.
@item @code{:copy-in-global-log:}
@cindex :copy-in-global-log:
@cindex reStructuredText field, @code{:copy-in-global-log:}
successful. What happens when two or more @code{:copy-in-global-log:}
fields are present in the same @file{.trs} file is undefined behaviour.
-@c Keep in sync with 'test-metadata-global-result.test'.
+@c Keep in sync with 'test-metadata-global-result.sh'.
@item @code{:test-global-result:}
@cindex :test-global-result:
@cindex reStructuredText field, @code{:test-global-result:}
parse and interpret these results, and properly present them to the user,
and/or register them for later analysis. The exact details of how this
is accomplished can vary among different test harnesses. The Automake
-parallel harness will present the results on the console in the usual
+harness will present the results on the console in the usual
fashion (@pxref{Testsuite progress on console}), and will use the
@file{.trs} files (@pxref{Basics of test metadata}) to store the test
results and related metadata. Apart from that, it will try to remain
compatibility with the @command{prove} utility.
@table @option
-@c Keep in sync with 'tap-exit.test' and 'tap-signal.tap'.
+@c Keep in sync with 'tap-exit.sh' and 'tap-signal.tap'.
@item --ignore-exit
Causes the test driver to ignore the exit status of the test scripts;
by default, the driver will report an error if the script exits with a
% @kbd{cat configure.ac}
AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
AC_CONFIG_AUX_DIR([build-aux])
-AM_INIT_AUTOMAKE([foreign parallel-tests -Wall -Werror])
+AM_INIT_AUTOMAKE([foreign -Wall -Werror])
AC_CONFIG_FILES([Makefile])
AC_REQUIRE_AUX_FILE([tap-driver.sh])
AC_PROG_AWK
A @code{Bail out!} directive doesn't stop the whole testsuite, but only
the test script it occurs in. This doesn't follow TAP specifications,
but on the other hand it maximizes compatibility (and code sharing) with
-the ``hard error'' concept of the default @option{parallel-tests} driver.
+the ``hard error'' concept of the default testsuite driver.
@item
The @code{version} and @code{pragma} directives are not supported.
@item
If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
these automatic rebuilding rules are only enabled in maintainer mode.
-@vindex ACLOCAL_AMFLAGS
-Sometimes you need to run @command{aclocal} with an argument like
-@option{-I} to tell it where to find @file{.m4} files. Since
-sometimes @command{make} will automatically run @command{aclocal}, you
-need a way to specify these arguments. You can do this by defining
-@code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
-to @command{aclocal}. This variable is only useful in the top-level
-@file{Makefile.am}.
-
@vindex CONFIG_STATUS_DEPENDENCIES
@vindex CONFIGURE_DEPENDENCIES
@cindex @file{version.sh}, example
in the example above.
Speaking of @file{version.sh} scripts, we recommend against them
-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}:
+today. 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. 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.
+the file automatically.
@node Options
Cause @samp{make dist} to fail unless the current version number appears
in the first few lines of the @file{NEWS} file.
-@item @option{color-tests}
-@cindex Option, @option{color-tests}
-@opindex color-tests
-Cause output of the serial and parallel test harnesses (see @ref{Simple
-Tests}) and of properly-written custom test drivers (@pxref{Custom Test
-Drivers}) to be colorized on capable terminals.
-
@item @option{dejagnu}
@cindex Option, @option{dejagnu}
@opindex dejagnu
Don't require @file{texinfo.tex}, even if there are texinfo files in
this directory.
-@item @option{parallel-tests}
-@cindex Option, @option{parallel-tests}
-@opindex parallel-tests
-Enable test suite harness for @code{TESTS} that can run tests in parallel
-(@pxref{Parallel Test Harness}, for more information).
-
@item @option{serial-tests}
@cindex Option, @option{serial-tests}
@opindex serial-tests
Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
-Test Harness}, for more information). This is still the default for the
-moment.
+Test Harness}, for more information).
+
+@item @option{parallel-tests}
+@cindex Option, @option{parallel-tests}
+@opindex parallel-tests
+Enable test suite harness for @code{TESTS} that can run tests in parallel
+(@pxref{Parallel Test Harness}, for more information). This option is
+only kept for backward-compatibility, since the parallel test harness is
+the default now.
@item @option{readme-alpha}
@cindex Option, @option{readme-alpha}
@vindex @code{AM_DEFAULT_VERBOSITY}
@vindex @code{AM_V}
@vindex @code{AM_DEFAULT_V}
-To extend the silent mode to your own rules, you have two choices:
+To extend the silent mode to your own rules, you have few choices:
@itemize @bullet
+
@item
You can use the predefined variable @code{AM_V_GEN} as a prefix to
commands that should output a status line in silent mode, and
@code{AM_V_at} as a prefix to commands that should not output anything
in silent mode. When output is to be verbose, both of these variables
will expand to the empty string.
+
+@item
+You can silence a recipe unconditionally with @code{@@}, and then use
+the predefined variable @code{AM_V_P} to know whether make is being run
+in silent or verbose mode, adjust the verbose information your recipe
+displays accordingly:
+
+@example
+generate-headers:
+ @set -e; \
+ ... [commands defining a shell variable '$headers'] ...; \
+ if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \
+ rm -f $$headers && generate-header --flags $$headers
+@end example
+
@item
You can add your own variables, so strings of your own choice are shown.
The following snippet shows how you would define your own equivalent of
how third-party @file{Makefile}s can be used with Automake. The
@file{Makefile}s @command{gettextize} puts in the @file{po/} and
@file{intl/} directories are handwritten @file{Makefile}s that
-implement all these targets. That way they can be added to
+implement all of these targets. That way they can be added to
@code{SUBDIRS} in Automake packages.
Directories that are only listed in @code{DIST_SUBDIRS} but not in
definitions of the M4 macros put in @file{aclocal.m4} as well as the
behavior of the auxiliary tools installed.
-Because all these files are closely related, it is important to
+Because all of these files are closely related, it is important to
regenerate all of them when upgrading to a newer Automake release.
The usual way to do that is
The use of @option{--force-missing} ensures that auxiliary tools will be
overridden by new versions (@pxref{automake Invocation}).
-It is important to regenerate all these files each time Automake is
+It is important to regenerate all of these files each time Automake is
upgraded, even between bug fixes releases. For instance, it is not
unusual for a bug fix to involve changes to both the rules generated
in @file{Makefile.in} and the supporting M4 macros copied to
Packages made with Autoconf and Automake ship with some generated
files like @file{configure} or @file{Makefile.in}. These files were
-generated on the developer's host and are distributed so that
+generated on the developer's machine and are distributed so that
end-users do not have to install the maintainer tools required to
rebuild them. Other generated files like Lex scanners, Yacc parsers,
or Info documentation, are usually distributed on similar grounds.
-Automake outputs rules in @file{Makefile}s to rebuild these files. For
+Automake output rules in @file{Makefile}s to rebuild these files. For
instance, @command{make} will run @command{autoconf} to rebuild
@file{configure} whenever @file{configure.ac} is changed. This makes
development safer by ensuring a @file{configure} is never out-of-date
inaccurate. Some rebuild rules will be triggered and attempt to
run developer tools such as @command{autoconf} or @command{automake}.
-Actually, calls to such tools are all wrapped into a call to the
-@command{missing} script discussed later (@pxref{maintainer-mode}).
-@command{missing} will take care of fixing the timestamps when these
-tools are not installed, so that the build can continue.
+Calls to such tools are all wrapped into a call to the @command{missing}
+script discussed later (@pxref{maintainer-mode}), so that the user will
+see more descriptive warnings about missing or out-of-date tools, and
+possible suggestions about how to obtain them, rather than just some
+``command not found'' error, or (worse) some obscure message from some
+older version of the required tool they happen to have installed.
+
+Maintainers interested in keeping their package buildable from a CVS
+checkout even for those users that lack maintainer-specific tools might
+want to provide an helper script (or to enhance their existing bootstrap
+script) to fix the timestamps after a
+@command{cvs update} or a @command{git checkout}, to prevent spurious
+rebuilds. In case of a project committing the Autotools-generated
+files, as well as the generated @file{.info} files, such script might
+look something like this:
+
+@smallexample
+#!/bin/sh
+# fix-timestamp.sh: prevents useless rebuilds after "cvs update"
+sleep 1
+# aclocal-generated aclocal.m4 depends on locally-installed
+# '.m4' macro files, as well as on 'configure.ac'
+touch aclocal.m4
+sleep 1
+# autoconf-generated configure depends on aclocal.m4 and on
+# configure.ac
+configure config.h.in
+# so does autoheader-generated config.h.in
+configure config.h.in
+# and all the automake-generated Makefile.in files
+touch `find . -name Makefile.in -print`
+# finally, the makeinfo-generated '.info' files depend on the
+# corresponding '.texi' files
+touch doc/*.info
+@end smallexample
@item
In distributed development, developers are likely to have different
folks have such a script).
@item
Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
-disable all these rebuild rules by default. This is further discussed
+disable all of these rebuild rules by default. This is further discussed
in @ref{maintainer-mode}.
@end itemize
checked for in @file{configure}.
However, if for some reason a rebuild rule is triggered and involves a
-missing tool, @command{missing} will notice it and warn the user.
-Besides the warning, when a tool is missing, @command{missing} will
-attempt to fix timestamps in a way that allows the build to continue.
-For instance, @command{missing} will touch @file{configure} if
-@command{autoconf} is not installed. When all distributed files are
-kept under version control, this feature of @command{missing} allows a
-user @emph{with no maintainer tools} to build a package off its version
-control repository, bypassing any timestamp inconsistency (implied by
-e.g.@: @samp{cvs update} or @samp{git clone}).
+missing tool, @command{missing} will notice it and warn the user, even
+suggesting how to obtain such a tool (at least in case it is a well-known
+one, like @command{makeinfo} or @command{bison}). This is more helpful
+and user-friendly than just having the rebuild rules spewing out a terse
+error message like @samp{sh: @var{tool}: command not found}. Similarly,
+@command{missing} will warn the user if it detects that a maintainer
+tool it attempted to use seems too old (be warned that diagnosing this
+correctly is typically more difficult that detecting missing tools, and
+requires cooperation from the tool itself, so it won't always work).
If the required tool is installed, @command{missing} will run it and
won't attempt to continue after failures. This is correct during
development: developers love fixing failures. However, users with
-wrong versions of maintainer tools may get an error when the rebuild
+missing or too old maintainer tools may get an error when the rebuild
rule is spuriously triggered, halting the build. This failure to let
the build continue is one of the arguments of the
@code{AM_MAINTAINER_MODE} advocates.
@cindex @code{AM_LFLAGS} and @code{LFLAGS}
@cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
@cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
+@cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
@cindex @code{AM_RFLAGS} and @code{RFLAGS}
@cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
@cindex @code{AM_YFLAGS} and @code{YFLAGS}
@cindex @code{LFLAGS} and @code{AM_LFLAGS}
@cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
@cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
+@cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
@cindex @code{RFLAGS} and @code{AM_RFLAGS}
@cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
@cindex @code{YFLAGS} and @code{AM_YFLAGS}
answer holds for all the compile flags used in Automake:
@code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
@code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
-@code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
-@code{UPCFLAGS}, and @code{YFLAGS}.
+@code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
+@code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
@code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
three variables that can be used to pass flags to the C preprocessor
Using variables like this gives you full control over the ordering of
the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
you want to negate for a particular target, you can use something like
-@samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
+@samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
been forcefully appended to @code{CFLAGS}, there would be no way to
disable one flag. Yet another reason to leave user variables to
users.
@code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
@command{make} itself.
-However you should not think that all variables ending with
-@code{FLAGS} follow this convention. For instance,
-@code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
-@code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
-are two variables that are only useful to the maintainer and have no
-user counterpart.
-
@code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
has neither @code{AM_} nor per-target cousin.
sure to include the versions of Autoconf and Automake that you use.
Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
reproduces the problem you encounter. If you have encountered test
-suite failures, please attach the @file{tests/test-suite.log} file.
+suite failures, please attach the @file{test-suite.log} file.
@c ========================================================== Appendices
@c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
@c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
@c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
+@c LocalWords: OBJCXXFLAGS
@c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
@c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
@c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
projects / platform / upstream / automake.git / blobdiff