Document the use of pixie/prof; create make targets for it.

TODO: make t/TEST pixie-aware.

p4raw-id: //depot/perl@9220

diff --git a/Makefile.SH b/Makefile.SH
index 416f66e..9fb3800 100644 (file)
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -493,6 +493,8 @@ miniperl: $& miniperlmain$(OBJ_EXT) $(LIBPERL) opmini$(OBJ_EXT)
 perl: $& perlmain$(OBJ_EXT) $(LIBPERL) $(DYNALOADER) $(static_ext) ext.libs $(PERLEXPORT)
        $(SHRPENV) $(LDLIBPTH) $(CC) -o perl $(CLDFLAGS) $(CCDLFLAGS) perlmain$(OBJ_EXT) $(DYNALOADER) $(static_ext) $(LLIBPERL) `cat ext.libs` $(libs)
 
+# Purify/Quantify Perls.
+
 pureperl: $& perlmain$(OBJ_EXT) $(LIBPERL) $(DYNALOADER) $(static_ext) ext.libs $(PERLEXPORT)
        $(SHRPENV) $(LDLIBPTH) purify $(CC) -o pureperl $(CLDFLAGS) $(CCDLFLAGS) perlmain$(OBJ_EXT) $(DYNALOADER) $(static_ext) $(LLIBPERL) `cat ext.libs` $(libs)
 
@@ -502,11 +504,16 @@ purecovperl: $& perlmain$(OBJ_EXT) $(LIBPERL) $(DYNALOADER) $(static_ext) ext.li
 quantperl: $& perlmain$(OBJ_EXT) $(LIBPERL) $(DYNALOADER) $(static_ext) ext.libs $(PERLEXPORT)
        $(SHRPENV) $(LDLIBPTH) quantify $(CC) -o quantperl $(CLDFLAGS) $(CCDLFLAGS) perlmain$(OBJ_EXT) $(DYNALOADER) $(static_ext) $(LLIBPERL) `cat ext.libs` $(libs)
 
-perl.third.config: config.sh
-       @echo "To build perl.third you must Configure -Doptimize=-g -Uusemymalloc, checking..."
+# Third Degree Perl (Tru64 only)
+
+perl.config.-g:
        @echo "Checking optimize='-g'..."
        @grep "^optimize=" config.sh
        @grep -q "^optimize='-g'" config.sh || exit 1
+
+perl.third.config: config.sh
+       @echo "To build perl.third you must Configure -Doptimize=-g -Uusemymalloc, checking..."
+       $(MAKE) perl.config.-g
        @echo "Checking usemymalloc='n'..."
        @grep "^usemymalloc=" config.sh
        @grep -q "^usemymalloc='n'" config.sh || exit 1
@@ -514,6 +521,25 @@ perl.third.config: config.sh
 perl.third: /usr/bin/atom perl.third.config perl
        atom -tool third -L. -all -gp -toolargs="-quiet -invalid -uninit heap+stack+partword+copy -min 0" perl
 
+# Pixie Perls (Tru64 and IRIX only)
+
+perl.pixie.atom.config: config.sh
+       @echo "To build perl.pixie you must Configure -Doptimize=-g, checking..."
+       $(MAKE) perl.config.-g
+
+perl.pixie.atom: /usr/bin/atom perl.pixie.atom.config perl
+       atom -tool pixie -L. -all -toolargs="-quiet" perl
+
+perl.pixie.irix: perl
+       pixie perl
+
+perl.pixie: perl
+       if test -x /usr/bin/atom; then \
+         $(MAKE) perl.pixie.atom; \
+       else \
+         $(MAKE) perl.pixie.irix; \
+       fi
+
 # This version, if specified in Configure, does ONLY those scripts which need
 # set-id emulation.  Suidperl must be setuid root.  It contains the "taint"
 # checks as well as the special code to validate that the script in question

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 490049b..a5fbc20 100644 (file)
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -1686,12 +1686,12 @@ and -Uusemymalloc flags, after that you can use the make targets
 "perl.third" and "test.third".
 
 The short story is that with "atom" you can instrument the Perl
-executable to create a new executable called "perl.third".
-When the instrumented executable is run, it creates a log of dubious
-memory traffic in file called "perl.3log".  See man atom and man 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".
+executable to create a new executable called "perl.third".  When the
+instrumented executable is run, it creates a log of dubious memory
+traffic in file called "perl.3log".  See the manual pages of atom and
+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 perl.3log.* in the t/
 subdirectory.  There is a problem with these files: Third Degree is so
@@ -1728,6 +1728,28 @@ need to do too, if you don't want to see the "global leaks":
 
        PERL_DESTRUCT_LEVEL=2 ./perl.third t/foo/bar.t
 
+=head2 Pixie Profiling
+
+Pixie is a profiling tool available on Tru64 (aka Digital UNIX aka DEC
+OSF/1) and IRIX platforms.  Pixie does its profiling using
+"basic-block counting".  A basic block is a program region that
+is entered only at the beginning and exited only at the end.
+
+You can build a profiled version of perl called "perl.pixie" by
+invoking the make target "perl.pixie" (in Tru64 a file called
+"perl.Addrs" will also be silently created, this file contains the
+addresses of the basic blocks).  Running the profiled version of Perl
+will create a new file called "Perl.Counts" which contains the basic
+block counts for that particular run.
+
+To display the results you must use the "prof" utility.  The exact
+incantation depends on your operating system, "prof perl.Counts" in
+IRIX, and "prof -pixie -all -L. perl" in Tru64.
+
+By default prof shows the most executed source code lines in
+descending order of use.  For further information, see your system's
+manual pages for pixie and prof.
+
 =head2 CONCLUSION
 
 We've had a brief look around the Perl source, an overview of the stages