1 # Copyright (C) 2001-2009, Parrot Foundation.
6 docs/debugger.pod - The Parrot Debugger
10 This document describes F<parrot_debugger>, 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<parrot_debugger>, and is an interactive environment
16 that let you step through bytecode, set breakpoints, evaluate assembly
17 instructions and peek 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.
24 =head1 BUILDING parrot_debugger
26 The debugger is built along with Parrot when you run 'make', but if you want to build
27 *only* the debugger, then you can run:
31 Which will create a new parrot_debugger executable in the same directory as the parrot
34 =head1 THE DEBUGGER SHELL
36 To start the debugger type:
38 parrot_debugger file.pbc
40 That is, F<parrot_debugger> takes exactly one argument, which is the Parrot file that
41 you're going to debug. This file may be Parrot bytecode (*.pbc), PASM source code (*.pasm)
42 or PIR (*.pir). F<parrot_debugger> 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<parrot_debugger> is ready to receive commands and give output. To list the
53 available 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. Debugger commands are case
68 sensitive (LOAD is not a valid command) but Parrot register names are not.
70 A blank line always repeats the last command entered.
72 Also note that at this point in its development, F<parrot_debugger> has very
73 poor error checking on commands and their arguments, so type carefully or
74 something bad will happen. Feel free to report bugs, or better yet patch the
75 source code (see L</FILES> below).
81 Assign to a Parrot register. For example:
91 The first command sets I0 to 42 and the second sets N1 to 3.14. Register names are not
92 case sensitive, so you can use either i0 or I0 .
96 Disassemble a loaded bytecode file. This will turn a file loaded with C<load>
97 into proper Parrot assembler.
101 Load a source code (assembler) file. The syntax is:
107 List the source code. The syntax is:
111 Both arguments are optional. By default C<FROM> is from where the last list
112 command ended (or the first line if this is the first invocation) and C<NUM> is
113 10. That is, it lists the source code ten lines at a time.
115 Note that the disassembled source code is not the same as the original source
116 code: labels take the names C<L1 .. Ln> and opcodes are fully qualified (eg.
117 C<set_i_ic> instead of just C<set>). See also C<eval (e)>.
121 # lists the first three source code lines
124 2 L3: print_sc "fact of "
129 Run (or restart) the program. The syntax is:
133 Any arguments you give are passed as command line arguments to the program (ie.
136 After the program has ended, you can run it again with this command. See also
137 the C<continue (c)> command.
154 Add a breakpoint. The syntax is:
156 b LINE [if CONDITION]
158 If you want a conditional breakpoint you should first specify the register that
159 is involved in the condition (at least one must be), the comparison and then
160 the third argument can be either another register or a constant, which must be
161 of the same type as the first register specified.
163 The command returns a number which is the breakpoint identifier. You should
164 note this number for the C<delete (d)> command (see below).
168 # sets a breakpoint on line 10 (will be breakpoint 0)
170 Breakpoint 0 at line 10
172 # another breakpoint on line 11 (will be breakpoint 1)
174 Breakpoint 1 at line 11
176 # break at line 4 if I16 is less than or equal to 123456
177 (pdb) b 4 if I16 <= 123456
178 Breakpoint 2 at line 4
180 # break at line 4 if N27 is greater than 5.23
181 (pdb) b 5 if N27 > 5.23
182 Breakpoint 3 at line 5
184 # break at line 4 if S2 is equal to S13
185 (pdb) b 6 if S2 == S13
186 Breakpoint 4 at line 6
188 # break at line 4 if S5 is equal to "stop"
189 (pdb) b 7 if S2 == "stop"
190 Breakpoint 5 at line 7
194 Add a watchpoint. The syntax is:
198 The condition has the same format as in C<break>
202 Delete a breakpoint. The syntax is:
206 The C<NUM> argument is the breakpoint number (from 0 to N) as emitted by the
207 C<break (b)> command. It is NOT the line that has the breakpoint.
211 # delete the first breakpoint (was on line 10, see example above)
216 Disable a breakpoint. The syntax is the same as for the C<delete> command.
217 Disabled breakpoints can be re-enabled with C<enable>.
221 Re-enable a disabled breakpoint. The syntax is:
225 where C<NUM> is the number of the breakpoint.
229 Continue the program execution. The syntax of this command is:
233 Without arguments, the command just runs the source code until a breakpoint is
234 found (or until the end of the program).
236 If you specify a number, it will skip the next C<NUM> breakpoints it
239 When the program has ended, continue will do nothing. Use C<run (r)> to execute
244 Run the next instruction. The syntax is:
248 C<NUM> defaults to 1, but you can give a number of instructions to execute
249 before stopping again.
253 The eval command is currently unimplemeneted.
255 Run an instruction. The syntax is:
274 Trace the next instruction. The syntax is:
278 It executes the next C<NUM> instructions (default is 1) just as C<next (n)>
279 does, but printing additional trace information. This is the same as the
280 information you get when running Parrot with the C<-t> option.
284 # executes 2 instructions and trace them
286 PC=0; OP=67 (set_i_ic); ARGS=(I1=0, 0)
287 PC=3; OP=24 (print_sc); ARGS=("fact of ")
293 Print the interpreter registers. Register names are not case sensitive. The syntax is:
301 =item A register name: C<I3>
303 Prints out the single register specified.
305 =item A register type: C<i>, C<n>, C<s>, or C<p>
307 Prints out all registers of the given type
309 =item An aggregate key: C<P0[1]>
311 Looks up the given (integer- or string-valued) key in a PMC register.
315 For PMC registers, the command will print the number, the class of the PMC (in
316 square brackets) and its string representation (when available). It prints
317 <PMCNULL> for uninitialized PMC registers.
321 # prints the content of I2
325 # prints the content of P0
327 P0 = [ResizablePMCArray]
329 # prints the content of all string registers
338 Print interpreter information.
343 Total memory allocated = 81936
350 Header allocations since last collect = 0
351 Memory allocations since last collect = 2
359 Prints information about debugger commands. The syntax is:
363 If C<COMMAND> is omitted, prints a list of the available commands.
371 =item src/parrot_debugger.c
373 This is the file that will produce the executable. Nothing fancy here, it
374 mostly consists of the C<main> function.
378 Most of the debugger is implemented here. You may want to start from the
379 C<PDB_run_command> function and go down from there for the real meat.
383 C<Parrot_debug>, the function which launches the debugger, is implemented here.
385 =item include/parrot/debugger.h
387 This defines all the PDB structures, which hold data used by the debugger.
397 First version (SVN debug.c revision 1.24), authored by Aldo Calpini