corresponding @file{Makefile.am}. This option is deprecated and will be
removed in a future release.
+@item --silent-rules
+@opindex --silent-rules
+Enable the @option{silent-rules} option globally (@pxref{Options}).
+
@item -v
@itemx --verbose
@opindex -v
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.
@vindex WARNINGS
The environment variable @env{WARNINGS} can contain a comma separated
The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
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.
+LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
+@command{libtool} can also be influenced with the Automake
+@option{silent-rules} option (@pxref{Options}).
@node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
@cindex @code{make check}
@trindex check
-Automake supports two forms of test suites.
+Automake supports three forms of test suites, the first two of which
+are very similar.
@section Simple Tests
@vindex TESTS
@vindex TESTS_ENVIRONMENT
The variable @code{TESTS_ENVIRONMENT} can be used to set environment
-variables for the test run; the environment variable @code{srcdir} is
+variables for the test run; the environment variable @env{srcdir} is
set in the rule. If all your test programs are scripts, you can also
set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
@samp{$(SHELL) -x} can be useful for debugging the tests), or any other
by the tests, not the tests themselves. Of course you can set
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
+
+@section Simple tests using @samp{parallel-tests}
+@cindex @option{parallel-tests}, Using
+The option @option{parallel-tests} (@pxref{Options}) enables a test
+suite driver that is mostly compatible to the simple test driver
+described above, but provides a few more features and slightly different
+semantics. It features concurrent execution of tests with @code{make -j},
+allows to specify inter-test dependencies, lazy reruns of tests that
+have not completed in a prior run, summary and verbose output in
+@samp{RST} (reStructuredText) and @samp{HTML} format, and hard errors
+for exceptional failures. Similar to the simple test driver,
+@code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS}, @code{XFAIL_TESTS}, and
+the @code{check_*} variables are honored, and the environment variable
+@env{srcdir} is set during test execution.
+
+@vindex TEST_SUITE_LOG
+@vindex TEST_LOGS
+The driver operates by defining a set of @command{make} rules to create
+a summary log file, @code{TEST_SUITE_LOG}, which defaults to
+@file{test-suite.log} and requires a @file{.log} suffix. This file
+depends upon log files created for each single test program listed in
+@code{TESTS}, which in turn contain all output produced by the
+corresponding tests.
+
+@vindex TEST_EXTENSIONS
+Each log file is created when the corresponding test has completed.
+The set of log files is listed in the read-only variable
+@code{TEST_LOGS}, and defaults to @code{TESTS}, with the executable
+extension if any (@pxref{EXEEXT}), as well as any suffix listed in
+@code{TEST_EXTENSIONS} removed, and @file{.log} appended.
+@code{TEST_EXTENSIONS} defaults to @file{.test}. Results are undefined
+if a test file name ends in several concatenated suffixes.
+
+@vindex VERBOSE
+As with the simple driver above, by default one status line is printed
+per completed test, and a short summary after the suite has completed.
+However, standard output and standard error of the test are redirected
+to a per-test log file, so that parallel execution does not produce
+intermingled output. The output from failed tests is collected in the
+@file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
+file is output after the summary. For best results, the tests should be
+verbose by default now.
+
+@trindex mostlyclean
+@trindex check-html
+@vindex RST2HTML
+@vindex TEST_SUITE_HTML
+With @code{make check-html}, the log files may be converted from RST
+(reStructuredText, see @uref{http://docutils.sourceforge.net/@/rst.html})
+to HTML using @samp{RST2HTML}, which defaults to @command{rst2html} or
+@command{rst2html.py}. The variable @samp{TEST_SUITE_HTML} contains the
+set of converted log files. The log and HTML files are removed upon
+@code{make mostlyclean}.
+
+@vindex DISABLE_HARD_ERRORS
+@cindex Exit status 99, special interpretation
+@cindex hard error
+Even in the presence of expected failures (see @code{XFAIL_TESTS}, there
+may be conditions under which a test outcome needs attention. For
+example, with test-driven development, you may write tests for features
+that you have not implemented yet, and thus mark these tests as expected
+to fail. However, you may still be interested in exceptional conditions,
+for example, tests that fail due to a segmentation violation or another
+error that is independent of the feature awaiting implementation.
+Tests can exit with an exit status of 99 to signal such a @emph{hard
+error}. Unless the variable @code{DISABLE_HARD_ERRORS} is set to a
+nonempty value, such tests will be counted as failed.
+
+@vindex LAZY_TEST_SUITE
+By default, all tests listed in @code{TESTS} are run upon @code{make
+check}. When @code{LAZY_TEST_SUITE} is nonempty, then log files of
+a previous run are not removed before starting the test suite, so only
+tests that have not yet been completed are run, as well as tests that
+have been modified after the previous run.
+
+In order to guarantee an ordering between tests even with @code{make
+-j@var{N}}, dependencies between the corresponding log files may be
+specified through usual @command{make} dependencies. For example, the
+following snippet lets the test named @file{foo-execute.test} depend
+upon completion of the test @file{foo-compile.test}:
+
+@example
+TESTS = foo-compile.test foo-execute.test
+foo-execute.log: foo-compile.log
+@end example
+
+@noindent
+Please note that this ordering ignores the @emph{results} of required
+tests, thus the test @file{foo-execute.test} is run even if the test
+@file{foo-compile.test} failed or was skipped beforehand.
+
+@cindex Unit tests
+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
+may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
+instead of with @code{check_PROGRAMS}, as the former allows intertwined
+compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
+not cleaned automatically, @pxref{Uniform}).
+
+The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
+conditional parts as well as configure substitutions. In the latter
+case, however, certain restrictions apply: substituted test names
+must end with a nonempty test suffix like @file{.test}, so that one of
+the inference rules generated by @command{automake} can apply. For
+literal test names, @command{automake} can generate per-target rules
+to avoid this limitation.
+
+
@section DejaGnu Tests
If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
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 driver for @code{TESTS} that can run tests in parallel
+(@pxref{Tests}, for more information).
+
@item @option{readme-alpha}
@cindex Option, @option{readme-alpha}
@opindex 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 silent build rules. This will cause many build rules to output a
+status line of the form
+
+@example
+ GEN @var{output-file}
+@end example
+
+@noindent
+instead of printing the command that will be executed to update
+@var{output-file}. It will also silence @command{libtool} output.
+
+@vindex @code{V}
+The verbosity can be influenced at @command{make} run time by setting the
+variable @code{V}: @samp{make V=0} is equivalent to @code{V} being unset,
+while @samp{make V=1} will produce verbose output.
+
+For portability to different @command{make} implementations, package authors
+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 relies on a non-POSIX, but in
+practice rather widely supported @file{Makefile} construct of nested
+variable expansion @samp{$(@var{var1}$(V))}. Do not use the
+@option{silent-rules} option if your package needs to build with
+@command{make} implementations that do not support it. The
+@option{silent-rules} option turns off warnings about recursive variable
+expansion, which are in turn enabled by @option{-Wportability}
+(@pxref{Invoking Automake}).
+
+@vindex @code{AM_V_GEN}
+@vindex @code{AM_V_at}
+To extend the silent mode to your own rules, 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. With @code{V=1}, these
+variables will expand to empty strings.
+
@item @option{std-options}
@cindex Options, @option{std-options}
@cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
projects / platform / upstream / automake.git / blobdiff