What Is the Debugger?

The Perl debugger is a built-in feature of the Perl interpreter. It allows you to take any Perl program and step through that program statement by statement. Along the way, you can examine variables , change them, let the program run for a while longer, interrupt the program, or start it over again.

From your program's perspective, nothing is different. Input still comes from the keyboard, and output still goes to the screen. The program doesn't know when it's stopped or when it's running. In fact, you can examine your program's workings without disturbing them at all.

Starting the Debugger

If you are a Macintosh user running Perl, to use the debugger you need only select Debugger from the Script menu, and a Debugger window opens with a prompt for you.

Under any other operating system, to start the Perl debugger you must be at your operating system's command prompt. For DOS and Windows users, this means the standard MS-DOS C:\ prompt. For Unix users, this means the prompt that you were presented with when you logged in (usually % or $ ).

All the examples in this section use the Employee program from Listing 9.1 in Hour 9, "More Functions and Operators." You might find it handy to put a bookmark on that page and flip back and forth for reference.

To start the debugger at the prompt ”an MS-DOS prompt is used for the example ”type this line:

 C:\>  perl -d Employee  

The -d switch to perl causes Perl to start up in debugging mode; the program to be debugged is also indicated on the command line. Some messages giving version information are then displayed, as shown here:

 Loading DB routines from perl5db.pl version 1.0401 Emacs support available. Enter h or `h h' for help. main::(Employee:5):     my @employees=( main::(Employee:6):         'Smith,Bob,123101,9.35,40', main::(Employee:7):         'Franklin,Alice,132912,10.15,35', main::(Employee:8):         'Wojohowicz,Ted,198131,6.50,39', main::(Employee:9):         'Ng,Wendy,141512,9.50,40', main::(Employee:10):        'Cliburn,Stan,131211,11.25,40', main::(Employee:11):    );  DB<1>__ 

The debugger first displays the version number ( 1.0401 ”yours will vary) and the help prompt. Next , the first executable line of the program is displayed. Because the first statement is actually seven lines long ”starting with my @employees=( and ending with ); ”all seven lines of the statement are shown along with a description that shows what file they came from (Employee) and what line or lines of the file they were found on (5 through 11).

Last, you see the debugger prompt DB<1> . The 1 signifies that the debugger is waiting for its first command. The cursor waits at the debugger prompt for your command.

At this point, your Perl program is not running. The program is actually paused just before the first instruction -my @employees=(, and so on. Whenever the debugger shows you a statement from your program, it is the statement about to be executed, not the last statement run.

The debugger is now ready for your commands.

Basic Debugger Commands

The first ”and most important ”command you can give the debugger is the help command. If you type h at the debugger prompt, all the available debugger commands are printed. You also can use some variations: h h prints a summary of commands and syntax, and h cmd prints help for a specific command.

The list of help commands is probably longer than your screen will allow, and the first few commands will probably scroll right off. To make any debugger command's output display a screen at a time, put a in front of the command. So, to see the help a screen at a time, the command is h .

The most-used feature of the debugger is the capability to run Perl code an instruction at a time. So, continuing with the previous example, to go to the next statement in your Perl program, you use the debugger's n command:

After you type the n command, Perl executes the statement from lines 5 to 11 of the Employee program. The debugger then prints, but does not yet run, the next statement to be executed ” my($L1, $F1)=split(',', $a); ”and displays another prompt.

At this point in the execution, @employees is initialized to the five names , salaries, and so on. To view them, you can simply print them:

 DB<1>  print @employees  Smith,Bob,123101,9.35,40Franklin,Alice,132912,10.15,35Wojohowicz,Ted,198131,6.50 ,39Ng,Wendy,141512,9.50,40Cliburn,Stan,131211,11.25,40   DB<2> __ 

In fact, any Perl statement can be run at a debugger prompt. Notice that the array elements from @employees are all run together. You can enter the following to print them nicely :

 DB<2>  print join("\n", @employees)  Smith,Bob,123101,9.35,40 Franklin,Alice,132912,10.15,35 Wojohowicz,Ted,198131,6.50,39 Ng,Wendy,141512,9.50,40 Cliburn,Stan,131211,11.25,40   DB<3> __ 

To continue stepping through the program, just keep typing n, as shown here:

 DB<3>  n  main::(Employee:23):    @employees=sort {   DB<3>  n  main::(Employee:25):        my ($L2, $F2)=split(',', $b);   DB<3>  n  main::(Employee:26):        return( $L1 cmp $L2 main::(Employee:27):                 main::(Employee:28):            $F1 cmp $F2 main::(Employee:29):        );   DB<3>  n  main::(Employee:23):    @employees=sort {   DB<3> 

Apparently, the debugger moves backward through the program here; line 23 is about to be executed again. The Perl sort statement is actually a kind of loop, and the debugger steps through each statement in the block of the sort . If you keep typing n , the debugger keeps looping until the sort is finished ”which might take awhile.

To repeat the previous command, you can also just press the Enter key at a debugger prompt.

Breakpoints

Instead of stepping through the program an instruction at a time, you also can have the debugger continue to run your Perl program until a certain statement is reached and then stop. These places to stop are called breakpoints .

To set a breakpoint, you must first select a place in the program to stop. The l command lists the next 10 lines of the program. Typing l again lists the next 10 lines, and so on. To list the program starting at a particular line, type l lineno , where lineno is the line number of the program. You can also specify a range of lines by using the command l start-end .

In the listing, a ===> marks the current line about to be executed by the debugger, as you can see here:

 DB<3> l  11 23:==>   @employees=sort { 24:          my ($L1, $F1)=split(',', $a); 25:          my ($L2, $F2)=split(',', $b); 26:          return( $L1 cmp $L2 27:                   28:              $F1 cmp $F2 29:          ); 30:           } @employees; 31: 32:     foreach(@employees) { 33:         print_emp($_);   DB<3> __ 

In this case, line 33 is a good place for a breakpoint: It's after the sort statement, and it's the first statement inside the main loop of the program. You can set a breakpoint anywhere in a Perl program as long as the breakpoint is a valid Perl statement; you cannot break on a brace (line 30), punctuation (line 29), a blank line (line 31), or a line containing only a comment.

To set the breakpoint, use the b breakpoint command, where breakpoint can be a line number or a subroutine name . To set the breakpoint at line 33, for example, you enter the following:

 DB<3>  b 33  DB<4> 

The other command you need to know with breakpoints is the continue command, c . The c command instructs the debugger to let the Perl program run until the next breakpoint is reached or the end of the program is reached ”whichever comes first:

 DB<5>  c  main::(Employee:33):            print_emp($_);   DB<6> 

In this case, the debugger stops the Perl program at line 33 before the print_emp function is called, as expected. The breakpoint is still set, so typing another c causes the program to continue, run the print_emp() function, and stop again on line 33:

 DB<8>  L  Employee:  33:            print_emp($_); 

To examine the breakpoints you have set in your program, you can use the L command like this:

This example shows that the debugger has one breakpoint, in the file Employee at line 33.

To get rid of a breakpoint in the program, you use the d command in the same way you set the breakpoint ” d line or d subname :

 DB<9>  d 33  DB<10> 

Other Debugger Commands

If you want to examine the workings of the print_emp() function, you can do so in a few different ways. First, restart the program by using the R command:

 DB<11>  R  Warning: some settings and command-line options may be lost! Loading DB routines from perl5db.pl version 1.0401 Emacs support available. Enter h or `h h' for help. main::(Employee:5):    my @employees=( main::(Employee:6):        'Smith,Bob,123101,9.35,40', main::(Employee:7):        'Franklin,Alice,132912,10.15,35', main::(Employee:8):        'Wojohowicz,Ted,198131,6.50,39', main::(Employee:9):        'Ng,Wendy,141512,9.50,40', main::(Employee:10):       'Cliburn,Stan,131211,11.25,40', main::(Employee:11):   );   DB<12>  b 33  

The R command resets the Perl program to the beginning and prepares to execute it again. Any breakpoints you have set remain set, and any variables in the Perl program are reset. In the preceding example, a breakpoint is set at line 33. Then you can continue the program with the following:

 DB<13>  c  main::(Employee:33):            print_emp($_);   DB<14> __ 

Executing the n command would execute the next instruction:

 DB<14>  n  131211 Stan Cliburn          11.25  40  450.00 main::(Employee:32):    foreach(@employees) {   DB<15> n main::(Employee:33):            print_emp($_);   DB<16> __ 

Moving through the program this way doesn't allow you to examine what's in print_emp() . To step into print_emp() , instead of the n command, you should use s , the step command. The s command works just like n , but instead of simply executing subroutines and moving to the next instruction, s stops at the first instruction inside the subroutine, as you can see here:

 main::(Employee:33):            print_emp($_);   DB<16>  s  main::print_emp(Employee:14):           my($last,$first,$emp,$hourly,$time)= main::print_emp(Employee:15):                   split(',', $_[0]);   DB<17>__ 

Here, the first statement of