docs/debugger.pod

   1 # Copyright (C) 2001-2006, The Perl 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 =head1 BUILDING parrot_debugger
  24
  25 The debugger is not built with Parrot, but you should make it with its specific
  26 target:
  27
  28   make parrot_debugger
  29
  30 (where C<make> is the same C<make> incarnation you used to build Parrot).
  31
  32 If everything goes well, you should come up with a F<parrot_debugger>
  33 executable in the same directory as the Parrot program.
  34
  35 =head1 THE DEBUGGER SHELL
  36
  37 To start the debugger type:
  38
  39   parrot_debugger file.pbc
  40
  41 That is, F<parrot_debugger> takes exactly one argument, which is the Parrot bytecode that
  42 you're going to debug. 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 Run an instruction. The syntax is:
 239
 240   eval INSTRUCTION
 241
 242
 243 Example:
 244
 245   (pdb) e set I0, 42
 246
 247   (pdb) e print I0
 248   42
 249
 250   (pdb) p i
 251   I0 =           42
 252   I1 =            0
 253   ...
 254
 255 =item trace (t)
 256
 257 Trace the next instruction. The syntax is:
 258
 259   trace [NUM]
 260
 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.
 264
 265 Example:
 266
 267   # executes 2 instructions and trace them
 268   (pdb) t 2
 269   PC=0; OP=67 (set_i_ic); ARGS=(I1=0, 0)
 270   PC=3; OP=24 (print_sc); ARGS=("fact of ")
 271   fact of
 272   3  print_i I1
 273
 274 =item print (p)
 275
 276 Print the interpreter registers. The syntax is:
 277
 278   print VALUE
 279
 280 C<VALUE> may be:
 281
 282 =over 4
 283
 284 =item A register name: C<I3>
 285
 286 Prints out the single register specified.
 287
 288 =item A register type: C<i>, C<n>, C<s>, or C<p>
 289
 290 Prints out all registers of the given type
 291
 292 =item An aggregate key: C<P0[1]>
 293
 294 Looks up the given (integer- or string-valued) key in a PMC register.
 295
 296 =back
 297
 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.
 301
 302 Example:
 303
 304   # prints the content of I2
 305   (pdb) p i2
 306   Integer Registers:
 307   I2 =              0
 308
 309   # prints the content of P0
 310   (pdb) p P0
 311   PMC Registers:
 312   P0 = [ResizablePMCArray]
 313
 314   # prints the content of all string registers
 315   (pdb) p s
 316   String Registers:
 317    0 =
 318           Buflen  =                  4
 319           Flags   =                  0
 320           Bufused =                  4
 321           Strlen  =                  4
 322           Offset  =                  0
 323           String  =       Just
 324    1 =
 325           Buflen  =                  8
 326           Flags   =                  0
 327           Bufused =                  7
 328           Strlen  =                  7
 329           String  =       another
 330    2 =
 331           Buflen  =                  8
 332           Flags   =                  0
 333           Bufused =                  6
 334           Strlen  =                  6
 335           String  =       Parrot
 336    3 =
 337           Buflen  =                  8
 338           Flags   =                  0
 339           Bufused =                  6
 340           Strlen  =                  6
 341           String  =       hacker
 342    4 =
 343    5 =
 344    6 =
 345    7 =
 346    8 =
 347    # ... and so on
 348
 349 =item info
 350
 351 Print interpreter information.
 352
 353 Example:
 354
 355   (pdb) info
 356   Total memory allocated = 81936
 357   DOD runs = 6
 358   Collect runs = 0
 359   Active PMCs = 8197
 360   Active buffers = 7
 361   Total PMCs = 21840
 362   Total buffers = 48
 363   Header allocations since last collect = 0
 364   Memory allocations since last collect = 2
 365
 366 =item quit (q)
 367
 368 Exit the debugger.
 369
 370 =item help (h)
 371
 372 Prints information about debugger commands. The syntax is:
 373
 374   help [COMMAND]
 375
 376 If C<COMMAND> is omitted, prints a list of the available commands.
 377
 378 =back
 379
 380 =head1 FILES
 381
 382 =over 4
 383
 384 =item src/pdb.c
 385
 386 This is the file that will produce the executable.  Nothing fancy here, only
 387 the C<main> function.
 388
 389 =item src/debug.c
 390
 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.
 393
 394 =item src/embed.c
 395
 396 C<Parrot_debug>, the function which launches the debugger, is implemented here.
 397
 398 =item include/parrot/debug.h
 399
 400 This defines all the PDB structures, which hold data used by the debugger.
 401
 402 =back
 403
 404 =head1 HISTORY
 405
 406 =over 4
 407
 408 =item Version 1.0
 409
 410 First version (SVN debug.c revision 1.24), authored by Aldo Calpini
 411
 412 =back
 413