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 * Valgrind options::
  15 * Using valgrind manually::
  16 * Valgrind and shell scripts::
  17 @end menu
  18
  19 @node Using valgrind automatically
  20 @subsection Using valgrind without developer intervention
  21
  22 The @code{valgrind-tests} module searches for Valgrind at configure time
  23 and declares the @code{LOG_VALGRIND} automake variable for use with
  24 automake's @code{LOG_COMPILER}.
  25
  26 After importing the @code{valgrind-tests} module to your project, you
  27 use it by adding the following to the @code{Makefile.am} that runs the
  28 self-tests:
  29
  30 @smallexample
  31 LOG_COMPILER = $(LOG_VALGRIND)
  32 @end smallexample
  33
  34 This will run all self-checks under valgrind.
  35
  36 Replace @code{LOG_COMPILER} with @code{TESTS_ENVIRONMENT} if you are
  37 using the old serial test harness.  The parallel test harness has been
  38 the default in automake since version 1.11.3, but if you are using an
  39 older automake, or put @samp{serial-tests} in
  40 @samp{AM_INIT_AUTOMAKE}/@samp{AUTOMAKE_OPTIONS} you would still be using
  41 the serial test harness.
  42
  43 If you desire a project-wide decision that valgrind is not enabled by
  44 default, but still allow users to enable it with
  45 @code{--enable-valgrind-tests} you may put the following in configure.ac
  46 before gl_INIT.
  47
  48 @smallexample
  49 gl_VALGRIND_TESTS_DEFAULT_NO
  50 @end smallexample
  51
  52 @node Valgrind options
  53 @subsection Valgrind options
  54
  55 The @code{VALGRIND} variable holds the name of the valgrind binary and
  56 some options passed to valgrind.  You may provide additional options
  57 that are passed to valgrind using the @samp{VALGRINDFLAGS} variable, for
  58 example:
  59
  60 @smallexample
  61 ./configure VALGRINDFLAGS="--suppressions=~/local.supp"
  62 @end smallexample
  63
  64 Alternatively during build phase:
  65
  66 @smallexample
  67 make check VALGRINDFLAGS="--suppressions=~/local.supp"
  68 @end smallexample
  69
  70 This is useful if you have a valgrind suppression files that are needed
  71 to avoid triggering errors for known errors, typically in system
  72 libraries.
  73
  74 The @code{VALGRIND} variable include options that are useful when
  75 valgrind is run non-interactively through the test harness.  The default
  76 parameters are @code{-q} to silence the output,
  77 @code{--error-exitcode=1} to cause valgrind errors to be treated as
  78 fatal errors, and @code{--leak-check=full} to check for memory leaks.
  79
  80 These options can be controlled through the @code{DEFAULT_VALGRINDFLAGS}
  81 variable.  For example, when configuring the package:
  82
  83 @smallexample
  84 ./configure DEFAULT_VALGRINDFLAGS="--quiet"
  85 @end smallexample
  86
  87 Alternatively, during the build phase:
  88
  89 @smallexample
  90 make check DEFAULT_VALGRINDFLAGS="--quiet"
  91 @end smallexample
  92
  93 That would have the effect of removing @code{--error-exitcode=1} and
  94 @code{--leak-check=full} from the default options, thus causing any
  95 valgrind errors to be silently ignored, instead of causing fatal test
  96 failures.
  97
  98 As a developer you may use the variables in @code{configure.ac} before
  99 calling @code{gl_INIT}, like this if your program has deeply-nested call
 100 chains:
 101
 102 @smallexample
 103 gl_EARLY
 104 ...
 105 VALGRINDFLAGS="$VALGRINDFLAGS --num-callers=42"
 106 ...
 107 gl_INIT
 108 @end smallexample
 109
 110 Note that any user-supplied @code{VALGRINDFLAGS} value is preserved,
 111 which is usually what you want.
 112
 113 Finally, as a developer you may want to provide additional per-directory
 114 options to valgrind and the @code{AM_VALGRINDFLAGS} variable can be used
 115 for this.  For example:
 116
 117 @smallexample
 118 AM_VALGRINDFLAGS = --suppressions=$(srcdir)/local-valgrind.supp
 119 LOG_COMPILER = $(LOG_VALGRIND)
 120 @end smallexample
 121
 122 @node Using valgrind manually
 123 @subsection Using valgrind at the developer's discretion
 124
 125 In this approach, you define a @code{Makefile.am} variable @samp{VALGRIND}
 126 (or, more abstractly, @samp{CHECKER}), that is usually set to empty.
 127 When you have configured and built the package and you decide that you want
 128 to run the tests with valgrind, you do so by modifying the definition of
 129 @samp{VALGRIND} in the Makefile.
 130
 131 @node Valgrind and shell scripts
 132 @subsection How to use Valgrind with shell scripts
 133
 134 It is not desirable to apply valgrind to shell scripts or other non-binaries,
 135 because
 136 @itemize @bullet
 137 @item
 138 It is wasteful, and you usually don't want to look for memory leaks in bash.
 139 @item
 140 On a bi-arch system, you may get an error message such as
 141 "valgrind: wrong executable class (eg. 32-bit instead of 64-bit)".
 142 @end itemize
 143
 144 There are two ways to avoid this:
 145
 146 @itemize @bullet
 147 @item
 148 Using the Automake parallel-tests feature, you can use the following instead:
 149
 150 @smallexample
 151 TEST_EXTENSIONS = .pl .sh
 152 LOG_COMPILER = $(LOG_VALGRIND)
 153 @end smallexample
 154
 155 Then valgrind will only be used for the non-.sh and non-.pl tests.
 156
 157 For old automake (before 1.11.3), you will need @code{AUTOMAKE_OPTIONS =
 158 parallel-tests} to enable the parallel test harness.
 159
 160 @item
 161 You can make use of the @code{build-aux/run-test} script from Gnulib.
 162 Add these lines to your @code{Makefile.am}:
 163
 164 @smallexample
 165 LOG_COMPILER += $(SHELL) $(top_srcdir)/build-aux/run-test '$(LOG_VALGRIND)'
 166 @end smallexample
 167
 168 Replace @code{LOG_COMPILER} with @code{TESTS_ENVIRONMENT} if you use the
 169 old serial test harness.
 170 @end itemize
 171
 172 However, with this measure in place, binaries invoked through scripts will
 173 not be invoked under valgrind.  This can be solved by defining environment
 174 variables in the @code{TESTS_ENVIRONMENT} variable that are then used by the
 175 shell scripts.  For example, add the following:
 176
 177 @smallexample
 178 TESTS_ENVIRONMENT = VALGRIND='$(LOG_VALGRIND)'
 179 @end smallexample
 180
 181 And then modify the shell scripts to invoke the binary prefixed with
 182 @code{$VALGRIND}.