automake-1.16: Testsuite Environment Overrides
15.2.1.1 Testsuite Environment Overrides
........................................
The ‘AM_TESTS_ENVIRONMENT’ and ‘TESTS_ENVIRONMENT’ variables can be used
to run initialization code and set environment variables for the test
scripts. The former variable is developer-reserved, and can be defined
in the ‘Makefile.am’, while the latter is reserved for the user, which
can employ it to extend or override the settings in the former; for this
to work portably, however, the contents of a non-empty
‘AM_TESTS_ENVIRONMENT’ _must_ be terminated by a semicolon.
The ‘AM_TESTS_FD_REDIRECT’ variable can be used to define file
descriptor redirections for the test scripts. One might think that
‘AM_TESTS_ENVIRONMENT’ could be used for this purpose, but experience
has shown that doing so portably is practically impossible. The main
hurdle is constituted by Korn shells, which usually set the
close-on-exec flag on file descriptors opened with the ‘exec’ builtin,
thus rendering an idiom like ‘AM_TESTS_ENVIRONMENT = exec 9>&2;’
ineffectual. This issue also affects some Bourne shells, such as the
HP-UX’s ‘/bin/sh’.
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;
## With this, the test scripts will be able to print diagnostic
## messages to the original standard error stream, even if the test
## driver redirects the stderr of the test scripts to a log file
## before executing them.
AM_TESTS_FD_REDIRECT = 9>&2
As another example, a notice that a test is starting can be emitted
using ‘AM_TESTS_ENVIRONMENT’ (for package maintainers) or
‘TESTS_ENVIRONMENT’ by users:
make -j12 ... TESTS_ENVIRONMENT='echo RUNNING: "$$f";' check
The shell variable ‘$f’ contains the test name. (Although technically
this is not guaranteed, in practice it is extremely unlikely to ever
change.) This can be helpful to see when trying to debug test failures.
Notwithstanding these benefits, ‘AM_TESTS_ENVIRONMENT’ is, for
historical and implementation reasons, _not_ supported by the serial
harness (⇒Serial Test Harness).