From 085815ce102e45bceefe8ea290dcf2efcd2dc74b Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Mon, 22 Feb 2016 12:30:37 +0000
Subject: [PATCH] build: Describe how to set up check-valgrind rules correctly.

Since we enabled parallel tests, you can no longer run tests
under valgrind merely by doing:

  TESTS_ENVIRONMENT = $(top_builddir)/run --test $(VG)
  check-valgrind:
      $(MAKE) check VG="@VG@"

The reason is that the parallel tests framework doesn't run
``$(TESTS_ENVIRONMENT) <test>''.  It inserts some other processes in
between the environment and the test, so you end up valgrinding some
unrelated process (currently the 'env' program).

In run.in, remove out of date documentation for using $(VG).
In guestfs-hacking(1), document how to do it properly.
---
 docs/guestfs-hacking.pod | 32 ++++++++++++++++++++++++++++++--
 run.in                   |  5 +----
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/docs/guestfs-hacking.pod b/docs/guestfs-hacking.pod
index c35771732..419a4c29b 100644
--- a/docs/guestfs-hacking.pod
+++ b/docs/guestfs-hacking.pod
@@ -274,8 +274,7 @@ the automake documentation for details.
 
 Runs a subset of the test suite under valgrind.
 
-Any F<Makefile.am> in the tree that has a C<check-valgrind:> target
-will be run by this rule.
+See L</VALGRIND> below.
 
 =item C<make check-valgrind-local-guests>
 
@@ -383,6 +382,35 @@ Do:
 
 =back
 
+=head2 VALGRIND
+
+When you do C<make check-valgrind>, it searches for any F<Makefile.am>
+in the tree that has a C<check-valgrind:> target and runs it.
+
+Writing the F<Makefile.am> and tests correctly to use valgrind and
+working with automake parallel tests is subtle.
+
+If your tests are run via a shell script wrapper, then in the wrapper
+use:
+
+ $VG virt-foo
+
+and in the F<Makefile.am> use:
+
+ check-valgrind:
+     make VG="$(top_builddir)/run @VG@" check
+
+However, if your binaries run directly from the C<TESTS> rule, you
+have to modify the F<Makefile.am> like this:
+
+ LOG_COMPILER = $(VG)
+ 
+ check-valgrind:
+     make VG="@VG@" check
+
+In either case, check that the right program is being tested by
+examining the F<tmp/valgrind*> log files carefully.
+
 =head1 SUBMITTING PATCHES
 
 Submit patches to the mailing list:
diff --git a/run.in b/run.in
index ed4109c80..c91183416 100755
--- a/run.in
+++ b/run.in
@@ -33,13 +33,10 @@
 #
 # The script should also be used for tests like this:
 #
-#   TESTS_ENVIRONMENT = ... $(top_builddir)/run --test [$(VG)]
+#   TESTS_ENVIRONMENT = ... $(top_builddir)/run --test
 #
 # The --test parameter introduces a timeout, stopping tests from
 # running forever.
-#
-# Use the optional $(VG) when the tests must also be run under
-# valgrind.
 
 #----------------------------------------------------------------------