1N/Aperldebtut - Perl debugging tutorial
1N/AA (very) lightweight introduction in the use of the perl debugger, and a
1N/Apointer to existing, deeper sources of information on the subject of debugging
1N/AThere's an extraordinary number of people out there who don't appear to know
1N/Aanything about using the perl debugger, though they use the language every
1N/AFirst of all, there's a few things you can do to make your life a lot more
1N/Astraightforward when it comes to debugging perl programs, without using the
1N/Adebugger at all. To demonstrate, here's a simple script, named "hello", with
1N/A $var1 = 'Hello World'; # always wanted to do that :-)
1N/AWhile this compiles and runs happily, it probably won't do what's expected,
1N/Anamely it doesn't print "Hello World\n" at all; It will on the other hand do
1N/Aexactly what it was told to do, computers being a bit that way inclined. That
1N/Ais, it will print out a newline character, and you'll get what looks like a
1N/Ablank line. It looks like there's 2 variables when (because of the typo)
1N/A $var1 = 'Hello World';
1N/ATo catch this kind of problem, we can force each variable to be declared
1N/Abefore use by pulling in the strict module, by putting 'use strict;' after the
1N/Afirst line of the script.
1N/ANow when you run it, perl complains about the 3 undeclared variables and we
1N/Aget four error messages because one variable is referenced twice:
1N/A Global symbol "$var1" requires explicit package name at ./t1 line 4.
1N/A Global symbol "$var2" requires explicit package name at ./t1 line 5.
1N/A Global symbol "$varl" requires explicit package name at ./t1 line 5.
1N/A Global symbol "$var2" requires explicit package name at ./t1 line 7.
1N/A Execution of ./hello aborted due to compilation errors.
1N/ALuvverly! and to fix this we declare all variables explicitly and now our
1N/Ascript looks like this:
1N/A my $var1 = 'Hello World';
1N/A my $var2 = "$varl\n";
1N/AWe then do (always a good idea) a syntax check before we try to run it again:
1N/AAnd now when we run it, we get "\n" still, but at least we know why. Just
1N/Agetting this script to compile has exposed the '$varl' (with the letter 'l')
1N/Avariable, and simply changing $varl to $var1 solves the problem.
1N/A=head1 Looking at data and -w and v
1N/AOk, but how about when you want to really see your data, what's in that
1N/Adynamic variable, just before using it?
1N/A my $key = 'welcome';
1N/A 'tom' => qw(and jerry),
1N/A 'welcome' => q(Hello World),
1N/A 'zip' => q(welcome),
1N/A my @data = keys %data;
1N/A print "$data{$key}\n";
1N/ALooks OK, after it's been through the syntax check (perl -c scriptname), we
1N/Arun it and all we get is a blank line again! Hmmmm.
1N/AOne common debugging approach here, would be to liberally sprinkle a few print
1N/Astatements, to add a check just before we print out our data, and another just
1N/A print "All OK\n" if grep($key, keys %data);
1N/A print "$data{$key}\n";
1N/A print "done: '$data{$key}'\n";
1N/AAfter much staring at the same piece of code and not seeing the wood for the
1N/Atrees for some time, we get a cup of coffee and try another approach. That
1N/Ais, we bring in the cavalry by giving perl the 'B<-d>' switch on the command
1N/A Default die handler restored.
1N/A Editor support available.
1N/A Enter h or `h h' for help, or `man perldebug' for more help.
1N/A main::(./data:4): my $key = 'welcome';
1N/ANow, what we've done here is to launch the built-in perl debugger on our
1N/Ascript. It's stopped at the first line of executable code and is waiting for
1N/ABefore we go any further, you'll want to know how to quit the debugger: use
1N/Ajust the letter 'B<q>', not the words 'quit' or 'exit':
1N/AThat's it, you're back on home turf again.
1N/AFire the debugger up again on your script and we'll look at the help menu.
1N/AThere's a couple of ways of calling help: a simple 'B<h>' will get the summary
1N/Ahelp list, 'B<|h>' (pipe-h) will pipe the help through your pager (which is
1N/A(probably 'more' or 'less'), and finally, 'B<h h>' (h-space-h) will give you
1N/Athe entire help screen. Here is the summary page:
1N/A l [ln|sub] List source code T Stack trace
1N/A v [line] View around line n [expr] Next, steps over subs
1N/A f filename View source in file <
CR/Enter> Repeat last n or s
1N/A M Show module versions c [ln|sub] Continue until position
1N/A o [...] Set debugger options t [expr] Toggle trace [trace expr]
1N/A ! [N|pat] Redo a previous command B ln|* Delete
a/all breakpoints
1N/A H [-num] Display last num commands a [ln] cmd Do cmd before line
1N/A h [db_cmd] Get help on command w expr Add a watch expression
1N/A h h Complete help page W expr|* Delete
a/all watch exprs
1N/A |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess
1N/A q or ^D Quit R Attempt a restart
1N/A Data Examination: expr Execute perl code, also see: s,n,t expr
1N/A x|m expr Evals expr in list context, dumps the result or lists methods.
1N/A p expr Print expression (uses script's current package).
1N/A S [[!]pat] List subroutine names [not] matching pattern
1N/A V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern.
1N/A X [Vars] Same as "V current_package [Vars]".
1N/A y [n [Vars]] List lexicals in higher scope <n>. Vars same as V.
1N/A For more help, type h cmd_letter, or run man perldebug for all docs.
1N/AMore confusing options than you can shake a big stick at! It's not as bad as
1N/Ait looks and it's very useful to know more about all of it, and fun too!
1N/AThere's a couple of useful ones to know about straight away. You wouldn't
1N/Athink we're using any libraries at all at the moment, but 'B<M>' will show
1N/Awhich modules are currently loaded, and their version number, while 'B<m>'
1N/Awill show the methods, and 'B<S>' shows all subroutines (by pattern) as
1N/Ashown below. 'B<V>' and 'B<X>' show variables in the program by package
1N/Ascope and can be constrained by pattern.
1N/AUsing 'X' and cousins requires you not to use the type identifiers ($@%), just
1N/A FileHandle(stderr) => fileno(2)
1N/ARemember we're in our tiny program with a problem, we should have a look at
1N/Awhere we are, and what our data looks like. First of all let's view some code
1N/Aat our present position (the first line of code in this case), via 'B<v>':
1N/A 4==> my $key = 'welcome';
1N/A 6 'this' => qw(that),
1N/A 7 'tom' => qw(and jerry),
1N/A 8 'welcome' => q(Hello World),
1N/A 9 'zip' => q(welcome),
1N/AAt line number 4 is a helpful pointer, that tells you where you are now. To
1N/Asee more code, type 'v' again:
1N/A 8 'welcome' => q(Hello World),
1N/A 9 'zip' => q(welcome),
1N/A 11: my @data = keys %data;
1N/A 12: print "All OK\n" if grep($key, keys %data);
1N/A 13: print "$data{$key}\n";
1N/A 14: print "done: '$data{$key}'\n";
1N/AAnd if you wanted to list line 5 again, type 'l 5', (note the space):
1N/AIn this case, there's not much to see, but of course normally there's pages of
1N/Astuff to wade through, and 'l' can be very useful. To reset your view to the
1N/Aline we're about to execute, type a lone period '.':
1N/A main::(./data_a:4): my $key = 'welcome';
1N/AThe line shown is the one that is about to be executed B<next>, it hasn't
1N/Ahappened yet. So while we can print a variable with the letter 'B<p>', at
1N/Athis point all we'd get is an empty (undefined) value back. What we need to
1N/Ado is to step through the next executable statement with an 'B<s>':
1N/A main::(./data_a:5): my %data = (
1N/A main::(./data_a:6): 'this' => qw(that),
1N/A main::(./data_a:7): 'tom' => qw(and jerry),
1N/A main::(./data_a:8): 'welcome' => q(Hello World),
1N/A main::(./data_a:9): 'zip' => q(welcome),
1N/A main::(./data_a:10): );
1N/ANow we can have a look at that first ($key) variable:
1N/Aline 13 is where the action is, so let's continue down to there via the letter
1N/A'B<c>', which by the way, inserts a 'one-time-only' breakpoint at the given
1N/A main::(./data_a:13): print "$data{$key}\n";
1N/AWe've gone past our check (where 'All OK' was printed) and have stopped just
1N/Abefore the meat of our task. We could try to print out a couple of variables
1N/Ato see what is happening:
1N/ANot much in there, lets have a look at our hash:
1N/A Hello Worldziptomandwelcomejerrywelcomethisthat
1N/A Hello Worldtomwelcomejerrythis
1N/AWell, this isn't very easy to read, and using the helpful manual (B<h h>), the
1N/A'B<x>' command looks promising:
1N/AThat's not much help, a couple of welcomes in there, but no indication of
1N/Awhich are keys, and which are values, it's just a listed array dump and, in
1N/Athis case, not particularly helpful. The trick here, is to use a B<reference>
1N/Ato the data structure:
1N/A 'Hello World' => 'zip'
1N/A 'jerry' => 'welcome'
1N/AThe reference is truly dumped and we can finally see what we're dealing with.
1N/AOur quoting was perfectly valid but wrong for our purposes, with 'and jerry'
1N/Abeing treated as 2 separate words rather than a phrase, thus throwing the
1N/Aevenly paired hash structure out of alignment.
1N/AThe 'B<-w>' switch would have told us about this, had we used it at the start,
1N/Aand saved us a lot of trouble:
1N/A Odd number of elements in hash assignment at ./data line 5.
1N/AWe fix our quoting: 'tom' => q(and jerry), and run it again, this time we get
1N/AWhile we're here, take a closer look at the 'B<x>' command, it's really useful
1N/Aand will merrily dump out nested references, complete objects, partial objects
1N/A- just about whatever you throw at it:
1N/ALet's make a quick object and x-plode it, first we'll start the debugger:
1N/Ait wants some form of input from STDIN, so we give it something non-commital,
1N/A Default die handler restored.
1N/A Editor support available.
1N/A Enter h or `h h' for help, or `man perldebug' for more help.
1N/ANow build an on-the-fly object over a couple of lines (note the backslash):
1N/A DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
1N/A cont: {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
1N/AAnd let's have a look at it:
1N/A 0 MY_class=HASH(0x828ad98)
1N/A 'attr' => HASH(0x828ad68)
1N/A 'things' => ARRAY(0x828abb8)
1N/AUseful, huh? You can eval nearly anything in there, and experiment with bits
1N/Aof code or regexes until the cows come home:
1N/A DB<3> @data = qw(this that the other atheism leather theory scythe)
1N/A DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
1N/AIf you want to see the command History, type an 'B<H>':
1N/A 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
1N/A 3: @data = qw(this that the other atheism leather theory scythe)
1N/A 1: $obj = bless({'unique_id'=>'123', 'attr'=>
1N/A {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
1N/AAnd if you want to repeat any previous command, use the exclamation: 'B<!>':
1N/A p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
1N/AFor more on references see L<perlref> and L<perlreftut>
1N/A=head1 Stepping through code
1N/AHere's a simple program which converts between Celsius and Fahrenheit, it too
1N/A my $arg = $ARGV[0] || '-c20';
1N/A if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
1N/A my ($deg, $num) = ($1, $2);
1N/A my ($in, $out) = ($num, $num);
1N/A $out = sprintf('%0.2f', $out);
1N/A $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
1N/A print "$out $deg\n";
1N/A print "Usage: $0 -[c|f] num\n";
1N/A my $c = 5 * $f - 32 / 9;
1N/A my $f = 9 * $c / 5 + 32;
1N/AFor some reason, the Fahrenheit to Celsius conversion fails to return the
1N/Aexpected output. This is what it does:
1N/ANot very consistent! We'll set a breakpoint in the code manually and run it
1N/Aunder the debugger to see what's going on. A breakpoint is a flag, to which
1N/Athe debugger will run without interruption, when it reaches the breakpoint, it
1N/Awill stop execution and offer a prompt for further interaction. In normal
1N/Ause, these debugger commands are completely ignored, and they are safe - if a
1N/Alittle messy, to leave in production code.
1N/A my ($in, $out) = ($num, $num);
1N/A $DB::single=2; # insert at line 9!
1N/A > perl -d temp -f33.3
1N/A Default die handler restored.
1N/A Editor support available.
1N/A Enter h or `h h' for help, or `man perldebug' for more help.
1N/A main::(temp:4): my $arg = $ARGV[0] || '-c100';
1N/AWe'll simply continue down to our pre-set breakpoint with a 'B<c>':
1N/A main::(temp:10): if ($deg eq 'c') {
1N/AFollowed by a view command to see where we are:
1N/A 7: my ($deg, $num) = ($1, $2);
1N/A 8: my ($in, $out) = ($num, $num);
1N/A 10==> if ($deg eq 'c') {
1N/A 12: $out = &c2f($num);
1N/A 15: $out = &f2c($num);
1N/AAnd a print to show what values we're currently using:
1N/AWe can put another break point on any line beginning with a colon, we'll use
1N/Aline 17 as that's just as we come out of the subroutine, and we'd like to
1N/Apause there later on:
1N/AThere's no feedback from this, but you can see what breakpoints are set by
1N/Ausing the list 'L' command:
1N/A 17: print "$out $deg\n";
1N/ANote that to delete a breakpoint you use 'd' or 'D'.
1N/ANow we'll continue down into our subroutine, this time rather than by line
1N/Anumber, we'll use the subroutine name, followed by the now familiar 'v':
1N/A main::f2c(temp:30): my $f = shift;
1N/A 27==> my $f = shift;
1N/A 28: my $c = 5 * $f - 32 / 9;
1N/ANote that if there was a subroutine call between us and line 29, and we wanted
1N/Ato B<single-step> through it, we could use the 'B<s>' command, and to step
1N/Aover it we would use 'B<n>' which would execute the sub, but not descend into
1N/Ait for inspection. In this case though, we simply continue down to line 29:
1N/A main::f2c(temp:29): return $c;
1N/AAnd have a look at the return value:
1N/AThis is not the right answer at all, but the sum looks correct. I wonder if
1N/Ait's anything to do with operator precedence? We'll try a couple of other
1N/Apossibilities with our sum:
1N/A DB<6> p (5 * $f - 32 / 9)
1N/A DB<7> p 5 * $f - (32 / 9)
1N/A DB<8> p (5 * $f) - 32 / 9
1N/A DB<9> p 5 * ($f - 32) / 9
1N/A:-) that's more like it! Ok, now we can set our return variable and we'll
1N/Areturn out of the sub with an 'r':
1N/A DB<10> $c = 5 * ($f - 32) / 9
1N/A scalar context return from main::f2c: 0.722222222222221
1N/ALooks good, let's just continue off the end of the script:
1N/A Debugged program terminated. Use q to quit or R to restart,
1N/A use O inhibit_exit to avoid stopping after program termination,
1N/A h q, h R or h O to get additional info.
1N/AA quick fix to the offending line (insert the missing parentheses) in the
1N/Aactual program and we're finished.
1N/A=head1 Placeholder for a, w, t, T
1N/AActions, watch variables, stack traces etc.: on the TODO list.
1N/A=head1 REGULAR EXPRESSIONS
1N/AEver wanted to know what a regex looked like? You'll need perl compiled with
1N/Athe DEBUGGING flag for this one:
1N/A > perl -Dr -e '/^pe(a)*rl$/i'
1N/A Compiling REx `^pe(a)*rl$'
1N/A 4: CURLYN[1] {0,32767}(14)
1N/A floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
1N/Aanchored(BOL) minlen 4
1N/A Omitting $` $& $' support.
1N/A Freeing REx: `^pe(a)*rl$'
1N/ADid you really want to know? :-)
1N/AFor more gory details on getting regular expressions to work, have a look at
1N/AL<perlre>, L<perlretut>, and to decode the mysterious labels (BOL and CURLYN,
1N/Aetc. above), see L<perldebguts>.
1N/ATo get all the output from your error log, and not miss any messages via
1N/Ahelpful operating system buffering, insert a line like this, at the start of
1N/ATo watch the tail of a dynamically growing logfile, (from the command line):
1N/AWrapping all die calls in a handler routine can be useful to see how, and from
1N/Awhere, they're being called, L<perlvar> has more information:
1N/A BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
1N/AVarious useful techniques for the redirection of STDOUT and STDERR filehandles
1N/Aare explained in L<perlopentut> and L<perlfaq8>.
1N/AJust a quick hint here for all those CGI programmers who can't figure out how
1N/Aon earth to get past that 'waiting for input' prompt, when running their CGI
1N/Ascript from the command-line, try something like this:
1N/AOf course L<CGI> and L<perlfaq9> will tell you more.
1N/AThe command line interface is tightly integrated with an B<emacs> extension
1N/Aand there's a B<vi> interface too.
1N/AYou don't have to do this all on the command line, though, there are a few GUI
1N/Aoptions out there. The nice thing about these is you can wave a mouse over a
1N/Avariable and a dump of its data will appear in an appropriate window, or in a
1N/Apopup balloon, no more tiresome typing of 'x $varname' :-)
1N/AIn particular have a hunt around for the following:
1N/AB<ptkdb> perlTK based wrapper for the built-in debugger
1N/AB<ddd> data display debugger
1N/AB<PerlDevKit> and B<PerlBuilder> are NT specific
1N/ANB. (more info on these and others would be appreciated).
1N/AWe've seen how to encourage good coding practices with B<use strict> and
1N/AB<-w>. We can run the perl debugger B<perl -d scriptname> to inspect your
1N/Adata from within the perl debugger with the B<p> and B<x> commands. You can
1N/Awalk through your code, set breakpoints with B<b> and step through that code
1N/Awith B<s> or B<n>, continue with B<c> and return from a sub with B<r>. Fairly
1N/Aintuitive stuff when you get down to it.
1N/AThere is of course lots more to find out about, this has just scratched the
1N/Asurface. The best way to learn more is to use perldoc to find out more about
1N/Athe language, to read the on-line help (L<perldebug> is probably the next
1N/Aplace to go), and of course, experiment.
1N/ARichard Foley <richard@rfi.net> Copyright (c) 2000
1N/AVarious people have made helpful suggestions and contributions, in particular:
1N/ARonald J Kimball <rjk@linguist.dartmouth.edu>
1N/AHugo van der Sanden <hv@crypt0.demon.co.uk>
1N/APeter Scott <Peter@PSDT.com>