1 # Copyright (C) 2001-2006, The Perl Foundation.
6 docs/debugger.pod - The Parrot Debugger
10 This document describes F<pdb>, the Parrot Debugger.
14 Starting from version 0.0.6 Parrot has its own debugger, which is modeled after
15 Perl's one. Its name is F<pdb>, and is an interactive environment that let you
16 step through bytecode, set breakpoints, evaluate assembly instructions and peek
17 at the interpreter status.
19 A good (well, at least some) knowledge of the Parrot internals is obviously
20 required to read this document. Some familiarity with debugging principles is
21 also mandatory beyond this point.
25 The debugger is not built with Parrot, but you should make it with its specific
30 (where C<make> is the same C<make> incarnation you used to build Parrot).
32 If everything goes well, you should come up with a F<pdb> executable in the
33 same directory as the Parrot program.
35 =head1 THE DEBUGGER SHELL
37 To start the debugger type:
41 That is, F<pdb> takes exactly one argument, which is the Parrot bytecode that
42 you're going to debug. F<pdb> will automatically load and disassemble the
43 bytecode file for you.
45 Note that you can't pass command line arguments to your program when you invoke
46 the debugger. See the C<run (r)> command below for this.
48 After the version banner, you'll see the friendly debugger prompt:
52 F<pdb> is ready to receive commands and give output. To list the available
53 commands type 'h'. To quit the debugger type 'q'.
55 As with the Perl debugger, whenever it halts and shows you a line of code, it
56 is always the line it's I<about> to execute, not the one that it has just
59 =head1 DEBUGGER COMMANDS
61 Always remember that you can enter 'h' to get a list of commands (this document
62 may be outdated in respect to the actual debugger, so let it speak for itself).
64 Most commands can be shortened to their first letter. When available, this is
65 signaled by the letter in parentheses after the command name Thus, C<help (h)>
66 means that the command can be given as 'help' or just 'h'. On the other hand,
67 C<load> can only be given as 'load', verbatim. And the debugger is case
70 A blank line always repeats the last command entered.
72 Also note that at this point in its development, F<pdb> has very poor error
73 checking on commands and their arguments, so type carefully or something bad
74 will happen. Feel free to report bugs, or better yet patch the source code (see
81 Disassemble a loaded bytecode file. This will turn a file loaded with C<load>
82 into proper Parrot assembler.
86 Load a source code (assembler) file. The syntax is:
92 List the source code. The syntax is:
96 Both arguments are optional. By default C<FROM> is from where the last list
97 command ended (or the first line if this is the first invocation) and C<NUM> is
98 10. That is, it lists the source code ten lines at a time.
100 Note that the disassembled source code is not the same as the original source
101 code: labels take the names C<L1 .. Ln> and opcodes are fully qualified (eg.
102 C<set_i_ic> instead of just C<set>). See also C<eval (e)>.
106 # lists the first three source code lines
109 2 L3: print_sc "fact of "
114 Run (or restart) the program. The syntax is:
118 Any arguments you give are passed as command line arguments to the program (ie.
121 After the program has ended, you can run it again with this command. See also
122 the C<continue (c)> command.
139 Add a breakpoint. The syntax is:
141 b LINE [if CONDITION]
143 If you want a conditional breakpoint you should first specify the register that
144 is involved in the condition (at least one must be), the comparison and then
145 the third argument can be either another register or a constant, which must be
146 of the same type as the first register specified.
148 The command returns a number which is the breakpoint identifier. You should
149 note this number for the C<delete (d)> command (see below).
153 # sets a breakpoint on line 10 (will be breakpoint 0)
155 Breakpoint 0 at line 10
157 # another breakpoint on line 11 (will be breakpoint 1)
159 Breakpoint 1 at line 11
161 # break at line 4 if I16 is less than or equal to 123456
162 (pdb) b 4 if I16 <= 123456
163 Breakpoint 2 at line 4
165 # break at line 4 if N27 is greater than 5.23
166 (pdb) b 5 if N27 > 5.23
167 Breakpoint 3 at line 5
169 # break at line 4 if S2 is equal to S13
170 (pdb) b 6 if S2 == S13
171 Breakpoint 4 at line 6
173 # break at line 4 if S5 is equal to "stop"
174 (pdb) b 7 if S2 == "stop"
175 Breakpoint 5 at line 7
179 Add a watchpoint. The syntax is:
183 The condition has the same format as in C<break>
187 Delete a breakpoint. The syntax is:
191 The C<NUM> argument is the breakpoint number (from 0 to N) as emitted by the
192 C<break (b)> command. It is NOT the line that has the breakpoint.
196 # delete the first breakpoint (was on line 10, see example above)
201 Disable a breakpoint. The syntax is the same as for the C<delete> command.
202 Disabled breakpoints can be re-enabled with C<enable>.
206 Re-enable a disabled breakpoint. The syntax is:
210 where C<NUM> is the number of the breakpoint.
214 Continue the program execution. The syntax of this command is:
218 Without arguments, the command just runs the source code until a breakpoint is
219 found (or until the end of the program).
221 If you specify a number, it will skip the next C<NUM> breakpoints it
224 When the program has ended, continue will do nothing. Use C<run (r)> to execute
229 Run the next instruction. The syntax is:
233 C<NUM> defaults to 1, but you can give a number of instructions to execute
234 before stopping again.
238 Run an instruction. The syntax is:
257 Trace the next instruction. The syntax is:
261 It executes the next C<NUM> instructions (default is 1) just as C<next (n)>
262 does, but printing additional trace information. This is the same as the
263 information you get when running Parrot with the C<-t> option.
267 # executes 2 instructions and trace them
269 PC=0; OP=67 (set_i_ic); ARGS=(I1=0, 0)
270 PC=3; OP=24 (print_sc); ARGS=("fact of ")
276 Print the interpreter registers. The syntax is:
284 =item A register name: C<I3>
286 Prints out the single register specified.
288 =item A register type: C<i>, C<n>, C<s>, or C<p>
290 Prints out all registers of the given type
292 =item An aggregate key: C<P0[1]>
294 Looks up the given (integer- or string-valued) key in a PMC register.
298 For PMC registers, the command will print the number, the class of the PMC (in
299 square brackets) and its string representation (when available). It prints
300 <null pmc> for uninitialized PMC registers.
304 # prints the content of I2
309 # prints the content of P0
312 P0 = [ResizablePMCArray]
314 # prints the content of all string registers
351 Print interpreter information.
356 Total memory allocated = 81936
363 Header allocations since last collect = 0
364 Memory allocations since last collect = 2
372 Prints information about debugger commands. The syntax is:
376 If C<COMMAND> is omitted, prints a list of the available commands.
386 This is the file that will produce the executable. Nothing fancy here, only
387 the C<main> function.
391 Most of the debugger is implemented here. You may want to start from the
392 C<PDB_run_command> function and go down from there for the real meat.
396 C<Parrot_debug>, the function which launches the debugger, is implemented here.
398 =item include/parrot/debug.h
400 This defines all the PDB structures, which hold data used by the debugger.
410 First version (SVN debug.c revision 1.24), authored by Aldo Calpini