docs/debug.pod

   1 # Copyright (C) 2001-2004, The Perl Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/debug.pod - Debugging Parrot
   7
   8 =head1 ABSTRACT
   9
  10 This document describes how to debug various parts of Parrot.
  11
  12 =head1 VERSION
  13
  14 $Revision $
  15
  16 =head1 THE PARROT BINARY
  17
  18 =head2 Using a debugger
  19
  20 Per default the C<parrot> binary is being built with debugging symbols. This
  21 means that you can run C<parrot> under an debugger like C<gdb>.
  22
  23 Debugging support can be explicitly enabled with:
  24
  25     shell> perl Configure.pl --debugging
  26     shell> make
  27
  28 For testing it might be a good idea to make test runs without debug support. So
  29 debugging can also be turned off with:
  30
  31   shell> perl Configure.pl --debugging=0
  32   shell> make
  33
  34 =head2 Using a memory checker
  35
  36 You could, and should, also run the tests with a memory checker such as
  37 C<valgrind>.  You can enable C<valgrind>, by running:
  38
  39   shell> make test VALGRIND="valgrind --logfile=/tmp/grind"
  40
  41 Another possibility is to use Electric Fence, or ...
  42
  43 =head2 MEMORY MANAGEMENT
  44
  45 Some of the more frequent and exasperating C<parrot> bugs are related to memory
  46 management in general, and garbage collection in particular.
  47
  48 Infant mortality
  49
  50 See F<docs/dev/infant.dev> for details of one frequent problem: infant
  51 mortality. Infant mortality is when you create a Parrot object, but the garbage
  52 collector runs before you put it into a Parrot register or in something else
  53 that is itself within a Parrot register.
  54
  55 To help in resolving these issues, the parrot binary accepts a C<--gc-debug>
  56 flag. This flag makes garbage collection occur as frequently as possible, which
  57 maximizes the probability that any newborn objects will run afoul of the
  58 garbage collector.
  59
  60 Within the C<--gc-debug> mode, there is another tool to help narrow down the
  61 problem. You can edit F<src/dod.c> and C<#define> the C<GC_VERBOSE> flag to 1.
  62 After recompiling C<parrot>, the garbage collector will perform additional
  63 checks. After the garbage collector has traced all objects to find which ones
  64 are still alive, it will scan through all of the dead objects to see if any of
  65 them believe they are alive (which will happen for infants, since they come
  66 into existence marked live.) If it finds any, it will print them out. You can
  67 then re-run the program with a breakpoint set on the routine that allocated the
  68 object (e.g. C<get_free_object> in F<src/smallobject.c>).  You'll probably want
  69 to make the breakpoint conditional on the object having the version number that
  70 was reported, because the same memory location will probably hold many
  71 different objects over the lifetime of the program.
  72
  73 =head1 PIR AND PASM CODE
  74
  75 Let's say you have written (or generated) a huge .pasm or .pir file.  It's not
  76 working. You'd like some help in figuring out why.
  77
  78 =head2 pdb
  79
  80 One possible tool is C<pdb>, the Parrot Debugger. See F<docs/debugger.pod> for
  81 details on it.
  82
  83 =head2 stabs
  84
  85 If you are running on a jit-capable machine, you can also try using C<gdb> by
  86 having the JIT compiler generate C<stabs> metadata and then stepping through
  87 the code with C<gdb> as if it were any other language.
  88
  89 To use this, you'll want to use C<parrot> to generate your bytecode (.pbc
  90 file). It is not strictly necessary, but you'll get more information into the
  91 bytecode this way.
  92
  93 Let's say your file is named C<test.pasm>. (Note: these instructions will also
  94 work if you use C<test.pir> everywhere C<test.pasm> occurs.)
  95
  96 Step 1: Generate the .pbc file with extra debugging information.
  97
  98   shell> parrot -d -o test.pbc test.pasm
  99
 100 Step 2: Start up C<parrot> under C<gdb>
 101
 102   % gdb parrot
 103
 104 or
 105
 106   % emacs &
 107   (in emacs) M-x gdb
 108   (in emacs) type "parrot" so it says "gdb parrot"
 109
 110 Step 3: Set a breakpoint on runops_jit
 111
 112   gdb> b runops_jit
 113
 114 Step 4: Run your program under C<gdb> with JIT and debugging on
 115
 116   gdb> run -j -D4 test.pbc
 117
 118 Step 5: C<gdb> will stop at the beginning of runops_jit. Step through the lines
 119 until just before the JITed code is executed (the line will be something like
 120 C<(jit_code)(interpreter,pc)>.
 121
 122   gdb> n
 123   gdb> n
 124   .
 125   .
 126   .
 127
 128 Step 6: load in the debugging information from the symbol file that the jit
 129 just generated.
 130
 131   gdb> add-symbol-file test.o 0
 132
 133 Step 7: Step into the JITed code
 134
 135   gdb> s
 136
 137 At this point, you can step through the instructions, or print out the
 138 various Parrot registers. FIXME: C<gdb> will know about I0-I31,
 139 N0-N31, S0-S31, and P0-P31.
 140
 141
 142 WARNING: Stepping too far
 143
 144 One thing to watch out for is that C<gdb> gets confused when attempting to step
 145 over certain instructions. The only ones that I have noticed having problems is
 146 keyed operations. With my version of C<gdb>, if I do 'n' to step over the
 147 instruction, C<gdb> will start running and only stop when the entire parrot
 148 program has finished. To work around this, do 'si' twice just before executing
 149 any keyed op. For some reason, C<gdb> can then figure out when it's supposed to
 150 stop next. If you know of a better technique, please let the mailing list know
 151 (C<parrot-porters@perl.org>).
 152
 153 =head1 PIR CODE GENERATION
 154
 155 The C<parrot> binary has a bunch of debugging flags for spewing out information
 156 about various aspects of its processing. See L<running.pod> for a
 157 list of flags. Or have a look at the information provided by:
 158
 159   shell> parrot --help
 160
 161 or
 162
 163   shell> parrot --help-debug