docs/debugger.pod

   1 # Copyright (C) 2001-2009, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/debugger.pod - The Parrot Debugger
   7
   8 =head1 ABSTRACT
   9
  10 This document describes F<parrot_debugger>, the Parrot Debugger.
  11
  12 =head1 DESCRIPTION
  13
  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.
  18
  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.
  22
  23
  24 =head1 BUILDING parrot_debugger
  25
  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:
  28
  29   make parrot_debugger
  30
  31 Which will create a new parrot_debugger executable in the same directory as the parrot
  32 executable.
  33
  34 =head1 THE DEBUGGER SHELL
  35
  36 To start the debugger type:
  37
  38   parrot_debugger file.pbc
  39
  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.
  44
  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.
  47
  48 After the version banner, you'll see the friendly debugger prompt:
  49
  50   (pdb)
  51
  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'.
  54
  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
  57 executed.
  58
  59 =head1 DEBUGGER COMMANDS
  60
  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).
  63
  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
  68 sensitive.
  69
  70 A blank line always repeats the last command entered.
  71
  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).
  76
  77 =over 4
  78
  79 =item disassemble
  80
  81 Disassemble a loaded bytecode file. This will turn a file loaded with C<load>
  82 into proper Parrot assembler.
  83
  84 =item load
  85
  86 Load a source code (assembler) file. The syntax is:
  87
  88   load FILE
  89
  90 =item list (l)
  91
  92 List the source code. The syntax is:
  93
  94   list [FROM] [NUM]
  95
  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.
  99
 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)>.
 103
 104 Example:
 105
 106   # lists the first three source code lines
 107   (pdb) l 1 3
 108   1  set_i_ic I1,0
 109   2  L3:  print_sc "fact of "
 110   3  print_i I1
 111
 112 =item run (r)
 113
 114 Run (or restart) the program. The syntax is:
 115
 116   run [ARGUMENTS]
 117
 118 Any arguments you give are passed as command line arguments to the program (ie.
 119 they populate P0).
 120
 121 After the program has ended, you can run it again with this command. See also
 122 the C<continue (c)> command.
 123
 124 Example:
 125
 126   (pdb) r
 127   Restarting
 128   fact of 0 is: 1
 129   fact of 1 is: 1
 130   fact of 2 is: 2
 131   fact of 3 is: 6
 132   fact of 4 is: 24
 133   fact of 5 is: 120
 134   fact of 6 is: 720
 135   Program exited.
 136
 137 =item break (b)
 138
 139 Add a breakpoint. The syntax is:
 140
 141   b LINE [if CONDITION]
 142
 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.
 147
 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).
 150
 151 Example:
 152
 153   # sets a breakpoint on line 10 (will be breakpoint 0)
 154   (pdb) b 10
 155   Breakpoint 0 at line 10
 156
 157   # another breakpoint on line 11 (will be breakpoint 1)
 158   (pdb) b 11
 159   Breakpoint 1 at line 11
 160
 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
 164
 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
 168
 169   # break at line 4 if S2 is equal to S13
 170   (pdb) b 6 if S2 == S13
 171   Breakpoint 4 at line 6
 172
 173   # break at line 4 if S5 is equal to "stop"
 174   (pdb) b 7 if S2 == "stop"
 175   Breakpoint 5 at line 7
 176
 177 =item watch (w)
 178
 179 Add a watchpoint. The syntax is:
 180
 181   w CONDITION
 182
 183 The condition has the same format as in C<break>
 184
 185 =item delete (d)
 186
 187 Delete a breakpoint. The syntax is:
 188
 189   d NUM
 190
 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.
 193
 194 Example:
 195
 196   # delete the first breakpoint (was on line 10, see example above)
 197   (pdb) d 0
 198
 199 =item disable
 200
 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>.
 203
 204 =item enable
 205
 206 Re-enable a disabled breakpoint. The syntax is:
 207
 208   enable [NUM]
 209
 210 where C<NUM> is the number of the breakpoint.
 211
 212 =item continue (c)
 213
 214 Continue the program execution. The syntax of this command is:
 215
 216   continue [NUM]
 217
 218 Without arguments, the command just runs the source code until a breakpoint is
 219 found (or until the end of the program).
 220
 221 If you specify a number, it will skip the next C<NUM> breakpoints it
 222 encounters.
 223
 224 When the program has ended, continue will do nothing. Use C<run (r)> to execute
 225 it again.
 226
 227 =item next (n)
 228
 229 Run the next instruction. The syntax is:
 230
 231   next [NUM]
 232
 233 C<NUM> defaults to 1, but you can give a number of instructions to execute
 234 before stopping again.
 235
 236 =item eval (e)
 237
 238 The eval command is currently unimplemeneted.
 239
 240 Run an instruction. The syntax is:
 241
 242   eval INSTRUCTION
 243
 244
 245 Example:
 246
 247   (pdb) e set I0, 42
 248
 249   (pdb) e print I0
 250   42
 251
 252   (pdb) p i
 253   I0 =           42
 254   I1 =            0
 255   ...
 256
 257 =item trace (t)
 258
 259 Trace the next instruction. The syntax is:
 260
 261   trace [NUM]
 262
 263 It executes the next C<NUM> instructions (default is 1) just as C<next (n)>
 264 does, but printing additional trace information. This is the same as the
 265 information you get when running Parrot with the C<-t> option.
 266
 267 Example:
 268
 269   # executes 2 instructions and trace them
 270   (pdb) t 2
 271   PC=0; OP=67 (set_i_ic); ARGS=(I1=0, 0)
 272   PC=3; OP=24 (print_sc); ARGS=("fact of ")
 273   fact of
 274   3  print_i I1
 275
 276 =item print (p)
 277
 278 Print the interpreter registers. The syntax is:
 279
 280   print VALUE
 281
 282 C<VALUE> may be:
 283
 284 =over 4
 285
 286 =item A register name: C<I3>
 287
 288 Prints out the single register specified.
 289
 290 =item A register type: C<i>, C<n>, C<s>, or C<p>
 291
 292 Prints out all registers of the given type
 293
 294 =item An aggregate key: C<P0[1]>
 295
 296 Looks up the given (integer- or string-valued) key in a PMC register.
 297
 298 =back
 299
 300 For PMC registers, the command will print the number, the class of the PMC (in
 301 square brackets) and its string representation (when available). It prints
 302 <PMCNULL> for uninitialized PMC registers.
 303
 304 Examples:
 305
 306   # prints the content of I2
 307   (pdb) p i2
 308   I2 =              0
 309
 310   # prints the content of P0
 311   (pdb) p P0
 312   P0 = [ResizablePMCArray]
 313
 314   # prints the content of all string registers
 315   (pdb) p s
 316    S0 = Just
 317    S1 = Another
 318    S2 = Parrot
 319    S3 = Hacker
 320
 321 =item info
 322
 323 Print interpreter information.
 324
 325 Example:
 326
 327   (pdb) info
 328   Total memory allocated = 81936
 329   GC mark runs = 6
 330   GC collect runs = 0
 331   Active PMCs = 8197
 332   Active buffers = 7
 333   Total PMCs = 21840
 334   Total buffers = 48
 335   Header allocations since last collect = 0
 336   Memory allocations since last collect = 2
 337
 338 =item quit (q)
 339
 340 Exit the debugger.
 341
 342 =item help (h)
 343
 344 Prints information about debugger commands. The syntax is:
 345
 346   help [COMMAND]
 347
 348 If C<COMMAND> is omitted, prints a list of the available commands.
 349
 350 =back
 351
 352 =head1 FILES
 353
 354 =over 4
 355
 356 =item src/parrot_debugger.c
 357
 358 This is the file that will produce the executable.  Nothing fancy here, it
 359 mostly consists of the C<main> function.
 360
 361 =item src/debug.c
 362
 363 Most of the debugger is implemented here.  You may want to start from the
 364 C<PDB_run_command> function and go down from there for the real meat.
 365
 366 =item src/embed.c
 367
 368 C<Parrot_debug>, the function which launches the debugger, is implemented here.
 369
 370 =item include/parrot/debugger.h
 371
 372 This defines all the PDB structures, which hold data used by the debugger.
 373
 374 =back
 375
 376 =head1 HISTORY
 377
 378 =over 4
 379
 380 =item Version 1.0
 381
 382 First version (SVN debug.c revision 1.24), authored by Aldo Calpini
 383
 384 =back
 385