3 perldebtut - Perl debugging tutorial
7 A (very) lightweight introduction in the use of the perl debugger, and a
8 pointer to existing, deeper sources of information on the subject of debugging
11 There's an extraordinary number of people out there who don't appear to know
12 anything about using the perl debugger, though they use the language every
19 There's a few things you can do to make your life a lot more straightforward
20 when it comes to debugging perl programs. To demonstrate, here's a simple
21 script with a problem:
25 $var1 = 'Hello World'; # always wanted to do that :-)
31 While this compiles and runs happily, it probably won't do what's expected,
32 namely it doesn't print "Hello World\n" at all; It will on the other hand do
33 exactly what it was told to do, computers being a bit that way inclined. That
34 is, it will print out a newline character, and you'll get what looks like a
35 blank line. It looks like there's 2 variables when (because of the typo)
42 To catch this kind of problem, we can force each variable to be declared
43 before use by pulling in the strict module, by putting 'use strict;' after the
44 first line of the script.
46 Now when you run it, perl complains about the 3 undeclared variables and we
47 get four error messages because one variable is referenced twice:
49 Global symbol "$var1" requires explicit package name at ./t1 line 4.
50 Global symbol "$var2" requires explicit package name at ./t1 line 5.
51 Global symbol "$varl" requires explicit package name at ./t1 line 5.
52 Global symbol "$var2" requires explicit package name at ./t1 line 7.
53 Execution of ./t1 aborted due to compilation errors.
55 Luvverly! and to fix this we declare all variables explicitly and now our
56 script looks like this:
61 my $var1 = 'Hello World';
68 We then do (always a good idea) a syntax check before we try to run it again:
73 And now when we run it, we get "\n" still, but at least we know why. Just
74 getting this script to compile has exposed the '$varl' (with the letter 'l)
75 variable, and simply changing $varl to $var1 solves the problem.
78 =head1 Looking at data and -w
80 Ok, but how about when you want to really see your data, what's in that
81 dynamic variable, just before using it?
89 'tom' => qw(and jerry),
90 'welcome' => q(Hello World),
93 my @data = keys %data;
95 print "$data{$key}\n";
98 Looks OK, after it's been through the syntax check (perl -c scriptname), we
99 run it and all we get is a blank line again! Hmmmm.
101 One common debugging approach here, would be to liberally sprinkle a few print
102 statements, to add a check just before we print out our data, and another just
105 print "All OK\n" if grep($key, keys %data);
106 print "$data{$key}\n";
107 print "done: '$data{$key}'\n";
116 After much staring at the same piece of code and not seeing the wood for the
117 trees for some time, we get a cup of coffee and try another approach. That
118 is, we bring in the cavalry by giving perl the C<-d> switch on the command
122 Default die handler restored.
124 Loading DB routines from perl5db.pl version 1.07
125 Editor support available.
127 Enter h or `h h' for help, or `man perldebug' for more help.
129 main::(./data:4): my $key = 'welcome';
131 Now, what we've done here is to launch the built-in perl debugger on our
132 script. It's stopped at the first line of executable code and is waiting for
135 Before we go any further, you'll want to know how to quit the debugger: use
136 just the letter 'q', not the words 'quit' or 'exit':
141 That's it, you're back on home turf again.
143 Fire the debugger up again on your script and we'll look at the help menu.
144 There's a couple of ways of calling help: a simple 'h' will get you a long
145 scrolled list of help, '|h' (pipe-h) will pipe the help through your pager
146 ('more' or 'less' probably), and finally, 'h h' (h-space-h) will give you a
147 helpful mini-screen snapshot:
150 List/search source lines: Control script execution:
151 l [ln|sub] List source code T Stack trace
152 - or . List previous/current line s [expr] Single step [in expr]
153 w [line] List around line n [expr] Next, steps over subs
154 f filename View source in file <CR/Enter> Repeat last n or s
155 /pattern/ ?patt? Search forw/backw r Return from subroutine
156 v Show versions of modules c [ln|sub] Continue until position
157 Debugger controls: L List
159 O [...] Set debugger options t [expr] Toggle trace [trace expr]
160 <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
161 ! [N|pat] Redo a previous command d [ln] or D Delete a/all breakpoints
162 H [-num] Display last num commands a [ln] cmd Do cmd before line
163 = [a val] Define/list an alias W expr Add a watch expression
164 h [db_cmd] Get help on command A or W Delete all actions/watch
165 |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess
166 q or ^D Quit R Attempt a restart
167 Data Examination: expr Execute perl code, also see: s,n,t expr
168 x|m expr Evals expr in array context, dumps the result or lists methods.
169 p expr Print expression (uses script's current package).
170 S [[!]pat] List subroutine names [not] matching pattern
171 V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern.
172 X [Vars] Same as "V current_package [Vars]".
173 For more help, type h cmd_letter, or run man perldebug for all docs.
175 More confusing options than you can shake a big stick at! It's not as bad as
176 it looks and it's very useful to know more about all of it, and fun too!
178 There's a couple of useful ones to know about straight away:
179 You wouldn't think we're using any libraries at all at the moment, but 'v'
180 will show which modules are currently loaded, by the debugger as well your
181 script. 'V' and 'X' show variables in the program by package scope and can be
182 constrained by pattern. 'S' shows all subroutines (by pattern):
190 Remember we're in our tiny program with a problem, we want to have a look at
191 where we are, and what our data looks like. First of all let's have a window
192 on our present position (the first line of code), via the letter 'w':
198 4==> my $key = 'welcome';
200 6 'this' => qw(that),
201 7 'tom' => qw(and jerry),
202 8 'welcome' => q(Hello World),
203 9 'zip' => q(welcome),
206 At line number 4 is a helpful pointer, that tells you where you are now. To
207 see more code, type 'w' again:
210 8 'welcome' => q(Hello World),
211 9 'zip' => q(welcome),
213 11: my @data = keys %data;
214 12: print "All OK\n" if grep($key, keys %data);
215 13: print "$data{$key}\n";
216 14: print "done: '$data{$key}'\n";
219 And if you wanted to list line 5 again, type 'l 5', note the space:
224 In this case, there's not much to see, but of course normally there's pages of
225 stuff to wade through. To reset your view to the line we're about to execute,
226 type a lone period '.':
229 main::(./data_a:4): my $key = 'welcome';
231 The line shown is the one that is about to be executed B<next>, it hasn't
232 happened yet. So while we can print a variable with the letter 'p', at this
233 point all we'd get is an empty (undefined) value back. What we need to do is
234 to step to the next executable statement with an 's':
237 main::(./data_a:5): my %data = (
238 main::(./data_a:6): 'this' => qw(that),
239 main::(./data_a:7): 'tom' => qw(and jerry),
240 main::(./data_a:8): 'welcome' => q(Hello World),
241 main::(./data_a:9): 'zip' => q(welcome),
242 main::(./data_a:10): );
244 Now we can have a look at that first ($key) variable:
249 line 13 is where the action is, so let's continue down to there via the letter
254 main::(./data_a:13): print "$data{$key}\n";
256 We've gone past our check (where 'All OK' was printed) and have stopped just
257 before the meat of our task. We could try to print out a couple of variables
258 to see what is happening:
265 Hello Worldziptomandwelcomejerrywelcomethisthat
268 Hello Worldtomwelcomejerrythis
270 Reading the helpful manual (h h), the 'x' command looks promising:
284 That's not much help, a couple of welcome's in there, but no indication of
285 which are keys, and which are values, it's just a straight array dump and, in
286 this case, not particularly helpful. The trick here, is to use a B<reference>
287 to the data structure:
291 'Hello World' => 'zip'
297 The reference is truly dumped and we can finally see what we're dealing with.
298 Our quoting was perfectly valid but wrong for our purposes, with 'and jerry'
299 being treated as 2 separate words rather than a phrase, thus throwing the
300 evenly paired hash structure out of alignment.
302 The '-w' switch would have told us about this, had we used it at the start,
303 and saved us a lot of trouble:
306 Odd number of elements in hash assignment at ./data line 5.
308 We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get
315 While we're here, take a closer look at the 'x' command, it's really useful
316 and will merrily dump out nested references, complete objects, partial objects
317 - justabout whatever you throw at it:
319 Let's make a quick object and x-plode it, first we'll start the the debugger:
320 it wants some form of input from STDIN, so we give it something non-commital,
324 Default die handler restored.
326 Loading DB routines from perl5db.pl version 1.07
327 Editor support available.
329 Enter h or `h h' for help, or `man perldebug' for more help.
333 Now build an on-the-fly object over a couple of lines (note the backslash):
335 DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
336 cont: {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
338 And let's have a look at it:
341 0 MY_class=HASH(0x828ad98)
342 'attr' => HASH(0x828ad68)
344 'things' => ARRAY(0x828abb8)
351 Useful, huh? You can eval nearly anything in there, and experiment with bits
352 of code or regexes until the cows come home:
354 DB<3> @data = qw(this that the other atheism leather theory scythe)
356 DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
365 If you want to see all the command history, an 'H':
368 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
369 3: @data = qw(this that the other atheism leather theory scythe)
371 1: $obj = bless({'unique_id'=>'123', 'attr'=>
372 {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
375 And if you want to repeat any previous command, use the exclamation: '!':
378 p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
388 =head1 Stepping through code
390 Here's a simple program which converts between celsius and farenheit, it too
396 my $arg = $ARGV[0] || '-c20';
398 if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
399 my ($deg, $num) = ($1, $2);
400 my ($in, $out) = ($num, $num);
408 $out = sprintf('%0.2f', $out);
409 $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
412 print "Usage: $0 -[c|f] num\n";
418 my $c = 5 * $f - 32 / 9;
424 my $f = 9 * $c / 5 + 32;
429 For some reason, the farenheit to celsius conversion fails to return the
430 expected output. This is what it does:
438 Not very consistent! We'll set a breakpoint in the code manually and run it
439 under the debugger to see what's going on. A breakpoint is a flag, to which
440 the debugger will run without interuption, when it reaches the breakpoint, it
441 will stop execution and offer a prompt for further interaction. In normal
442 use, these debugger commands are completely ignored, and they are safe - if a
443 little messy, to leave in production code.
445 my ($in, $out) = ($num, $num);
446 $DB::single=2; # insert at line 9!
450 > perl -d temp -f33.3
451 Default die handler restored.
453 Loading DB routines from perl5db.pl version 1.07
454 Editor support available.
456 Enter h or `h h' for help, or `man perldebug' for more help.
458 main::(temp:4): my $arg = $ARGV[0] || '-c100';
460 We'll simply continue down to our pre-set breakpoint with a 'c':
463 main::(temp:10): if ($deg eq 'c') {
465 Followed by a window command to see where we are:
468 7: my ($deg, $num) = ($1, $2);
469 8: my ($in, $out) = ($num, $num);
471 10==> if ($deg eq 'c') {
473 12: $out = &c2f($num);
476 15: $out = &f2c($num);
479 And a print to show what values we're currently using:
484 We can put another break point on any line beginning with a colon, we'll use
485 line 17 as that's just as we come out of the subroutine, and we'd like to
486 pause there later on:
490 There's no feedback from this, but you can see what breakpoints are set by
491 using the list 'L' command:
495 17: print "$out $deg\n";
498 Note that to delete a breakpoint you use 'd' or 'D'.
500 Now we'll continue down into our subroutine, this time rather than by line
501 number, we'll use the subroutine name, followed by the now familiar 'w':
504 main::f2c(temp:30): my $f = shift;
511 31: my $c = 5 * $f - 32 / 9;
517 Note that if there was a subroutine call between us and line 32, and we didn't
518 want to single-step through it, we could use the next command 'n', which would
519 execute the sub, but not descend into it for inspection. In this case though,
520 we simply single step down to line 32:
523 main::f2c(temp:28): return $c;
525 And have a look at the return value:
530 This is not the right answer at all, but the sum looks correct. I wonder if
531 it's anything to do with operator precedence? We'll try a couple of other
532 possibilities with our sum:
534 DB<10> p (5 * $f - 32 / 9)
537 DB<11> p 5 * $f - (32 / 9)
540 DB<12> p (5 * $f) - 32 / 9
543 DB<13> p 5 * ($f - 32) / 9
546 :-) that's more like it! Ok, now we can set our return variable and we'll
547 return out of the sub with an 'r':
549 DB<14> $c = 5 * ($f - 32) / 9
552 scalar context return from main::f2c: 0.722222222222221
554 Looks good, let's just continue off the end of the script:
558 Debugged program terminated. Use q to quit or R to restart,
559 use O inhibit_exit to avoid stopping after program termination,
560 h q, h R or h O to get additional info.
562 A quick fix to the offending line (insert the missing parentheses) in the
563 actual program and we're finished.
566 =head1 Placeholder for a, w, t, T
568 Actions, watch variables, stack traces on the TODO list.
579 =head1 Regular expressions
581 Ever wanted to know what a regex looked like? You'll need perl compiled with
582 the DEBUGGING flag for this one:
584 > perl -Dr -e '/^pe(a)*rl$/i'
585 Compiling REx `^pe(a)*rl$'
591 4: CURLYN[1] {0,32767}(14)
599 floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
600 anchored(BOL) minlen 4
601 Omitting $` $& $' support.
605 Freeing REx: `^pe(a)*rl$'
607 Did you really want to know? :-)
610 =head1 Some ideas for output
612 To get all the output from your error log, and not miss any messages via
613 helpful operating system buffering, insert a line like this, at the start of
618 To watch the tail of a dynamically growing logfile, (from the command line):
622 Wrapping all die calls in a handler routine can be useful to see how, and from
623 where, they're being called, L<perlvar> has more information:
625 BEGIN { $SIG{__DIE__} = sub { use Carp; Carp::confess(@_) } }
627 Various useful techniques for the redirection of STDOUT and STDERR filehandles
628 are explained in L<perlfunc> and L<perlopentut> and L<perlfaq8>
633 Just a hint here for all those CGI programmers who can't figure out how on
634 earth to get past that 'waiting for input' prompt, try something like this:
636 > perl -d my_cgi.pl -nodebug
638 Of course 'L<perldoc CGI>' and L<perlfaq9> will tell you more.
643 The command line interface is tightly integrated with an B<emacs> extension
644 and there's a B<vi> interface too.
646 You don't have to do this all on the command line, though, there are a few GUI
647 options out there. The nice thing about these is you can wave a mouse over a
648 variable and a dump of it's data will appear in an appropriate window, or in a
649 popup balloon, no more tiresome typing of 'x $varname' :-)
651 In particular have a hunt around for the following:
653 B<ptkdb> perlTK based wrapper for the built-in debugger
655 B<ddd> data display debugger
657 B<PerlDevKit> and B<PerlBuilder> are NT specific
659 NB. (more info on these and others would be appreciated).
664 We've seen how to encourage good coding practices with B<use strict> and
665 B<-w>. We can run the perl debugger B<perl -d scriptname> to inspect your
666 data from within the perl debugger with the B<p> and B<x> commands. You can
667 walk through your code, set breakpoints with B<b> and step through that code
668 with B<s> or B<n>, continue with B<c> and return from a sub with B<r>. Fairly
669 intuitive stuff when you get down to it.
671 There is of course lots more to find out about, this has just scratched the
672 surface. The best way to learn more is to use perldoc to find out more about
673 the language, to read the on-line help (L<perldebug> is probably the next
674 place to go), and of course, experiment.
688 Richard Foley <richard@rfi.net> Copyright (c) 2000
693 Various people have made helpful suggestions and contributions, in particular:
695 Ronald J Kimball <rjk@linguist.dartmouth.edu>
697 Hugo <hv@crypt.compulink.co.uk>