Documentation for the parallel-tests driver. [4/4]

[Ralf Wildenhues]

    Documentation for the parallel-tests driver.
    
    * doc/automake.texi (Tests, Options): Document the `parallel-tests'
    option, including new features of the test driver.
    * NEWS: Update.

diff --git a/NEWS b/NEWS
index ed71e9e..6171e2e 100644
--- a/NEWS
+++ b/NEWS
@@ -101,6 +101,11 @@ New in 1.10a:
 
   - The `color-tests' option causes colored test result output on terminals.
 
+  - The `parallel-tests' option enables a new test driver that allows for
+    parallel test execution, and formatted result output as RST
+    (reStructuredText) and HTML.  Enabling this option may require some
+    changes to your test suite setup; see the manual for details.
+
   - New prefix `notrans_' for manpages which should not be transformed
     by --program-transform.
 
diff --git a/doc/automake.texi b/doc/automake.texi
index 9c157ae..8e494e8 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8323,7 +8323,8 @@ default, only the @code{dist-gzip} target is hooked to 
@code{dist}.
 @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
 
@@ -8359,7 +8360,7 @@ terminal with @samp{AM_COLOR_TESTS=always}.
 @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
@@ -8396,6 +8397,107 @@ that @code{check_PROGRAMS} are @emph{not} automatically 
added to
 by the tests, not the tests themselves.  Of course you can set
 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
 
+
address@hidden Simple tests using @samp{parallel-tests}
address@hidden @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
address@hidden (reStructuredText) and @samp{HTML} format, and hard errors
+for early abort of test runs.  Similar to the simple test driver,
address@hidden, @code{AM_COLOR_TESTS}, @code{XFAIL_TESTS}, and
+the @code{check_*} variables are honored, and the environment variable
address@hidden is set during test execution.
+
address@hidden TEST_SUITE_LOG
address@hidden 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
address@hidden and requires a @file{.log} suffix.  This file
+depends upon log files created for each single test program listed in
address@hidden, which in turn contain all output produced by the
+corresponding tests.
+
address@hidden TEST_SUFFIXES
+Each log file is created when the corresponding test has completed.
+The set of log files is listed in the read-only variable
address@hidden, and defaults to @code{TESTS}, with the executable
+extension if any (@pxref{EXEEXT}), as well as any suffix listed in
address@hidden removed, and @file{.log} appended.
address@hidden defaults to @file{.test}.  Results are undefined
+if a test file name ends in several concatenated suffixes.
+
address@hidden 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.
+If the variable @samp{VERBOSE} is set, the @file{test-suite.log} file is
+appended after the summary.
+
address@hidden mostlyclean
address@hidden check-html
address@hidden RST2HTML
address@hidden 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
address@hidden  The variable @samp{TEST_SUITE_HTML} contains the
+set of converted log files.  The log and HTML files are removed upon
address@hidden mostlyclean}.
+
address@hidden DISABLE_HARD_ERRORS
address@hidden Exit status 99, special interpretation
+Sometimes, a condition may arise during a test suite run that makes it
+desirable to avoid running further tests, for example when an external
+resource like disk space is exhausted.  Unless the variable
address@hidden is set to a nonempty value, an exit status of
+99 of a test will prevent further tests from being spawned.
+
address@hidden 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
address@hidden, 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}:
+
address@hidden
+TESTS = foo-compile.test foo-execute.test
+foo-execute.log: foo-compile.log
address@hidden example
+
address@hidden
+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
address@hidden failed or was skipped beforehand.  You can use
+hard errors as described above to achieve this, or provide suitable
+additional checks within your test code.
+
address@hidden 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
@@ -8710,6 +8812,13 @@ are ordinarily automatically provided by Automake.
 Don't require @file{texinfo.tex}, even if there are texinfo files in
 this directory.
 
address@hidden @option{parallel-tests}
address@hidden Option, @option{parallel-tests}
address@hidden 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