This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Correct 'map' documentation to reflect operation on a list.
[perl5.git] / pod / perlhacktips.pod
index 06c8aa9..5aa0b63 100644 (file)
@@ -79,7 +79,7 @@ If you want to have arrays of constant strings, note carefully the
 right combination of C<const>s:
 
     static const char * const yippee[] =
-       {"hi", "ho", "silver"};
+        {"hi", "ho", "silver"};
 
 There is a way to completely hide any modifiable globals (they are all
 moved to heap), the compilation setting
@@ -134,7 +134,7 @@ Use the Configure C<-Dgccansipedantic> flag to enable the gcc C<-ansi
 -pedantic> flags which enforce stricter ANSI rules.
 
 If using the C<gcc -Wall> note that not all the possible warnings (like
-C<-Wunitialized>) are given unless you also compile with C<-O>.
+C<-Wuninitialized>) are given unless you also compile with C<-O>.
 
 Note that if using gcc, starting from Perl 5.9.5 the Perl core source
 code files (the ones at the top level of the source code distribution,
@@ -201,7 +201,7 @@ guaranteed to be B<int> or B<long>.  If you really explicitly need
 Assuming one can dereference any type of pointer for any type of data
 
   char *p = ...;
-  long pony = *p;    /* BAD */
+  long pony = *(long *)p;    /* BAD */
 
 Many platforms, quite rightly so, will give you a core dump instead of
 a pony if the p happens not to be correctly aligned.
@@ -299,7 +299,7 @@ Also, the range 'A' - 'Z' in ASCII is an unbroken sequence of 26 upper
 case alphabetic characters.  That is not true in EBCDIC.  Nor for 'a' to
 'z'.  But '0' - '9' is an unbroken range in both systems.  Don't assume
 anything about other ranges.  (Note that special handling of ranges in
-regular expression patterns makes it appear to Perl
+regular expression patterns and transliterations makes it appear to Perl
 code that the aforementioned ranges are all unbroken.)
 
 Many of the comments in the existing code ignore the possibility of
@@ -516,6 +516,9 @@ Or you can try casting to a "wide enough" type:
 
    printf("i = %"IVdf"\n", (IV)something_very_small_and_signed);
 
+See L<perlguts/Formatted Printing of Size_t and SSize_t> for how to
+print those.
+
 Also remember that the C<%p> format really does require a void pointer:
 
    U8* p = ...;
@@ -601,6 +604,10 @@ temporarily try the following:
 But in any case, try to keep the features and operating systems
 separate.
 
+A good resource on the predefined macros for various operating
+systems, compilers, and so forth is
+L<http://sourceforge.net/p/predef/wiki/Home/>
+
 =item *
 
 Assuming the contents of static memory pointed to by the return values
@@ -729,28 +736,39 @@ happened, or how did we end up having wrong or unexpected results.
 To really poke around with Perl, you'll probably want to build Perl for
 debugging, like this:
 
-    ./Configure -d -D optimize=-g
+    ./Configure -d -DDEBUGGING
     make
 
-C<-g> is a flag to the C compiler to have it produce debugging
-information which will allow us to step through a running program, and
-to see in which C function we are at (without the debugging information
-we might see only the numerical addresses of the functions, which is
-not very helpful).
-
-F<Configure> will also turn on the C<DEBUGGING> compilation symbol
-which enables all the internal debugging code in Perl.  There are a
-whole bunch of things you can debug with this: L<perlrun> lists them
-all, and the best way to find out about them is to play about with
-them.  The most useful options are probably
+C<-DDEBUGGING> turns on the C compiler's C<-g> flag to have it produce
+debugging information which will allow us to step through a running
+program, and to see in which C function we are at (without the debugging
+information we might see only the numerical addresses of the functions,
+which is not very helpful). It will also turn on the C<DEBUGGING>
+compilation symbol which enables all the internal debugging code in Perl.
+There are a whole bunch of things you can debug with this: L<perlrun>
+lists them all, and the best way to find out about them is to play about
+with them.  The most useful options are probably
 
     l  Context (loop) stack processing
+    s  Stack snapshots (with v, displays all stacks)
     t  Trace execution
     o  Method and overloading resolution
     c  String/numeric conversions
 
-Some of the functionality of the debugging code can be achieved using
-XS modules.
+For example
+
+    $ perl -Dst -e '$a + 1'
+    ....
+    (-e:1)     gvsv(main::a)
+        =>  UNDEF
+    (-e:1)     const(IV(1))
+        =>  UNDEF  IV(1)
+    (-e:1)     add
+        =>  NV(1)
+
+
+Some of the functionality of the debugging code can be achieved with a
+non-debugging perl by using XS modules:
 
     -Dr => use re 'debug'
     -Dx => use O 'Debug'
@@ -1040,6 +1058,17 @@ a testbed for their product they periodically check several open source
 projects, and they give out accounts to open source developers to the
 defect databases.
 
+There is Coverity setup for the perl5 project:
+L<https://scan.coverity.com/projects/perl5>
+
+=head2 HP-UX cadvise (Code Advisor)
+
+HP has a C/C++ static analyzer product for HP-UX caller Code Advisor.
+(Link not given here because the URL is horribly long and seems horribly
+unstable; use the search engine of your choice to find it.)  The use of
+the C<cadvise_cc> recipe with C<Configure ... -Dcc=./cadvise_cc>
+(see cadvise "User Guide") is recommended; as is the use of C<+wall>.
+
 =head2 cpd (cut-and-paste detector)
 
 The cpd tool detects cut-and-paste coding.  If one instance of the
@@ -1396,7 +1425,7 @@ variable PERL_DESTRUCT_LEVEL to a non-zero value.  The t/TEST wrapper
 does set this to 2, and this is what you need to do too, if you don't
 want to see the "global leaks": For example, for running under valgrind
 
-       env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib t/foo/bar.t
+    env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -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
@@ -1436,17 +1465,18 @@ C<-DPERL_MEM_LOG> instead.
 
 =head2 PERL_MEM_LOG
 
-If compiled with C<-DPERL_MEM_LOG>, both memory and SV allocations go
-through logging functions, which is handy for breakpoint setting.
+If compiled with C<-DPERL_MEM_LOG> (C<-Accflags=-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:
+Unless C<-DPERL_MEM_LOG_NOIMPL> (C<-Accflags=-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:
 
-    $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)
+    $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)
 
 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