| 1 |
NAME |
| 2 |
Test::Valgrind - Generate suppressions, analyse and test any command |
| 3 |
with valgrind. |
| 4 |
|
| 5 |
VERSION |
| 6 |
Version 1.19 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
# From the command-line |
| 10 |
perl -MTest::Valgrind leaky.pl |
| 11 |
|
| 12 |
# From the command-line, snippet style |
| 13 |
perl -MTest::Valgrind -e 'leaky()' |
| 14 |
|
| 15 |
# In a test file |
| 16 |
use Test::More; |
| 17 |
eval 'use Test::Valgrind'; |
| 18 |
plan skip_all => 'Test::Valgrind is required to test your distribution with valgrind' if $@; |
| 19 |
leaky(); |
| 20 |
|
| 21 |
# In all the test files of a directory |
| 22 |
prove --exec 'perl -Iblib/lib -Iblib/arch -MTest::Valgrind' t/*.t |
| 23 |
|
| 24 |
DESCRIPTION |
| 25 |
This module is a front-end to the "Test::Valgrind::*" API that lets you |
| 26 |
run Perl code through the "memcheck" tool of the "valgrind" memory |
| 27 |
debugger, to test for memory errors and leaks. If they aren't available |
| 28 |
yet, it will first generate suppressions for the current "perl" |
| 29 |
interpreter and store them in the portable flavour of |
| 30 |
~/.perl/Test-Valgrind/suppressions/$VERSION. The actual run will then |
| 31 |
take place, and tests will be passed or failed according to the result |
| 32 |
of the analysis. |
| 33 |
|
| 34 |
The complete API is much more versatile than this. By declaring an |
| 35 |
appropriate Test::Valgrind::Command class, you can run any executable |
| 36 |
(that is, not only Perl scripts) under valgrind, generate the |
| 37 |
corresponding suppressions on-the-fly and convert the analysis result to |
| 38 |
TAP output so that it can be incorporated into your project's testsuite. |
| 39 |
If you're not interested in producing TAP, you can output the results in |
| 40 |
whatever format you like (for example HTML pages) by defining your own |
| 41 |
Test::Valgrind::Action class. |
| 42 |
|
| 43 |
Due to the nature of perl's memory allocator, this module can't track |
| 44 |
leaks of Perl objects. This includes non-mortalized scalars and memory |
| 45 |
cycles. However, it can track leaks of chunks of memory allocated in XS |
| 46 |
extensions with "Newx" and friends or "malloc". As such, it's |
| 47 |
complementary to the other very good leak detectors listed in the "SEE |
| 48 |
ALSO" section. |
| 49 |
|
| 50 |
METHODS |
| 51 |
"analyse" |
| 52 |
Test::Valgrind->analyse(%options); |
| 53 |
|
| 54 |
Run a "valgrind" analysis configured by %options : |
| 55 |
|
| 56 |
* "command => $command" |
| 57 |
|
| 58 |
The Test::Valgrind::Command object (or class name) to use. |
| 59 |
|
| 60 |
Defaults to Test::Valgrind::Command::PerlScript. |
| 61 |
|
| 62 |
* "tool => $tool" |
| 63 |
|
| 64 |
The Test::Valgrind::Tool object (or class name) to use. |
| 65 |
|
| 66 |
Defaults to Test::Valgrind::Tool::memcheck. |
| 67 |
|
| 68 |
* "action => $action" |
| 69 |
|
| 70 |
The Test::Valgrind::Action object (or class name) to use. |
| 71 |
|
| 72 |
Defaults to Test::Valgrind::Action::Test. |
| 73 |
|
| 74 |
* "file => $file" |
| 75 |
|
| 76 |
The file name of the script to analyse. |
| 77 |
|
| 78 |
Ignored if you supply your own custom "command", but mandatory |
| 79 |
otherwise. |
| 80 |
|
| 81 |
* "callers => $number" |
| 82 |
|
| 83 |
Specify the maximum stack depth studied when valgrind encounters an |
| 84 |
error. Raising this number improves granularity. |
| 85 |
|
| 86 |
Ignored if you supply your own custom "tool", otherwise defaults to |
| 87 |
24 (the maximum allowed by "valgrind"). |
| 88 |
|
| 89 |
* "diag => $bool" |
| 90 |
|
| 91 |
If true, print the output of the test script as diagnostics. |
| 92 |
|
| 93 |
Ignored if you supply your own custom "action", otherwise defaults |
| 94 |
to false. |
| 95 |
|
| 96 |
* "regen_def_supp => $bool" |
| 97 |
|
| 98 |
If true, forcefully regenerate the default suppression file. |
| 99 |
|
| 100 |
Defaults to false. |
| 101 |
|
| 102 |
* "no_def_supp => $bool" |
| 103 |
|
| 104 |
If true, do not use the default suppression file. |
| 105 |
|
| 106 |
Defaults to false. |
| 107 |
|
| 108 |
* "allow_no_supp => $bool" |
| 109 |
|
| 110 |
If true, force running the analysis even if the suppression files do |
| 111 |
not refer to any "perl"-related symbol. |
| 112 |
|
| 113 |
Defaults to false. |
| 114 |
|
| 115 |
* "extra_supps => \@files" |
| 116 |
|
| 117 |
Also use suppressions from @files besides "perl"'s. |
| 118 |
|
| 119 |
Defaults to empty. |
| 120 |
|
| 121 |
"import" |
| 122 |
use Test::Valgrind %options; |
| 123 |
|
| 124 |
In the parent process, "import" calls "analyse" with the arguments it |
| 125 |
received itself - except that if no "file" option was supplied, it tries |
| 126 |
to pick the first caller context that looks like a script. When the |
| 127 |
analysis ends, it exits with the status returned by the action (for the |
| 128 |
default TAP-generator action, it's the number of failed tests). |
| 129 |
|
| 130 |
In the child process, it just "return"s so that the calling code is |
| 131 |
actually run under "valgrind", albeit two side-effects : |
| 132 |
|
| 133 |
* Perl::Destruct::Level is loaded and the destruction level is set to |
| 134 |
3. |
| 135 |
|
| 136 |
* Autoflush on "STDOUT" is turned on. |
| 137 |
|
| 138 |
VARIABLES |
| 139 |
$dl_unload |
| 140 |
When set to true, all dynamic extensions that were loaded during the |
| 141 |
analysis will be unloaded at "END" time by "dl_unload_file" in |
| 142 |
DynaLoader. |
| 143 |
|
| 144 |
Since this obfuscates error stack traces, it's disabled by default. |
| 145 |
|
| 146 |
CAVEATS |
| 147 |
Perl 5.8 is notorious for leaking like there's no tomorrow, so the |
| 148 |
suppressions are very likely not to be complete on it. You also have a |
| 149 |
better chance to get more accurate results if your perl is built with |
| 150 |
debugging enabled. Using the latest "valgrind" available will also help. |
| 151 |
|
| 152 |
This module is not really secure. It's definitely not taint safe. That |
| 153 |
shouldn't be a problem for test files. |
| 154 |
|
| 155 |
What your tests output to "STDOUT" and "STDERR" is eaten unless you pass |
| 156 |
the "diag" option, in which case it will be reprinted as diagnostics. |
| 157 |
|
| 158 |
DEPENDENCIES |
| 159 |
XML::Twig, File::HomeDir, Env::Sanctify, Perl::Destruct::Level. |
| 160 |
|
| 161 |
SEE ALSO |
| 162 |
All the "Test::Valgrind::*" API, including Test::Valgrind::Command, |
| 163 |
Test::Valgrind::Tool, Test::Valgrind::Action and |
| 164 |
Test::Valgrind::Session. |
| 165 |
|
| 166 |
The valgrind(1) man page. |
| 167 |
|
| 168 |
Test::LeakTrace. |
| 169 |
|
| 170 |
Devel::Leak, Devel::LeakTrace, Devel::LeakTrace::Fast. |
| 171 |
|
| 172 |
AUTHOR |
| 173 |
Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>. |
| 174 |
|
| 175 |
You can contact me by mail or on "irc.perl.org" (vincent). |
| 176 |
|
| 177 |
BUGS |
| 178 |
Please report any bugs or feature requests to "bug-test-valgrind at |
| 179 |
rt.cpan.org", or through the web interface at |
| 180 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Valgrind>. I will |
| 181 |
be notified, and then you'll automatically be notified of progress on |
| 182 |
your bug as I make changes. |
| 183 |
|
| 184 |
SUPPORT |
| 185 |
You can find documentation for this module with the perldoc command. |
| 186 |
|
| 187 |
perldoc Test::Valgrind |
| 188 |
|
| 189 |
ACKNOWLEDGEMENTS |
| 190 |
Rafaƫl Garcia-Suarez, for writing and instructing me about the existence |
| 191 |
of Perl::Destruct::Level (Elizabeth Mattijsen is a close second). |
| 192 |
|
| 193 |
H.Merijn Brand, for daring to test this thing. |
| 194 |
|
| 195 |
David Cantrell, for providing shell access to one of his smokers where |
| 196 |
the tests were failing. |
| 197 |
|
| 198 |
The Debian-perl team, for offering all the feedback they could regarding |
| 199 |
the build issues they met. |
| 200 |
|
| 201 |
All you people that showed interest in this module, which motivated me |
| 202 |
into completely rewriting it. |
| 203 |
|
| 204 |
COPYRIGHT & LICENSE |
| 205 |
Copyright 2008,2009,2010,2011,2013,2015,2016 Vincent Pit, all rights |
| 206 |
reserved. |
| 207 |
|
| 208 |
This program is free software; you can redistribute it and/or modify it |
| 209 |
under the same terms as Perl itself. |
| 210 |
|