|parrotcode: The Parrot Debugger|
|Contents | Documentation|
docs/debugger.pod - The Parrot Debugger
This document describes pdb, the Parrot Debugger.
Starting from version 0.0.6 Parrot has its own debugger, which is modeled after Perl's one. Its name is pdb, and is an interactive environment that let you step through bytecode, set breakpoints, evaluate assembly instructions and peek at the interpreter status.
A good (well, at least some) knowledge of the Parrot internals is obviously required to read this document. Some familiarity with debugging principles is also mandatory beyond this point.
The debugger is not built with Parrot, but you should make it with its specific target:
make is the same
make incarnation you used to build Parrot).
If everything goes well, you should come up with a pdb executable in the same directory as the Parrot program.
To start the debugger type:
That is, pdb takes exactly one argument, which is the Parrot bytecode that you're going to debug. pdb will automatically load and disassemble the bytecode file for you.
Note that you can't pass command line arguments to your program when you invoke the debugger. See the
run (r) command below for this.
After the version banner, you'll see the friendly debugger prompt:
pdb is ready to receive commands and give output. To list the available commands type 'h'. To quit the debugger type 'q'.
As with the Perl debugger, whenever it halts and shows you a line of code, it is always the line it's about to execute, not the one that it has just executed.
Always remember that you can enter 'h' to get a list of commands (this document may be outdated in respect to the actual debugger, so let it speak for itself).
Most commands can be shortened to their first letter. When available, this is signaled by the letter in parentheses after the command name Thus,
help (h) means that the command can be given as 'help' or just 'h'. On the other hand,
load can only be given as 'load', verbatim. And the debugger is case sensitive.
A blank line always repeats the last command entered.
Also note that at this point in its development, pdb has very poor error checking on commands and their arguments, so type carefully or something bad will happen. Feel free to report bugs, or better yet patch the source code (see "FILES" below).
loadinto proper Parrot assembler.
list [FROM] [NUM]
FROMis from where the last list command ended (or the first line if this is the first invocation) and
NUMis 10. That is, it lists the source code ten lines at a time.
L1 .. Lnand opcodes are fully qualified (eg.
set_i_icinstead of just
set). See also
# lists the first three source code lines (pdb) l 1 3 1 set_i_ic I1,0 2 L3: print_sc "fact of " 3 print_i I1
(pdb) r Restarting fact of 0 is: 1 fact of 1 is: 1 fact of 2 is: 2 fact of 3 is: 6 fact of 4 is: 24 fact of 5 is: 120 fact of 6 is: 720 Program exited.
b LINE [if CONDITION]
delete (d)command (see below).
# sets a breakpoint on line 10 (will be breakpoint 0) (pdb) b 10 Breakpoint 0 at line 10 # another breakpoint on line 11 (will be breakpoint 1) (pdb) b 11 Breakpoint 1 at line 11 # break at line 4 if I16 is less than or equal to 123456 (pdb) b 4 if I16 <= 123456 Breakpoint 2 at line 4 # break at line 4 if N27 is greater than 5.23 (pdb) b 5 if N27 > 5.23 Breakpoint 3 at line 5 # break at line 4 if S2 is equal to S13 (pdb) b 6 if S2 == S13 Breakpoint 4 at line 6 # break at line 4 if S5 is equal to "stop" (pdb) b 7 if S2 == "stop" Breakpoint 5 at line 7
NUMargument is the breakpoint number (from 0 to N) as emitted by the
break (b)command. It is NOT the line that has the breakpoint.
# delete the first breakpoint (was on line 10, see example above) (pdb) d 0
deletecommand. Disabled breakpoints can be reenabled with
NUMis the number of the breakpoint.
NUMbreakpoints it encounters.
run (r)to execute it again.
NUMdefaults to 1, but you can give a number of instructions to execute before stopping again.
(pdb) e set I0, 42 (pdb) e print I0 42 (pdb) p i I0 = 42 I1 = 0 ...
NUMinstructions (default is 1) just as
next (n)does, but printing additional trace information. This is the same as the information you get when running Parrot with the
# executes 2 instructions and trace them (pdb) t 2 PC=0; OP=67 (set_i_ic); ARGS=(I1=0, 0) PC=3; OP=24 (print_sc); ARGS=("fact of ") fact of 3 print_i I1
# prints the content of I2 (pdb) p i2 Integer Registers: I2 = 0 # prints the content of P0 (pdb) p P0 PMC Registers: P0 = [PerlArray] # prints the content of all string registers (pdb) p s String Registers: 0 = Buflen = 4 Flags = 0 Bufused = 4 Strlen = 4 Offset = 0 String = Just 1 = Buflen = 8 Flags = 0 Bufused = 7 Strlen = 7 String = another 2 = Buflen = 8 Flags = 0 Bufused = 6 Strlen = 6 String = Parrot 3 = Buflen = 8 Flags = 0 Bufused = 6 Strlen = 6 String = hacker 4 = 5 = 6 = 7 = 8 = # ... and so on
stack TYPE [NUM] stack NUM
push_p). For the meaning of
print (p)command. The
NUMargument is the frame number (defaults to 0). The whole frame (0..31) is printed out.
NUM) from the generic stack (eg. results from
save), prepending the type of the entry on output.
# prints the value on top of the generic stack (pdb) s 0 Integer = 42 # prints the first integer register stack frame (pdb) s i Integer stack, frame 0, depth 0 Integer Registers: 0 = 0 1 = 0 2 = 0 3 = 0 4 = 0 5 = 0 6 = 0 7 = 0 8 = 0 # ... and so on
(pdb) info Total memory allocated = 81936 DOD runs = 6 Collect runs = 0 Active PMCs = 8197 Active buffers = 7 Total PMCs = 21840 Total buffers = 48 Header allocations since last collect = 0 Memory allocations since last collect = 2
COMMANDis omitted, prints a list of the available commands.
PDB_run_commandfunction and go down from there for the real meat.
Parrot_debug, the function which launches the debugger, is implemented here.