X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FTest-Valgrind.git;a=blobdiff_plain;f=README;h=95c8a4a4a94ef19213f2dd7604b574137436bc76;hp=e34907e6da14f7abc4ed9d9b449011b8e5bca667;hb=HEAD;hpb=08860dad1f820cce06758ec4add9353a4dbc8175 diff --git a/README b/README index e34907e..95c8a4a 100644 --- a/README +++ b/README @@ -3,7 +3,7 @@ NAME with valgrind. VERSION - Version 1.10 + Version 1.19 SYNOPSIS # From the command-line @@ -24,17 +24,21 @@ SYNOPSIS DESCRIPTION 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 + debugger, to test 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. - The complete API is much more versatile than this. It allows you to run - *any* executable under valgrind, generate the corresponding suppressions - and convert the analysis output to TAP so that it can be incorporated - into your project's testsuite. + The complete API is much more versatile than this. By declaring an + appropriate Test::Valgrind::Command class, you can run any executable + (that is, not only Perl scripts) under valgrind, generate the + corresponding suppressions on-the-fly and convert the analysis result to + TAP output so that it can be incorporated into your project's testsuite. + If you're not interested in producing TAP, you can output the results in + whatever format you like (for example HTML pages) by defining your own + Test::Valgrind::Action class. 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 @@ -44,7 +48,9 @@ DESCRIPTION ALSO" section. METHODS - "analyse [ %options ]" + "analyse" + Test::Valgrind->analyse(%options); + Run a "valgrind" analysis configured by %options : * "command => $command" @@ -78,7 +84,7 @@ METHODS error. Raising this number improves granularity. Ignored if you supply your own custom "tool", otherwise defaults to - 12. + 24 (the maximum allowed by "valgrind"). * "diag => $bool" @@ -87,11 +93,11 @@ METHODS Ignored if you supply your own custom "action", otherwise defaults to false. - * "extra_supps => \@files" + * "regen_def_supp => $bool" - Also use suppressions from @files besides "perl"'s. + If true, forcefully regenerate the default suppression file. - Defaults to empty. + Defaults to false. * "no_def_supp => $bool" @@ -99,14 +105,35 @@ METHODS Defaults to false. - "import [ %options ]" + * "allow_no_supp => $bool" + + If true, force running the analysis even if the suppression files do + not refer to any "perl"-related symbol. + + Defaults to false. + + * "extra_supps => \@files" + + Also use suppressions from @files besides "perl"'s. + + Defaults to empty. + + "import" + use Test::Valgrind %options; + In the parent process, "import" calls "analyse" with the arguments it received itself - except that if no "file" option was supplied, it tries to pick the first caller context that looks like a script. When the - analyse ends, it exits with the status that was returned. + analysis ends, it exits with the status returned by the action (for the + default TAP-generator action, it's the number of failed tests). In the child process, it just "return"s so that the calling code is - actually run under "valgrind". + actually run under "valgrind", albeit two side-effects : + + * Perl::Destruct::Level is loaded and the destruction level is set to + 3. + + * Autoflush on "STDOUT" is turned on. VARIABLES $dl_unload @@ -118,9 +145,9 @@ VARIABLES CAVEATS 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. + suppressions are very likely not to be complete on it. You also have a + better chance to get more accurate results 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. @@ -129,15 +156,15 @@ CAVEATS the "diag" option, in which case it will be reprinted as diagnostics. DEPENDENCIES - Valgrind 3.1.0 (). - - XML::Twig, version, File::HomeDir, Env::Sanctify, Perl::Destruct::Level. + XML::Twig, 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. + The valgrind(1) man page. + Test::LeakTrace. Devel::Leak, Devel::LeakTrace, Devel::LeakTrace::Fast. @@ -160,17 +187,23 @@ SUPPORT perldoc Test::Valgrind ACKNOWLEDGEMENTS - Rafaël Garcia-Suarez, for writing and instructing me about the - existence of Perl::Destruct::Level (Elizabeth Mattijsen is a close - second). + Rafaël Garcia-Suarez, for writing and instructing me about the existence + of Perl::Destruct::Level (Elizabeth Mattijsen is a close second). H.Merijn Brand, for daring to test this thing. + David Cantrell, for providing shell access to one of his smokers where + the tests were failing. + + The Debian-perl team, for offering all the feedback they could regarding + the build issues they met. + All you people that showed interest in this module, which motivated me into completely rewriting it. COPYRIGHT & LICENSE - Copyright 2008-2009 Vincent Pit, all rights reserved. + Copyright 2008,2009,2010,2011,2013,2015,2016 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.