doc/valgrind-tests.texi

   1 @node Running self-tests under valgrind
   2 @section Running self-tests under valgrind
   3
   4 @cindex valgrind
   5
   6 For projects written in C or similar languages, running the self-tests
   7 under Valgrind can reveal hard to find memory issues.  Gnulib supports
   8 two ways to make use of Valgrind: one that enables use of Valgrind at
   9 configure time, when @code{configure} found it to be present; and one
  10 at the discretion of the developer.
  11
  12 @menu
  13 * Using valgrind automatically::
  14 * Using valgrind manually::
  15 * Valgrind and shell scripts::
  16 @end menu
  17
  18 @node Using valgrind automatically
  19 @subsection Using valgrind without developer intervention
  20
  21 The @code{valgrind-tests} module searches for Valgrind at configure time
  22 and declares the @code{VALGRIND} automake variable for use with automake's
  23 @code{TESTS_ENVIRONMENT}.
  24
  25 After importing the @code{valgrind-tests} module to your project, you
  26 use it by adding the following to the @code{Makefile.am} that runs the
  27 self-tests:
  28
  29 @smallexample
  30 TESTS_ENVIRONMENT = $(VALGRIND)
  31 @end smallexample
  32
  33 This will run all self-checks under valgrind.
  34
  35 @node Using valgrind manually
  36 @subsection Using valgrind at the developer's discretion
  37
  38 In this approach, you define a @code{Makefile.am} variable @samp{VALGRIND}
  39 (or, more abstractly, @samp{CHECKER}), that is usually set to empty.
  40 When you have configured and built the package and you decide that you want
  41 to run the tests with valgrind, you do so by modifying the definition of
  42 @samp{VALGRIND} in the Makefile.
  43
  44 @node Valgrind and shell scripts
  45 @subsection How to use Valgrind with shell scripts
  46
  47 It is not desirable to apply valgrind to shell scripts or other non-binaries,
  48 because
  49 @itemize @bullet
  50 @item
  51 It is wasteful, and you usually don't want to look for memory leaks in bash.
  52 @item
  53 On a bi-arch system, you may get an error message such as
  54 "valgrind: wrong executable class (eg. 32-bit instead of 64-bit)".
  55 @end itemize
  56
  57 There are two ways to avoid this:
  58
  59 @itemize @bullet
  60 @item
  61 You can make use of the @code{build-aux/run-test} script from Gnulib.
  62 Add these lines to your @code{Makefile.am}:
  63
  64 @smallexample
  65 # This must be the last thing that gets added to TESTS_ENVIRONMENT.
  66 TESTS_ENVIRONMENT += $(SHELL) $(top_srcdir)/build-aux/run-test '$(VALGRIND)'
  67 @end smallexample
  68
  69 @item
  70 Using the Automake parallel-tests feature, you can use the following instead:
  71
  72 @smallexample
  73 AUTOMAKE_OPTIONS = parallel-tests
  74 TEST_EXTENSIONS = .pl .sh
  75 LOG_COMPILER = $(VALGRIND)
  76 @end smallexample
  77
  78 Then valgrind will only be used for the non-.sh and non-.pl tests.
  79 @end itemize
  80
  81 However, with this measure in place, binaries invoked through scripts will
  82 not be invoked under valgrind.  This can be solved by defining environment
  83 variables in the @code{TESTS_ENVIRONMENT} variable that are then used by the
  84 shell scripts.  For example, add the following:
  85
  86 @smallexample
  87 TESTS_ENVIRONMENT = VALGRIND='$(VALGRIND)'
  88 @end smallexample
  89
  90 And then modify the shell scripts to invoke the binary prefixed with
  91 @code{$VALGRIND}.