A (very) lightweight introduction in the use of the perl debugger, and a
pointer to existing, deeper sources of information on the subject of debugging
-perl programs.
+perl programs.
There's an extraordinary number of people out there who don't appear to know
anything about using the perl debugger, though they use the language every
=head1 use strict
-There's a few things you can do to make your life a lot more straightforward
-when it comes to debugging perl programs. To demonstrate, here's a simple
-script with a problem:
+First of all, there's a few things you can do to make your life a lot more
+straightforward when it comes to debugging perl programs, without using the
+debugger at all. To demonstrate, here's a simple script, named "hello", with
+a problem:
#!/usr/bin/perl
-
+
$var1 = 'Hello World'; # always wanted to do that :-)
$var2 = "$varl\n";
-
+
print $var2;
exit;
blank line. It looks like there's 2 variables when (because of the typo)
there's really 3:
- $var1 = 'Hello World'
- $varl = undef
- $var2 = "\n"
+ $var1 = 'Hello World';
+ $varl = undef;
+ $var2 = "\n";
To catch this kind of problem, we can force each variable to be declared
before use by pulling in the strict module, by putting 'use strict;' after the
Now when you run it, perl complains about the 3 undeclared variables and we
get four error messages because one variable is referenced twice:
-
+
Global symbol "$var1" requires explicit package name at ./t1 line 4.
Global symbol "$var2" requires explicit package name at ./t1 line 5.
Global symbol "$varl" requires explicit package name at ./t1 line 5.
Global symbol "$var2" requires explicit package name at ./t1 line 7.
- Execution of ./t1 aborted due to compilation errors.
+ Execution of ./hello aborted due to compilation errors.
Luvverly! and to fix this we declare all variables explicitly and now our
script looks like this:
#!/usr/bin/perl
use strict;
-
+
my $var1 = 'Hello World';
- my $varl = '';
+ my $varl = undef;
my $var2 = "$varl\n";
-
+
print $var2;
exit;
hello syntax OK
And now when we run it, we get "\n" still, but at least we know why. Just
-getting this script to compile has exposed the '$varl' (with the letter 'l)
+getting this script to compile has exposed the '$varl' (with the letter 'l')
variable, and simply changing $varl to $var1 solves the problem.
-=head1 Looking at data and -w
+=head1 Looking at data and -w and v
Ok, but how about when you want to really see your data, what's in that
dynamic variable, just before using it?
Looks OK, after it's been through the syntax check (perl -c scriptname), we
run it and all we get is a blank line again! Hmmmm.
-
+
One common debugging approach here, would be to liberally sprinkle a few print
statements, to add a check just before we print out our data, and another just
after:
print "done: '$data{$key}'\n";
And try again:
-
+
> perl data
All OK
-
+
done: ''
After much staring at the same piece of code and not seeing the wood for the
trees for some time, we get a cup of coffee and try another approach. That
-is, we bring in the cavalry by giving perl the C<-d> switch on the command
+is, we bring in the cavalry by giving perl the 'B<-d>' switch on the command
line:
> perl -d data
input.
Before we go any further, you'll want to know how to quit the debugger: use
-just the letter 'q', not the words 'quit' or 'exit':
+just the letter 'B<q>', not the words 'quit' or 'exit':
DB<1> q
>
-
+
That's it, you're back on home turf again.
+
+=head1 help
+
Fire the debugger up again on your script and we'll look at the help menu.
-There's a couple of ways of calling help: a simple 'h' will get you a long
-scrolled list of help, '|h' (pipe-h) will pipe the help through your pager
-('more' or 'less' probably), and finally, 'h h' (h-space-h) will give you a
-helpful mini-screen snapshot:
-
- DB<1> h h
- List/search source lines: Control script execution:
- l [ln|sub] List source code T Stack trace
- - or . List previous/current line s [expr] Single step [in expr]
- w [line] List around line n [expr] Next, steps over subs
- f filename View source in file <CR/Enter> Repeat last n or s
- /pattern/ ?patt? Search forw/backw r Return from subroutine
- v Show versions of modules c [ln|sub] Continue until position
- Debugger controls: L List
-break/watch/actions
- O [...] Set debugger options t [expr] Toggle trace [trace expr]
- <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
- ! [N|pat] Redo a previous command d [ln] or D Delete a/all breakpoints
- H [-num] Display last num commands a [ln] cmd Do cmd before line
- = [a val] Define/list an alias W expr Add a watch expression
- h [db_cmd] Get help on command A or W Delete all actions/watch
- |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess
- q or ^D Quit R Attempt a restart
- Data Examination: expr Execute perl code, also see: s,n,t expr
- x|m expr Evals expr in array context, dumps the result or lists methods.
- p expr Print expression (uses script's current package).
- S [[!]pat] List subroutine names [not] matching pattern
- V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern.
- X [Vars] Same as "V current_package [Vars]".
- For more help, type h cmd_letter, or run man perldebug for all docs.
-
+There's a couple of ways of calling help: a simple 'B<h>' will get the summary
+help list, 'B<|h>' (pipe-h) will pipe the help through your pager (which is
+(probably 'more' or 'less'), and finally, 'B<h h>' (h-space-h) will give you
+the entire help screen. Here is the summary page:
+
+DB<1>h
+
+ List/search source lines: Control script execution:
+ l [ln|sub] List source code T Stack trace
+ - or . List previous/current line s [expr] Single step [in expr]
+ v [line] View around line n [expr] Next, steps over subs
+ f filename View source in file <CR/Enter> Repeat last n or s
+ /pattern/ ?patt? Search forw/backw r Return from subroutine
+ M Show module versions c [ln|sub] Continue until position
+ Debugger controls: L List break/watch/actions
+ o [...] Set debugger options t [expr] Toggle trace [trace expr]
+ <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
+ ! [N|pat] Redo a previous command B ln|* Delete a/all breakpoints
+ H [-num] Display last num commands a [ln] cmd Do cmd before line
+ = [a val] Define/list an alias A ln|* Delete a/all actions
+ h [db_cmd] Get help on command w expr Add a watch expression
+ h h Complete help page W expr|* Delete a/all watch exprs
+ |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess
+ q or ^D Quit R Attempt a restart
+ Data Examination: expr Execute perl code, also see: s,n,t expr
+ x|m expr Evals expr in list context, dumps the result or lists methods.
+ p expr Print expression (uses script's current package).
+ S [[!]pat] List subroutine names [not] matching pattern
+ V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern.
+ X [Vars] Same as "V current_package [Vars]".
+ y [n [Vars]] List lexicals in higher scope <n>. Vars same as V.
+ For more help, type h cmd_letter, or run man perldebug for all docs.
+
More confusing options than you can shake a big stick at! It's not as bad as
it looks and it's very useful to know more about all of it, and fun too!
-There's a couple of useful ones to know about straight away:
-You wouldn't think we're using any libraries at all at the moment, but 'v'
-will show which modules are currently loaded, by the debugger as well your
-script. 'V' and 'X' show variables in the program by package scope and can be
-constrained by pattern. 'S' shows all subroutines (by pattern):
+There's a couple of useful ones to know about straight away. You wouldn't
+think we're using any libraries at all at the moment, but 'B<M>' will show
+which modules are currently loaded, and their version number, while 'B<m>'
+will show the methods, and 'B<S>' shows all subroutines (by pattern) as
+shown below. 'B<V>' and 'B<X>' show variables in the program by package
+scope and can be constrained by pattern.
DB<2>S str
dumpvar::stringify
strict::bits
strict::import
strict::unimport
-
-Remember we're in our tiny program with a problem, we want to have a look at
-where we are, and what our data looks like. First of all let's have a window
-on our present position (the first line of code), via the letter 'w':
- DB<3> w
+Using 'X' and cousins requires you not to use the type identifiers ($@%), just
+the 'name':
+
+ DM<3>X ~err
+ FileHandle(stderr) => fileno(2)
+
+Remember we're in our tiny program with a problem, we should have a look at
+where we are, and what our data looks like. First of all let's view some code
+at our present position (the first line of code in this case), via 'B<v>':
+
+ DB<4> v
1 #!/usr/bin/perl
2: use strict;
3
10 );
At line number 4 is a helpful pointer, that tells you where you are now. To
-see more code, type 'w' again:
-
- DB<3> w
+see more code, type 'v' again:
+
+ DB<4> v
8 'welcome' => q(Hello World),
9 'zip' => q(welcome),
10 );
14: print "done: '$data{$key}'\n";
15: exit;
-And if you wanted to list line 5 again, type 'l 5', note the space:
+And if you wanted to list line 5 again, type 'l 5', (note the space):
DB<4> l 5
5: my %data = (
-
+
In this case, there's not much to see, but of course normally there's pages of
-stuff to wade through. To reset your view to the line we're about to execute,
-type a lone period '.':
+stuff to wade through, and 'l' can be very useful. To reset your view to the
+line we're about to execute, type a lone period '.':
- DB<6> .
+ DB<5> .
main::(./data_a:4): my $key = 'welcome';
-
+
The line shown is the one that is about to be executed B<next>, it hasn't
-happened yet. So while we can print a variable with the letter 'p', at this
-point all we'd get is an empty (undefined) value back. What we need to do is
-to step to the next executable statement with an 's':
-
+happened yet. So while we can print a variable with the letter 'B<p>', at
+this point all we'd get is an empty (undefined) value back. What we need to
+do is to step through the next executable statement with an 'B<s>':
+
DB<6> s
main::(./data_a:5): my %data = (
main::(./data_a:6): 'this' => qw(that),
welcome
line 13 is where the action is, so let's continue down to there via the letter
-'c':
+'B<c>', which by the way, inserts a 'one-time-only' breakpoint at the given
+line or sub routine:
DB<8> c 13
All OK
main::(./data_a:13): print "$data{$key}\n";
-
+
We've gone past our check (where 'All OK' was printed) and have stopped just
before the meat of our task. We could try to print out a couple of variables
to see what is happening:
DB<9> p $data{$key}
-
-Nothing!
-
+
+Not much in there, lets have a look at our hash:
+
DB<10> p %data
Hello Worldziptomandwelcomejerrywelcomethisthat
DB<11> p keys %data
Hello Worldtomwelcomejerrythis
-
-Reading the helpful manual (h h), the 'x' command looks promising:
+
+Well, this isn't very easy to read, and using the helpful manual (B<h h>), the
+'B<x>' command looks promising:
DB<12> x %data
0 'Hello World'
8 'this'
9 'that'
-That's not much help, a couple of welcome's in there, but no indication of
-which are keys, and which are values, it's just a straight array dump and, in
+That's not much help, a couple of welcomes in there, but no indication of
+which are keys, and which are values, it's just a listed array dump and, in
this case, not particularly helpful. The trick here, is to use a B<reference>
to the data structure:
being treated as 2 separate words rather than a phrase, thus throwing the
evenly paired hash structure out of alignment.
-The '-w' switch would have told us about this, had we used it at the start,
+The 'B<-w>' switch would have told us about this, had we used it at the start,
and saved us a lot of trouble:
> perl -w data
Hello World
-While we're here, take a closer look at the 'x' command, it's really useful
+While we're here, take a closer look at the 'B<x>' command, it's really useful
and will merrily dump out nested references, complete objects, partial objects
-- justabout whatever you throw at it:
+- just about whatever you throw at it:
-Let's make a quick object and x-plode it, first we'll start the the debugger:
-it wants some form of input from STDIN, so we give it something non-commital,
+Let's make a quick object and x-plode it, first we'll start the debugger:
+it wants some form of input from STDIN, so we give it something non-committal,
a zero:
> perl -de 0
cont: {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
And let's have a look at it:
-
+
DB<2> x $obj
0 MY_class=HASH(0x828ad98)
'attr' => HASH(0x828ad68)
of code or regexes until the cows come home:
DB<3> @data = qw(this that the other atheism leather theory scythe)
-
+
DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
atheism
leather
theory
saw -> 6
-If you want to see all the command history, an 'H':
+If you want to see the command History, type an 'B<H>':
DB<5> H
4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
1: $obj = bless({'unique_id'=>'123', 'attr'=>
{'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
DB<5>
-
-And if you want to repeat any previous command, use the exclamation: '!':
+
+And if you want to repeat any previous command, use the exclamation: 'B<!>':
DB<5> !4
p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
theory
saw -> 12
+For more on references see L<perlref> and L<perlreftut>
+
=head1 Stepping through code
-Here's a simple program which converts between celsius and farenheit, it too
+Here's a simple program which converts between Celsius and Fahrenheit, it too
has a problem:
#!/usr/bin/perl -w
}
-For some reason, the farenheit to celsius conversion fails to return the
+For some reason, the Fahrenheit to Celsius conversion fails to return the
expected output. This is what it does:
> temp -c0.72
33.30 f
-
+
> temp -f33.3
162.94 c
-
+
Not very consistent! We'll set a breakpoint in the code manually and run it
under the debugger to see what's going on. A breakpoint is a flag, to which
-the debugger will run without interuption, when it reaches the breakpoint, it
+the debugger will run without interruption, when it reaches the breakpoint, it
will stop execution and offer a prompt for further interaction. In normal
use, these debugger commands are completely ignored, and they are safe - if a
little messy, to leave in production code.
-
+
my ($in, $out) = ($num, $num);
$DB::single=2; # insert at line 9!
if ($deg eq 'c')
...
-
+
> perl -d temp -f33.3
Default die handler restored.
main::(temp:4): my $arg = $ARGV[0] || '-c100';
-We'll simply continue down to our pre-set breakpoint with a 'c':
+We'll simply continue down to our pre-set breakpoint with a 'B<c>':
DB<1> c
main::(temp:10): if ($deg eq 'c') {
-Followed by a window command to see where we are:
-
- DB<2> w
+Followed by a view command to see where we are:
+
+ DB<1> v
7: my ($deg, $num) = ($1, $2);
8: my ($in, $out) = ($num, $num);
9: $DB::single=2;
And a print to show what values we're currently using:
- DB<3> p $deg, $num
+ DB<1> p $deg, $num
f33.3
-
+
We can put another break point on any line beginning with a colon, we'll use
line 17 as that's just as we come out of the subroutine, and we'd like to
pause there later on:
-
- DB<4> b 17
-
+
+ DB<2> b 17
+
There's no feedback from this, but you can see what breakpoints are set by
using the list 'L' command:
- DB<5> L
+ DB<3> L
temp:
17: print "$out $deg\n";
break if (1)
-Note that to delete a breakpoint you use 'd' or 'D'.
+Note that to delete a breakpoint you use 'B'.
Now we'll continue down into our subroutine, this time rather than by line
-number, we'll use the subroutine name, followed by the now familiar 'w':
+number, we'll use the subroutine name, followed by the now familiar 'v':
- DB<6> c f2c
+ DB<3> c f2c
main::f2c(temp:30): my $f = shift;
- DB<7> w
- 27 }
- 28
- 29 sub f2c {
- 30==> my $f = shift;
- 31: my $c = 5 * $f - 32 / 9;
- 32: return $c;
- 33 }
- 34
-
-
-Note that if there was a subroutine call between us and line 32, and we didn't
-want to single-step through it, we could use the next command 'n', which would
-execute the sub, but not descend into it for inspection. In this case though,
-we simply single step down to line 32:
-
- DB<8> s 32
- main::f2c(temp:28): return $c;
-
+ DB<4> v
+ 24: exit;
+ 25
+ 26 sub f2c {
+ 27==> my $f = shift;
+ 28: my $c = 5 * $f - 32 / 9;
+ 29: return $c;
+ 30 }
+ 31
+ 32 sub c2f {
+ 33: my $c = shift;
+
+
+Note that if there was a subroutine call between us and line 29, and we wanted
+to B<single-step> through it, we could use the 'B<s>' command, and to step
+over it we would use 'B<n>' which would execute the sub, but not descend into
+it for inspection. In this case though, we simply continue down to line 29:
+
+ DB<4> c 29
+ main::f2c(temp:29): return $c;
+
And have a look at the return value:
- DB<9> p $c
+ DB<5> p $c
162.944444444444
This is not the right answer at all, but the sum looks correct. I wonder if
it's anything to do with operator precedence? We'll try a couple of other
possibilities with our sum:
- DB<10> p (5 * $f - 32 / 9)
+ DB<6> p (5 * $f - 32 / 9)
162.944444444444
-
- DB<11> p 5 * $f - (32 / 9)
+
+ DB<7> p 5 * $f - (32 / 9)
162.944444444444
-
- DB<12> p (5 * $f) - 32 / 9
+
+ DB<8> p (5 * $f) - 32 / 9
162.944444444444
-
- DB<13> p 5 * ($f - 32) / 9
+
+ DB<9> p 5 * ($f - 32) / 9
0.722222222222221
:-) that's more like it! Ok, now we can set our return variable and we'll
return out of the sub with an 'r':
- DB<14> $c = 5 * ($f - 32) / 9
-
- DB<15> r
+ DB<10> $c = 5 * ($f - 32) / 9
+
+ DB<11> r
scalar context return from main::f2c: 0.722222222222221
-
+
Looks good, let's just continue off the end of the script:
- DB<16> c
+ DB<12> c
0.72 c
Debugged program terminated. Use q to quit or R to restart,
use O inhibit_exit to avoid stopping after program termination,
=head1 Placeholder for a, w, t, T
-Actions, watch variables, stack traces on the TODO list.
+Actions, watch variables, stack traces etc.: on the TODO list.
a
-
- W
-
+
+ w
+
t
-
+
T
-=head1 Regular expressions
+=head1 REGULAR EXPRESSIONS
Ever wanted to know what a regex looked like? You'll need perl compiled with
the DEBUGGING flag for this one:
-
+
> perl -Dr -e '/^pe(a)*rl$/i'
Compiling REx `^pe(a)*rl$'
size 17 first at 2
floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
anchored(BOL) minlen 4
Omitting $` $& $' support.
-
+
EXECUTING...
Freeing REx: `^pe(a)*rl$'
Did you really want to know? :-)
+For more gory details on getting regular expressions to work, have a look at
+L<perlre>, L<perlretut>, and to decode the mysterious labels (BOL and CURLYN,
+etc. above), see L<perldebguts>.
-=head1 Some ideas for output
+=head1 OUTPUT TIPS
To get all the output from your error log, and not miss any messages via
helpful operating system buffering, insert a line like this, at the start of
Wrapping all die calls in a handler routine can be useful to see how, and from
where, they're being called, L<perlvar> has more information:
- BEGIN { $SIG{__DIE__} = sub { use Carp; Carp::confess(@_) } }
+ BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
Various useful techniques for the redirection of STDOUT and STDERR filehandles
-are explained in L<perlfunc> and L<perlopentut> and L<perlfaq8>
+are explained in L<perlopentut> and L<perlfaq8>.
=head1 CGI
-Just a hint here for all those CGI programmers who can't figure out how on
-earth to get past that 'waiting for input' prompt, try something like this:
+Just a quick hint here for all those CGI programmers who can't figure out how
+on earth to get past that 'waiting for input' prompt, when running their CGI
+script from the command-line, try something like this:
> perl -d my_cgi.pl -nodebug
-Of course
'L<perldoc CGI>' and L<perlfaq9> will tell you more.
+Of course
L<CGI> and L<perlfaq9> will tell you more.
=head1 GUIs
You don't have to do this all on the command line, though, there are a few GUI
options out there. The nice thing about these is you can wave a mouse over a
-variable and a dump of it's data will appear in an appropriate window, or in a
+variable and a dump of its data will appear in an appropriate window, or in a
popup balloon, no more tiresome typing of 'x $varname' :-)
In particular have a hunt around for the following:
B<ptkdb> perlTK based wrapper for the built-in debugger
B<ddd> data display debugger
-
+
B<PerlDevKit> and B<PerlBuilder> are NT specific
NB. (more info on these and others would be appreciated).
-=head1 Summary
+=head1 SUMMARY
We've seen how to encourage good coding practices with B<use strict> and
B<-w>. We can run the perl debugger B<perl -d scriptname> to inspect your
L<perldebug>,
L<perldebguts>,
L<perldiag>,
-L<dprofpp>,
L<perlrun>
=head1 AUTHOR
-Richard Foley <richard@rfi.net> Copyright (c) 2000
+Richard Foley <richard.foley@rfi.net> Copyright (c) 2000
=head1 CONTRIBUTORS
Ronald J Kimball <rjk@linguist.dartmouth.edu>
-Hugo <hv@crypt.compulink.co.uk>
+Hugo van der Sanden <hv@crypt0.demon.co.uk>
+
+Peter Scott <Peter@PSDT.com>
https://perl5.git.perl.org / perl5.git / blobdiff