README

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