Re: [FYI] {master} docs: fix unportable example of AM_TESTS_ENVIRONMENT usage

[Stefano Lattarini]

On Thursday 23 June 2011, Stefano Lattarini wrote:
> On Thursday 23 June 2011, Ralf Wildenhues wrote:
> > * Stefano Lattarini wrote on Thu, Jun 23, 2011 at 07:09:16PM CEST:
> > > * doc/automake.texi (Simple Tests using parallel-tests): The
> > > old example on AM_TESTS_ENVIRONMENT relied on unportable shell
> > > features, and in particular didn't work with various Korn
> > > Shells (see also commit `v1.11-925-g29ca903').  Give another
> > > example, simpler this time, but still inspired to real-world
> > > usage (the GNU coreutils testsuite).
> > 
> > > --- a/doc/automake.texi
> > > +++ b/doc/automake.texi
> > > @@ -8742,21 +8742,23 @@ code and set environment variables for the tests' 
> > > runs.  The user can
> > >  still employ the @code{TESTS_ENVIRONMENT} variable to override settings
> > >  from @code{AM_TESTS_ENVIRONMENT}.  Note that, for implementation reasons,
> > >  if the @code{AM_TESTS_ENVIRONMENT} variable is set, its contents
> > > address@hidden be terminated by a semicolon.
> > > -
> > > address@hidden
> > > -# The tests below are expected to use the file descriptor passed in
> > > -# the environment variable 'warn_fileno' to print warnings (e.g.,
> > > -# about skipped and failed tests).  If this variable were to be set
> > > -# to `2' (i.e. default stderr), the warnings would be redirected by
> > > -# the automake parallel-tests driver into the .log files.  But the
> > > -# AM_TESTS_ENVIRONMENT definition below will cause the reasons for
> > > -# skip/failure to be printed to the console instead.  The user
> > > -# can still override this by setting TESTS_ENVIRONMENT to e.g.
> > > -# `warn_fileno=2' at make runtime, which will cause the warnings
> > > -# to be sent to the .log files again.
> > > -TESTS = test1.sh test2.sh ...
> > > -AM_TESTS_ENVIRONMENT = exec 9>&2; warn_fileno=9; export warn_fileno;
> > 
> > This example served two purposes: use of AM_TESTS_ENVIRONMENT, and
> > showing how to produce output while the test is running.  Your patch
> > removes the second feature.  Can we have it back, ideally in a portable
> > fashion?
> >
> Alas, no.  The only way to do that portably is to either:
>  1. add a trailing `; >&2' to AM_TESTS_ENVIRONMENT, *and* force the user
>     not to define TESTS_ENVIRONMENT; or
>  2. use TESTS_ENVIRONMENT, not AM_TESTS_ENVIRONMENT, in the Makefile.am
>     (still with a trailing `; >&2' obviously).
> In each case, the user's namespace is invaded, and we go against our own
> advice (in [1] we violate the "always terminate AM_TESTS_ENVIRONMENT with
> a semicolon" rule, in [2] we violate "don't define TESTS_ENVIRONMENT in
> the Makefile.am, it's user-reserved" rule).
> 
> Also, the example above belongs IMHO more in a FAQ rather than in a
> reference manual.
> 
> > > address@hidden be terminated by a semicolon.  Here is an example of a
> > > +slightly elaborate definition:
> > > +
> > > address@hidden
> > > +# Some environment initializations are kept in a separate shell file
> > > +# `tests-env.sh', which can be helpful to run tests from the command 
> > > line.
> > 
> > > +# We don't want to depend on the `srcdir' value exported by the Automake
> > > +# testsuite harness; we define it statically in the `tests-env' file.
> > 
> > This sentence does not make sense to me, in this particular context.
> > As a user, it would confuse me, at least without further explanation.
> >
> Let's just remove the sentence and the unset then (their purpose was just
> to make the example a little more varied and interesting, but this purpose
> is defied if they end up maing the example less clear instead).  OK?
> 
> > > +# On Solaris, prefer more POSIX-compliant versions of the standard tools
> > > +# by default.
> > > +AM_TESTS_ENVIRONMENT = \
> > > +  unset srcdir; \
> > > +  . $(srcdir)/tests-env.sh; \
> > > +  if test -d /usr/xpg4/bin; then \
> > > +    PATH=/usr/xpg4/bin:$$PATH; export PATH; \
> > > +  fi;
> > > address@hidden $$ restore font-lock
> > >  @end example
> > >  
> > >  @trindex mostlyclean
> > 
> > Thanks,
> > Ralf
> > 
> > 
> Regards,
>   Stefano
> 
Attached is what I've finally pushed.

Regards,
  Stefano

From 69bb25618c4f3a14e5b405822d726620e955b07b Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Stefano Lattarini <address@hidden>
Date: Thu, 23 Jun 2011 19:05:44 +0200
Subject: [PATCH] docs: fix unportable example of AM_TESTS_ENVIRONMENT usage

* doc/automake.texi (Simple Tests using parallel-tests): The
old example on AM_TESTS_ENVIRONMENT relied on unportable shell
features, and in particular didn't work with various Korn
Shells (see also commit `v1.11-925-g29ca903').  Give another
example, simpler this time, but still inspired to real-world
usage (the GNU coreutils testsuite).
---
 ChangeLog         |   10 ++++++++++
 doc/automake.texi |   30 +++++++++++++++---------------
 2 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f121e0e..7c8888e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2011-06-29  Stefano Lattarini  <address@hidden>
+
+       docs: fix unportable example of AM_TESTS_ENVIRONMENT usage
+       * doc/automake.texi (Simple Tests using parallel-tests): The
+       old example on AM_TESTS_ENVIRONMENT relied on unportable shell
+       features, and in particular didn't work with various Korn
+       Shells (see also commit `v1.11-925-g29ca903').  Give another
+       example, simpler this time, but still inspired to real-world
+       usage (the GNU coreutils testsuite).
+
 2011-04-18  Stefano Lattarini  <address@hidden>
 
        check: rename AM_TESTS_SETUP -> AM_TESTS_ENVIRONMENT
diff --git a/doc/automake.texi b/doc/automake.texi
index 7394253..d60bfe4 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8742,21 +8742,21 @@ code and set environment variables for the tests' runs. 
 The user can
 still employ the @code{TESTS_ENVIRONMENT} variable to override settings
 from @code{AM_TESTS_ENVIRONMENT}.  Note that, for implementation reasons,
 if the @code{AM_TESTS_ENVIRONMENT} variable is set, its contents
address@hidden be terminated by a semicolon.
-
address@hidden
-# The tests below are expected to use the file descriptor passed in
-# the environment variable 'warn_fileno' to print warnings (e.g.,
-# about skipped and failed tests).  If this variable were to be set
-# to `2' (i.e. default stderr), the warnings would be redirected by
-# the automake parallel-tests driver into the .log files.  But the
-# AM_TESTS_ENVIRONMENT definition below will cause the reasons for
-# skip/failure to be printed to the console instead.  The user
-# can still override this by setting TESTS_ENVIRONMENT to e.g.
-# `warn_fileno=2' at make runtime, which will cause the warnings
-# to be sent to the .log files again.
-TESTS = test1.sh test2.sh ...
-AM_TESTS_ENVIRONMENT = exec 9>&2; warn_fileno=9; export warn_fileno;
address@hidden be terminated by a semicolon.  Here is an example of a
+slightly elaborate definition:
+
address@hidden
+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 from the
+## command line.
+  . $(srcdir)/tests-env.sh; \
+## On Solaris, prefer more POSIX-compliant versions of the standard tools
+## by default.
+  if test -d /usr/xpg4/bin; then \
+    PATH=/usr/xpg4/bin:$$PATH; export PATH; \
+  fi;
address@hidden $$ restore font-lock
 @end example
 
 @trindex mostlyclean
-- 
1.7.2.3