1 # Copyright (C) 2001-2009, Parrot Foundation.
6 docs/debug.pod - Debugging Parrot
10 This document describes how to debug various parts of Parrot.
16 =head1 THE PARROT BINARY
18 =head2 Using a debugger
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>.
23 Debugging support can be explicitly enabled with:
25 shell> perl Configure.pl --debugging
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:
31 shell> perl Configure.pl --debugging=0
34 =head2 Using a memory checker
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:
39 shell> make test VALGRIND="valgrind --log-file=/tmp/grind"
41 Another possibility is to use Electric Fence, or ...
43 =head2 MEMORY MANAGEMENT
45 Some of the more frequent and exasperating C<parrot> bugs are related to memory
46 management in general, and garbage collection in particular.
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.
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
60 Within the C<--gc-debug> mode, there is another tool to help narrow down the
61 problem. You can edit F<include/parrot/gc_api.h> and C<#define> the C<GC_VERBOSE> flag to
62 1. 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.
67 You can then re-run the program with a breakpoint set on the routine that
68 allocated the object (e.g. C<get_free_object> in F<src/gc/mark_sweep.c>).
69 You'll probably want to make the breakpoint conditional on the object having
70 the version number that was reported, because the same memory location will
71 probably hold many different objects over the lifetime of the program.
73 =head1 PIR AND PASM CODE
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.
78 =head2 parrot_debugger
80 One possible tool is C<parrot_debugger>, the Parrot Debugger.
81 See F<docs/debugger.pod> for details on it.
83 =head1 PIR CODE GENERATION
85 The C<parrot> binary has a bunch of debugging flags for spewing out information
86 about various aspects of its processing. See L<running.pod> for a
87 list of flags. Or have a look at the information provided by:
93 shell> parrot --help-debug
100 If Parrot is built on a system with GNU libc it is capable of automatically
101 generating a backtrace on C<stderr> for debugging purposes. Currently these
102 automatically backtraces are only generated by assertion failures but in the
103 future they also be produced by other bad events (for example, C<SEGV>).
105 Here is an example of a what a backtrace might look like:
107 Backtrace - Obtained 15 stack frames (max trace depth is 32).
111 Parrot_String_get_string
117 Parrot_runops_fromc_args
125 It must be noted that glibc's backtraces are not without limitation. It's
126 method depends completely on information that is available at run time.
130 =item * Functions marked as C<static> can only be identified by address as they
131 have no "symbol name" for dynamic linking in the executable's symbol table.
132 Static functions will appears as C<(unknown)>.
134 =item * There must be some means available for walking the stack at runtime.
135 On x86(-64)? the "stack pointer" must be in C<[re]sp> register. For example,
136 this C<gcc> compilation flag would break backtracing (except for functions
137 that do dynamic allocation on the stack as this optimization can no be allied
138 to them). C<perl Configure.pl --ccflags=-fomit-frame-pointer>
140 =item * Some platforms may require extra linker flags in order to get all of
141 the required symbols exported in the symbol table. C<Configure.pl
144 =item * Any debugging information embedded in the object is not accessible. So
145 file and line number can not be included as part of the backtrace information.
147 =item * Be warned that signals may cause incorrect backtraces!
153 On systems not equipped with libc, one will need to use an external debugger to
154 get backtrace information. This method is actually more capable then the
155 L<auto-magical> approach as most debuggers will use debugging information if
156 it's available in the object code (for example, if parrot was built with
159 Since the C<Parrot_confess> symbol is I<always> compiled into parrot it can be
160 used as a break point to obtain a backtrace. Here is an example of doing this
161 with gdb and a version of parrot compiled with C<gcc> and the C<-g> flag.
165 Copyright (C) 2006 Free Software Foundation, Inc.
166 GDB is free software, covered by the GNU General Public License, and you are
167 welcome to change it and/or distribute copies of it under certain conditions.
168 Type "show copying" to see the conditions.
169 There is absolutely no warranty for GDB. Type "show warranty" for details.
170 This GDB was configured as "i686-pc-linux-gnu"...
171 Using host libthread_db library "/lib/libthread_db.so.1".
173 Breakpoint 1 at 0x80488a0: file src/main.c, line 38.
175 Starting program: /home/moanui/jhoblitt/parrot/parrot foo.pir
176 Failed to read a valid object file image from memory.
177 [Thread debugging using libthread_db enabled]
178 [New Thread -1213900128 (LWP 23148)]
179 [Switching to Thread -1213900128 (LWP 23148)]
181 Breakpoint 1, main (argc=-400292727, argv=0x159a0) at src/main.c:38
183 (gdb) b Parrot_confess
184 Breakpoint 2 at 0xb7c542a0: file src/exceptions.c, line 767.
187 [New Thread -1214039152 (LWP 23151)]
188 [New Thread -1222431856 (LWP 23152)]
191 Breakpoint 2, Parrot_confess (cond=0xb7eeda65 "s",
192 file=0xb7eeda58 "src/string.c", line=129) at src/exceptions.c:767
193 warning: Source file is more recent than executable.
196 #0 Parrot_confess (cond=0xb7eeda65 "s", file=0xb7eeda58 "src/string.c",
197 line=129) at src/exceptions.c:767
199 #1 0xb7c433b1 in Parrot_str_new_COW (interp=0x804e008, s=0x0)
201 d = (STRING *) 0x81c21b8
202 __PRETTY_FUNCTION__ = "Parrot_str_new_COW"
203 #2 0xb7e40db3 in Parrot_String_get_string (interp=0x804e008, pmc=0x81c8578)
204 at src/pmc/string.c:310
206 #3 0xb7cc7d41 in Parrot_set_s_p (cur_opcode=0x825d470, interp=0x804e008)
207 at src/ops/set.ops:159
209 #4 0xb7c9da32 in runops_slow_core (interp=0x804e008, pc=0x825d470)
210 at src/runcore/cores.c:184
212 #5 0xb7c67acf in runops_int (interp=0x804e008, offset=0)
213 at src/interp/interpreter.c:816
214 pc = (opcode_t * const) 0x8239730
215 lo_var_ptr = 134537224
216 core = (opcode_t *(*)(Parrot_Interp,
217 opcode_t *)) 0xb7c9d940 <runops_slow_core at src/runcore/cores.c:169>
218 #6 0xb7c6854e in runops (interp=0x804e008, offs=0) at src/call/ops.c:100
221 our_runloop_level = 1
223 #7 0xb7c687da in runops_args (interp=0x804e008, sub=0x8204d58, obj=0x80912d8,
224 meth_unused=0x0, sig=0xb7eefca6 "vP",
225 ap=0xbfec614c "@M \b�b��P�\222K\230�\004\b@\236\"\b@M \bXM
226 \b\004����t��\b�\004\b\001") at src/call/ops.c:216
228 dest = (opcode_t *) 0x8239730
229 ctx = (Parrot_Context *) 0x822a3b0
231 sig_p = 0xb7eefca7 "P"
232 old_ctx = (Parrot_Context * const) 0x804e298
233 #8 0xb7c688fb in Parrot_runops_fromc_args (interp=0x804e008, sub=0x8204d58,
234 sig=0xb7eefca6 "vP") at src/call/ops.c:293
235 args = 0xbfec614c "@M \b�b��P�\222K\230�\004\b@\236\"\b@M
236 \bXM \b\004����t��\b�\004\b\001"
237 ctx = (Parrot_Context *) 0xb7fa1548
238 #9 0xb7c50c51 in Parrot_runcode (interp=0x804e008, argc=1, argv=0xbfec62e8)
240 userargv = (PMC *) 0x8204d40
241 main_sub = (PMC *) 0x8204d58
242 #10 0xb7ed74a1 in imcc_run_pbc (interp=0x804e008, obj_file=0, output_file=0x0,
243 argc=1, argv=0xbfec62e8) at compilers/imcc/main.c:614
245 #11 0xb7ed7d90 in imcc_run (interp=0x804e008, sourcefile=0xbfec6e0a "foo.pir",
246 argc=1, argv=0xbfec62e8) at compilers/imcc/main.c:815
248 yyscanner = (yyscan_t) 0x822a090
250 #12 0x080489b7 in main (argc=136704448, argv=0x825f220) at src/main.c:62
251 sourcefile = 0xbfec6e0a "foo.pir"
252 interp = (Interp *) 0x804e008
253 executable_name = (STRING *) 0x821b8e4
254 executable_name_pmc = (PMC *) 0x8204d70