valgrind-tests: Doc fix and introduce AM_VALGRINDFLAGS.

* doc/valgrind-tests.texi (Using valgrind automatically): Clarify
when the parallel vs serial test harness is used, suggested by
Bruno Haible <bruno@clisp.org>.
* m4/valgrind-tests.m4: Add VALGRIND_PROGRAM and AM_VALGRINDFLAGS.

3 files changed, 43 insertions, 12 deletions

diff --git a/ChangeLog b/ChangeLog
index 191f4549e4..136445e8fa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2021-05-14  Simon Josefsson  <simon@josefsson.org>
+
+	valgrind-tests: Doc fix and introduce AM_VALGRINDFLAGS.
+	* doc/valgrind-tests.texi (Using valgrind automatically): Clarify
+	when the parallel vs serial test harness is used, suggested by
+	Bruno Haible <bruno@clisp.org>.
+	* m4/valgrind-tests.m4: Add VALGRIND_PROGRAM and AM_VALGRINDFLAGS.
+
 2021-05-14  Bruno Haible  <bruno@clisp.org>
 
 	malloc-gnu, realloc-gnu, calloc-gnu: Ensure errno gets set to ENOMEM.
diff --git a/doc/valgrind-tests.texi b/doc/valgrind-tests.texi
index 9f3b309680..96a6bbbeef 100644
--- a/doc/valgrind-tests.texi
+++ b/doc/valgrind-tests.texi
@@ -34,7 +34,11 @@ LOG_COMPILER = $(LOG_VALGRIND)
 This will run all self-checks under valgrind.
 
 Replace @code{LOG_COMPILER} with @code{TESTS_ENVIRONMENT} if you are
-using the old serial test harness.
+using the old serial test harness.  The parallel test harness has been
+the default in automake since version 1.11.3, but if you are using an
+older automake, or put @samp{serial-tests} in
+@samp{AM_INIT_AUTOMAKE}/@samp{AUTOMAKE_OPTIONS} you would still be using
+the serial test harness.
 
 If you desire a project-wide decision that valgrind is not enabled by
 default, but still allow users to enable it with
@@ -54,13 +58,13 @@ that are passed to valgrind using the @samp{VALGRINDFLAGS} variable, for
 example:
 
 @smallexample
-./configure VALGRINDFLAGS="--suppressions=/your/local/valgrind/suppressions/file.txt"
+./configure VALGRINDFLAGS="--suppressions=~/local.supp"
 @end smallexample
 
 Alternatively during build phase:
 
 @smallexample
-make check VALGRINDFLAGS="--suppressions=/your/local/valgrind/suppressions/file.txt"
+make check VALGRINDFLAGS="--suppressions=~/local.supp"
 @end smallexample
 
 This is useful if you have a valgrind suppression files that are needed
@@ -106,6 +110,14 @@ gl_INIT
 Note that any user-supplied @code{VALGRINDFLAGS} value is preserved,
 which is usually what you want.
 
+Finally, as a developer you may want to provide additional per-directory
+options to valgrind and the @code{AM_VALGRINDFLAGS} variable can be used
+for this.  For example:
+
+@smallexample
+AM_VALGRINDFLAGS = --suppressions=$(srcdir)/local-valgrind.supp
+LOG_COMPILER = $(LOG_VALGRIND)
+@end smallexample
 
 @node Using valgrind manually
 @subsection Using valgrind at the developer's discretion
@@ -142,8 +154,8 @@ LOG_COMPILER = $(LOG_VALGRIND)
 
 Then valgrind will only be used for the non-.sh and non-.pl tests.
 
-For old automake, you will need @code{AUTOMAKE_OPTIONS = parallel-tests}
-to enable the parallel test harness.
+For old automake (before 1.11.3), you will need @code{AUTOMAKE_OPTIONS =
+parallel-tests} to enable the parallel test harness.
 
 @item
 You can make use of the @code{build-aux/run-test} script from Gnulib.
diff --git a/m4/valgrind-tests.m4 b/m4/valgrind-tests.m4
index b6b46a4963..7727372664 100644
--- a/m4/valgrind-tests.m4
+++ b/m4/valgrind-tests.m4
@@ -13,10 +13,10 @@ dnl From Simon Josefsson
 # Sets VALGRIND to command line (including options) to invoke valgrind
 # with, may be used directly in autoconf, makefiles or shell scripts.
 
-# Sets LOG_VALGRIND, suitable for use with LOG_COMPILER, that in a
-# makefile will expand to command line to invoke self-tests with,
+# Sets LOG_VALGRIND, suitable for use with LOG_COMPILER, that in
+# Makefile will expand to command line to invoke self-tests with,
 # i.e., LOG_VALGRIND = $(VALGRIND) $(DEFAULT_VALGRINDFLAGS)
-# $(VALGRINDFLAGS).
+# $(VALGRINDFLAGS) $(AM_VALGRINDFLAGS).
 
 # Whether to look for valgrind and set the variables can be influenced
 # by calling gl_VALGRIND_TESTS_DEFAULT_NO in configure.ac.
@@ -26,7 +26,8 @@ dnl From Simon Josefsson
 # You may modify the VALGRIND, DEFAULT_VALGRINDFLAGS and VALGRINDFLAGS
 # variables before calling this function to override defaults.  Either
 # as developer from configure.ac or user on the ./configure command
-# line.
+# line.  You may set the AM_VALGRINDFLAGS in Makefile.am to provide a
+# per-directory additional flag.
 
 AC_DEFUN([gl_VALGRIND_TESTS_DEFAULT_NO],
 [
@@ -44,6 +45,13 @@ AC_DEFUN_ONCE([gl_VALGRIND_TESTS],
   if test "$opt_valgrind_tests" = "yes" && test "$cross_compiling" = no; then
     AC_CHECK_PROGS([VALGRIND], [valgrind])
 
+    # VALGRIND_PROGRAM contains the tool found by AC_CHECK_PROGS.  For
+    # backwards compatibility, the VALGRIND variable is later modified
+    # to also include all enabled options.  However the new variable
+    # LOG_VALGRIND needs to be able to refer to the valgrind tool
+    # without options, hence it uses this variable.
+    AC_SUBST([VALGRIND_PROGRAM], [$VALGRIND])
+
     AC_SUBST([DEFAULT_VALGRINDFLAGS])
     if test -z "$DEFAULT_VALGRINDFLAGS"; then
       DEFAULT_VALGRINDFLAGS="-q --error-exitcode=1 --leak-check=full"
@@ -81,12 +89,15 @@ AC_DEFUN_ONCE([gl_VALGRIND_TESTS],
         ])
     fi
 
+    AC_SUBST([AM_VALGRINDFLAGS])
+    AC_SUBST([LOG_VALGRIND], ["\$(VALGRIND_PROGRAM) \$(DEFAULT_VALGRINDFLAGS) \$(VALGRINDFLAGS) \$(AM_VALGRINDFLAGS)"])
+
     if test "$gl_cv_prog_valgrind_works" != yes; then
+      DEFAULT_VALGRINDFLAGS=
+      LOG_VALGRIND=
       VALGRIND=
       VALGRINDFLAGS=
-      DEFAULT_VALGRINDFLAGS=
+      VALGRIND_PROGRAM=
     fi
-
-   AC_SUBST([LOG_VALGRIND], ["\$(VALGRIND) \$(DEFAULT_VALGRINDFLAGS) \$(VALGRINDFLAGS)"])
   fi
 ])