Misc/PURIFY.README

   1 Purify (tm) and Quantify (tm) are commercial software quality
   2 assurance tools available from Rational Software Corporation
   3 <http://www.rational.com/>.  Purify is essentially a memory access
   4 verifier and leak detector; Quantify is a C level profiler.  The rest
   5 of this file assumes you generally know how to use Purify and
   6 Quantify, and that you have installed valid licenses for these
   7 products.  If you haven't installed such licenses, you can ignore the
   8 following since it won't help you a bit!
   9
  10 You can easily build a Purify or Quantify instrumented version of the
  11 Python interpreter by passing the PURIFY variable to the make command
  12 at the top of the Python tree:
  13
  14     make PURIFY=purify
  15
  16 This assumes that the `purify' program is on your $PATH.  Note that
  17 you cannot both Purify and Quantify the Python interpreter (or any
  18 program for that matter) at the same time.  If you want to build a
  19 Quantify'd interpreter, do this:
  20
  21     make PURIFY=quantify
  22
  23 When running the regression test (make test), I have found it useful
  24 to set my PURIFYOPTIONS environment variable using the following
  25 (bash) shell function.  Check out the Purify documentation for
  26 details:
  27
  28 p() {
  29   chainlen='-chain-length=12'
  30   ignoresigs='-ignore-signals="SIGHUP,SIGINT,SIGQUIT,SIGILL,SIGTRAP,SIGAVRT,SIGEMT,SIGFPE,SIGKILL,SIGBUS,SIGSEGV,SIGPIPE,SIGTERM,SIGUSR1,SIGUSR2,SIGPOLL,SIGXCPU,SIGXFSZ,SIGFREEZE,SIGTHAW,SIGRTMIN,SIGRTMAX"'
  31   followchild='-follow-child-processes=yes'
  32   threads='-max-threads=50'
  33   export PURIFYOPTIONS="$chainlen $ignoresigs $followchild $threads"
  34   echo $PURIFYOPTIONS
  35 }
  36
  37 Note that you may want to crank -chain-length up even further.  A
  38 value of 20 should get you the entire stack up into the Python C code
  39 in all situations.
  40
  41 With the regression test on a fatly configured interpreter
  42 (i.e. including as many modules as possible in your Modules/Setup
  43 file), you'll probably get a gabillion UMR errors, and a few MLK
  44 errors.  I think most of these can be safely suppressed by putting the
  45 following in your .purify file:
  46
  47     suppress umr ...; "socketmodule.c"
  48     suppress umr ...; time_strftime
  49     suppress umr ...; "dbmmodule.c"
  50     suppress umr ...; "gdbmmodule.c"
  51     suppress umr ...; "grpmodule.c"
  52     suppress umr ...; "nismodule.c"
  53     suppress umr ...; "pwdmodule.c"
  54
  55 This will still leave you with just a few UMR, mostly in the readline
  56 library, which you can safely ignore.  A lot of work has gone into
  57 Python 1.5 to plug as many leaks as possible.
  58
  59 Using Purify or Quantify in this way will give you coarse grained
  60 reports on the whole Python interpreter.  You can actually get more
  61 fine grained control over both by linking with the optional `pure'
  62 module, which exports (most of) the Purify and Quantify C API's into
  63 Python.  To link in this module (it must be statically linked), edit
  64 your Modules/Setup file for your site, and rebuild the interpreter.
  65 You might want to check out the comments in the Modules/puremodule.c
  66 file for some idiosyncrasies.
  67
  68 Using this module, you can actually profile or leak test a small
  69 section of code, instead of the whole interpreter.  Using this in
  70 conjuction with pdb.py, dbx, or the profiler.py module really gives
  71 you quite a bit of introspective power.
  72
  73 Naturally there are a couple of caveats.  This has only been tested
  74 with Purify 4.0.1 and Quantify 2.1-beta on Solaris 2.5.  Purify 4.0.1
  75 does not work with Solaris 2.6, but Purify 4.1 which reportedly will,
  76 is currently in beta test.  There are funky problems when Purify'ing a
  77 Python interpreter build with threads.  I've had a lot of problems
  78 getting this to work, so I generally don't build with threads when I'm
  79 Purify'ing.  If you get this to work, let us know!
  80
  81 -Barry Warsaw <bwarsaw@cnri.reston.va.us>