* Conditionals:: Conditionals
* Silencing Make:: Obtain less verbose output from @command{make}
* Gnits:: The effect of @option{--gnu} and @option{--gnits}
-* Cygnus:: The effect of @option{--cygnus} (deprecated, soon to be removed)
* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in
* API Versioning:: About compatibility between Automake versions
Autoconf macros supplied with Automake
* Public Macros:: Macros that you can use.
-* Obsolete Macros:: Macros that will soon be removed.
* Private Macros:: Macros that you should not use.
Directories
Silencing Make
-* Make verbosity:: Make is verbose by default
-* Tricks For Silencing Make:: Standard and generic ways to silence make
-* Automake silent-rules Option:: How Automake can help in silencing make
+* Make verbosity:: Make is verbose by default
+* Tricks For Silencing Make:: Standard and generic ways to silence make
+* Automake Silent Rules:: How Automake can help in silencing make
When Automake Isn't Enough
@xref{Gnits}, for more information on the precise implications of the
strictness level.
-Automake also has a special (and @emph{today deprecated}) ``cygnus'' mode
-that is similar to strictness but handled differently. This mode is
-useful for packages that are put into a ``Cygnus'' style tree (e.g., older
-versions of the GCC and gdb trees). @xref{Cygnus}, for more information
-on this mode. Please note that this mode @emph{is deprecated and will be
-removed in the next major Automake release (1.13)}; you must avoid its use
-in new packages, and should stop using it in existing packages as well.
-
@node Uniform
@section The Uniform Naming Scheme
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
When used with @option{--add-missing}, causes installed files to be
copied. The default is to make a symbolic link.
-@item --cygnus
-@opindex --cygnus
-Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
-of GNU or Gnits rules. For more information, see @ref{Cygnus}.
-Note that @emph{this mode of operation is deprecated, and will be removed}
-in the next major Automake release (1.13).
-
@item -f
@opindex -f
@itemx --force-missing
The categories output by default are @samp{syntax} and
@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
are enabled in @option{--gnu} and @option{--gnits} strictness.
-On the other hand, the @option{silent-rules} options (@pxref{Options})
-turns off portability warnings about recursive variable expansions.
@c Checked by extra-portability.sh
Turning off @samp{portability} will also turn off @samp{extra-portability},
@file{config.guess},
@file{config.sub},
@file{depcomp},
-@file{elisp-comp},
@file{compile},
@file{install-sh},
@file{ltmain.sh},
@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.
+of Automake required the use of @code{AM_CONFIG_HEADER}; this is no
+longer the case, and that macro has indeed been removed.
As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
specification using shell variables will be ignored as far as
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 of 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
-
-@example
-ACLOCAL_AMFLAGS = -I 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}.
-
-When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
+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}:
+
+@example
+AC_CONFIG_MACRO_DIR([m4])
+@end example
+
+@command{aclocal} will then take care of automatically adding @file{m4/}
+to its search path for m4 files.
+
+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:
-
-@example
-ACLOCAL_AMFLAGS = -I m4 --install
-@end example
+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.
-@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
@menu
* Public Macros:: Macros that you can use.
-* Obsolete Macros:: Macros that will soon be removed.
* Private Macros:: Macros that you should not use.
@end menu
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 (1.13)}):
+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:
@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])
@item AM_SILENT_RULES
@acindex AM_SILENT_RULES
-Enable the machinery for less verbose build output (@pxref{Options}).
+Control the machinery for less verbose build output
+(@pxref{Automake Silent Rules}).
@item AM_WITH_DMALLOC
@acindex AM_WITH_DMALLOC
@end table
-@node Obsolete Macros
-@subsection Obsolete Macros
-@cindex obsolete macros
-@cindex autoupdate
-
-Although using some of the following macros was required in past
-releases, you should not use any of them in new code. @emph{All
-these macros will be removed in the next major Automake version};
-if you are still using them, running @command{autoupdate} should
-adjust your @file{configure.ac} automatically (@pxref{autoupdate
-Invocation, , Using @command{autoupdate} to Modernize
-@file{configure.ac}, autoconf, The Autoconf Manual}).
-@emph{Do it NOW!}
-
-@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}).
-
-@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>}. This macro is obsolete, you should
-use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
-
-@item AM_PROG_MKDIR_P
-@acindex AM_PROG_MKDIR_P
-@cindex @code{mkdir -p}, macro check
-@vindex MKDIR_P
-@vindex mkdir_p
-
-From Automake 1.8 to 1.9.6 this macro used to define the output
-variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
--d}, or @code{mkinstalldirs}.
-
-Nowadays Autoconf provides a similar functionality with
-@code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
-Program Checks, autoconf, The Autoconf Manual}), however this defines
-the output variable @code{MKDIR_P} instead. In case you are still
-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.
-
-@item AM_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}. This macro is obsolete,
-you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
-
-@end table
-
-
@node Private Macros
@subsection Private Macros
built after everything else since they are meant to test what has
been constructed.
+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 Subdirectories, building conditionally
not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
Variables Ordering}. It allows users to run @samp{make
LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
-@command{libtool} can also be influenced with the Automake
-@option{silent-rules} option (@pxref{Options}).
-
+@command{libtool} can also be influenced by the Automake support
+for silent rules (@pxref{Automake Silent Rules}).
@node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
@subsection @code{LTLIBOBJS} and @code{LTALLOCA}
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)},
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
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 cover
-test protocols in a later section (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
@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.
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
@item @option{gnits}
@itemx @option{gnu}
@itemx @option{foreign}
-@itemx @option{cygnus}
@cindex Option, @option{gnits}
@cindex Option, @option{gnu}
@cindex Option, @option{foreign}
-@cindex Option, @option{cygnus}
@opindex gnits
@opindex gnu
@opindex foreign
-@opindex cygnus
Set the strictness as appropriate. The @option{gnits} option also
implies options @option{readme-alpha} and @option{check-news}.
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}
@samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
letter; it should be omitted for non-alpha releases.
-@item @option{silent-rules}
-@cindex Option, @option{silent-rules}
-@opindex silent-rules
-Enable less verbose build rules. This can be used to let build rules
-output status lines of the form:
-@example
-GEN @var{output-file}
- CC @var{object-file}
-@end example
-@noindent
-instead of printing the command that will be executed to update
-@var{output-file} or to compile @var{object-file}. It can also
-silence @command{libtool} output.
-
-For more information about how to use, enable, or disable silent
-rules, @pxref{Automake silent-rules Option}.
-
@item @option{std-options}
@cindex Options, @option{std-options}
@cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
@cindex Silent @command{make} rules
@menu
-* Make verbosity:: Make is verbose by default
-* Tricks For Silencing Make:: Standard and generic ways to silence make
-* Automake silent-rules Option:: How Automake can help in silencing make
+* Make verbosity:: Make is verbose by default
+* Tricks For Silencing Make:: Standard and generic ways to silence make
+* Automake Silent Rules:: How Automake can help in silencing make
@end menu
@node Make verbosity
Here we describe some common idioms/tricks to obtain a quieter make
output, with their relative advantages and drawbacks. In the next
-section (@ref{Automake silent-rules Option}) we'll see how Automake
-can help in this respect.
+section (@ref{Automake Silent Rules}) we'll see how Automake can help
+in this respect, providing more elaborate and flexible idioms.
@itemize @bullet
@end itemize
-@node Automake silent-rules Option
+@node Automake Silent Rules
@section How Automake can help in silencing make
The tricks and idioms for silencing @command{make} described in the
previous section can be useful from time to time, but we've seen that
they all have their serious drawbacks and limitations. That's why
automake provides support for a more advanced and flexible way of
-obtaining quieter output from @command{make}: the @option{silent-rules}
-mode.
+obtaining quieter output from @command{make} (for most rules at least).
@c TODO: Maybe describe in brief the precedent set by the build system
@c of the Linux Kernel, from which Automake took inspiration ... Links?
-To give the gist of what @option{silent-rules} can do, here is a simple
+To give the gist of what Automake can do in this respect, here is a simple
comparison between a typical @command{make} output (where silent rules
are disabled) and one with silent rules enabled:
CCLD foo
@end example
-@cindex silent-rules and libtool
+@cindex silent rules and libtool
Also, in projects using @command{libtool}, the use of silent rules can
automatically enable the @command{libtool}'s @option{--silent} option:
CCLD libx.la
@end example
-Let's now see how the @option{silent-rules} mode interfaces with the
-package developer and the package user.
-
-To enable the use of @option{silent-rules} in his package, a developer
-needs to do either of the following:
-
-@itemize @bullet
-@item
-Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
-@item
-Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
-file.
-@end itemize
-
-It is not possible to instead specify @option{silent-rules} in a
-@file{Makefile.am} file.
-
-If the developer has done either of the above, then the user of the
-package may influence the verbosity at @command{configure} run time as
-well as at @command{make} run time:
+For Automake-generated @file{Makefile}s, the user may influence the
+verbosity at @command{configure} run time as well as at @command{make}
+run time:
@itemize @bullet
@item
@code{make V=0} less verbose output.
@end itemize
-@cindex default verbosity for silent-rules
+@cindex default verbosity for silent rules
Note that silent rules are @emph{disabled} by default; the user must
enable them explicitly at either @command{configure} run time or at
@command{make} run time. We think that this is a good policy, since
it provides the casual user with enough information to prepare a good
bug report in case anything breaks.
-Still, notwithstanding the rationales above, a developer who wants to
-make silent rules enabled by default in his own package can do so by
-adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
-@file{configure.ac}. We advise against this approach, though.
+Still, notwithstanding the rationales above, a developer who really
+wants to make silent rules enabled by default in his own package can
+do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
@c Keep in sync with silent-configsite.sh
Users who prefer to have silent rules enabled by default can edit their
are advised to not set the variable @code{V} inside the @file{Makefile.am}
file, to allow the user to override the value for subdirectories as well.
-The current implementation of this feature normally uses nested
-variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
-that is not required by POSIX 2008 but is widely supported in
-practice. The @option{silent-rules} option thus turns off warnings
-about recursive variable expansion, which are in turn enabled by
-@option{-Wportability} (@pxref{automake Invocation}). On the rare
-@command{make} implementations that do not support nested variable
-expansion, whether rules are silent is always determined at configure
-time, and cannot be overridden at make time. Future versions of POSIX
-are likely to require nested variable expansion, so this minor
+To work at its best, the current implementation of this feature normally
+uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
+feature that is not required by POSIX 2008 but is widely supported in
+practice. On the rare @command{make} implementations that do not support
+nested variable expansion, whether rules are silent is always determined at
+configure time, and cannot be overridden at make time. Future versions of
+POSIX are likely to require nested variable expansion, so this minor
limitation should go away with time.
@vindex @code{AM_V_GEN}
@end itemize
-@node Cygnus
-@chapter The effect of @option{--cygnus}
-
-@cindex @option{cygnus} strictness
-
-@emph{The features described in this section are deprecated; you must
-not use any of them in new code, and should remove their use from older
-but still maintained code: they will be withdrawn the next major Automake
-release (1.13).}
-
-Some packages, notably GNU GCC and GNU gdb, used to have a build
-environment originally written at Cygnus Support (subsequently renamed
-Cygnus Solutions, and then later purchased by Red Hat). Packages with
-this ancestry are sometimes referred to as ``Cygnus'' trees.
-
-A Cygnus tree has slightly different rules for how a
-@file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
-@command{automake} will cause any generated @file{Makefile.in} to
-comply with Cygnus rules.
-
-Here are the precise effects of @option{--cygnus}:
-
-@itemize @bullet
-
-@item
-The @option{foreign} strictness is implied.
-
-@item
-The options @option{no-installinfo}, @option{no-dependencies} and
-@option{no-dist} are implied (@pxref{Options}).
-
-@item
-The macro @code{AM_MAINTAINER_MODE} is required.
-
-@item
-Info files are always created in the build directory, and not in the
-source directory. Packages that don't use the @option{cygnus} option
-can emulate this effect by using the @option{no-installinfo} option
-and listing the generated info files in the @code{CLEANFILES} variable.
-
-@item
-@file{texinfo.tex} is not required if a Texinfo source file is
-specified. The assumption is that the file will be supplied, but in a
-place that Automake cannot find -- it is an artifact of how Cygnus
-packages are typically bundled. This effect can be emulated in
-packages not using the @option{cygnus} option with a proper definition
-of the @code{TEXINFO_TEX} variable (@pxref{Texinfo}).
-
-@item
-Certain tools will be searched for in the build tree as well as in the
-user's @env{PATH}. These tools are @command{runtest}, @command{expect},
-@command{makeinfo} and @command{texi2dvi}.
-
-@item
-The @code{check} target doesn't depend on @code{all}.
-@end itemize
-
-
@node Not Enough
@chapter When Automake Isn't Enough
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
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.
@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.
@itemize
@item
-If less verbose output has been enabled in the package with the
-@samp{silent-rules} option (@pxref{Options}), you can use
+If less verbose output has been enabled in the package with the use
+of silent rules (@pxref{Automake Silent Rules}), you can use
@code{make V=1} to see the commands being executed.
@item
@code{make -n} can help show what would be done without actually doing
@c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
@c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
@c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
-@c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
+@c LocalWords: dir Automake's ac Dist Gnits gnits 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 cpio bindir sbindir rmt pax sbin zar zardir acindex
projects / platform / upstream / automake.git / commitdiff