Output what we got when t/30-bad.t fails

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

diff --git a/README b/README
index 10e0c557bfaf13520d9108514d06eb5463266515..9ee1160357ef5a411963ea39baece580ff1aa686 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Test::Valgrind - Test Perl code through valgrind.
 
 VERSION
-    Version 0.04
+    Version 0.08
 
 SYNOPSIS
         use Test::More;
@@ -24,56 +24,86 @@ DESCRIPTION
 
         perl -MTest::Valgrind leaky.pl
 
+    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
+    extensions with "Newx" and friends or "malloc". As such, it's
+    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 :
 
-    "supp => $file"
+    *   "supp => $file"
+
         Also use suppressions from $file besides perl's.
 
-    "no_supp => $bool"
+    *   "no_supp => $bool"
+
         If true, do not use any suppressions.
 
-    "callers => $number"
+    *   "callers => $number"
+
         Specify the maximum stack depth studied when valgrind encounters an
-        error. Raising this number improves granularity. Default is 50.
+        error. Raising this number improves granularity. Default is 12.
+
+    *   "extra => [ @args ]"
 
-    "extra => [ @args ]"
         Add @args to valgrind parameters.
 
-    "diag => $bool"
+    *   "diag => $bool"
+
         If true, print the raw output of valgrind as diagnostics (may be
         quite verbose).
 
-    "no_test => $bool"
+    *   "no_test => $bool"
+
         If true, do not actually output the plan and the tests results.
 
+    *   "cb => sub { my ($val, $name) = @_; ...; return $passed }"
+
+        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
+
+            sub {
+             is($_[0], 0, $_[1]);
+             (defined $_[0] and $_[0] == 0) : 1 : 0
+            }
+
 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
+    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 is eaten unless you pass the "diag"
+    option, in which case it will be reprinted as diagnostics. STDERR is
+    kept untouched.
 
 DEPENDENCIES
     Valgrind 3.1.0 (<http://valgrind.org>).
 
-    Carp, POSIX (core modules since perl 5) and Test::More (since 5.6.2).
+    Carp, Fcntl, POSIX (core modules since perl 5) and Test::Builder (since
+    5.6.2).
 
     Perl::Destruct::Level.
 
+SEE ALSO
+    Devel::Leak, Devel::LeakTrace, Devel::LeakTrace::Fast.
+
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
-    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
@@ -95,7 +125,7 @@ ACKNOWLEDGEMENTS
     H.Merijn Brand, for daring to test this thing.
 
 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.