/ 
Devel-hdb-0.08
River stage one • 1 direct dependent • 2 total dependents
/ Devel::hdb

NAME

Devel::hdb - Perl debugger as a web page and REST service

DESCRIPTION

hdb is a Perl debugger that uses HTML and javascript to implement the GUI. This front-end talks to a REST service provided by the debugger running with the Perl code.

SYNOPSIS

To debug a Perl program, start it like this:

perl -d:hdb youprogram.pl

It will print a message on STDERR with the URL the debugger is listening to. Point you web browser at this URL and it will being up the debugger GUI. It defaults to listening on localhost port 8080; to use a different port, start it like this:

perl -d:hdb=port:9876 yourprogram.pl

To specify a particular IP address to listen on:

perl -d:hdb=host:192.168.0.123 yourprogram.pl

And to listen on any interface:

perl -d:hdb=a yourprogram.pl

Interface

The GUI is divided into three main parts: Control buttons, Code browser and Watch expressions. Additionally, click on the thick border between the code and watch panes to slide out the breakpoint list.

Control buttons
Step In

Causes the debugger to execute the next line and stop. If the next line is a subroutine call, it will stop at the first executable line in the subroutine.

Step Over

Causes the debugger to execute the next line and stop. If the next line is a subroutine call, it will step over the call and stop when the subroutine returns.

Step Out

Causes the debugger to run the program until it returns from the current subroutine.

Run

Resumes execution of the program until the next breakpoint.

Exit

The debugged program immediately exits. The GUI in the web browser remains running.

Code Browser

Most of the interface is taken up by the code browser. Tabs along the top show one file at a time. The "+" next to the last tab brings up a dialog to choose another file to open. Click the "x" next to a file name to close that tab.

The first tab is special: it shows the stack frames of the currently executing program and cannot be closed. The stack tab itself has tabs along the left, one tab for each stack frame; the most recent frame is at the top.

Each of these tabs shows a Code Pane. The line numbers on the left are struck through if that line is not breakable. For breakable lines, clicking on the line number will set an unconditional breakpoint and turn the number red. Right-clicking on a breakable line number will bring up a menu where a breakpoint condition and action can be set. Lines with conditional breakpoints are blue. Lines with actions have a circle outline, and are dimmed when the breakpoint is inactive.

The banner at the top of the Code Pane shows the current function and its arguments. Clicking on the banner will scoll the Code Pane to show the currently executing line.

Hover the mouse over a variable to see its value. It shows the value in whichever stack frame is being displayed. To see the values for variables in higher frames, select the appropriate frame from the tab on the left.

Watch Expressions

The right side of the GUI shows watch expressions. To add a new expression to the watch window, click on the "+". To remove a watched expression, click on the "x" next to its name. Composite types like Hashes and arrays have a blue circled number indicating how many elements belong to it. To collapse/expand them, click the blue cicle.

Child Processes

The debugger overrides Perl's fork() built-in so that the child process will stop with the first statement after the fork(). In the parent process' debugger window, it will pop up a dialog with two options

Open Open a new browser window and debug the child process inside it
Detach Disables the debugger in the child process, and forces it to run to completion.

Trace and Follow mode

Devel::hdb can trace the execution of a program and stop if the code path differs from that of a previously save run. First, run the program in trace mode:

perl -d:hdb=trace:<tracefile> yourprogram.pl

In trace mode, the program runs normally, and the debugger does not stop execution. It records information about which lines of code were run into the specified file (tracefile, in this example). Next, run the program again in follow mode:

perl -d:hdb=follow:<tracefile> yourprogram.pl

This time, the debugger starts up normally, stopping on the first line of the program. As the program runs, the debugger reads the trace information from the specified file. The first time the current location is different than what is in the file, the debugger will stop and report which line it expected. After it stops in this way, follow mode is disabled.

Included Code

This package includes these third party libraries:

AUTHOR

Anthony Brummett <brummett@cpan.org>

COPYRIGHT

Copyright 2013, Anthony Brummett. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.