Doc tweaks.

[p5sagit/p5-mst-13.2.git] / pod / perlhack.pod

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 986d473..66023bd 100644 (file)
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -1683,7 +1683,7 @@ warnings during the compilation phase.  Make sure that you mention
 this when you post your patch to P5P; the pumpking needs to know this.
 
 When you write your new code, please be conscious of existing code
-conventions used in the perl source files.  See <perlstyle> for
+conventions used in the perl source files.  See L<perlstyle> for
 details.  Although most of the guidelines discussed seem to focus on
 Perl code, rather than c, they all apply (except when they don't ;).
 See also I<Porting/patching.pod> file in the Perl source distribution
@@ -1803,6 +1803,47 @@ You must be triply conscious of cross-platform concerns.  This usually
 boils down to using File::Spec and avoiding things like C<fork()> and
 C<system()> unless absolutely necessary.
 
+=head2 Special Make Test Targets
+
+There are various special make targets that can be used to test Perl
+slightly differently than the standard "test" target.  Not all them
+are expected to give a 100% success rate.  Many of them have several
+aliases.
+
+=over 4
+
+=item coretest
+
+Run F<perl> on all but F<lib/*> tests.
+
+=item test.deparse
+
+Run all the tests through the B::Deparse.  Not all tests will succeed.
+
+=item minitest
+
+Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>,
+F<t/op>, and F<t/uni> tests.
+
+=item test.third check.third utest.third ucheck.third
+
+(Only in Tru64)  Run all the tests using the memory leak + naughty
+memory access tool "Third Degree".  The log files will be named
+F<perl3.log.testname>.
+
+=item test.torture torturetest
+
+Run all the usual tests and some extra tests.  As of Perl 5.8.0 the
+only extra tests are Abigail's JAPHs, t/japh/abigail.t.
+
+You can also run the torture test with F<t/harness> by giving
+C<-torture> argument to F<t/harness>.
+
+=item utest ucheck test.utf8 check.utf8
+
+Run all the tests with -Mutf8.  Not all tests will succeed.
+
+=back
 
 =head1 EXTERNAL TOOLS FOR DEBUGGING PERL
 
@@ -1909,12 +1950,12 @@ If you plan to use the "Viewer" windows, then you only need this option:
 
 In Bourne-type shells:
 
-    PURIFY_OPTIONS="..."
-    export PURIFY_OPTIONS
+    PURIFYOPTIONS="..."
+    export PURIFYOPTIONS
 
 or if you have the "env" utility:
 
-    env PURIFY_OPTIONS="..." ../pureperl ...
+    env PURIFYOPTIONS="..." ../pureperl ...
 
 =head2 Purify on NT
 
@@ -1966,7 +2007,15 @@ standard Perl testset you would create and run Purify as:
 which would instrument Perl in memory, run Perl on test.pl,
 then finally report any memory problems.
 
-=head2 Compaq's/Digital's Third Degree
+B<NOTE>: as of Perl 5.8.0, the ext/Encode/t/Unicode.t takes
+extraordinarily long (hours?) to complete under Purify.  It has been
+theorized that it would eventually finish, but nobody has so far been
+patient enough :-) (This same extreme slowdown has been seen also with
+the Third Degree tool, so the said test must be doing something that
+is quite unfriendly for memory debuggers.)  It is suggested that you
+simply kill away that testing process.
+
+=head2 Compaq's/Digital's/HP's Third Degree
 
 Third Degree is a tool for memory leak detection and memory access checks.
 It is one of the many tools in the ATOM toolkit.  The toolkit is only
@@ -1986,21 +2035,11 @@ third for more information.  The most extensive Third Degree
 documentation is available in the Compaq "Tru64 UNIX Programmer's
 Guide", chapter "Debugging Programs with Third Degree".
 
-The "test.third" leaves a lot of files named F<perl.3log.*> in the t/
+The "test.third" leaves a lot of files named F<foo_bar.3log> in the t/
 subdirectory.  There is a problem with these files: Third Degree is so
 effective that it finds problems also in the system libraries.
-Therefore there are certain types of errors that you should ignore in
-your debugging.  Errors with stack traces matching
-
-    __actual_atof|__catgets|_doprnt|__exc_|__exec|_findio|__localtime|setlocale|__sia_|__strxfrm
-
-(all in libc.so) are known to be non-serious.  You can also
-ignore the combinations
-
-    Perl_gv_fetchfile() calling strcpy()
-    S_doopen_pmc() calling strcmp()
-
-causing "rih" (reading invalid heap) errors.
+Therefore you should used the Porting/thirdclean script to cleanup
+the F<*.3log> files.
 
 There are also leaks that for given certain definition of a leak,
 aren't.  See L</PERL_DESTRUCT_LEVEL> for more information.
@@ -2022,6 +2061,10 @@ For example, for "third-degreed" Perl:
 
        env PERL_DESTRUCT_LEVEL=2 ./perl.third -Ilib t/foo/bar.t
 
+(Note: the mod_perl apache module uses also this environment variable
+for its own purposes and extended its semantics. Refer to the mod_perl
+documentation for more information.)
+
 =head2 Profiling
 
 Depending on your platform there are various of profiling Perl.
@@ -2248,6 +2291,11 @@ Alternatively edit the init file interactively via:
 Note: you can define up to 20 conversion shortcuts in the gdb
 section.
 
+=item *
+
+If you see in a debugger a memory area mysteriously full of 0xabababab,
+you may be seeing the effect of the Poison() macro, see L<perlclib>.
+
 =back
 
 =head2 CONCLUSION