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

[Stefano Lattarini]

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