This is 0.08

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

diff --git a/README b/README
index acbd863cb62d0428c47f1f438205bdac9cd089a0..9ee1160357ef5a411963ea39baece580ff1aa686 100644 (file)
--- a/README
+++ b/README
@@ -1,13 +1,13 @@
 NAME
-    Test::Valgrind - Test your code through valgrind.
+    Test::Valgrind - Test Perl code through valgrind.
 
 VERSION
-    Version 0.01
+    Version 0.08
 
 SYNOPSIS
         use Test::More;
         eval 'use Test::Valgrind';
-        plan skip_all => 'Test::Valgrind is required to test your distribution with valgrind';
+        plan skip_all => 'Test::Valgrind is required to test your distribution with valgrind' if $@;
 
         # Code to inspect for memory leaks/errors.
 
@@ -20,46 +20,90 @@ DESCRIPTION
     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
+
+    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. 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.
+    switch.
+
+    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.
+
+    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
@@ -73,8 +117,15 @@ 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).
+
+    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.