| @node Running self-tests under valgrind |
| @section Running self-tests under valgrind |
| |
| @cindex valgrind |
| |
| For projects written in C or similar languages, running the self-tests |
| under Valgrind can reveal hard to find memory issues. Gnulib supports |
| two ways to make use of Valgrind: one that enables use of Valgrind at |
| configure time, when @code{configure} found it to be present; and one |
| at the discretion of the developer. |
| |
| @menu |
| * Using valgrind automatically:: |
| * Using valgrind manually:: |
| * Valgrind and shell scripts:: |
| @end menu |
| |
| @node Using valgrind automatically |
| @subsection Using valgrind without developer intervention |
| |
| The @code{valgrind-tests} module searches for Valgrind at configure time |
| and declares the @code{VALGRIND} automake variable for use with automake's |
| @code{TESTS_ENVIRONMENT}. |
| |
| After importing the @code{valgrind-tests} module to your project, you |
| use it by adding the following to the @code{Makefile.am} that runs the |
| self-tests: |
| |
| @smallexample |
| TESTS_ENVIRONMENT = $(VALGRIND) |
| @end smallexample |
| |
| This will run all self-checks under valgrind. |
| |
| @node Using valgrind manually |
| @subsection Using valgrind at the developer's discretion |
| |
| In this approach, you define a @code{Makefile.am} variable @samp{VALGRIND} |
| (or, more abstractly, @samp{CHECKER}), that is usually set to empty. |
| When you have configured and built the package and you decide that you want |
| to run the tests with valgrind, you do so by modifying the definition of |
| @samp{VALGRIND} in the Makefile. |
| |
| @node Valgrind and shell scripts |
| @subsection How to use Valgrind with shell scripts |
| |
| It is not desirable to apply valgrind to shell scripts or other non-binaries, |
| because |
| @itemize @bullet |
| @item |
| It is wasteful, and you usually don't want to look for memory leaks in bash. |
| @item |
| On a bi-arch system, you may get an error message such as |
| "valgrind: wrong executable class (eg. 32-bit instead of 64-bit)". |
| @end itemize |
| |
| There are two ways to avoid this: |
| |
| @itemize @bullet |
| @item |
| You can make use of the @code{build-aux/run-test} script from Gnulib. |
| Add these lines to your @code{Makefile.am}: |
| |
| @smallexample |
| # This must be the last thing that gets added to TESTS_ENVIRONMENT. |
| TESTS_ENVIRONMENT += $(SHELL) $(top_srcdir)/build-aux/run-test '$(VALGRIND)' |
| @end smallexample |
| |
| @item |
| Using the Automake parallel-tests feature, you can use the following instead: |
| |
| @smallexample |
| AUTOMAKE_OPTIONS = parallel-tests |
| TEST_EXTENSIONS = .pl .sh |
| LOG_COMPILER = $(VALGRIND) |
| @end smallexample |
| |
| Then valgrind will only be used for the non-.sh and non-.pl tests. |
| @end itemize |
| |
| However, with this measure in place, binaries invoked through scripts will |
| not be invoked under valgrind. This can be solved by defining environment |
| variables in the @code{TESTS_ENVIRONMENT} variable that are then used by the |
| shell scripts. For example, add the following: |
| |
| @smallexample |
| TESTS_ENVIRONMENT = VALGRIND='$(VALGRIND)' |
| @end smallexample |
| |
| And then modify the shell scripts to invoke the binary prefixed with |
| @code{$VALGRIND}. |