This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
013dfb44641a33c839cec2a0237c02b20d6364f4
[perl5.git] / pod / perldebtut.pod
1 =head1 NAME
2
3 perldebtut - Perl debugging tutorial
4
5 =head1 DESCRIPTION
6
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
9 perl programs.  
10
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
13 day.  
14 This is for them.  
15
16
17 =head1 use strict
18
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
22 a problem:
23
24         #!/usr/bin/perl
25
26         $var1 = 'Hello World'; # always wanted to do that :-)
27         $var2 = "$varl\n";
28
29         print $var2; 
30         exit;
31
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)
37 there's really 3:
38
39         $var1 = 'Hello World';
40         $varl = undef;
41         $var2 = "\n";
42
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.
46
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:
49
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.     
55
56 Luvverly! and to fix this we declare all variables explicitly and now our
57 script looks like this: 
58
59         #!/usr/bin/perl
60         use strict;
61
62         my $var1 = 'Hello World';
63         my $varl = undef;
64         my $var2 = "$varl\n";
65
66         print $var2; 
67         exit;
68
69 We then do (always a good idea) a syntax check before we try to run it again:
70
71         > perl -c hello
72         hello syntax OK 
73
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.
77
78
79 =head1 Looking at data and -w and v
80
81 Ok, but how about when you want to really see your data, what's in that
82 dynamic variable, just before using it?
83
84         #!/usr/bin/perl 
85         use strict;
86
87         my $key = 'welcome';
88         my %data = (
89                 'this' => qw(that), 
90                 'tom' => qw(and jerry),
91                 'welcome' => q(Hello World),
92                 'zip' => q(welcome),
93         );
94         my @data = keys %data;
95
96         print "$data{$key}\n";
97         exit;                               
98
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.
101
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
104 after:
105
106         print "All OK\n" if grep($key, keys %data);
107         print "$data{$key}\n";
108         print "done: '$data{$key}'\n";
109
110 And try again:
111
112         > perl data
113         All OK     
114
115         done: ''
116
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
120 line:
121
122         > perl -d data 
123         Default die handler restored.
124
125         Loading DB routines from perl5db.pl version 1.07
126         Editor support available.
127
128         Enter h or `h h' for help, or `man perldebug' for more help.
129
130         main::(./data:4):     my $key = 'welcome';   
131
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
134 input.
135
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':
138
139         DB<1> q
140         >
141
142 That's it, you're back on home turf again.
143
144
145 =head1 help
146
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:
152
153 DB<1>h
154
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 [in expr]
158   v [line]    View around line            n [expr]    Next, steps over subs
159   f filename  View source in file         <CR/Enter>  Repeat last n or s
160   /pattern/ ?patt?   Search forw/backw    r           Return from subroutine
161   M           Show module versions        c [ln|sub]  Continue until position
162  Debugger controls:                        L           List break/watch/actions
163   o [...]     Set debugger options        t [expr]    Toggle trace [trace expr]
164   <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint
165   ! [N|pat]   Redo a previous command     B ln|*      Delete a/all breakpoints
166   H [-num]    Display last num commands   a [ln] cmd  Do cmd before line
167   = [a val]   Define/list an alias        A ln|*      Delete a/all actions
168   h [db_cmd]  Get help on command         w expr      Add a watch expression
169   h h         Complete help page          W expr|*    Delete a/all watch expressions
170   |[|]db_cmd  Send output to pager        ![!] syscmd Run cmd in a subprocess
171   q or ^D     Quit                        R           Attempt a restart
172  Data Examination:     expr     Execute perl code, also see: s,n,t expr
173   x|m expr       Evals expr in list context, dumps the result or lists methods.
174   p expr         Print expression (uses script's current package).
175   S [[!]pat]     List subroutine names [not] matching pattern
176   V [Pk [Vars]]  List Variables in Package.  Vars can be ~pattern or !pattern.
177   X [Vars]       Same as "V current_package [Vars]".
178  For more help, type h cmd_letter, or run man perldebug for all docs. 
179
180 More confusing options than you can shake a big stick at!  It's not as bad as
181 it looks and it's very useful to know more about all of it, and fun too!
182
183 There's a couple of useful ones to know about straight away.  You wouldn't
184 think we're using any libraries at all at the moment, but 'B<M>' will show
185 which modules are currently loaded, and their version number, while 'B<m>' 
186 will show the methods, and 'B<S>' shows all subroutines (by pattern) as 
187 shown below.  'B<V>' and 'B<X>' show variables in the program by package 
188 scope and can be constrained by pattern. 
189
190         DB<2>S str 
191         dumpvar::stringify
192         strict::bits
193         strict::import
194         strict::unimport  
195
196 Using 'X' and cousins requires you not to use the type identifiers ($@%), just
197 the 'name':
198
199         DM<3>X ~err
200         FileHandle(stderr) => fileno(2)    
201
202 Remember we're in our tiny program with a problem, we should have a look at
203 where we are, and what our data looks like. First of all let's view some code 
204 at our present position (the first line of code in this case), via 'B<v>':
205
206         DB<4> v
207         1       #!/usr/bin/perl
208         2:      use strict;
209         3
210         4==>    my $key = 'welcome';
211         5:      my %data = (
212         6               'this' => qw(that),
213         7               'tom' => qw(and jerry),
214         8               'welcome' => q(Hello World),
215         9               'zip' => q(welcome),
216         10      );                                 
217
218 At line number 4 is a helpful pointer, that tells you where you are now.  To
219 see more code, type 'v' again:
220
221         DB<4> v
222         8               'welcome' => q(Hello World),
223         9               'zip' => q(welcome),
224         10      );
225         11:     my @data = keys %data;
226         12:     print "All OK\n" if grep($key, keys %data);
227         13:     print "$data{$key}\n";
228         14:     print "done: '$data{$key}'\n";
229         15:     exit;      
230
231 And if you wanted to list line 5 again, type 'l 5', (note the space):
232
233         DB<4> l 5
234         5:      my %data = (
235
236 In this case, there's not much to see, but of course normally there's pages of
237 stuff to wade through, and 'l' can be very useful.  To reset your view to the
238 line we're about to execute, type a lone period '.':
239
240         DB<5> .
241         main::(./data_a:4):     my $key = 'welcome';  
242
243 The line shown is the one that is about to be executed B<next>, it hasn't
244 happened yet.  So while we can print a variable with the letter 'B<p>', at
245 this point all we'd get is an empty (undefined) value back.  What we need to
246 do is to step through the next executable statement with an 'B<s>':
247
248         DB<6> s
249         main::(./data_a:5):     my %data = (
250         main::(./data_a:6):             'this' => qw(that),
251         main::(./data_a:7):             'tom' => qw(and jerry),
252         main::(./data_a:8):             'welcome' => q(Hello World),
253         main::(./data_a:9):             'zip' => q(welcome),
254         main::(./data_a:10):    );   
255
256 Now we can have a look at that first ($key) variable:
257
258         DB<7> p $key 
259         welcome 
260
261 line 13 is where the action is, so let's continue down to there via the letter
262 'B<c>', which by the way, inserts a 'one-time-only' breakpoint at the given
263 line or sub routine:
264
265         DB<8> c 13
266         All OK
267         main::(./data_a:13):    print "$data{$key}\n";
268
269 We've gone past our check (where 'All OK' was printed) and have stopped just
270 before the meat of our task.  We could try to print out a couple of variables
271 to see what is happening:
272
273         DB<9> p $data{$key}
274
275 Not much in there, lets have a look at our hash:
276
277         DB<10> p %data
278         Hello Worldziptomandwelcomejerrywelcomethisthat 
279
280         DB<11> p keys %data
281         Hello Worldtomwelcomejerrythis  
282
283 Well, this isn't very easy to read, and using the helpful manual (B<h h>), the
284 'B<x>' command looks promising:
285
286         DB<12> x %data
287         0  'Hello World'
288         1  'zip'
289         2  'tom'
290         3  'and'
291         4  'welcome'
292         5  undef
293         6  'jerry'
294         7  'welcome'
295         8  'this'
296         9  'that'     
297
298 That's not much help, a couple of welcomes in there, but no indication of
299 which are keys, and which are values, it's just a listed array dump and, in
300 this case, not particularly helpful.  The trick here, is to use a B<reference>
301 to the data structure:
302
303         DB<13> x \%data
304         0  HASH(0x8194bc4)
305            'Hello World' => 'zip'
306            'jerry' => 'welcome'
307            'this' => 'that'
308            'tom' => 'and'
309            'welcome' => undef  
310
311 The reference is truly dumped and we can finally see what we're dealing with. 
312 Our quoting was perfectly valid but wrong for our purposes, with 'and jerry'
313 being treated as 2 separate words rather than a phrase, thus throwing the
314 evenly paired hash structure out of alignment.
315
316 The 'B<-w>' switch would have told us about this, had we used it at the start,
317 and saved us a lot of trouble: 
318
319         > perl -w data
320         Odd number of elements in hash assignment at ./data line 5.    
321
322 We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get
323 our expected output:
324
325         > perl -w data
326         Hello World
327
328
329 While we're here, take a closer look at the 'B<x>' command, it's really useful
330 and will merrily dump out nested references, complete objects, partial objects
331 - just about whatever you throw at it:
332
333 Let's make a quick object and x-plode it, first we'll start the debugger:
334 it wants some form of input from STDIN, so we give it something non-commital,
335 a zero:
336
337         > perl -de 0
338         Default die handler restored.
339
340         Loading DB routines from perl5db.pl version 1.07
341         Editor support available.
342
343         Enter h or `h h' for help, or `man perldebug' for more help.
344
345         main::(-e:1):   0                       
346
347 Now build an on-the-fly object over a couple of lines (note the backslash):
348
349         DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
350         cont:   {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
351
352 And let's have a look at it:
353
354         DB<2> x $obj
355         0  MY_class=HASH(0x828ad98)
356                 'attr' => HASH(0x828ad68)
357         'col' => 'black'
358         'things' => ARRAY(0x828abb8)
359                 0  'this'
360                 1  'that'
361                 2  'etc'
362                 'unique_id' => 123       
363         DB<3>
364
365 Useful, huh?  You can eval nearly anything in there, and experiment with bits
366 of code or regexes until the cows come home:
367
368         DB<3> @data = qw(this that the other atheism leather theory scythe)
369
370         DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
371         atheism
372         leather
373         other
374         scythe
375         the
376         theory  
377         saw -> 6
378
379 If you want to see the command History, type an 'B<H>':
380
381         DB<5> H
382         4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
383         3: @data = qw(this that the other atheism leather theory scythe)
384         2: x $obj
385         1: $obj = bless({'unique_id'=>'123', 'attr'=>
386         {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
387         DB<5>
388
389 And if you want to repeat any previous command, use the exclamation: 'B<!>':
390
391         DB<5> !4
392         p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
393         atheism
394         leather
395         other
396         scythe
397         the
398         theory  
399         saw -> 12
400
401 For more on references see L<perlref> and L<perlreftut>
402
403
404 =head1 Stepping through code
405
406 Here's a simple program which converts between Celsius and Fahrenheit, it too
407 has a problem:
408
409         #!/usr/bin/perl -w
410         use strict;
411
412         my $arg = $ARGV[0] || '-c20';
413
414         if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
415                 my ($deg, $num) = ($1, $2);
416                 my ($in, $out) = ($num, $num);
417                 if ($deg eq 'c') {
418                         $deg = 'f';
419                         $out = &c2f($num);
420                 } else {
421                         $deg = 'c';
422                         $out = &f2c($num);
423                 }
424                 $out = sprintf('%0.2f', $out);
425                 $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
426                 print "$out $deg\n";
427         } else {
428                 print "Usage: $0 -[c|f] num\n";
429         }
430         exit;
431
432         sub f2c {
433                 my $f = shift;
434                 my $c = 5 * $f - 32 / 9;
435                 return $c;
436         }
437
438         sub c2f {
439                 my $c = shift;
440                 my $f = 9 * $c / 5 + 32;
441                 return $f;
442         }
443
444
445 For some reason, the Fahrenheit to Celsius conversion fails to return the
446 expected output.  This is what it does:
447
448         > temp -c0.72
449         33.30 f
450
451         > temp -f33.3
452         162.94 c
453
454 Not very consistent!  We'll set a breakpoint in the code manually and run it
455 under the debugger to see what's going on.  A breakpoint is a flag, to which
456 the debugger will run without interruption, when it reaches the breakpoint, it
457 will stop execution and offer a prompt for further interaction.  In normal
458 use, these debugger commands are completely ignored, and they are safe - if a
459 little messy, to leave in production code.
460
461         my ($in, $out) = ($num, $num);
462         $DB::single=2; # insert at line 9!
463         if ($deg eq 'c') 
464                 ...
465
466         > perl -d temp -f33.3
467         Default die handler restored.
468
469         Loading DB routines from perl5db.pl version 1.07
470         Editor support available.
471
472         Enter h or `h h' for help, or `man perldebug' for more help.
473
474         main::(temp:4): my $arg = $ARGV[0] || '-c100';     
475
476 We'll simply continue down to our pre-set breakpoint with a 'B<c>':
477
478         DB<1> c
479         main::(temp:10):                if ($deg eq 'c') {   
480
481 Followed by a view command to see where we are:
482
483         DB<1> v
484         7:              my ($deg, $num) = ($1, $2);
485         8:              my ($in, $out) = ($num, $num);
486         9:              $DB::single=2;
487         10==>           if ($deg eq 'c') {
488         11:                     $deg = 'f';
489         12:                     $out = &c2f($num);
490         13              } else {
491         14:                     $deg = 'c';
492         15:                     $out = &f2c($num);
493         16              }                             
494
495 And a print to show what values we're currently using:
496
497         DB<1> p $deg, $num
498         f33.3
499
500 We can put another break point on any line beginning with a colon, we'll use
501 line 17 as that's just as we come out of the subroutine, and we'd like to
502 pause there later on:
503
504         DB<2> b 17
505
506 There's no feedback from this, but you can see what breakpoints are set by
507 using the list 'L' command:
508
509         DB<3> L
510         temp:
511                 17:            print "$out $deg\n";
512                 break if (1)     
513
514 Note that to delete a breakpoint you use 'd' or 'D'.
515
516 Now we'll continue down into our subroutine, this time rather than by line
517 number, we'll use the subroutine name, followed by the now familiar 'v':
518
519         DB<3> c f2c
520         main::f2c(temp:30):             my $f = shift;  
521
522         DB<4> v
523         24:     exit;
524         25
525         26      sub f2c {
526         27==>           my $f = shift;
527         28:             my $c = 5 * $f - 32 / 9; 
528         29:             return $c;
529         30      }
530         31
531         32      sub c2f {
532         33:             my $c = shift;   
533
534
535 Note that if there was a subroutine call between us and line 29, and we wanted
536 to B<single-step> through it, we could use the 'B<s>' command, and to step
537 over it we would use 'B<n>' which would execute the sub, but not descend into
538 it for inspection.  In this case though, we simply continue down to line 29:
539
540         DB<4> c 29  
541         main::f2c(temp:29):             return $c;
542
543 And have a look at the return value:
544
545         DB<5> p $c
546         162.944444444444
547
548 This is not the right answer at all, but the sum looks correct.  I wonder if
549 it's anything to do with operator precedence?  We'll try a couple of other
550 possibilities with our sum:
551
552         DB<6> p (5 * $f - 32 / 9)
553         162.944444444444
554
555         DB<7> p 5 * $f - (32 / 9) 
556         162.944444444444
557
558         DB<8> p (5 * $f) - 32 / 9
559         162.944444444444
560
561         DB<9> p 5 * ($f - 32) / 9
562         0.722222222222221
563
564 :-) that's more like it!  Ok, now we can set our return variable and we'll
565 return out of the sub with an 'r':
566
567         DB<10> $c = 5 * ($f - 32) / 9
568
569         DB<11> r
570         scalar context return from main::f2c: 0.722222222222221
571
572 Looks good, let's just continue off the end of the script:
573
574         DB<12> c
575         0.72 c 
576         Debugged program terminated.  Use q to quit or R to restart,
577         use O inhibit_exit to avoid stopping after program termination,
578         h q, h R or h O to get additional info.   
579
580 A quick fix to the offending line (insert the missing parentheses) in the
581 actual program and we're finished.
582
583
584 =head1 Placeholder for a, w, t, T
585
586 Actions, watch variables, stack traces etc.: on the TODO list.
587
588         a 
589
590         w 
591
592         t 
593
594         T
595
596
597 =head1 REGULAR EXPRESSIONS
598
599 Ever wanted to know what a regex looked like?  You'll need perl compiled with
600 the DEBUGGING flag for this one:
601
602         > perl -Dr -e '/^pe(a)*rl$/i'
603         Compiling REx `^pe(a)*rl$'
604         size 17 first at 2
605         rarest char
606          at 0
607            1: BOL(2)
608            2: EXACTF <pe>(4)
609            4: CURLYN[1] {0,32767}(14)
610            6:   NOTHING(8)
611            8:   EXACTF <a>(0)
612           12:   WHILEM(0)
613           13: NOTHING(14)
614           14: EXACTF <rl>(16)
615           16: EOL(17)
616           17: END(0)
617         floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
618 anchored(BOL) minlen 4
619         Omitting $` $& $' support.
620
621         EXECUTING...
622
623         Freeing REx: `^pe(a)*rl$'  
624
625 Did you really want to know? :-)
626 For more gory details on getting regular expressions to work, have a look at
627 L<perlre>, L<perlretut>, and to decode the mysterious labels (BOL and CURLYN,
628 etc. above), see L<perldebguts>.
629
630
631 =head1 OUTPUT TIPS
632
633 To get all the output from your error log, and not miss any messages via
634 helpful operating system buffering, insert a line like this, at the start of
635 your script:
636
637         $|=1;   
638
639 To watch the tail of a dynamically growing logfile, (from the command line):
640
641         tail -f $error_log
642
643 Wrapping all die calls in a handler routine can be useful to see how, and from
644 where, they're being called, L<perlvar> has more information:
645
646         BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
647
648 Various useful techniques for the redirection of STDOUT and STDERR filehandles
649 are explained in L<perlopentut> and L<perlfaq8>.
650
651
652 =head1 CGI
653
654 Just a quick hint here for all those CGI programmers who can't figure out how
655 on earth to get past that 'waiting for input' prompt, when running their CGI
656 script from the command-line, try something like this:
657
658         > perl -d my_cgi.pl -nodebug 
659
660 Of course L<CGI> and L<perlfaq9> will tell you more.
661
662
663 =head1 GUIs
664
665 The command line interface is tightly integrated with an B<emacs> extension
666 and there's a B<vi> interface too.  
667
668 You don't have to do this all on the command line, though, there are a few GUI
669 options out there.  The nice thing about these is you can wave a mouse over a
670 variable and a dump of its data will appear in an appropriate window, or in a
671 popup balloon, no more tiresome typing of 'x $varname' :-)
672
673 In particular have a hunt around for the following:
674
675 B<ptkdb> perlTK based wrapper for the built-in debugger
676
677 B<ddd> data display debugger
678
679 B<PerlDevKit> and B<PerlBuilder> are NT specific
680
681 NB. (more info on these and others would be appreciated).
682
683
684 =head1 SUMMARY
685
686 We've seen how to encourage good coding practices with B<use strict> and
687 B<-w>.  We can run the perl debugger B<perl -d scriptname> to inspect your
688 data from within the perl debugger with the B<p> and B<x> commands.  You can
689 walk through your code, set breakpoints with B<b> and step through that code
690 with B<s> or B<n>, continue with B<c> and return from a sub with B<r>.  Fairly
691 intuitive stuff when you get down to it.  
692
693 There is of course lots more to find out about, this has just scratched the
694 surface.  The best way to learn more is to use perldoc to find out more about
695 the language, to read the on-line help (L<perldebug> is probably the next
696 place to go), and of course, experiment.  
697
698
699 =head1 SEE ALSO
700
701 L<perldebug>, 
702 L<perldebguts>, 
703 L<perldiag>,
704 L<dprofpp>,
705 L<perlrun>
706
707
708 =head1 AUTHOR
709
710 Richard Foley <richard@rfi.net> Copyright (c) 2000
711
712
713 =head1 CONTRIBUTORS
714
715 Various people have made helpful suggestions and contributions, in particular:
716
717 Ronald J Kimball <rjk@linguist.dartmouth.edu>
718
719 Hugo van der Sanden <hv@crypt0.demon.co.uk>
720
721 Peter Scott <Peter@PSDT.com>
722