X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=ec80e574022c187a4feb9c8f84dcf2963b395cec;hb=14d9a30088d40282446f97180ac6e383fa9ababf;hp=6a1b258ff8a11f31ad06e755b48be94453a71ad4;hpb=f6f6b610f4471652428707ae0203563eae291669;p=perl%2Fmodules%2FTest-Valgrind.git diff --git a/README b/README index 6a1b258..ec80e57 100644 --- a/README +++ b/README @@ -2,27 +2,30 @@ NAME Test::Valgrind - Test Perl code through valgrind. VERSION - Version 0.051 + Version 1.00 SYNOPSIS + # From the command-line + perl -MTest::Valgrind leaky.pl + + # In a test file use Test::More; eval 'use Test::Valgrind'; plan skip_all => 'Test::Valgrind is required to test your distribution with valgrind' if $@; + ... - # Code to inspect for memory leaks/errors. + # In all the test files of a directory + prove --exec 'perl -Iblib/lib -Iblib/arch -MTest::Valgrind' t/*.t DESCRIPTION - This module lets you run some code through the valgrind memory debugger, - to test it for memory errors and leaks. Just add "use Test::Valgrind" at - the beginning of the code you want to test. Behind the hood, - "Test::Valgrind::import" forks so that the child can basically "exec - 'valgrind', $^X, $0" (except that of course $0 isn't right there). The - parent then parses the report output by valgrind and pass or fail tests - accordingly. - - You can also use it from the command-line to test a given script : - - perl -MTest::Valgrind leaky.pl + This module is a front-end to the "Test::Valgrind::*" API that lets you + run Perl code through the "memcheck" tool of the "valgrind" memory + debugger, to test it for memory errors and leaks. If they aren't + available yet, it will first generate suppressions for the current + "perl" interpreter and store them in the portable flavour of + ~/.perl/Test-Valgrind/suppressions/$VERSION. The actual run will then + take place, and tests will be passed or failed according to the result + of the analysis. Due to the nature of perl's memory allocator, this module can't track leaks of Perl objects. This includes non-mortalized scalars and memory @@ -35,73 +38,70 @@ CONFIGURATION You can pass parameters to "import" as a list of key / value pairs, where valid keys are : - * "supp => $file" + * "tool => $tool" - Also use suppressions from $file besides perl's. + The Test::Valgrind::Tool object (or class name) to use. - * "no_supp => $bool" + Defaults to Test::Valgrind::Tool::memcheck. - If true, do not use any suppressions. + * "action => $action" - * "callers => $number" + The Test::Valgrind::Action object (or class name) to use. - Specify the maximum stack depth studied when valgrind encounters an - error. Raising this number improves granularity. Default is 12. + Defaults to Test::Valgrind::Action::Test. - * "extra => [ @args ]" + * "diag => $bool" - Add @args to valgrind parameters. + If true, print the output of the test script as diagnostics. - * "diag => $bool" + * "callers => $number" - If true, print the raw output of valgrind as diagnostics (may be - quite verbose). + Specify the maximum stack depth studied when valgrind encounters an + error. Raising this number improves granularity. - * "no_test => $bool" + Default is 12. - If true, do not actually output the plan and the tests results. + * "extra_supps => \@files" - * "cb => sub { my ($val, $name) = @_; ...; return $passed }" + Also use suppressions from @files besides "perl"'s. - Specifies a subroutine to execute for each test instead of - "Test::More::is". It receives the number of bytes leaked in $_[0] - and the test name in $_[1], and is expected to return true if the - test passed and false otherwise. Defaults to + * "no_def_supp => $bool" - sub { - is($_[0], 0, $_[1]); - (defined $_[0] and $_[0] == 0) : 1 : 0 - } + If true, do not use the default suppression file. CAVEATS You can't use this module to test code given by the "-e" command-line switch. - Results will most likely be better if your perl is built with debugging - enabled. Using the latest valgrind available will also help. + Perl 5.8 is notorious for leaking like there's no tomorrow, so the + suppressions are very likely not to be very accurate on it. Anyhow, + results will most likely be better if your perl is built with debugging + enabled. Using the latest "valgrind" available will also help. This module is not really secure. It's definitely not taint safe. That shouldn't be a problem for test files. - If your tests output to STDERR, everything will be eaten in the process. - In particular, running this module against test files will obliterate - their original test results. + What your tests output to "STDOUT" and "STDERR" is eaten unless you pass + the "diag" option, in which case it will be reprinted as diagnostics. DEPENDENCIES Valgrind 3.1.0 (). - Carp, POSIX (core modules since perl 5) and Test::More (since 5.6.2). - - Perl::Destruct::Level. + XML::Twig, version, File::HomeDir, Env::Sanctify, Perl::Destruct::Level. SEE ALSO + All the "Test::Valgrind::*" API, including Test::Valgrind::Command, + Test::Valgrind::Tool, Test::Valgrind::Action and + Test::Valgrind::Session. + + Test::LeakTrace. + Devel::Leak, Devel::LeakTrace, Devel::LeakTrace::Fast. AUTHOR Vincent Pit, "", . - You can contact me by mail or on #perl @ FreeNode (vincent or - Prof_Vince). + You can contact me by mail or on "irc.perl.org" (vincent). BUGS Please report any bugs or feature requests to "bug-test-valgrind at @@ -122,8 +122,11 @@ ACKNOWLEDGEMENTS H.Merijn Brand, for daring to test this thing. + All you people that showed interest in this module, which motivated me + into completely rewriting it. + COPYRIGHT & LICENSE - Copyright 2008 Vincent Pit, all rights reserved. + Copyright 2008-2009 Vincent Pit, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.