First pass through the changelog to get the perldelta current.

[perl5.git] / pod / perlhack.pod

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 72c2fc0..be860ee 100644 (file)
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -321,10 +321,12 @@ might start to make sense - don't worry if it doesn't yet, because the
 best way to study it is to read it in conjunction with poking at Perl
 source, and we'll do that later on.
 
-You might also want to look at Gisle Aas's illustrated perlguts -
-there's no guarantee that this will be absolutely up-to-date with the
-latest documentation in the Perl core, but the fundamentals will be
-right. ( http://gisle.aas.no/perl/illguts/ )
+Gisle Aas's illustrated perlguts (also known as I<illguts>) is wonderful,
+although a little out of date with regard to some size details; the
+various SV structures have since been reworked for smaller memory footprint.
+The fundamentals are right however, and the pictures are very helpful.
+
+L<http://www.perl.org/tpc/1998/Perl_Language_and_Modules/Perl%20Illustrated/>
 
 =item L<perlxstut> and L<perlxs>
 
@@ -1754,6 +1756,9 @@ so there are some snags (and it would be wonderful for you to brush
 them out), but it basically works that way.  Everything else lives in
 F<t/>.
 
+If you add a new test directory under F<t/>, it is imperative that you 
+add that directory to F<t/HARNESS> and F<t/TEST>.
+
 =over 3
 
 =item F<t/base/>
@@ -1797,6 +1802,11 @@ other directories.
 Tests for POD directives.  There are still some tests for the Pod
 modules hanging around in here that need to be moved out into F<lib/>.
 
+=item F<t/re/>
+
+Tests for regex related functions or behaviour. (These used to live
+in t/op).
+
 =item F<t/run/>
 
 Testing features of how perl actually runs, including exit codes and
@@ -2940,27 +2950,29 @@ by C<-DPERL_MEM_LOG> instead.
 
 =head2 PERL_MEM_LOG
 
-If compiled with C<-DPERL_MEM_LOG>, all Newx() and Renew() allocations
-and Safefree() in the Perl core go through logging functions, which is
-handy for breakpoint setting.  If also compiled with C<-DPERL_MEM_LOG_STDERR>,
-the allocations and frees are logged to STDERR (or more precisely, to the
-file descriptor 2) in these logging functions, with the calling source code
-file and line number (and C function name, if supported by the C compiler).
+If compiled with C<-DPERL_MEM_LOG>, both memory and SV allocations go
+through logging functions, which is handy for breakpoint setting.
+
+Unless C<-DPERL_MEM_LOG_NOIMPL> is also compiled, the logging
+functions read $ENV{PERL_MEM_LOG} to determine whether to log the
+event, and if so how:
 
-This logging is somewhat similar to C<-Dm> but independent of C<-DDEBUGGING>,
-and at a higher level (the C<-Dm> is directly at the point of C<malloc()>,
-while the C<PERL_MEM_LOG> is at the level of C<New()>).
+    $ENV{PERL_MEM_LOG} =~ /m/          Log all memory ops
+    $ENV{PERL_MEM_LOG} =~ /s/          Log all SV ops
+    $ENV{PERL_MEM_LOG} =~ /t/          include timestamp in Log
+    $ENV{PERL_MEM_LOG} =~ /^(\d+)/     write to FD given (default is 2)
 
-In addition to memory allocations, SV allocations will be logged, just as
-with C<-Dm>. However, since the logging doesn't use PerlIO, all SV allocations
-are logged and no extra SV allocations are introduced by enabling the logging.
-If compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for each SV
-allocation is also logged.
+Memory logging is somewhat similar to C<-Dm> but is independent of
+C<-DDEBUGGING>, and at a higher level; all uses of Newx(), Renew(),
+and Safefree() are logged with the caller's source code file and line
+number (and C function name, if supported by the C compiler).  In
+contrast, C<-Dm> is directly at the point of C<malloc()>.  SV logging
+is similar.
 
-You can control the logging from your environment if you compile with
-C<-DPERL_MEM_LOG_ENV>. Then you need to explicitly set C<PERL_MEM_LOG> and/or
-C<PERL_SV_LOG> to a non-zero value to enable logging of memory and/or SV
-allocations.
+Since the logging doesn't use PerlIO, all SV allocations are logged
+and no extra SV allocations are introduced by enabling the logging.
+If compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for
+each SV allocation is also logged.
 
 =head2 Profiling
 
@@ -3041,9 +3053,9 @@ formats, see your own local documentation of gprof.
 
 quick hint:
 
-    $ sh Configure -des -Dusedevel -Doptimize='-g' -Accflags='-pg' -Aldflags='-pg' && make
-    $ ./perl someprog # creates gmon.out in current directory
-    $ gprof perl > out
+    $ sh Configure -des -Dusedevel -Doptimize='-pg' && make perl.gprof
+    $ ./perl.gprof someprog # creates gmon.out in current directory
+    $ gprof ./perl.gprof > out
     $ view out
 
 =head2 GCC gcov Profiling