| 1 | =head1 NAME |
| 2 | X<debug> X<debugger> |
| 3 | |
| 4 | perldebug - Perl debugging |
| 5 | |
| 6 | =head1 DESCRIPTION |
| 7 | |
| 8 | First of all, have you tried using L<C<use strict;>|strict> and |
| 9 | L<C<use warnings;>|warnings>? |
| 10 | |
| 11 | |
| 12 | If you're new to the Perl debugger, you may prefer to read |
| 13 | L<perldebtut>, which is a tutorial introduction to the debugger. |
| 14 | |
| 15 | =head1 The Perl Debugger |
| 16 | |
| 17 | If you invoke Perl with the B<-d> switch, your script runs under the |
| 18 | Perl source debugger. This works like an interactive Perl |
| 19 | environment, prompting for debugger commands that let you examine |
| 20 | source code, set breakpoints, get stack backtraces, change the values of |
| 21 | variables, etc. This is so convenient that you often fire up |
| 22 | the debugger all by itself just to test out Perl constructs |
| 23 | interactively to see what they do. For example: |
| 24 | X<-d> |
| 25 | |
| 26 | $ perl -d -e 42 |
| 27 | |
| 28 | In Perl, the debugger is not a separate program the way it usually is in the |
| 29 | typical compiled environment. Instead, the B<-d> flag tells the compiler |
| 30 | to insert source information into the parse trees it's about to hand off |
| 31 | to the interpreter. That means your code must first compile correctly |
| 32 | for the debugger to work on it. Then when the interpreter starts up, it |
| 33 | preloads a special Perl library file containing the debugger. |
| 34 | |
| 35 | The program will halt I<right before> the first run-time executable |
| 36 | statement (but see below regarding compile-time statements) and ask you |
| 37 | to enter a debugger command. Contrary to popular expectations, whenever |
| 38 | the debugger halts and shows you a line of code, it always displays the |
| 39 | line it's I<about> to execute, rather than the one it has just executed. |
| 40 | |
| 41 | Any command not recognized by the debugger is directly executed |
| 42 | (C<eval>'d) as Perl code in the current package. (The debugger |
| 43 | uses the DB package for keeping its own state information.) |
| 44 | |
| 45 | Note that the said C<eval> is bound by an implicit scope. As a |
| 46 | result any newly introduced lexical variable or any modified |
| 47 | capture buffer content is lost after the eval. The debugger is a |
| 48 | nice environment to learn Perl, but if you interactively experiment using |
| 49 | material which should be in the same scope, stuff it in one line. |
| 50 | |
| 51 | For any text entered at the debugger prompt, leading and trailing whitespace |
| 52 | is first stripped before further processing. If a debugger command |
| 53 | coincides with some function in your own program, merely precede the |
| 54 | function with something that doesn't look like a debugger command, such |
| 55 | as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses |
| 56 | or braces. |
| 57 | |
| 58 | =head2 Calling the Debugger |
| 59 | |
| 60 | There are several ways to call the debugger: |
| 61 | |
| 62 | =over 4 |
| 63 | |
| 64 | =item perl -d program_name |
| 65 | |
| 66 | On the given program identified by C<program_name>. |
| 67 | |
| 68 | =item perl -d -e 0 |
| 69 | |
| 70 | Interactively supply an arbitrary C<expression> using C<-e>. |
| 71 | |
| 72 | =item perl -d:ptkdb program_name |
| 73 | |
| 74 | Debug a given program via the C<Devel::ptkdb> GUI. |
| 75 | |
| 76 | =item perl -dt threaded_program_name |
| 77 | |
| 78 | Debug a given program using threads (experimental). |
| 79 | |
| 80 | =back |
| 81 | |
| 82 | =head2 Debugger Commands |
| 83 | |
| 84 | The interactive debugger understands the following commands: |
| 85 | |
| 86 | =over 12 |
| 87 | |
| 88 | =item h |
| 89 | X<debugger command, h> |
| 90 | |
| 91 | Prints out a summary help message |
| 92 | |
| 93 | =item h [command] |
| 94 | |
| 95 | Prints out a help message for the given debugger command. |
| 96 | |
| 97 | =item h h |
| 98 | |
| 99 | The special argument of C<h h> produces the entire help page, which is quite long. |
| 100 | |
| 101 | If the output of the C<h h> command (or any command, for that matter) scrolls |
| 102 | past your screen, precede the command with a leading pipe symbol so |
| 103 | that it's run through your pager, as in |
| 104 | |
| 105 | DB> |h h |
| 106 | |
| 107 | You may change the pager which is used via C<o pager=...> command. |
| 108 | |
| 109 | =item p expr |
| 110 | X<debugger command, p> |
| 111 | |
| 112 | Same as C<print {$DB::OUT} expr> in the current package. In particular, |
| 113 | because this is just Perl's own C<print> function, this means that nested |
| 114 | data structures and objects are not dumped, unlike with the C<x> command. |
| 115 | |
| 116 | The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of |
| 117 | where STDOUT may be redirected to. |
| 118 | |
| 119 | =item x [maxdepth] expr |
| 120 | X<debugger command, x> |
| 121 | |
| 122 | Evaluates its expression in list context and dumps out the result in a |
| 123 | pretty-printed fashion. Nested data structures are printed out |
| 124 | recursively, unlike the real C<print> function in Perl. When dumping |
| 125 | hashes, you'll probably prefer 'x \%h' rather than 'x %h'. |
| 126 | See L<Dumpvalue> if you'd like to do this yourself. |
| 127 | |
| 128 | The output format is governed by multiple options described under |
| 129 | L<"Configurable Options">. |
| 130 | |
| 131 | If the C<maxdepth> is included, it must be a numeral I<N>; the value is |
| 132 | dumped only I<N> levels deep, as if the C<dumpDepth> option had been |
| 133 | temporarily set to I<N>. |
| 134 | |
| 135 | =item V [pkg [vars]] |
| 136 | X<debugger command, V> |
| 137 | |
| 138 | Display all (or some) variables in package (defaulting to C<main>) |
| 139 | using a data pretty-printer (hashes show their keys and values so |
| 140 | you see what's what, control characters are made printable, etc.). |
| 141 | Make sure you don't put the type specifier (like C<$>) there, just |
| 142 | the symbol names, like this: |
| 143 | |
| 144 | V DB filename line |
| 145 | |
| 146 | Use C<~pattern> and C<!pattern> for positive and negative regexes. |
| 147 | |
| 148 | This is similar to calling the C<x> command on each applicable var. |
| 149 | |
| 150 | =item X [vars] |
| 151 | X<debugger command, X> |
| 152 | |
| 153 | Same as C<V currentpackage [vars]>. |
| 154 | |
| 155 | =item y [level [vars]] |
| 156 | X<debugger command, y> |
| 157 | |
| 158 | Display all (or some) lexical variables (mnemonic: C<mY> variables) |
| 159 | in the current scope or I<level> scopes higher. You can limit the |
| 160 | variables that you see with I<vars> which works exactly as it does |
| 161 | for the C<V> and C<X> commands. Requires the C<PadWalker> module |
| 162 | version 0.08 or higher; will warn if this isn't installed. Output |
| 163 | is pretty-printed in the same style as for C<V> and the format is |
| 164 | controlled by the same options. |
| 165 | |
| 166 | =item T |
| 167 | X<debugger command, T> X<backtrace> X<stack, backtrace> |
| 168 | |
| 169 | Produce a stack backtrace. See below for details on its output. |
| 170 | |
| 171 | =item s [expr] |
| 172 | X<debugger command, s> X<step> |
| 173 | |
| 174 | Single step. Executes until the beginning of another |
| 175 | statement, descending into subroutine calls. If an expression is |
| 176 | supplied that includes function calls, it too will be single-stepped. |
| 177 | |
| 178 | =item n [expr] |
| 179 | X<debugger command, n> |
| 180 | |
| 181 | Next. Executes over subroutine calls, until the beginning |
| 182 | of the next statement. If an expression is supplied that includes |
| 183 | function calls, those functions will be executed with stops before |
| 184 | each statement. |
| 185 | |
| 186 | =item r |
| 187 | X<debugger command, r> |
| 188 | |
| 189 | Continue until the return from the current subroutine. |
| 190 | Dump the return value if the C<PrintRet> option is set (default). |
| 191 | |
| 192 | =item <CR> |
| 193 | |
| 194 | Repeat last C<n> or C<s> command. |
| 195 | |
| 196 | =item c [line|sub] |
| 197 | X<debugger command, c> |
| 198 | |
| 199 | Continue, optionally inserting a one-time-only breakpoint |
| 200 | at the specified line or subroutine. |
| 201 | |
| 202 | =item l |
| 203 | X<debugger command, l> |
| 204 | |
| 205 | List next window of lines. |
| 206 | |
| 207 | =item l min+incr |
| 208 | |
| 209 | List C<incr+1> lines starting at C<min>. |
| 210 | |
| 211 | =item l min-max |
| 212 | |
| 213 | List lines C<min> through C<max>. C<l -> is synonymous to C<->. |
| 214 | |
| 215 | =item l line |
| 216 | |
| 217 | List a single line. |
| 218 | |
| 219 | =item l subname |
| 220 | |
| 221 | List first window of lines from subroutine. I<subname> may |
| 222 | be a variable that contains a code reference. |
| 223 | |
| 224 | =item - |
| 225 | X<debugger command, -> |
| 226 | |
| 227 | List previous window of lines. |
| 228 | |
| 229 | =item v [line] |
| 230 | X<debugger command, v> |
| 231 | |
| 232 | View a few lines of code around the current line. |
| 233 | |
| 234 | =item . |
| 235 | X<debugger command, .> |
| 236 | |
| 237 | Return the internal debugger pointer to the line last |
| 238 | executed, and print out that line. |
| 239 | |
| 240 | =item f filename |
| 241 | X<debugger command, f> |
| 242 | |
| 243 | Switch to viewing a different file or C<eval> statement. If I<filename> |
| 244 | is not a full pathname found in the values of %INC, it is considered |
| 245 | a regex. |
| 246 | |
| 247 | C<eval>ed strings (when accessible) are considered to be filenames: |
| 248 | C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string |
| 249 | (in the order of execution). The bodies of the currently executed C<eval> |
| 250 | and of C<eval>ed strings that define subroutines are saved and thus |
| 251 | accessible. |
| 252 | |
| 253 | =item /pattern/ |
| 254 | |
| 255 | Search forwards for pattern (a Perl regex); final / is optional. |
| 256 | The search is case-insensitive by default. |
| 257 | |
| 258 | =item ?pattern? |
| 259 | |
| 260 | Search backwards for pattern; final ? is optional. |
| 261 | The search is case-insensitive by default. |
| 262 | |
| 263 | =item L [abw] |
| 264 | X<debugger command, L> |
| 265 | |
| 266 | List (default all) actions, breakpoints and watch expressions |
| 267 | |
| 268 | =item S [[!]regex] |
| 269 | X<debugger command, S> |
| 270 | |
| 271 | List subroutine names [not] matching the regex. |
| 272 | |
| 273 | =item t [n] |
| 274 | X<debugger command, t> |
| 275 | |
| 276 | Toggle trace mode (see also the C<AutoTrace> option). |
| 277 | Optional argument is the maximum number of levels to trace below |
| 278 | the current one; anything deeper than that will be silent. |
| 279 | |
| 280 | =item t [n] expr |
| 281 | X<debugger command, t> |
| 282 | |
| 283 | Trace through execution of C<expr>. |
| 284 | Optional first argument is the maximum number of levels to trace below |
| 285 | the current one; anything deeper than that will be silent. |
| 286 | See L<perldebguts/"Frame Listing Output Examples"> for examples. |
| 287 | |
| 288 | =item b |
| 289 | X<breakpoint> |
| 290 | X<debugger command, b> |
| 291 | |
| 292 | Sets breakpoint on current line |
| 293 | |
| 294 | =item b [line] [condition] |
| 295 | X<breakpoint> |
| 296 | X<debugger command, b> |
| 297 | |
| 298 | Set a breakpoint before the given line. If a condition |
| 299 | is specified, it's evaluated each time the statement is reached: a |
| 300 | breakpoint is taken only if the condition is true. Breakpoints may |
| 301 | only be set on lines that begin an executable statement. Conditions |
| 302 | don't use C<if>: |
| 303 | |
| 304 | b 237 $x > 30 |
| 305 | b 237 ++$count237 < 11 |
| 306 | b 33 /pattern/i |
| 307 | |
| 308 | If the line number is C<.>, sets a breakpoint on the current line: |
| 309 | |
| 310 | b . $n > 100 |
| 311 | |
| 312 | =item b [file]:[line] [condition] |
| 313 | X<breakpoint> |
| 314 | X<debugger command, b> |
| 315 | |
| 316 | Set a breakpoint before the given line in a (possibly different) file. If a |
| 317 | condition is specified, it's evaluated each time the statement is reached: a |
| 318 | breakpoint is taken only if the condition is true. Breakpoints may only be set |
| 319 | on lines that begin an executable statement. Conditions don't use C<if>: |
| 320 | |
| 321 | b lib/MyModule.pm:237 $x > 30 |
| 322 | b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11 |
| 323 | |
| 324 | =item b subname [condition] |
| 325 | X<breakpoint> |
| 326 | X<debugger command, b> |
| 327 | |
| 328 | Set a breakpoint before the first line of the named subroutine. I<subname> may |
| 329 | be a variable containing a code reference (in this case I<condition> |
| 330 | is not supported). |
| 331 | |
| 332 | =item b postpone subname [condition] |
| 333 | X<breakpoint> |
| 334 | X<debugger command, b> |
| 335 | |
| 336 | Set a breakpoint at first line of subroutine after it is compiled. |
| 337 | |
| 338 | =item b load filename |
| 339 | X<breakpoint> |
| 340 | X<debugger command, b> |
| 341 | |
| 342 | Set a breakpoint before the first executed line of the I<filename>, |
| 343 | which should be a full pathname found amongst the %INC values. |
| 344 | |
| 345 | =item b compile subname |
| 346 | X<breakpoint> |
| 347 | X<debugger command, b> |
| 348 | |
| 349 | Sets a breakpoint before the first statement executed after the specified |
| 350 | subroutine is compiled. |
| 351 | |
| 352 | =item B line |
| 353 | X<breakpoint> |
| 354 | X<debugger command, B> |
| 355 | |
| 356 | Delete a breakpoint from the specified I<line>. |
| 357 | |
| 358 | =item B * |
| 359 | X<breakpoint> |
| 360 | X<debugger command, B> |
| 361 | |
| 362 | Delete all installed breakpoints. |
| 363 | |
| 364 | =item disable [file]:[line] |
| 365 | X<breakpoint> |
| 366 | X<debugger command, disable> |
| 367 | X<disable> |
| 368 | |
| 369 | Disable the breakpoint so it won't stop the execution of the program. |
| 370 | Breakpoints are enabled by default and can be re-enabled using the C<enable> |
| 371 | command. |
| 372 | |
| 373 | =item disable [line] |
| 374 | X<breakpoint> |
| 375 | X<debugger command, disable> |
| 376 | X<disable> |
| 377 | |
| 378 | Disable the breakpoint so it won't stop the execution of the program. |
| 379 | Breakpoints are enabled by default and can be re-enabled using the C<enable> |
| 380 | command. |
| 381 | |
| 382 | This is done for a breakpoint in the current file. |
| 383 | |
| 384 | =item enable [file]:[line] |
| 385 | X<breakpoint> |
| 386 | X<debugger command, disable> |
| 387 | X<disable> |
| 388 | |
| 389 | Enable the breakpoint so it will stop the execution of the program. |
| 390 | |
| 391 | =item enable [line] |
| 392 | X<breakpoint> |
| 393 | X<debugger command, disable> |
| 394 | X<disable> |
| 395 | |
| 396 | Enable the breakpoint so it will stop the execution of the program. |
| 397 | |
| 398 | This is done for a breakpoint in the current file. |
| 399 | |
| 400 | =item a [line] command |
| 401 | X<debugger command, a> |
| 402 | |
| 403 | Set an action to be done before the line is executed. If I<line> is |
| 404 | omitted, set an action on the line about to be executed. |
| 405 | The sequence of steps taken by the debugger is |
| 406 | |
| 407 | 1. check for a breakpoint at this line |
| 408 | 2. print the line if necessary (tracing) |
| 409 | 3. do any actions associated with that line |
| 410 | 4. prompt user if at a breakpoint or in single-step |
| 411 | 5. evaluate line |
| 412 | |
| 413 | For example, this will print out $foo every time line |
| 414 | 53 is passed: |
| 415 | |
| 416 | a 53 print "DB FOUND $foo\n" |
| 417 | |
| 418 | =item A line |
| 419 | X<debugger command, A> |
| 420 | |
| 421 | Delete an action from the specified line. |
| 422 | |
| 423 | =item A * |
| 424 | X<debugger command, A> |
| 425 | |
| 426 | Delete all installed actions. |
| 427 | |
| 428 | =item w expr |
| 429 | X<debugger command, w> |
| 430 | |
| 431 | Add a global watch-expression. Whenever a watched global changes the |
| 432 | debugger will stop and display the old and new values. |
| 433 | |
| 434 | =item W expr |
| 435 | X<debugger command, W> |
| 436 | |
| 437 | Delete watch-expression |
| 438 | |
| 439 | =item W * |
| 440 | X<debugger command, W> |
| 441 | |
| 442 | Delete all watch-expressions. |
| 443 | |
| 444 | =item o |
| 445 | X<debugger command, o> |
| 446 | |
| 447 | Display all options. |
| 448 | |
| 449 | =item o booloption ... |
| 450 | X<debugger command, o> |
| 451 | |
| 452 | Set each listed Boolean option to the value C<1>. |
| 453 | |
| 454 | =item o anyoption? ... |
| 455 | X<debugger command, o> |
| 456 | |
| 457 | Print out the value of one or more options. |
| 458 | |
| 459 | =item o option=value ... |
| 460 | X<debugger command, o> |
| 461 | |
| 462 | Set the value of one or more options. If the value has internal |
| 463 | whitespace, it should be quoted. For example, you could set C<o |
| 464 | pager="less -MQeicsNfr"> to call B<less> with those specific options. |
| 465 | You may use either single or double quotes, but if you do, you must |
| 466 | escape any embedded instances of same sort of quote you began with, |
| 467 | as well as any escaping any escapes that immediately precede that |
| 468 | quote but which are not meant to escape the quote itself. In other |
| 469 | words, you follow single-quoting rules irrespective of the quote; |
| 470 | eg: C<o option='this isn\'t bad'> or C<o option="She said, \"Isn't |
| 471 | it?\"">. |
| 472 | |
| 473 | For historical reasons, the C<=value> is optional, but defaults to |
| 474 | 1 only where it is safe to do so--that is, mostly for Boolean |
| 475 | options. It is always better to assign a specific value using C<=>. |
| 476 | The C<option> can be abbreviated, but for clarity probably should |
| 477 | not be. Several options can be set together. See L<"Configurable Options"> |
| 478 | for a list of these. |
| 479 | |
| 480 | =item < ? |
| 481 | X<< debugger command, < >> |
| 482 | |
| 483 | List out all pre-prompt Perl command actions. |
| 484 | |
| 485 | =item < [ command ] |
| 486 | X<< debugger command, < >> |
| 487 | |
| 488 | Set an action (Perl command) to happen before every debugger prompt. |
| 489 | A multi-line command may be entered by backslashing the newlines. |
| 490 | |
| 491 | =item < * |
| 492 | X<< debugger command, < >> |
| 493 | |
| 494 | Delete all pre-prompt Perl command actions. |
| 495 | |
| 496 | =item << command |
| 497 | X<< debugger command, << >> |
| 498 | |
| 499 | Add an action (Perl command) to happen before every debugger prompt. |
| 500 | A multi-line command may be entered by backwhacking the newlines. |
| 501 | |
| 502 | =item > ? |
| 503 | X<< debugger command, > >> |
| 504 | |
| 505 | List out post-prompt Perl command actions. |
| 506 | |
| 507 | =item > command |
| 508 | X<< debugger command, > >> |
| 509 | |
| 510 | Set an action (Perl command) to happen after the prompt when you've |
| 511 | just given a command to return to executing the script. A multi-line |
| 512 | command may be entered by backslashing the newlines (we bet you |
| 513 | couldn't have guessed this by now). |
| 514 | |
| 515 | =item > * |
| 516 | X<< debugger command, > >> |
| 517 | |
| 518 | Delete all post-prompt Perl command actions. |
| 519 | |
| 520 | =item >> command |
| 521 | X<<< debugger command, >> >>> |
| 522 | |
| 523 | Adds an action (Perl command) to happen after the prompt when you've |
| 524 | just given a command to return to executing the script. A multi-line |
| 525 | command may be entered by backslashing the newlines. |
| 526 | |
| 527 | =item { ? |
| 528 | X<debugger command, {> |
| 529 | |
| 530 | List out pre-prompt debugger commands. |
| 531 | |
| 532 | =item { [ command ] |
| 533 | |
| 534 | Set an action (debugger command) to happen before every debugger prompt. |
| 535 | A multi-line command may be entered in the customary fashion. |
| 536 | |
| 537 | Because this command is in some senses new, a warning is issued if |
| 538 | you appear to have accidentally entered a block instead. If that's |
| 539 | what you mean to do, write it as with C<;{ ... }> or even |
| 540 | C<do { ... }>. |
| 541 | |
| 542 | =item { * |
| 543 | X<debugger command, {> |
| 544 | |
| 545 | Delete all pre-prompt debugger commands. |
| 546 | |
| 547 | =item {{ command |
| 548 | X<debugger command, {{> |
| 549 | |
| 550 | Add an action (debugger command) to happen before every debugger prompt. |
| 551 | A multi-line command may be entered, if you can guess how: see above. |
| 552 | |
| 553 | =item ! number |
| 554 | X<debugger command, !> |
| 555 | |
| 556 | Redo a previous command (defaults to the previous command). |
| 557 | |
| 558 | =item ! -number |
| 559 | X<debugger command, !> |
| 560 | |
| 561 | Redo number'th previous command. |
| 562 | |
| 563 | =item ! pattern |
| 564 | X<debugger command, !> |
| 565 | |
| 566 | Redo last command that started with pattern. |
| 567 | See C<o recallCommand>, too. |
| 568 | |
| 569 | =item !! cmd |
| 570 | X<debugger command, !!> |
| 571 | |
| 572 | Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See |
| 573 | C<o shellBang>, also. Note that the user's current shell (well, |
| 574 | their C<$ENV{SHELL}> variable) will be used, which can interfere |
| 575 | with proper interpretation of exit status or signal and coredump |
| 576 | information. |
| 577 | |
| 578 | =item source file |
| 579 | X<debugger command, source> |
| 580 | |
| 581 | Read and execute debugger commands from I<file>. |
| 582 | I<file> may itself contain C<source> commands. |
| 583 | |
| 584 | =item H -number |
| 585 | X<debugger command, H> |
| 586 | |
| 587 | Display last n commands. Only commands longer than one character are |
| 588 | listed. If I<number> is omitted, list them all. |
| 589 | |
| 590 | =item q or ^D |
| 591 | X<debugger command, q> |
| 592 | X<debugger command, ^D> |
| 593 | |
| 594 | Quit. ("quit" doesn't work for this, unless you've made an alias) |
| 595 | This is the only supported way to exit the debugger, though typing |
| 596 | C<exit> twice might work. |
| 597 | |
| 598 | Set the C<inhibit_exit> option to 0 if you want to be able to step |
| 599 | off the end the script. You may also need to set $finished to 0 |
| 600 | if you want to step through global destruction. |
| 601 | |
| 602 | =item R |
| 603 | X<debugger command, R> |
| 604 | |
| 605 | Restart the debugger by C<exec()>ing a new session. We try to maintain |
| 606 | your history across this, but internal settings and command-line options |
| 607 | may be lost. |
| 608 | |
| 609 | The following setting are currently preserved: history, breakpoints, |
| 610 | actions, debugger options, and the Perl command-line |
| 611 | options B<-w>, B<-I>, and B<-e>. |
| 612 | |
| 613 | =item |dbcmd |
| 614 | X<debugger command, |> |
| 615 | |
| 616 | Run the debugger command, piping DB::OUT into your current pager. |
| 617 | |
| 618 | =item ||dbcmd |
| 619 | X<debugger command, ||> |
| 620 | |
| 621 | Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well. |
| 622 | |
| 623 | =item = [alias value] |
| 624 | X<debugger command, => |
| 625 | |
| 626 | Define a command alias, like |
| 627 | |
| 628 | = quit q |
| 629 | |
| 630 | or list current aliases. |
| 631 | |
| 632 | =item command |
| 633 | |
| 634 | Execute command as a Perl statement. A trailing semicolon will be |
| 635 | supplied. If the Perl statement would otherwise be confused for a |
| 636 | Perl debugger, use a leading semicolon, too. |
| 637 | |
| 638 | =item m expr |
| 639 | X<debugger command, m> |
| 640 | |
| 641 | List which methods may be called on the result of the evaluated |
| 642 | expression. The expression may evaluated to a reference to a |
| 643 | blessed object, or to a package name. |
| 644 | |
| 645 | =item M |
| 646 | X<debugger command, M> |
| 647 | |
| 648 | Display all loaded modules and their versions. |
| 649 | |
| 650 | =item man [manpage] |
| 651 | X<debugger command, man> |
| 652 | |
| 653 | Despite its name, this calls your system's default documentation |
| 654 | viewer on the given page, or on the viewer itself if I<manpage> is |
| 655 | omitted. If that viewer is B<man>, the current C<Config> information |
| 656 | is used to invoke B<man> using the proper MANPATH or S<B<-M> |
| 657 | I<manpath>> option. Failed lookups of the form C<XXX> that match |
| 658 | known manpages of the form I<perlXXX> will be retried. This lets |
| 659 | you type C<man debug> or C<man op> from the debugger. |
| 660 | |
| 661 | On systems traditionally bereft of a usable B<man> command, the |
| 662 | debugger invokes B<perldoc>. Occasionally this determination is |
| 663 | incorrect due to recalcitrant vendors or rather more felicitously, |
| 664 | to enterprising users. If you fall into either category, just |
| 665 | manually set the $DB::doccmd variable to whatever viewer to view |
| 666 | the Perl documentation on your system. This may be set in an rc |
| 667 | file, or through direct assignment. We're still waiting for a |
| 668 | working example of something along the lines of: |
| 669 | |
| 670 | $DB::doccmd = 'netscape -remote http://something.here/'; |
| 671 | |
| 672 | =back |
| 673 | |
| 674 | =head2 Configurable Options |
| 675 | |
| 676 | The debugger has numerous options settable using the C<o> command, |
| 677 | either interactively or from the environment or an rc file. |
| 678 | (./.perldb or ~/.perldb under Unix.) |
| 679 | |
| 680 | |
| 681 | =over 12 |
| 682 | |
| 683 | =item C<recallCommand>, C<ShellBang> |
| 684 | X<debugger option, recallCommand> |
| 685 | X<debugger option, ShellBang> |
| 686 | |
| 687 | The characters used to recall a command or spawn a shell. By |
| 688 | default, both are set to C<!>, which is unfortunate. |
| 689 | |
| 690 | =item C<pager> |
| 691 | X<debugger option, pager> |
| 692 | |
| 693 | Program to use for output of pager-piped commands (those beginning |
| 694 | with a C<|> character.) By default, C<$ENV{PAGER}> will be used. |
| 695 | Because the debugger uses your current terminal characteristics |
| 696 | for bold and underlining, if the chosen pager does not pass escape |
| 697 | sequences through unchanged, the output of some debugger commands |
| 698 | will not be readable when sent through the pager. |
| 699 | |
| 700 | =item C<tkRunning> |
| 701 | X<debugger option, tkRunning> |
| 702 | |
| 703 | Run Tk while prompting (with ReadLine). |
| 704 | |
| 705 | =item C<signalLevel>, C<warnLevel>, C<dieLevel> |
| 706 | X<debugger option, signalLevel> X<debugger option, warnLevel> |
| 707 | X<debugger option, dieLevel> |
| 708 | |
| 709 | Level of verbosity. By default, the debugger leaves your exceptions |
| 710 | and warnings alone, because altering them can break correctly running |
| 711 | programs. It will attempt to print a message when uncaught INT, BUS, or |
| 712 | SEGV signals arrive. (But see the mention of signals in L</BUGS> below.) |
| 713 | |
| 714 | To disable this default safe mode, set these values to something higher |
| 715 | than 0. At a level of 1, you get backtraces upon receiving any kind |
| 716 | of warning (this is often annoying) or exception (this is |
| 717 | often valuable). Unfortunately, the debugger cannot discern fatal |
| 718 | exceptions from non-fatal ones. If C<dieLevel> is even 1, then your |
| 719 | non-fatal exceptions are also traced and unceremoniously altered if they |
| 720 | came from C<eval'ed> strings or from any kind of C<eval> within modules |
| 721 | you're attempting to load. If C<dieLevel> is 2, the debugger doesn't |
| 722 | care where they came from: It usurps your exception handler and prints |
| 723 | out a trace, then modifies all exceptions with its own embellishments. |
| 724 | This may perhaps be useful for some tracing purposes, but tends to hopelessly |
| 725 | destroy any program that takes its exception handling seriously. |
| 726 | |
| 727 | =item C<AutoTrace> |
| 728 | X<debugger option, AutoTrace> |
| 729 | |
| 730 | Trace mode (similar to C<t> command, but can be put into |
| 731 | C<PERLDB_OPTS>). |
| 732 | |
| 733 | =item C<LineInfo> |
| 734 | X<debugger option, LineInfo> |
| 735 | |
| 736 | File or pipe to print line number info to. If it is a pipe (say, |
| 737 | C<|visual_perl_db>), then a short message is used. This is the |
| 738 | mechanism used to interact with a slave editor or visual debugger, |
| 739 | such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical |
| 740 | debugger. |
| 741 | |
| 742 | =item C<inhibit_exit> |
| 743 | X<debugger option, inhibit_exit> |
| 744 | |
| 745 | If 0, allows I<stepping off> the end of the script. |
| 746 | |
| 747 | =item C<PrintRet> |
| 748 | X<debugger option, PrintRet> |
| 749 | |
| 750 | Print return value after C<r> command if set (default). |
| 751 | |
| 752 | =item C<ornaments> |
| 753 | X<debugger option, ornaments> |
| 754 | |
| 755 | Affects screen appearance of the command line (see L<Term::ReadLine>). |
| 756 | There is currently no way to disable these, which can render |
| 757 | some output illegible on some displays, or with some pagers. |
| 758 | This is considered a bug. |
| 759 | |
| 760 | =item C<frame> |
| 761 | X<debugger option, frame> |
| 762 | |
| 763 | Affects the printing of messages upon entry and exit from subroutines. If |
| 764 | C<frame & 2> is false, messages are printed on entry only. (Printing |
| 765 | on exit might be useful if interspersed with other messages.) |
| 766 | |
| 767 | If C<frame & 4>, arguments to functions are printed, plus context |
| 768 | and caller info. If C<frame & 8>, overloaded C<stringify> and |
| 769 | C<tie>d C<FETCH> is enabled on the printed arguments. If C<frame |
| 770 | & 16>, the return value from the subroutine is printed. |
| 771 | |
| 772 | The length at which the argument list is truncated is governed by the |
| 773 | next option: |
| 774 | |
| 775 | =item C<maxTraceLen> |
| 776 | X<debugger option, maxTraceLen> |
| 777 | |
| 778 | Length to truncate the argument list when the C<frame> option's |
| 779 | bit 4 is set. |
| 780 | |
| 781 | =item C<windowSize> |
| 782 | X<debugger option, windowSize> |
| 783 | |
| 784 | Change the size of code list window (default is 10 lines). |
| 785 | |
| 786 | =back |
| 787 | |
| 788 | The following options affect what happens with C<V>, C<X>, and C<x> |
| 789 | commands: |
| 790 | |
| 791 | =over 12 |
| 792 | |
| 793 | =item C<arrayDepth>, C<hashDepth> |
| 794 | X<debugger option, arrayDepth> X<debugger option, hashDepth> |
| 795 | |
| 796 | Print only first N elements ('' for all). |
| 797 | |
| 798 | =item C<dumpDepth> |
| 799 | X<debugger option, dumpDepth> |
| 800 | |
| 801 | Limit recursion depth to N levels when dumping structures. |
| 802 | Negative values are interpreted as infinity. Default: infinity. |
| 803 | |
| 804 | =item C<compactDump>, C<veryCompact> |
| 805 | X<debugger option, compactDump> X<debugger option, veryCompact> |
| 806 | |
| 807 | Change the style of array and hash output. If C<compactDump>, short array |
| 808 | may be printed on one line. |
| 809 | |
| 810 | =item C<globPrint> |
| 811 | X<debugger option, globPrint> |
| 812 | |
| 813 | Whether to print contents of globs. |
| 814 | |
| 815 | =item C<DumpDBFiles> |
| 816 | X<debugger option, DumpDBFiles> |
| 817 | |
| 818 | Dump arrays holding debugged files. |
| 819 | |
| 820 | =item C<DumpPackages> |
| 821 | X<debugger option, DumpPackages> |
| 822 | |
| 823 | Dump symbol tables of packages. |
| 824 | |
| 825 | =item C<DumpReused> |
| 826 | X<debugger option, DumpReused> |
| 827 | |
| 828 | Dump contents of "reused" addresses. |
| 829 | |
| 830 | =item C<quote>, C<HighBit>, C<undefPrint> |
| 831 | X<debugger option, quote> X<debugger option, HighBit> |
| 832 | X<debugger option, undefPrint> |
| 833 | |
| 834 | Change the style of string dump. The default value for C<quote> |
| 835 | is C<auto>; one can enable double-quotish or single-quotish format |
| 836 | by setting it to C<"> or C<'>, respectively. By default, characters |
| 837 | with their high bit set are printed verbatim. |
| 838 | |
| 839 | =item C<UsageOnly> |
| 840 | X<debugger option, UsageOnly> |
| 841 | |
| 842 | Rudimentary per-package memory usage dump. Calculates total |
| 843 | size of strings found in variables in the package. This does not |
| 844 | include lexicals in a module's file scope, or lost in closures. |
| 845 | |
| 846 | =item C<HistFile> |
| 847 | X<debugger option, history, HistFile> |
| 848 | |
| 849 | The path of the file from which the history (assuming a usable |
| 850 | Term::ReadLine backend) will be read on the debugger's startup, and to which |
| 851 | it will be saved on shutdown (for persistence across sessions). Similar in |
| 852 | concept to Bash's C<.bash_history> file. |
| 853 | |
| 854 | =item C<HistSize> |
| 855 | X<debugger option, history, HistSize> |
| 856 | |
| 857 | The count of the saved lines in the history (assuming C<HistFile> above). |
| 858 | |
| 859 | =back |
| 860 | |
| 861 | After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}> |
| 862 | environment variable and parses this as the remainder of a "O ..." |
| 863 | line as one might enter at the debugger prompt. You may place the |
| 864 | initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop> |
| 865 | there. |
| 866 | |
| 867 | If your rc file contains: |
| 868 | |
| 869 | parse_options("NonStop=1 LineInfo=db.out AutoTrace"); |
| 870 | |
| 871 | then your script will run without human intervention, putting trace |
| 872 | information into the file I<db.out>. (If you interrupt it, you'd |
| 873 | better reset C<LineInfo> to F</dev/tty> if you expect to see anything.) |
| 874 | |
| 875 | =over 12 |
| 876 | |
| 877 | =item C<TTY> |
| 878 | X<debugger option, TTY> |
| 879 | |
| 880 | The TTY to use for debugging I/O. |
| 881 | |
| 882 | =item C<noTTY> |
| 883 | X<debugger option, noTTY> |
| 884 | |
| 885 | If set, the debugger goes into C<NonStop> mode and will not connect to a TTY. If |
| 886 | interrupted (or if control goes to the debugger via explicit setting of |
| 887 | $DB::signal or $DB::single from the Perl script), it connects to a TTY |
| 888 | specified in the C<TTY> option at startup, or to a tty found at |
| 889 | runtime using the C<Term::Rendezvous> module of your choice. |
| 890 | |
| 891 | This module should implement a method named C<new> that returns an object |
| 892 | with two methods: C<IN> and C<OUT>. These should return filehandles to use |
| 893 | for debugging input and output correspondingly. The C<new> method should |
| 894 | inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at |
| 895 | startup, or C<"$ENV{HOME}/.perldbtty$$"> otherwise. This file is not |
| 896 | inspected for proper ownership, so security hazards are theoretically |
| 897 | possible. |
| 898 | |
| 899 | =item C<ReadLine> |
| 900 | X<debugger option, ReadLine> |
| 901 | |
| 902 | If false, readline support in the debugger is disabled in order |
| 903 | to debug applications that themselves use ReadLine. |
| 904 | |
| 905 | =item C<NonStop> |
| 906 | X<debugger option, NonStop> |
| 907 | |
| 908 | If set, the debugger goes into non-interactive mode until interrupted, or |
| 909 | programmatically by setting $DB::signal or $DB::single. |
| 910 | |
| 911 | =back |
| 912 | |
| 913 | Here's an example of using the C<$ENV{PERLDB_OPTS}> variable: |
| 914 | |
| 915 | $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram |
| 916 | |
| 917 | That will run the script B<myprogram> without human intervention, |
| 918 | printing out the call tree with entry and exit points. Note that |
| 919 | C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally, |
| 920 | options could be uniquely abbreviated by the first letter (modulo |
| 921 | the C<Dump*> options). It is nevertheless recommended that you |
| 922 | always spell them out in full for legibility and future compatibility. |
| 923 | |
| 924 | Other examples include |
| 925 | |
| 926 | $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram |
| 927 | |
| 928 | which runs script non-interactively, printing info on each entry |
| 929 | into a subroutine and each executed line into the file named F<listing>. |
| 930 | (If you interrupt it, you would better reset C<LineInfo> to something |
| 931 | "interactive"!) |
| 932 | |
| 933 | Other examples include (using standard shell syntax to show environment |
| 934 | variable settings): |
| 935 | |
| 936 | $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out" |
| 937 | perl -d myprogram ) |
| 938 | |
| 939 | which may be useful for debugging a program that uses C<Term::ReadLine> |
| 940 | itself. Do not forget to detach your shell from the TTY in the window that |
| 941 | corresponds to F</dev/ttyXX>, say, by issuing a command like |
| 942 | |
| 943 | $ sleep 1000000 |
| 944 | |
| 945 | See L<perldebguts/"Debugger Internals"> for details. |
| 946 | |
| 947 | =head2 Debugger Input/Output |
| 948 | |
| 949 | =over 8 |
| 950 | |
| 951 | =item Prompt |
| 952 | |
| 953 | The debugger prompt is something like |
| 954 | |
| 955 | DB<8> |
| 956 | |
| 957 | or even |
| 958 | |
| 959 | DB<<17>> |
| 960 | |
| 961 | where that number is the command number, and which you'd use to |
| 962 | access with the built-in B<csh>-like history mechanism. For example, |
| 963 | C<!17> would repeat command number 17. The depth of the angle |
| 964 | brackets indicates the nesting depth of the debugger. You could |
| 965 | get more than one set of brackets, for example, if you'd already |
| 966 | at a breakpoint and then printed the result of a function call that |
| 967 | itself has a breakpoint, or you step into an expression via C<s/n/t |
| 968 | expression> command. |
| 969 | |
| 970 | =item Multiline commands |
| 971 | |
| 972 | If you want to enter a multi-line command, such as a subroutine |
| 973 | definition with several statements or a format, escape the newline |
| 974 | that would normally end the debugger command with a backslash. |
| 975 | Here's an example: |
| 976 | |
| 977 | DB<1> for (1..4) { \ |
| 978 | cont: print "ok\n"; \ |
| 979 | cont: } |
| 980 | ok |
| 981 | ok |
| 982 | ok |
| 983 | ok |
| 984 | |
| 985 | Note that this business of escaping a newline is specific to interactive |
| 986 | commands typed into the debugger. |
| 987 | |
| 988 | =item Stack backtrace |
| 989 | X<backtrace> X<stack, backtrace> |
| 990 | |
| 991 | Here's an example of what a stack backtrace via C<T> command might |
| 992 | look like: |
| 993 | |
| 994 | $ = main::infested called from file 'Ambulation.pm' line 10 |
| 995 | @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea' |
| 996 | line 7 |
| 997 | $ = main::pests('bactrian', 4) called from file 'camel_flea' |
| 998 | line 4 |
| 999 | |
| 1000 | The left-hand character up there indicates the context in which the |
| 1001 | function was called, with C<$> and C<@> meaning scalar or list |
| 1002 | contexts respectively, and C<.> meaning void context (which is |
| 1003 | actually a sort of scalar context). The display above says |
| 1004 | that you were in the function C<main::infested> when you ran the |
| 1005 | stack dump, and that it was called in scalar context from line |
| 1006 | 10 of the file I<Ambulation.pm>, but without any arguments at all, |
| 1007 | meaning it was called as C<&infested>. The next stack frame shows |
| 1008 | that the function C<Ambulation::legs> was called in list context |
| 1009 | from the I<camel_flea> file with four arguments. The last stack |
| 1010 | frame shows that C<main::pests> was called in scalar context, |
| 1011 | also from I<camel_flea>, but from line 4. |
| 1012 | |
| 1013 | If you execute the C<T> command from inside an active C<use> |
| 1014 | statement, the backtrace will contain both a C<require> frame and |
| 1015 | an C<eval> frame. |
| 1016 | |
| 1017 | =item Line Listing Format |
| 1018 | |
| 1019 | This shows the sorts of output the C<l> command can produce: |
| 1020 | |
| 1021 | DB<<13>> l |
| 1022 | 101: @i{@i} = (); |
| 1023 | 102:b @isa{@i,$pack} = () |
| 1024 | 103 if(exists $i{$prevpack} || exists $isa{$pack}); |
| 1025 | 104 } |
| 1026 | 105 |
| 1027 | 106 next |
| 1028 | 107==> if(exists $isa{$pack}); |
| 1029 | 108 |
| 1030 | 109:a if ($extra-- > 0) { |
| 1031 | 110: %isa = ($pack,1); |
| 1032 | |
| 1033 | Breakable lines are marked with C<:>. Lines with breakpoints are |
| 1034 | marked by C<b> and those with actions by C<a>. The line that's |
| 1035 | about to be executed is marked by C<< ==> >>. |
| 1036 | |
| 1037 | Please be aware that code in debugger listings may not look the same |
| 1038 | as your original source code. Line directives and external source |
| 1039 | filters can alter the code before Perl sees it, causing code to move |
| 1040 | from its original positions or take on entirely different forms. |
| 1041 | |
| 1042 | =item Frame listing |
| 1043 | |
| 1044 | When the C<frame> option is set, the debugger would print entered (and |
| 1045 | optionally exited) subroutines in different styles. See L<perldebguts> |
| 1046 | for incredibly long examples of these. |
| 1047 | |
| 1048 | =back |
| 1049 | |
| 1050 | =head2 Debugging Compile-Time Statements |
| 1051 | |
| 1052 | If you have compile-time executable statements (such as code within |
| 1053 | BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will |
| 1054 | I<not> be stopped by debugger, although C<require>s and INIT blocks |
| 1055 | will, and compile-time statements can be traced with the C<AutoTrace> |
| 1056 | option set in C<PERLDB_OPTS>). From your own Perl code, however, you |
| 1057 | can transfer control back to the debugger using the following |
| 1058 | statement, which is harmless if the debugger is not running: |
| 1059 | |
| 1060 | $DB::single = 1; |
| 1061 | |
| 1062 | If you set C<$DB::single> to 2, it's equivalent to having |
| 1063 | just typed the C<n> command, whereas a value of 1 means the C<s> |
| 1064 | command. The C<$DB::trace> variable should be set to 1 to simulate |
| 1065 | having typed the C<t> command. |
| 1066 | |
| 1067 | Another way to debug compile-time code is to start the debugger, set a |
| 1068 | breakpoint on the I<load> of some module: |
| 1069 | |
| 1070 | DB<7> b load f:/perllib/lib/Carp.pm |
| 1071 | Will stop on load of 'f:/perllib/lib/Carp.pm'. |
| 1072 | |
| 1073 | and then restart the debugger using the C<R> command (if possible). One can use C<b |
| 1074 | compile subname> for the same purpose. |
| 1075 | |
| 1076 | =head2 Debugger Customization |
| 1077 | |
| 1078 | The debugger probably contains enough configuration hooks that you |
| 1079 | won't ever have to modify it yourself. You may change the behaviour |
| 1080 | of the debugger from within the debugger using its C<o> command, from |
| 1081 | the command line via the C<PERLDB_OPTS> environment variable, and |
| 1082 | from customization files. |
| 1083 | |
| 1084 | You can do some customization by setting up a F<.perldb> file, which |
| 1085 | contains initialization code. For instance, you could make aliases |
| 1086 | like these (the last one is one people expect to be there): |
| 1087 | |
| 1088 | $DB::alias{'len'} = 's/^len(.*)/p length($1)/'; |
| 1089 | $DB::alias{'stop'} = 's/^stop (at|in)/b/'; |
| 1090 | $DB::alias{'ps'} = 's/^ps\b/p scalar /'; |
| 1091 | $DB::alias{'quit'} = 's/^quit(\s*)/exit/'; |
| 1092 | |
| 1093 | You can change options from F<.perldb> by using calls like this one; |
| 1094 | |
| 1095 | parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2"); |
| 1096 | |
| 1097 | The code is executed in the package C<DB>. Note that F<.perldb> is |
| 1098 | processed before processing C<PERLDB_OPTS>. If F<.perldb> defines the |
| 1099 | subroutine C<afterinit>, that function is called after debugger |
| 1100 | initialization ends. F<.perldb> may be contained in the current |
| 1101 | directory, or in the home directory. Because this file is sourced |
| 1102 | in by Perl and may contain arbitrary commands, for security reasons, |
| 1103 | it must be owned by the superuser or the current user, and writable |
| 1104 | by no one but its owner. |
| 1105 | |
| 1106 | You can mock TTY input to debugger by adding arbitrary commands to |
| 1107 | @DB::typeahead. For example, your F<.perldb> file might contain: |
| 1108 | |
| 1109 | sub afterinit { push @DB::typeahead, "b 4", "b 6"; } |
| 1110 | |
| 1111 | Which would attempt to set breakpoints on lines 4 and 6 immediately |
| 1112 | after debugger initialization. Note that @DB::typeahead is not a supported |
| 1113 | interface and is subject to change in future releases. |
| 1114 | |
| 1115 | If you want to modify the debugger, copy F<perl5db.pl> from the |
| 1116 | Perl library to another name and hack it to your heart's content. |
| 1117 | You'll then want to set your C<PERL5DB> environment variable to say |
| 1118 | something like this: |
| 1119 | |
| 1120 | BEGIN { require "myperl5db.pl" } |
| 1121 | |
| 1122 | As a last resort, you could also use C<PERL5DB> to customize the debugger |
| 1123 | by directly setting internal variables or calling debugger functions. |
| 1124 | |
| 1125 | Note that any variables and functions that are not documented in |
| 1126 | this document (or in L<perldebguts>) are considered for internal |
| 1127 | use only, and as such are subject to change without notice. |
| 1128 | |
| 1129 | =head2 Readline Support / History in the Debugger |
| 1130 | |
| 1131 | As shipped, the only command-line history supplied is a simplistic one |
| 1132 | that checks for leading exclamation points. However, if you install |
| 1133 | the Term::ReadKey and Term::ReadLine modules from CPAN (such as |
| 1134 | Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will |
| 1135 | have full editing capabilities much like those GNU I<readline>(3) provides. |
| 1136 | Look for these in the F<modules/by-module/Term> directory on CPAN. |
| 1137 | These do not support normal B<vi> command-line editing, however. |
| 1138 | |
| 1139 | A rudimentary command-line completion is also available, including |
| 1140 | lexical variables in the current scope if the C<PadWalker> module |
| 1141 | is installed. |
| 1142 | |
| 1143 | Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B", |
| 1144 | "^[[D"", "^H", ... when using the arrow keys and/or the backspace key. |
| 1145 | |
| 1146 | =head2 Editor Support for Debugging |
| 1147 | |
| 1148 | If you have the GNU's version of B<emacs> installed on your system, |
| 1149 | it can interact with the Perl debugger to provide an integrated |
| 1150 | software development environment reminiscent of its interactions |
| 1151 | with C debuggers. |
| 1152 | |
| 1153 | Recent versions of Emacs come with a |
| 1154 | start file for making B<emacs> act like a |
| 1155 | syntax-directed editor that understands (some of) Perl's syntax. |
| 1156 | See L<perlfaq3>. |
| 1157 | |
| 1158 | Users of B<vi> should also look into B<vim> and B<gvim>, the mousey |
| 1159 | and windy version, for coloring of Perl keywords. |
| 1160 | |
| 1161 | Note that only perl can truly parse Perl, so all such CASE tools |
| 1162 | fall somewhat short of the mark, especially if you don't program |
| 1163 | your Perl as a C programmer might. |
| 1164 | |
| 1165 | =head2 The Perl Profiler |
| 1166 | X<profile> X<profiling> X<profiler> |
| 1167 | |
| 1168 | If you wish to supply an alternative debugger for Perl to run, |
| 1169 | invoke your script with a colon and a package argument given to the |
| 1170 | B<-d> flag. Perl's alternative debuggers include a Perl profiler, |
| 1171 | L<Devel::NYTProf>, which is available separately as a CPAN |
| 1172 | distribution. To profile your Perl program in the file F<mycode.pl>, |
| 1173 | just type: |
| 1174 | |
| 1175 | $ perl -d:NYTProf mycode.pl |
| 1176 | |
| 1177 | When the script terminates the profiler will create a database of the |
| 1178 | profile information that you can turn into reports using the profiler's |
| 1179 | tools. See <perlperf> for details. |
| 1180 | |
| 1181 | =head1 Debugging Regular Expressions |
| 1182 | X<regular expression, debugging> |
| 1183 | X<regex, debugging> X<regexp, debugging> |
| 1184 | |
| 1185 | C<use re 'debug'> enables you to see the gory details of how the Perl |
| 1186 | regular expression engine works. In order to understand this typically |
| 1187 | voluminous output, one must not only have some idea about how regular |
| 1188 | expression matching works in general, but also know how Perl's regular |
| 1189 | expressions are internally compiled into an automaton. These matters |
| 1190 | are explored in some detail in |
| 1191 | L<perldebguts/"Debugging Regular Expressions">. |
| 1192 | |
| 1193 | =head1 Debugging Memory Usage |
| 1194 | X<memory usage> |
| 1195 | |
| 1196 | Perl contains internal support for reporting its own memory usage, |
| 1197 | but this is a fairly advanced concept that requires some understanding |
| 1198 | of how memory allocation works. |
| 1199 | See L<perldebguts/"Debugging Perl Memory Usage"> for the details. |
| 1200 | |
| 1201 | =head1 SEE ALSO |
| 1202 | |
| 1203 | You do have C<use strict> and C<use warnings> enabled, don't you? |
| 1204 | |
| 1205 | L<perldebtut>, |
| 1206 | L<perldebguts>, |
| 1207 | L<re>, |
| 1208 | L<DB>, |
| 1209 | L<Devel::NYTProf>, |
| 1210 | L<Dumpvalue>, |
| 1211 | and |
| 1212 | L<perlrun>. |
| 1213 | |
| 1214 | When debugging a script that uses #! and is thus normally found in |
| 1215 | $PATH, the -S option causes perl to search $PATH for it, so you don't |
| 1216 | have to type the path or C<which $scriptname>. |
| 1217 | |
| 1218 | $ perl -Sd foo.pl |
| 1219 | |
| 1220 | =head1 BUGS |
| 1221 | |
| 1222 | You cannot get stack frame information or in any fashion debug functions |
| 1223 | that were not compiled by Perl, such as those from C or C++ extensions. |
| 1224 | |
| 1225 | If you alter your @_ arguments in a subroutine (such as with C<shift> |
| 1226 | or C<pop>), the stack backtrace will not show the original values. |
| 1227 | |
| 1228 | The debugger does not currently work in conjunction with the B<-W> |
| 1229 | command-line switch, because it itself is not free of warnings. |
| 1230 | |
| 1231 | If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing |
| 1232 | from your keyboard or a socket) and haven't set up your own C<$SIG{INT}> |
| 1233 | handler, then you won't be able to CTRL-C your way back to the debugger, |
| 1234 | because the debugger's own C<$SIG{INT}> handler doesn't understand that |
| 1235 | it needs to raise an exception to longjmp(3) out of slow syscalls. |