home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / perl-5.003-base.tgz / perl-5.003-base.tar / fsf / perl / pod / perldebug.pod < prev    next >
Text File  |  1994-10-18  |  6KB  |  250 lines
  1. =head1 NAME
  2.  
  3. perldebug - Perl debugging
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. First of all, have you tried using the B<-w> switch?
  8.  
  9. =head2 Debugging
  10.  
  11. If you invoke Perl with a B<-d> switch, your script will be run under the
  12. debugger.  However, the Perl debugger is not a separate program as it is
  13. in a C environment.  Instead, the B<-d> flag tells the compiler to insert
  14. source information into the pseudocode it's about to hand to the
  15. interpreter.  (That means your code must compile correctly for the
  16. debugger to work on it.)  Then when the interpreter starts up, it
  17. pre-loads a Perl library file containing the debugger itself.  The program
  18. will halt before the first executable statement (but see below) and ask
  19. you for one of the following commands:
  20.  
  21. =over 12
  22.  
  23. =item h
  24.  
  25. Prints out a help message.
  26.  
  27. =item T
  28.  
  29. Stack trace.
  30. If you do bizarre things to your @_ arguments in a subroutine, the stack
  31. backtrace will not always show the original values.
  32.  
  33. =item s
  34.  
  35. Single step.  Executes until it reaches the beginning of another
  36. statement.
  37.  
  38. =item n
  39.  
  40. Next.  Executes over subroutine calls, until it reaches the beginning
  41. of the next statement.
  42.  
  43. =item f
  44.  
  45. Finish.  Executes statements until it has finished the current
  46. subroutine.
  47.  
  48. =item c
  49.  
  50. Continue.  Executes until the next breakpoint is reached.
  51.  
  52. =item c line
  53.  
  54. Continue to the specified line.  Inserts a one-time-only breakpoint at
  55. the specified line.
  56.  
  57. =item <CR>
  58.  
  59. Repeat last n or s.
  60.  
  61. =item l min+incr
  62.  
  63. List incr+1 lines starting at min.  If min is omitted, starts where
  64. last listing left off.  If incr is omitted, previous value of incr is
  65. used.
  66.  
  67. =item l min-max
  68.  
  69. List lines in the indicated range.
  70.  
  71. =item l line
  72.  
  73. List just the indicated line.
  74.  
  75. =item l
  76.  
  77. List next window.
  78.  
  79. =item -
  80.  
  81. List previous window.
  82.  
  83. =item w line
  84.  
  85. List window (a few lines worth of code) around line.
  86.  
  87. =item l subname
  88.  
  89. List subroutine.  If it's a long subroutine it just lists the
  90. beginning.  Use "l" to list more.
  91.  
  92. =item /pattern/
  93.  
  94. Regular expression search forward in the source code for pattern; the
  95. final / is optional.
  96.  
  97. =item ?pattern?
  98.  
  99. Regular expression search backward in the source code for pattern; the
  100. final ? is optional.
  101.  
  102. =item L
  103.  
  104. List lines that have breakpoints or actions.
  105.  
  106. =item S
  107.  
  108. Lists the names of all subroutines.
  109.  
  110. =item t
  111.  
  112. Toggle trace mode on or off.
  113.  
  114. =item b line [ condition ]
  115.  
  116. Set a breakpoint.  If line is omitted, sets a breakpoint on the line
  117. that is about to be executed.  If a condition is specified, it is
  118. evaluated each time the statement is reached and a breakpoint is taken
  119. only if the condition is true.  Breakpoints may only be set on lines
  120. that begin an executable statement.  Conditions don't use C<if>:
  121.  
  122.     b 237 $x > 30
  123.     b 33 /pattern/i
  124.  
  125. =item b subname [ condition ]
  126.  
  127. Set breakpoint at first executable line of subroutine.
  128.  
  129. =item d line
  130.  
  131. Delete breakpoint.  If line is omitted, deletes the breakpoint on the
  132. line that is about to be executed.
  133.  
  134. =item D
  135.  
  136. Delete all breakpoints.
  137.  
  138. =item a line command
  139.  
  140. Set an action for line.  A multiline command may be entered by
  141. backslashing the newlines.  This command is Perl code, not another
  142. debugger command.
  143.  
  144. =item A
  145.  
  146. Delete all line actions.
  147.  
  148. =item < command
  149.  
  150. Set an action to happen before every debugger prompt.  A multiline
  151. command may be entered by backslashing the newlines.
  152.  
  153. =item > command
  154.  
  155. Set an action to happen after the prompt when you've just given a
  156. command to return to executing the script.  A multiline command may be
  157. entered by backslashing the newlines.
  158.  
  159. =item V package [symbols]
  160.  
  161. Display all (or some) variables in package (defaulting to the C<main>
  162. package) using a data pretty-printer (hashes show their keys and values so
  163. you see what's what, control characters are made printable, etc.).  Make
  164. sure you don't put the type specifier (like $) there, just the symbol
  165. names, like this:
  166.  
  167.     V DB filename line 
  168.  
  169. =item X [symbols] 
  170.  
  171. Same as as "V" command, but within the current package.  
  172.  
  173. =item ! number
  174.  
  175. Redo a debugging command.  If number is omitted, redoes the previous
  176. command.
  177.  
  178. =item ! -number
  179.  
  180. Redo the command that was that many commands ago.
  181.  
  182. =item H -number
  183.  
  184. Display last n commands.  Only commands longer than one character are
  185. listed.  If number is omitted, lists them all.
  186.  
  187. =item q or ^D
  188.  
  189. Quit.  ("quit" doesn't work for this.)
  190.  
  191. =item command
  192.  
  193. Execute command as a Perl statement.  A missing semicolon will be
  194. supplied.
  195.  
  196. =item p expr
  197.  
  198. Same as C<print DB::OUT expr>.  The DB::OUT filehandle is opened to
  199. /dev/tty, regardless of where STDOUT may be redirected to.
  200.  
  201. =back
  202.  
  203. Any command you type in that isn't recognized by the debugger will be
  204. directly executed (C<eval>'d) as Perl code.  Leading white space will
  205. cause the debugger to think it's C<NOT> a debugger command.
  206.  
  207. If you have any compile-time executable statements (code within a BEGIN 
  208. block or a C<use> statement), these will I<NOT> be stopped by debugger,
  209. although C<require>s will.  From your own code, however, you can transfer
  210. control back to the debugger using the following statement, which is harmless
  211. if the debugger is not running:
  212.  
  213.     $DB::single = 1;
  214.  
  215. =head2 Customization
  216.  
  217. If you want to modify the debugger, copy F<perl5db.pl> from the Perl
  218. library to another name and modify it as necessary.  You'll also want
  219. to set environment variable PERL5DB to say something like this:
  220.  
  221.     BEGIN { require "myperl5db.pl" }
  222.  
  223. You can do some customization by setting up a F<.perldb> file which
  224. contains initialization code.  For instance, you could make aliases
  225. like these (the last one in particular most people seem to expect to 
  226. be there):
  227.  
  228.     $DB::alias{'len'} = 's/^len(.*)/p length($1)/';
  229.     $DB::alias{'stop'} = 's/^stop (at|in)/b/';
  230.     $DB::alias{'.'} = 's/^\./p '
  231.             . '"\$DB::sub(\$DB::filename:\$DB::line):\t"'
  232.             . ',\$DB::dbline[\$DB::line]/' ;
  233.  
  234.  
  235. =head2 Other resources
  236.  
  237. You did try the B<-w> switch, didn't you?
  238.  
  239. =head1 BUGS
  240.  
  241. If your program exit()s or die()s, so does the debugger.
  242.  
  243. There's no builtin way to restart the debugger without exiting and coming back
  244. into it.  You could use an alias like this:
  245.  
  246.     $DB::alias{'rerun'} = 'exec "perl -d $DB::filename"';
  247.  
  248. But you'd lose any pending breakpoint information, and that might not
  249. be the right path, etc.
  250.