/ 
Devel-tkdb-2.4
River stage zero No dependents
/ Devel::tkdb

NAME

Devel::tkdb - Perl debugger using a Tcl/Tk GUI

SYNOPSIS

perl -d:tkdb myscript.pl

DESCRIPTION

tkdb is a debugger for perl that uses perl+Tcl/Tk for a user interface. Features include:

Hot Variable Inspection (currently disabled)
Breakpoint Control Panel
Expression List
Subroutine Tree

Usage

To debug a script using tkdb invoke perl like this:

perl -d:tkdb myscript.pl

Code Pane

Line Numbers

Line numbers are presented on the left side of the window. Lines that have lines through them are not breakable. Lines that are plain text are breakable. Clicking on these line numbers will insert a breakpoint on that line and change the line number color to red. Clicking on the number again will remove the breakpoint. If you disable the breakpoint with the controls on the BrkPt notebook page the color will change to green.

Cursor Motion

If you place the cursor over a variable (i.e. $myVar, @myVar, or %myVar) and pause for a second the debugger will evaluate the current value of the variable and pop a balloon up with the evaluated result.

If there is an active selection, the text of that selection will be evaluated.

Notebook Pane

Exprs

This is a list of expressions that are evaluated each time the debugger stops. The results of the expresssion are presented heirarchically for expression that result in hashes or lists. Double clicking on such an expression will cause it to collapse; double clicking again will cause the expression to expand. Expressions are entered through Enter Expr entry, or by Alt-E when text is selected in the code pane.

The Quick Expr entry, will take an expression, evaluate it, and replace the entries contents with the result. The result is also transfered to the 'clipboard' for pasting.

Subs

Displays a list of all the packages invoked with the script heirarchially. At the bottom of the heirarchy are the subroutines within the packages. Double click on a package to expand it. Subroutines are listed by their full package names.

BrkPts

Presents a list of the breakpoints current in use. The pushbutton allows a breakpoint to be 'disabled' without removing it. Expressions can be applied to the breakpoint. If the expression evaluates to be 'true' (results in a defined value that is not 0) the debugger will stop the script. Pressing the 'Goto' button will set the text pane to that file and line where the breakpoint is set. Pressing the 'Delete' button will delete the breakpoint.

Menus

File Menu

About...

Presents a dialog box telling you about the version of tkdb. It recovers your OS name, version of perl, version of Tcl/Tk, and some other information

Open

Presents a list of files that are part of the invoked perl script. Selecting a file from this list will present this file in the text window.

Save Config...

Prompts for a filename to save the configuration to. Saves the breakpoints, expressions, eval text and window geometry. If the name given as the default is used and the script is reinvoked, this configuration will be reloaded automatically.

Restore Config...

Prompts for a filename to restore a configuration saved with the "Save Config..." menu item.

Goto Line...

Prompts for a line number. Pressing the "Okay" button sends the window to the line number entered.

Find Text...

Prompts for text to search for. Options include forward search, backwards search, and regular expression searching.

Quit

Causes the debugger and the target script to exit.

Control Menu

Run

The debugger allows the script to run to the next breakpoint or until the script exits.

Run To Here

Runs the debugger until it comes to wherever the insertion cursor in text window is placed.

Set Breakpoint

Sets a breakpoint on the line at the insertion cursor.

Clear Breakpoint

Remove a breakpoint on the at the insertion cursor.

Clear All Breakpoints

Removes all current breakpoints

Step Over

Causes the debugger to step over the next line. If the line is a subroutine call it steps over the call, stopping when the subroutine returns.

Step In

Causes the debugger to step into the next line. If the line is a subroutine call it steps into the subroutine, stopping at the first executable line within the subroutine.

Return

Runs the script until it returns from the currently executing subroutine.

Restart

Saves the breakpoints and expressions in a temporary file and restarts the script from the beginning. CAUTION: This feature will not work properly with debugging of CGI Scripts.

Stop On Warning

When -w is enabled the debugger will stop when warnings such as, "Use of uninitialized value at undef_warn.pl line N" are encountered. The debugger will stop on the NEXT line of execution since the error can't be detected until the current line has executed.

This feature can be turned on at startup by adding:

$DB::tkdb::stop_on_warning = 1 ;

to a .ptkdbrc file

Data Menu

Enter Expression

When an expression is entered in the "Enter Expression:" text box, selecting this item will enter the expression into the expression list. Each time the debugger stops this expression will be evaluated and its result updated in the list window.

Delete Expression

Deletes the highlighted expression in the expression window.

Delete All Expressions

Delete all expressions in the expression window.

Expression Eval Window

Pops up a two pane window. Expressions of virtually unlimitted length can be entered in the top pane. Pressing the 'Eval' button will cause the expression to be evaluated and its placed in the lower pane. Undo is enabled for the text in the upper pane.

HINT: You can enter multiple expressions by separating them with commas.

Stack Menu

Maintains a list of the current subroutine stack each time the debugger stops. Selecting an item from this menu will set the text in the code window to that particular subourtine entry point.

Bookmarks Menu

Maintains a list of bookmarks. The booksmarks are saved in ~/.ptkdb_bookmarks

Add Bookmark

Adds a bookmark to the bookmark list.

Options

Here is a list of the current active XResources options. Several of these can be overridden with environmental variables. Resources can be added to .Xresources or .Xdefaults depending on your X configuration. To enable these resources you must either restart your X server or use the xrdb -override resFile command. xfontsel can be used to select fonts.

/*
* Perl Tk Debugger XResources.   
* Note... These resources are subject to change.   
*
* Use 'xfontsel' to select different fonts.
*
* Append these resource to ~/.Xdefaults | ~/.Xresources
* and use xrdb -override ~/.Xdefaults | ~/.Xresources
* to activate them. 
*/

ptkdb.frame*font: fixed                    /* Menu Bar */
ptkdb.frame2.frame1.rotext.font: fixed     /* Code Pane */

ptkdb.toplevel.frame.textundo.font: fixed  /* Eval Expression Entry Window */
ptkdb.toplevel.frame1.text.font: fixed     /* Eval Expression Results Window */
ptkdb.toplevel.button.font:  fixed         /* "Eval..." Button */
ptkdb.toplevel.button1.font: fixed         /* "Clear Eval" Button */
ptkdb.toplevel.button2.font: fixed         /* "Clear Results" Button */
ptkdb.toplevel.button3.font: fixed         /* "Clear Dismiss" Button */

Environmental Variables

PTKDB_CODE_FONT

Sets the font of the Text in the code pane.

PTKDB_EXPRESSION_FONT

Sets the font used in the expression notebook page.

PTKDB_EVAL_FONT

Sets the font used in the Expression Eval Window

PTKDB_DISPLAY

Sets the X display that the ptkdb window will appear on when invoked. Useful for debugging CGI scripts on remote systems.

PTKDB_BOOKMARKS_PATH

Sets the path of the bookmarks file. Default is $ENV{'HOME'}/.ptkdb_bookmarks

FILES

.ptkdbrc

If this file is present in ~/ or in the directory where perl is invoked the file will be read and executed as a perl script before the debugger makes its initial stop at startup. There are several 'api' calls that can be used with such scripts. There is an internal variable $DB::no_stop_at_start that may be set to non-zero to prevent the debugger from stopping at the first line of the script. This is useful for debugging CGI scripts.

brkpt($fname, @lines)

Sets breakspoints on the list of lines in $fname. A warning message is generated if a line is not breakable.

condbrkpt($fname, @($line, $expr) )

Sets conditional breakpoints in $fname on pairs of $line and $expr. A warning message is generated if a line is not breakable. NOTE: the validity of the expression will not be determined until execution of that particular line.

brkonsub(@names)

Sets a breakpoint on each subroutine name listed. A warning message is generated if a subroutine does not exist. NOTE: for a script with no other packages the default package is "main::" and the subroutines would be "main::mySubs".

brkonsub_regex(@regExprs)

Uses the list of @regExprs as a list of regular expressions to set breakpoints. Sets breakpoints on every subroutine that matches any of the listed regular expressions.

NOTES

Debugging Other perlTk Applications

ptkdb can be used to debug other perlTk applications if some cautions are observed. Basically, do not click the mouse in the application's window(s) when you've entered the debugger and do not click in the debugger's window(s) while the application is running. Doing either one is not necessarily fatal, but it can confuse things that are going on and produce unexpected results.

Be aware that most perlTk applications have a central event loop. User actions, such as mouse clicks, key presses, window exposures, etc will generate 'events' that the script will process. When a perlTk application is running, its 'MainLoop' call will accept these events and then dispatch them to appropriate callbacks associated with the appropriate widgets.

Debugging CGI Scripts

One advantage of ptkdb over the builtin debugger(-d) is that it can be used to debug CGI perl scripts as they run on a web server. Be sure that that your web server's perl instalation includes Tcl::Tk.

Change your

#! /usr/local/bin/perl

to

#! /usr/local/bin/perl -d:tkdb

TIP: You can debug scripts remotely if you're using a unix based Xserver and where you are authoring the script has an Xserver. In your script insert the following BEGIN subroutine:

sub BEGIN {
  $ENV{'DISPLAY'} = "myHostname:0.0" ;
}

Be sure that your web server has permission to open windows on your Xserver (see the xhost manpage).

Access your web page with your browswer and 'submit' the script as normal. The ptkdb window should appear on myHostname's monitor. At this point you can start debugging your script. Be aware that your browser may timeout waiting for the script to run.

To expedite debugging you may want to setup your breakpoints in advance with a .ptkdbrc file and use the $DB::no_stop_at_start variable. NOTE: for debugging web scripts you may have to have the .ptkdbrc file installed in the server account's home directory (~www) or whatever username your webserver is running under. Also try installing a .ptkdbrc file in the same directory as the target script.

See also

https://github.com/vadrer/Perl-Devel-tkdb

AUTHORS

Andrew E. Page
Vadim Konovalov