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

@@ -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:

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.
 
 #----------------------------------------------------------------------