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
> > > -@emph{must} be terminated by a semicolon.
> > > -
> > > -@example
> > > -# 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.
>
> > > +@emph{must} be terminated by a semicolon. Here is an example of a
> > > +slightly elaborate definition:
> > > +
> > > +@example
> > > +# 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;
> > > +@c $$ 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: <69bb25618c4f3a14e5b405822d726620e955b07b.1309332209.git.stefano.lattar...@gmail.com>
From: Stefano Lattarini <stefano.lattar...@gmail.com>
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 <stefano.lattar...@gmail.com>
+
+ 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 <stefano.lattar...@gmail.com>
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
-@emph{must} be terminated by a semicolon.
-
-@example
-# 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;
+@emph{must} be terminated by a semicolon. Here is an example of a
+slightly elaborate definition:
+
+@example
+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;
+@c $$ restore font-lock
@end example
@trindex mostlyclean
--
1.7.2.3
