[PATCH] init.sh docs: prefer AM_TESTS_SETUP to TESTS_ENVIRONMENT

[Stefano Lattarini]

Hello Gnulibers.

The latest developement version of Automake has finally implemented
the support for the developer-reserved variable `AM_TESTS_SETUP',
which can be used to run initialization code and set environment
variables for the testsuite (when the "parallel-tests" option is
used) without invading the user's namespace.

I'd thus like to update the documentation in gnulib's `tests/init.sh'
consequently, suggesting to use `AM_TESTS_SETUP' instead of the older
and not namespace-safe `TESTS_ENVIRONMENT' (which can now truly be
reserved for user's own customization and overrides).

My tentative patch is attached.  Note that I've not put "tiny change"
in the ChangeLog entry because I've finally signed the copyright
assignment for Gnulib too.

Regards,
  Stefano

From 15d35254573a9d9fc52e6977b941f0312defff7d Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Sun, 17 Apr 2011 20:43:18 +0200
Subject: [PATCH] init.sh docs: prefer AM_TESTS_SETUP to TESTS_ENVIRONMENT

* tests/init.sh: In the comments documenting usage and interface
of this script, suggest the use of Automake special variable
`AM_TESTS_SETUP' rather than `TESTS_ENVIRONMENT', when the first
is available (i.e., for Automake >= 1.12 when the "parallel-tests"
option is used).  For more information, see the original mailing
list discussion at:
<http://lists.gnu.org/archive/html/automake-patches/2011-01/msg00213.html>
---
 ChangeLog     |   11 +++++++++++
 tests/init.sh |   21 ++++++++++++++-------
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index c81be0c..19b1f21 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2011-04-17  Stefano Lattarini  <address@hidden>
+
+       init.sh docs: prefer AM_TESTS_SETUP to TESTS_ENVIRONMENT
+       * tests/init.sh: In the comments documenting usage and interface
+       of this script, suggest the use of Automake special variable
+       `AM_TESTS_SETUP' rather than `TESTS_ENVIRONMENT', when the first
+       is available (i.e., for Automake >= 1.12 when the "parallel-tests"
+       option is used).  For more information, see the original mailing
+       list discussion at:
+       
<http://lists.gnu.org/archive/html/automake-patches/2011-01/msg00213.html>
+
 2011-04-16  Bruno Haible  <address@hidden>
 
        gettext: Clarify the needed programmer actions.
diff --git a/tests/init.sh b/tests/init.sh
index 71c6516..ca1ca68 100644
--- a/tests/init.sh
+++ b/tests/init.sh
@@ -30,7 +30,9 @@
 #   For example, if the programs you want to test are in src/, and this test
 #   script is named tests/test-1, then you would use "path_prepend_ ../src",
 #   or perhaps export PATH='$(abs_top_builddir)/src$(PATH_SEPARATOR)'"$$PATH"
-#   to all tests via automake's TESTS_ENVIRONMENT.
+#   to all tests via automake's AM_TESTS_SETUP (if you are using an automake
+#   version earlier than 1.12, or are not using the "parallel-tests" option,
+#   you'll have to use TEST_ENVIRONMENT instead of AM_TESTS_SETUP).
 #   Set the exit code 0 for success, 77 for skipped, or 1 or other for failure.
 #   Use the skip_ and fail_ functions to print a diagnostic and then exit
 #   with the corresponding exit code.
@@ -48,8 +50,9 @@
 # Running a single test, with single-stepping:
 #   1. Go into a sub-shell:
 #   $ bash
-#   2. Set relevant environment variables from TESTS_ENVIRONMENT in the
-#      Makefile:
+#   2. Run the setup code from AM_TESTS_SETUP and/or TESTS_ENVIRONMENT
+#      in the Makefile (in most situations, this will consist only of
+#      assignments of relevant environment variables):
 #   $ export srcdir=../../tests # this is an example
 #   3. Execute the commands from the test, copy&pasting them one by one:
 #   $ . "$srcdir/init.sh"; path_prepend_ .
@@ -68,10 +71,14 @@ Exit () { set +e; (exit $1); exit $1; }
 
 # Print warnings (e.g., about skipped and failed tests) to this file number.
 # Override by defining to say, 9, in init.cfg, and putting say,
-# "export ...ENVVAR_SETTINGS...; exec 9>&2; $(SHELL)" in the definition
-# of TESTS_ENVIRONMENT in your tests/Makefile.am file.
-# This is useful when using automake's parallel tests mode, to print
-# the reason for skip/failure to console, rather than to the .log files.
+# "export ...ENVVAR_SETTINGS...; exec 9>&2;" in the definition of
+# AM_TESTS_SETUP in your tests/Makefile.am file (note that if you're
+# using an automake version earlier than 1.12, or are not using the
+# "parallel-tests" option, you'll have to use TEST_ENVIRONMENT instead
+# of AM_TESTS_SETUP).
+# This is especially useful when using automake's parallel tests mode,
+# to print the reason for skip/failure to console, rather than to the
+# .log files.
 : ${stderr_fileno_=2}
 
 warn_ () { echo "$@" 1>&$stderr_fileno_; }
-- 
1.7.2.3