Also strip the (new) tail after cutting the suppression at Perl_runops

[perl/modules/Test-Valgrind.git] / README

diff --git a/README b/README
index ec80e574022c187a4feb9c8f84dcf2963b395cec..c032c3013c5ce8f477ab53186a87a1eddfe7ac8c 100644 (file)
--- a/README
+++ b/README
@@ -1,18 +1,22 @@
 NAME
-    Test::Valgrind - Test Perl code through valgrind.
+    Test::Valgrind - Generate suppressions, analyse and test any command
+    with valgrind.
 
 VERSION
-    Version 1.00
+    Version 1.11
 
 SYNOPSIS
         # From the command-line
         perl -MTest::Valgrind leaky.pl
 
+        # From the command-line, snippet style
+        perl -MTest::Valgrind -e 'leaky()'
+
         # 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 $@;
-        ...
+        leaky();
 
         # In all the test files of a directory
         prove --exec 'perl -Iblib/lib -Iblib/arch -MTest::Valgrind' t/*.t
@@ -27,6 +31,11 @@ DESCRIPTION
     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.
+
     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
     cycles. However, it can track leaks of chunks of memory allocated in XS
@@ -34,9 +43,15 @@ DESCRIPTION
     complementary to the other very good leak detectors listed in the "SEE
     ALSO" section.
 
-CONFIGURATION
-    You can pass parameters to "import" as a list of key / value pairs,
-    where valid keys are :
+METHODS
+  "analyse [ %options ]"
+    Run a "valgrind" analysis configured by %options :
+
+    *   "command => $command"
+
+        The Test::Valgrind::Command object (or class name) to use.
+
+        Defaults to Test::Valgrind::Command::PerlScript.
 
     *   "tool => $tool"
 
@@ -50,29 +65,58 @@ CONFIGURATION
 
         Defaults to Test::Valgrind::Action::Test.
 
-    *   "diag => $bool"
+    *   "file => $file"
 
-        If true, print the output of the test script as diagnostics.
+        The file name of the script to analyse.
+
+        Ignored if you supply your own custom "command", but mandatory
+        otherwise.
 
     *   "callers => $number"
 
         Specify the maximum stack depth studied when valgrind encounters an
         error. Raising this number improves granularity.
 
-        Default is 12.
+        Ignored if you supply your own custom "tool", otherwise defaults to
+        12.
+
+    *   "diag => $bool"
+
+        If true, print the output of the test script as diagnostics.
+
+        Ignored if you supply your own custom "action", otherwise defaults
+        to false.
 
     *   "extra_supps => \@files"
 
         Also use suppressions from @files besides "perl"'s.
 
+        Defaults to empty.
+
     *   "no_def_supp => $bool"
 
         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.
+        Defaults to false.
+
+  "import [ %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.
+
+    In the child process, it just "return"s so that the calling code is
+    actually run under "valgrind".
 
+VARIABLES
+  $dl_unload
+    When set to true, all dynamic extensions that were loaded during the
+    analysis will be unloaded at "END" time by "dl_unload_file" in
+    DynaLoader.
+
+    Since this obfuscates error stack traces, it's disabled by default.
+
+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
@@ -85,8 +129,6 @@ CAVEATS
     the "diag" option, in which case it will be reprinted as diagnostics.
 
 DEPENDENCIES
-    Valgrind 3.1.0 (<http://valgrind.org>).
-
     XML::Twig, version, File::HomeDir, Env::Sanctify, Perl::Destruct::Level.
 
 SEE ALSO
@@ -94,6 +136,8 @@ SEE ALSO
     Test::Valgrind::Tool, Test::Valgrind::Action and
     Test::Valgrind::Session.
 
+    The valgrind(1) man page.
+
     Test::LeakTrace.
 
     Devel::Leak, Devel::LeakTrace, Devel::LeakTrace::Fast.