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

TODO: make t/TEST pixie-aware.

p4raw-id: //depot/perl@9220

1 files changed, 28 insertions, 6 deletions

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 490049b394..a5fbc2092f 100644
--- 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