Commit | Line | Data |
a0d0e21e |
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. |