How to Add Opcode Tracking to Python-1.4
 by Perry A. Stoll <pas@xis.xerox.com>
------------------------------------------------------------

For a description of what opcode tracking is or why you might want to
add it to your interpreter, see the README file which should have
accompanied this distribution. Sorry, these instructions are
completely Unix biased. For those fortunate enough not to be using
Unix, you're on your own...

And always remember not to forget: this new python interpreter will be
slightly slower than a non-optracker enabled one, even when not
profiling. Not a lot slower, but a bit. And when profiling, it really
slows down. But if you're mucking around with opcode profiling, you
already knew all this.

(1) Uncompress and untar the distribution. This will create a
directory called opcodetracker.

     > gunzip optracker-1.4.tar.gz
     > tar -xvmf optracker-1.4.tar
     > cd optracker-1.4

(2) Copy the files into the Python source tree as appropriate.
If PYTHONROOT is the root of the Python-1.4 distribution:

     > cp optracker.h $PYTHONROOT/Include
     > cp optrackermodule.c $PYTHONROOT/Modules
     > cp ceval.optrack.patch $PYTHONROOT/Python

(3) Apply the patch to Python/ceval.c.

     > cd $PYTHONROOT/Python
     > patch < ceval.optrack.patch

(4) Compile ceval.c. To enable optracking in the interpreter, you MUST
compile ceval.c with ENABLE_OPTRACKER defined. One way to do this is:

     > cd $PYTHONROOT/Python 
     > make DEFS="-DHAVE_CONFIG_H -DENABLE_OPTRACKER" ceval.o

(5) Edit Modules/Setup from the python distribution to add the following lines:

# This must be above *shared* or *noconfig* if you are building dynamic extensions.
# Perry Stoll's Opcode Tracker module
optracker optrackermodule.c

(6) Recompile the python binary.

     > cd $PYTHONROOT
     > make

(7) Make sure opstats.py is somewhere on the PYTHONPATH. Either do a
make libinstall if you've copied opstats.py to $PYTHONROOT/Lib or just
copy it to the destination directory.

You should have a new python capable of being instrumented. See the
comments at the top of opstats.py for an example of usage.

(8) Try running optrackerscript.py with the new interpreter:

     > cd $OPTRACKERDIR
     > $PYTHONROOT/python optrackerscript.py

There should be some interesting stats printed out. 

