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 First of all, there's a few things you can do to make your life a lot more
20 straightforward when it comes to debugging perl programs, without using the
21 debugger at all. To demonstrate, here's a simple script, named "hello", with
26 $var1 = 'Hello World'; # always wanted to do that :-)
32 While this compiles and runs happily, it probably won't do what's expected,
33 namely it doesn't print "Hello World\n" at all; It will on the other hand do
34 exactly what it was told to do, computers being a bit that way inclined. That
35 is, it will print out a newline character, and you'll get what looks like a
36 blank line. It looks like there's 2 variables when (because of the typo)
39 $var1 = 'Hello World';
43 To catch this kind of problem, we can force each variable to be declared
44 before use by pulling in the strict module, by putting 'use strict;' after the
45 first line of the script.
47 Now when you run it, perl complains about the 3 undeclared variables and we
48 get four error messages because one variable is referenced twice:
50 Global symbol "$var1" requires explicit package name at ./t1 line 4.
51 Global symbol "$var2" requires explicit package name at ./t1 line 5.
52 Global symbol "$varl" requires explicit package name at ./t1 line 5.
53 Global symbol "$var2" requires explicit package name at ./t1 line 7.
54 Execution of ./hello aborted due to compilation errors.
56 Luvverly! and to fix this we declare all variables explicitly and now our
57 script looks like this:
62 my $var1 = 'Hello World';
69 We then do (always a good idea) a syntax check before we try to run it again:
74 And now when we run it, we get "\n" still, but at least we know why. Just
75 getting this script to compile has exposed the '$varl' (with the letter 'l')
76 variable, and simply changing $varl to $var1 solves the problem.
79 =head1 Looking at data and -w and v
81 Ok, but how about when you want to really see your data, what's in that
82 dynamic variable, just before using it?
90 'tom' => qw(and jerry),
91 'welcome' => q(Hello World),
94 my @data = keys %data;
96 print "$data{$key}\n";
99 Looks OK, after it's been through the syntax check (perl -c scriptname), we
100 run it and all we get is a blank line again! Hmmmm.
102 One common debugging approach here, would be to liberally sprinkle a few print
103 statements, to add a check just before we print out our data, and another just
106 print "All OK\n" if grep($key, keys %data);
107 print "$data{$key}\n";
108 print "done: '$data{$key}'\n";
117 After much staring at the same piece of code and not seeing the wood for the
118 trees for some time, we get a cup of coffee and try another approach. That
119 is, we bring in the cavalry by giving perl the 'B<-d>' switch on the command
123 Default die handler restored.
125 Loading DB routines from perl5db.pl version 1.07
126 Editor support available.
128 Enter h or `h h' for help, or `man perldebug' for more help.
130 main::(./data:4): my $key = 'welcome';
132 Now, what we've done here is to launch the built-in perl debugger on our
133 script. It's stopped at the first line of executable code and is waiting for
136 Before we go any further, you'll want to know how to quit the debugger: use
137 just the letter 'B<q>', not the words 'quit' or 'exit':
142 That's it, you're back on home turf again.
147 Fire the debugger up again on your script and we'll look at the help menu.
148 There's a couple of ways of calling help: a simple 'B<h>' will get the summary
149 help list, 'B<|h>' (pipe-h) will pipe the help through your pager (which is
150 (probably 'more' or 'less'), and finally, 'B<h h>' (h-space-h) will give you
151 the entire help screen. Here is the summary page:
155 List/search source lines: Control script execution:
156 l [ln|sub] List source code T Stack trace
157 - or . List previous/current line s [expr] Single step
159 v [line] View around line n [expr] Next, steps over
161 f filename View source in file <CR/Enter> Repeat last n or s
162 /pattern/ ?patt? Search forw/backw r Return from
164 M Show module versions c [ln|sub] Continue until
166 Debugger controls: L List break/watch/
168 o [...] Set debugger options t [expr] Toggle trace
170 <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set
172 ! [N|pat] Redo a previous command B ln|* Delete a/all
174 H [-num] Display last num commands a [ln] cmd Do cmd before line
175 = [a val] Define/list an alias A ln|* Delete a/all
177 h [db_cmd] Get help on command w expr Add a watch
179 h h Complete help page W expr|* Delete a/all watch
181 |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a
183 q or ^D Quit R Attempt a restart
184 Data Examination: expr Execute perl code, also see: s,n,t expr
185 x|m expr Evals expr in list context, dumps the result or lists
187 p expr Print expression (uses script's current package).
188 S [[!]pat] List subroutine names [not] matching pattern
189 V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or
191 X [Vars] Same as "V current_package [Vars]".
192 y [n [Vars]] List lexicals in higher scope <n>. Vars same as V.
193 For more help, type h cmd_letter, or run man perldebug for all docs.
195 More confusing options than you can shake a big stick at! It's not as bad as
196 it looks and it's very useful to know more about all of it, and fun too!
198 There's a couple of useful ones to know about straight away. You wouldn't
199 think we're using any libraries at all at the moment, but 'B<M>' will show
200 which modules are currently loaded, and their version number, while 'B<m>'
201 will show the methods, and 'B<S>' shows all subroutines (by pattern) as
202 shown below. 'B<V>' and 'B<X>' show variables in the program by package
203 scope and can be constrained by pattern.
211 Using 'X' and cousins requires you not to use the type identifiers ($@%), just
215 FileHandle(stderr) => fileno(2)
217 Remember we're in our tiny program with a problem, we should have a look at
218 where we are, and what our data looks like. First of all let's view some code
219 at our present position (the first line of code in this case), via 'B<v>':
225 4==> my $key = 'welcome';
227 6 'this' => qw(that),
228 7 'tom' => qw(and jerry),
229 8 'welcome' => q(Hello World),
230 9 'zip' => q(welcome),
233 At line number 4 is a helpful pointer, that tells you where you are now. To
234 see more code, type 'v' again:
237 8 'welcome' => q(Hello World),
238 9 'zip' => q(welcome),
240 11: my @data = keys %data;
241 12: print "All OK\n" if grep($key, keys %data);
242 13: print "$data{$key}\n";
243 14: print "done: '$data{$key}'\n";
246 And if you wanted to list line 5 again, type 'l 5', (note the space):
251 In this case, there's not much to see, but of course normally there's pages of
252 stuff to wade through, and 'l' can be very useful. To reset your view to the
253 line we're about to execute, type a lone period '.':
256 main::(./data_a:4): my $key = 'welcome';
258 The line shown is the one that is about to be executed B<next>, it hasn't
259 happened yet. So while we can print a variable with the letter 'B<p>', at
260 this point all we'd get is an empty (undefined) value back. What we need to
261 do is to step through the next executable statement with an 'B<s>':
264 main::(./data_a:5): my %data = (
265 main::(./data_a:6): 'this' => qw(that),
266 main::(./data_a:7): 'tom' => qw(and jerry),
267 main::(./data_a:8): 'welcome' => q(Hello World),
268 main::(./data_a:9): 'zip' => q(welcome),
269 main::(./data_a:10): );
271 Now we can have a look at that first ($key) variable:
276 line 13 is where the action is, so let's continue down to there via the letter
277 'B<c>', which by the way, inserts a 'one-time-only' breakpoint at the given
282 main::(./data_a:13): print "$data{$key}\n";
284 We've gone past our check (where 'All OK' was printed) and have stopped just
285 before the meat of our task. We could try to print out a couple of variables
286 to see what is happening:
290 Not much in there, lets have a look at our hash:
293 Hello Worldziptomandwelcomejerrywelcomethisthat
296 Hello Worldtomwelcomejerrythis
298 Well, this isn't very easy to read, and using the helpful manual (B<h h>), the
299 'B<x>' command looks promising:
313 That's not much help, a couple of welcomes in there, but no indication of
314 which are keys, and which are values, it's just a listed array dump and, in
315 this case, not particularly helpful. The trick here, is to use a B<reference>
316 to the data structure:
320 'Hello World' => 'zip'
326 The reference is truly dumped and we can finally see what we're dealing with.
327 Our quoting was perfectly valid but wrong for our purposes, with 'and jerry'
328 being treated as 2 separate words rather than a phrase, thus throwing the
329 evenly paired hash structure out of alignment.
331 The 'B<-w>' switch would have told us about this, had we used it at the start,
332 and saved us a lot of trouble:
335 Odd number of elements in hash assignment at ./data line 5.
337 We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get
344 While we're here, take a closer look at the 'B<x>' command, it's really useful
345 and will merrily dump out nested references, complete objects, partial objects
346 - just about whatever you throw at it:
348 Let's make a quick object and x-plode it, first we'll start the debugger:
349 it wants some form of input from STDIN, so we give it something non-committal,
353 Default die handler restored.
355 Loading DB routines from perl5db.pl version 1.07
356 Editor support available.
358 Enter h or `h h' for help, or `man perldebug' for more help.
362 Now build an on-the-fly object over a couple of lines (note the backslash):
364 DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
365 cont: {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
367 And let's have a look at it:
370 0 MY_class=HASH(0x828ad98)
371 'attr' => HASH(0x828ad68)
373 'things' => ARRAY(0x828abb8)
380 Useful, huh? You can eval nearly anything in there, and experiment with bits
381 of code or regexes until the cows come home:
383 DB<3> @data = qw(this that the other atheism leather theory scythe)
385 DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
394 If you want to see the command History, type an 'B<H>':
397 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
398 3: @data = qw(this that the other atheism leather theory scythe)
400 1: $obj = bless({'unique_id'=>'123', 'attr'=>
401 {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
404 And if you want to repeat any previous command, use the exclamation: 'B<!>':
407 p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
416 For more on references see L<perlref> and L<perlreftut>
419 =head1 Stepping through code
421 Here's a simple program which converts between Celsius and Fahrenheit, it too
427 my $arg = $ARGV[0] || '-c20';
429 if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
430 my ($deg, $num) = ($1, $2);
431 my ($in, $out) = ($num, $num);
439 $out = sprintf('%0.2f', $out);
440 $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
443 print "Usage: $0 -[c|f] num\n";
449 my $c = 5 * $f - 32 / 9;
455 my $f = 9 * $c / 5 + 32;
460 For some reason, the Fahrenheit to Celsius conversion fails to return the
461 expected output. This is what it does:
469 Not very consistent! We'll set a breakpoint in the code manually and run it
470 under the debugger to see what's going on. A breakpoint is a flag, to which
471 the debugger will run without interruption, when it reaches the breakpoint, it
472 will stop execution and offer a prompt for further interaction. In normal
473 use, these debugger commands are completely ignored, and they are safe - if a
474 little messy, to leave in production code.
476 my ($in, $out) = ($num, $num);
477 $DB::single=2; # insert at line 9!
481 > perl -d temp -f33.3
482 Default die handler restored.
484 Loading DB routines from perl5db.pl version 1.07
485 Editor support available.
487 Enter h or `h h' for help, or `man perldebug' for more help.
489 main::(temp:4): my $arg = $ARGV[0] || '-c100';
491 We'll simply continue down to our pre-set breakpoint with a 'B<c>':
494 main::(temp:10): if ($deg eq 'c') {
496 Followed by a view command to see where we are:
499 7: my ($deg, $num) = ($1, $2);
500 8: my ($in, $out) = ($num, $num);
502 10==> if ($deg eq 'c') {
504 12: $out = &c2f($num);
507 15: $out = &f2c($num);
510 And a print to show what values we're currently using:
515 We can put another break point on any line beginning with a colon, we'll use
516 line 17 as that's just as we come out of the subroutine, and we'd like to
517 pause there later on:
521 There's no feedback from this, but you can see what breakpoints are set by
522 using the list 'L' command:
526 17: print "$out $deg\n";
529 Note that to delete a breakpoint you use 'B'.
531 Now we'll continue down into our subroutine, this time rather than by line
532 number, we'll use the subroutine name, followed by the now familiar 'v':
535 main::f2c(temp:30): my $f = shift;
542 28: my $c = 5 * $f - 32 / 9;
550 Note that if there was a subroutine call between us and line 29, and we wanted
551 to B<single-step> through it, we could use the 'B<s>' command, and to step
552 over it we would use 'B<n>' which would execute the sub, but not descend into
553 it for inspection. In this case though, we simply continue down to line 29:
556 main::f2c(temp:29): return $c;
558 And have a look at the return value:
563 This is not the right answer at all, but the sum looks correct. I wonder if
564 it's anything to do with operator precedence? We'll try a couple of other
565 possibilities with our sum:
567 DB<6> p (5 * $f - 32 / 9)
570 DB<7> p 5 * $f - (32 / 9)
573 DB<8> p (5 * $f) - 32 / 9
576 DB<9> p 5 * ($f - 32) / 9
579 :-) that's more like it! Ok, now we can set our return variable and we'll
580 return out of the sub with an 'r':
582 DB<10> $c = 5 * ($f - 32) / 9
585 scalar context return from main::f2c: 0.722222222222221
587 Looks good, let's just continue off the end of the script:
591 Debugged program terminated. Use q to quit or R to restart,
592 use O inhibit_exit to avoid stopping after program termination,
593 h q, h R or h O to get additional info.
595 A quick fix to the offending line (insert the missing parentheses) in the
596 actual program and we're finished.
599 =head1 Placeholder for a, w, t, T
601 Actions, watch variables, stack traces etc.: on the TODO list.
612 =head1 REGULAR EXPRESSIONS
614 Ever wanted to know what a regex looked like? You'll need perl compiled with
615 the DEBUGGING flag for this one:
617 > perl -Dr -e '/^pe(a)*rl$/i'
618 Compiling REx `^pe(a)*rl$'
624 4: CURLYN[1] {0,32767}(14)
632 floating `'$ at 4..2147483647 (checking floating) stclass
633 `EXACTF <pe>' anchored(BOL) minlen 4
634 Omitting $` $& $' support.
638 Freeing REx: `^pe(a)*rl$'
640 Did you really want to know? :-)
641 For more gory details on getting regular expressions to work, have a look at
642 L<perlre>, L<perlretut>, and to decode the mysterious labels (BOL and CURLYN,
643 etc. above), see L<perldebguts>.
648 To get all the output from your error log, and not miss any messages via
649 helpful operating system buffering, insert a line like this, at the start of
654 To watch the tail of a dynamically growing logfile, (from the command line):
658 Wrapping all die calls in a handler routine can be useful to see how, and from
659 where, they're being called, L<perlvar> has more information:
661 BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
663 Various useful techniques for the redirection of STDOUT and STDERR filehandles
664 are explained in L<perlopentut> and L<perlfaq8>.
669 Just a quick hint here for all those CGI programmers who can't figure out how
670 on earth to get past that 'waiting for input' prompt, when running their CGI
671 script from the command-line, try something like this:
673 > perl -d my_cgi.pl -nodebug
675 Of course L<CGI> and L<perlfaq9> will tell you more.
680 The command line interface is tightly integrated with an B<emacs> extension
681 and there's a B<vi> interface too.
683 You don't have to do this all on the command line, though, there are a few GUI
684 options out there. The nice thing about these is you can wave a mouse over a
685 variable and a dump of its data will appear in an appropriate window, or in a
686 popup balloon, no more tiresome typing of 'x $varname' :-)
688 In particular have a hunt around for the following:
690 B<ptkdb> perlTK based wrapper for the built-in debugger
692 B<ddd> data display debugger
694 B<PerlDevKit> and B<PerlBuilder> are NT specific
696 NB. (more info on these and others would be appreciated).
701 We've seen how to encourage good coding practices with B<use strict> and
702 B<-w>. We can run the perl debugger B<perl -d scriptname> to inspect your
703 data from within the perl debugger with the B<p> and B<x> commands. You can
704 walk through your code, set breakpoints with B<b> and step through that code
705 with B<s> or B<n>, continue with B<c> and return from a sub with B<r>. Fairly
706 intuitive stuff when you get down to it.
708 There is of course lots more to find out about, this has just scratched the
709 surface. The best way to learn more is to use perldoc to find out more about
710 the language, to read the on-line help (L<perldebug> is probably the next
711 place to go), and of course, experiment.
724 Richard Foley <richard.foley@rfi.net> Copyright (c) 2000
729 Various people have made helpful suggestions and contributions, in particular:
731 Ronald J Kimball <rjk@linguist.dartmouth.edu>
733 Hugo van der Sanden <hv@crypt0.demon.co.uk>
735 Peter Scott <Peter@PSDT.com>