[t][cage] Remove PGE-dependence from t/op/inf_nan.t since it is part of 'make coretest'
[parrot.git] / docs / debug.pod
blob235e331c018cdfe9740ec6fc30e8c3c1d2f0cf59
1 # Copyright (C) 2001-2009, Parrot Foundation.
2 # $Id$
4 =head1 NAME
6 docs/debug.pod - Debugging Parrot
8 =head1 ABSTRACT
10 This document describes how to debug various parts of Parrot.
12 =head1 VERSION
14 $Revision $
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
26     shell> make
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
32   shell> make
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.
48 Infant mortality
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
58 garbage collector.
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:
89   shell> parrot --help
93   shell> parrot --help-debug
96 =head1 BACKTRACING
98 =head2 auto-magical
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).
108       (unknown)
109         Parrot_confess
110           Parrot_str_new_COW
111             Parrot_String_get_string
112               Parrot_set_s_p
113                 (unknown)
114                   (unknown)
115                     (unknown)
116                       (unknown)
117                         Parrot_runops_fromc_args
118                           Parrot_runcode
119                             (unknown)
120                               imcc_run
121                                 (unknown)
122                                   __libc_start_main
123                                     (unknown)
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.
128 =over
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
142 --ccflags=-rdynamic>
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!
149 =back
151 =head2 gdb
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
157 C<-g>).
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.
163     $ gdb parrot
164     GNU gdb 6.6
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".
172     (gdb) b main
173     Breakpoint 1 at 0x80488a0: file src/main.c, line 38.
174     (gdb) r foo.pir
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
182     38      {
183     (gdb) b Parrot_confess
184     Breakpoint 2 at 0xb7c542a0: file src/exceptions.c, line 767.
185     (gdb) c
186     Continuing.
187     [New Thread -1214039152 (LWP 23151)]
188     [New Thread -1222431856 (LWP 23152)]
189     1..1
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.
194     767     {
195     (gdb) bt full
196     #0  Parrot_confess (cond=0xb7eeda65 "s", file=0xb7eeda58 "src/string.c", 
197         line=129) at src/exceptions.c:767
198     No locals.
199     #1  0xb7c433b1 in Parrot_str_new_COW (interp=0x804e008, s=0x0)
200         at src/string.c:129
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
205     No locals.
206     #3  0xb7cc7d41 in Parrot_set_s_p (cur_opcode=0x825d470, interp=0x804e008)
207         at src/ops/set.ops:159
208     No locals.
209     #4  0xb7c9da32 in runops_slow_core (interp=0x804e008, pc=0x825d470)
210         at src/runcore/cores.c:184
211     No locals.
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
219             offset = 0
220             old_runloop_id = 0
221             our_runloop_level = 1
222             our_runloop_id = 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
227             offset = 0
228             dest = (opcode_t *) 0x8239730
229             ctx = (Parrot_Context *) 0x822a3b0
230             new_sig = ""
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)
239         at src/embed.c:783
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
244     No locals.
245     #11 0xb7ed7d90 in imcc_run (interp=0x804e008, sourcefile=0xbfec6e0a "foo.pir", 
246         argc=1, argv=0xbfec62e8) at compilers/imcc/main.c:815
247             obj_file = 0
248             yyscanner = (yyscan_t) 0x822a090
249             output_file = 0x0
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
255             status = 1267896320
256     (gdb)