docs/debug.pod

   1 # Copyright (C) 2001-2009, Parrot 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 --log-file=/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.pod> 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 =head1 PIR AND PASM CODE
  61
  62 Let's say you have written (or generated) a huge .pasm or .pir file.  It's not
  63 working. You'd like some help in figuring out why.
  64
  65 =head2 parrot_debugger
  66
  67 One possible tool is C<parrot_debugger>, the Parrot Debugger.
  68 See F<docs/debugger.pod> for details on it.
  69
  70 =head1 PIR CODE GENERATION
  71
  72 The C<parrot> binary has a bunch of debugging flags for spewing out information
  73 about various aspects of its processing. See L<running.pod> for a
  74 list of flags. Or have a look at the information provided by:
  75
  76   shell> parrot --help
  77
  78 or
  79
  80   shell> parrot --help-debug
  81
  82
  83 =head1 BACKTRACING
  84
  85 =head2 auto-magical
  86
  87 If Parrot is built on a system with GNU libc it is capable of automatically
  88 generating a backtrace on C<stderr> for debugging purposes.  Currently these
  89 automatically backtraces are only generated by assertion failures but in the
  90 future they also be produced by other bad events (for example, C<SEGV>).
  91
  92 Here is an example of a what a backtrace might look like:
  93
  94     Backtrace - Obtained 15 stack frames (max trace depth is 32).
  95       (unknown)
  96         Parrot_confess
  97           Parrot_str_new_COW
  98             Parrot_String_get_string
  99               Parrot_set_s_p
 100                 (unknown)
 101                   (unknown)
 102                     (unknown)
 103                       (unknown)
 104                         Parrot_runops_fromc_args
 105                           Parrot_runcode
 106                             (unknown)
 107                               imcc_run
 108                                 (unknown)
 109                                   __libc_start_main
 110                                     (unknown)
 111
 112 It must be noted that glibc's backtraces are not without limitation.  It's
 113 method depends completely on information that is available at run time.
 114
 115 =over
 116
 117 =item * Functions marked as C<static> can only be identified by address as they
 118 have no "symbol name" for dynamic linking in the executable's symbol table.
 119 Static functions will appears as C<(unknown)>.
 120
 121 =item * There must be some means available for walking the stack at runtime.
 122 On x86(-64)? the "stack pointer" must be in C<[re]sp> register.  For example,
 123 this C<gcc> compilation flag would break backtracing (except for functions
 124 that do dynamic allocation on the stack as this optimization can no be allied
 125 to them).  C<perl Configure.pl --ccflags=-fomit-frame-pointer>
 126
 127 =item * Some platforms may require extra linker flags in order to get all of
 128 the required symbols exported in the symbol table.  C<Configure.pl
 129 --ccflags=-rdynamic>
 130
 131 =item * Any debugging information embedded in the object is not accessible.  So
 132 file and line number can not be included as part of the backtrace information.
 133
 134 =item * Be warned that signals may cause incorrect backtraces!
 135
 136 =back
 137
 138 =head2 gdb
 139
 140 On systems not equipped with libc, one will need to use an external debugger to
 141 get backtrace information.   This method is actually more capable then the
 142 L<auto-magical> approach as most debuggers will use debugging information if
 143 it's available in the object code (for example, if parrot was built with
 144 C<-g>).
 145
 146 Since the C<Parrot_confess> symbol is I<always> compiled into parrot it can be
 147 used as a break point to obtain a backtrace.  Here is an example of doing this
 148 with gdb and a version of parrot compiled with C<gcc> and the C<-g> flag.
 149
 150     $ gdb parrot
 151     GNU gdb 6.6
 152     Copyright (C) 2006 Free Software Foundation, Inc.
 153     GDB is free software, covered by the GNU General Public License, and you are
 154     welcome to change it and/or distribute copies of it under certain conditions.
 155     Type "show copying" to see the conditions.
 156     There is absolutely no warranty for GDB.  Type "show warranty" for details.
 157     This GDB was configured as "i686-pc-linux-gnu"...
 158     Using host libthread_db library "/lib/libthread_db.so.1".
 159     (gdb) b main
 160     Breakpoint 1 at 0x80488a0: file src/main.c, line 38.
 161     (gdb) r foo.pir
 162     Starting program: /home/moanui/jhoblitt/parrot/parrot foo.pir
 163     Failed to read a valid object file image from memory.
 164     [Thread debugging using libthread_db enabled]
 165     [New Thread -1213900128 (LWP 23148)]
 166     [Switching to Thread -1213900128 (LWP 23148)]
 167
 168     Breakpoint 1, main (argc=-400292727, argv=0x159a0) at src/main.c:38
 169     38      {
 170     (gdb) b Parrot_confess
 171     Breakpoint 2 at 0xb7c542a0: file src/exceptions.c, line 767.
 172     (gdb) c
 173     Continuing.
 174     [New Thread -1214039152 (LWP 23151)]
 175     [New Thread -1222431856 (LWP 23152)]
 176     1..1
 177
 178     Breakpoint 2, Parrot_confess (cond=0xb7eeda65 "s",
 179         file=0xb7eeda58 "src/string.c", line=129) at src/exceptions.c:767
 180     warning: Source file is more recent than executable.
 181     767     {
 182     (gdb) bt full
 183     #0  Parrot_confess (cond=0xb7eeda65 "s", file=0xb7eeda58 "src/string.c",
 184         line=129) at src/exceptions.c:767
 185     No locals.
 186     #1  0xb7c433b1 in Parrot_str_new_COW (interp=0x804e008, s=0x0)
 187         at src/string.c:129
 188             d = (STRING *) 0x81c21b8
 189             __PRETTY_FUNCTION__ = "Parrot_str_new_COW"
 190     #2  0xb7e40db3 in Parrot_String_get_string (interp=0x804e008, pmc=0x81c8578)
 191         at src/pmc/string.c:310
 192     No locals.
 193     #3  0xb7cc7d41 in Parrot_set_s_p (cur_opcode=0x825d470, interp=0x804e008)
 194         at src/ops/set.ops:159
 195     No locals.
 196     #4  0xb7c9da32 in runops_slow_core (interp=0x804e008, pc=0x825d470)
 197         at src/runcore/cores.c:184
 198     No locals.
 199     #5  0xb7c67acf in runops_int (interp=0x804e008, offset=0)
 200         at src/interp/interpreter.c:816
 201             pc = (opcode_t * const) 0x8239730
 202             lo_var_ptr = 134537224
 203             core = (opcode_t *(*)(Parrot_Interp,
 204         opcode_t *)) 0xb7c9d940 <runops_slow_core at src/runcore/cores.c:169>
 205     #6  0xb7c6854e in runops (interp=0x804e008, offs=0) at src/call/ops.c:100
 206             offset = 0
 207             old_runloop_id = 0
 208             our_runloop_level = 1
 209             our_runloop_id = 1
 210     #7  0xb7c687da in runops_args (interp=0x804e008, sub=0x8204d58, obj=0x80912d8,
 211         meth_unused=0x0, sig=0xb7eefca6 "vP",
 212         ap=0xbfec614c "@M \bï¿½bï¿½ï¿½Pï¿½\222K\230ï¿½\004\b@\236\"\b@M \bXM
 213             \b\004ï¿½ï¿½ï¿½ï¿½tï¿½ï¿½\bï¿½\004\b\001") at src/call/ops.c:216
 214             offset = 0
 215             dest = (opcode_t *) 0x8239730
 216             ctx = (Parrot_Context *) 0x822a3b0
 217             new_sig = ""
 218             sig_p = 0xb7eefca7 "P"
 219             old_ctx = (Parrot_Context * const) 0x804e298
 220     #8  0xb7c688fb in Parrot_runops_fromc_args (interp=0x804e008, sub=0x8204d58,
 221         sig=0xb7eefca6 "vP") at src/call/ops.c:293
 222             args = 0xbfec614c "@M \bï¿½bï¿½ï¿½Pï¿½\222K\230ï¿½\004\b@\236\"\b@M
 223                 \bXM \b\004ï¿½ï¿½ï¿½ï¿½tï¿½ï¿½\bï¿½\004\b\001"
 224             ctx = (Parrot_Context *) 0xb7fa1548
 225     #9  0xb7c50c51 in Parrot_runcode (interp=0x804e008, argc=1, argv=0xbfec62e8)
 226         at src/embed.c:783
 227             userargv = (PMC *) 0x8204d40
 228             main_sub = (PMC *) 0x8204d58
 229     #10 0xb7ed74a1 in imcc_run_pbc (interp=0x804e008, obj_file=0, output_file=0x0,
 230         argc=1, argv=0xbfec62e8) at compilers/imcc/main.c:614
 231     No locals.
 232     #11 0xb7ed7d90 in imcc_run (interp=0x804e008, sourcefile=0xbfec6e0a "foo.pir",
 233         argc=1, argv=0xbfec62e8) at compilers/imcc/main.c:815
 234             obj_file = 0
 235             yyscanner = (yyscan_t) 0x822a090
 236             output_file = 0x0
 237     #12 0x080489b7 in main (argc=136704448, argv=0x825f220) at src/main.c:62
 238             sourcefile = 0xbfec6e0a "foo.pir"
 239             interp = (Interp *) 0x804e008
 240             executable_name = (STRING *) 0x821b8e4
 241             executable_name_pmc = (PMC *) 0x8204d70
 242             status = 1267896320
 243     (gdb)