|
Devel::ptkdb - Perl debugger using a Tk GUI |
Devel::ptkdb - Perl debugger using a Tk GUI
To debug a script using ptkdb invoke Perl like this:
perl <option> <script>
where
<option> is either -d:ptkdb or -dt:ptkdb
<script> is the file name to be debugged.
Example: start a debugging session of myScript.pl with multithreading support
perl -dt:ptkdb myScript.pl
ptkdb is a source debugger for Perl scripts that uses perlTk for a user interface.
It provides a wide spectrum of functionalities
The option PTKDB_BALLOON allow you to activate or deactivate this function. This may be useful on variables which store huge amount of data. The display of such variables may take lot of time and therefore considerably slow down the flow of the debugging session.
The option PTKDB_BALLOON_TIME specify the delay in millisec of the pause.
This feature is not available with Tk400.
If Data::Dumper(standard with perl5.00502)is available it will be used to format the result. If there is an active selection, the text of that selection will be evaluated. This may be useful , when th variable you want to inspect is on a non-breakable line.
Please note that this feature applies only to variables. If you want to inspect expression then select the expression and copy/past it into the quick expression window.
Please remeber that the balloon always will cut the displayed data down to PTKDB_BALLOON_MSG_MAX_LENGTH characters.
The Notebook pane contains these pages :
- Expression's page 'Exprs',
- Packages and subroutines 'Sub',
- Breakpoints definitions 'BrkPts',
- ptkdb log items 'Log'.
The 'expression frame', the 'proximity frame' and the 'quick expression frame'.
Both frames have the same format and therefore may be navigated in the same way. Nevertheless, the proximity frame is a display-only form which unlike the exprs frame cannot be manipulated. Both frames are always shown, although the parsing of the proximity is deactivated. In this case it can be reduced to a minimal size with the separating adjuster.
- The expression frame
This is a list of expressions (mostly called watched-expressions) that are evaluated each time the debugger stops. The results of the expresssion are presented hierarchically 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 proximity frame
This frame shows the content of the variables at the line of the current breakpoint.
- The quick expression frame
This frame contains an entry which will take an expression, evaluate it, and replace the entries contents with the result. The result is also transferred to the 'clipboard' for pasting.
NOTE: You may find this preferable to using
NOTES
- when you enter the filter conditions at a breakpoint, and conditions never meet on the next breakpoints, then the debbugged script either runs to end or to the next defined unconditional breakpoint. Actually, there is no way to resume the debugging session at the starting breakpoint during the current debugging session. To do that, the session must be first restarted and then repositioned manually setting the starting breakpoint again.
- the filter mechanism doesn't work when the debugging session continues by means of any 'run' command ('run', 'run to', 'return').
- usually the filter get used to force a breakpoint during the process between two unconditional breakpoints, typically on iterations or recursions.
- the filter starts working just at the time the session is continued by means of 'step in' or 'step over'.
Default value is 'ALL', which allows all kinds of TK-Events.
Remember:
- the autostep mode is automatically turned off when the commands 'run' , 'return' , 'run to' or 'quit' are entered.
- the autostep mode is also reset to off when a request is entered to evaluate an expression, a watched expression is added or deleted or the expression evaluation window is open.
- once the autostep mode is turned on, the next 'step in' or 'step over' shall start the stepping through.
- unconditional breakpoints always stop the stepping through, automatically resetting the austostep mode off.
CAUTION: This feature will not work properly on debugging sessions of CGI Scripts.
-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::ptkdb::stop_on_warning = 1 ;
to a .ptkdbrc file
Please note that the dialog content get not (yet) refreshed automatically. Thus, press the button 'Refresh' to update the shown trace.
HINT: You can enter multiple expressions by separating them with commas.
Maintains a list of the current subroutine stack each time the debugger stops. Selecting an item from this menu will cause the code page to show the file containing that particular location and make the corresponding line to appear like a breakpoint. Nevertheless, the current breakpoint isn't affected by this operation. So, the expression frame and the proximity frame remain unchanged, the evaluations window stil acts at the actual package/block of the current breakpoint.
Maintains a list of bookmarks. The bookmarks are saved in ~/.ptkdb_bookmarks
The statusbar at the upper right corner of the main window shows two important informations : the state o the configuration and the state of the debugger.
The state of the configuration is set to 'changed' on changes of breakpoints, expressions and options.
The state of the debugger can be one of these values
'ready' ptkdb is waiting on user's input 'running' the debugged process is executing after 'run' 'stepping' the debugged process is executing after 'step in/over' 'terminating' ptkdb is ending the debugging session on user's request 'session end' the debugged process entered its termination process
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.
*/
/* Set Value to se to place scrollbars on the right side of windows
CAUTION: extra whitespace at the end of the line is causing
failures with Tk800.011.
'sw' -> puts scrollbars on left, 'se' puts scrollbars on the right.
*/
ptkdb*scrollbars: sw
/* controls where the code pane is oriented, down the left side, or across the top */
/* values can be set to left, right, top, bottom */
ptkdb*codeside: left
/*
* Background color for the balloon
* CAUTION: For certain versions of Tk trailing
* characters after the color produces an error
*/
ptkdb.frame2.frame1.rotext.balloon.background: green
ptkdb.frame2.frame1.rotext.balloon.font: fixed /* Hot Variable Balloon Font */
ptkdb.frame*font: fixed /* Menu Bar */
ptkdb.frame.menubutton.font: fixed /* File menu */
ptkdb.frame2.frame1.rotext.font: fixed /* Code Pane */
ptkdb.notebook.datapage.frame1.hlist.font: fixed /* Expression Notebook Page */
ptkdb.notebook.subspage*font: fixed /* Subroutine Notebook Page */
ptkdb.notebook.brkptspage*entry.font: fixed /* Delete Breakpoint Buttons */
ptkdb.notebook.brkptspage*button.font: fixed /* Breakpoint Expression Entries */
ptkdb.notebook.brkptspage*button1.font: fixed /* Breakpoint Expression Entries */
ptkdb.notebook.brkptspage*checkbutton.font: fixed /* Breakpoint Checkbuttons */
ptkdb.notebook.brkptspage*label.font: fixed /* Breakpoint Checkbuttons */
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 Cancel" Button */
/*
* Background color for where the debugger has stopped
*/
ptkdb*stopcolor: blue
/*
* Background color for set breakpoints
*/
ptkdb*breaktagcolor*background: yellow
ptkdb*disabledbreaktagcolor*background: white
/*
* Font for where the debugger has stopped
*/
ptkdb*stopfont: -*-fixed-bold-*-*-*-*-*-*-*-*-*-*-*
/*
* Background color for the search tag
*/
ptkdb*searchtagcolor: green
Default value is 256 chars.
Overrides the Xresource ptkdb*codeside: side.
Default is 0 (disabled).
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 breakpoint at startup.
There is a system ptkdbrc file in $PREFIX/lib/perl5/$VERS/Devel/ptkdbrc
CAUTION: ptkdb evaluates the following ptkdbrc files
- $Config{'installprivlib'}/Devel/ptkdbrc
- $ENV{'HOME'}/.ptkdbrc
- ./.ptkdbrc
The ptkdbrc script may set global variables for the debugging session control, set text tag options for the code page and register callbacks.
This variable 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.
- $DB::no_stop_at_end
This variable may be set to non-zero to prevent the debugger ptkdb to stop at the end of the debugging session. When this flag is on, then a debugging session can be restarted only by means of the menu item '/Control/Restart'.
- $DB::ptkdb::stop_on_warning
This variable may be set to 1 in order to let the debugger stop the processing on warnings.
- $DB::ptkdb::stop_on_restart
This variable instructs ptkdb to set up a modal dialog in order to suspend the restart of the session. This allows to restore the test environment in the case it has been modified during the terminating debugging session. This flag may also be switched using the menu <Control/Stop on restart> .
Example:
register_user_window_init(
sub{warn ' I was there...'},
'warn " I was THERE..."'
);
- return values are discarded,
- callbacks are evaluated either as a block or as an expression.
- return values are discarded,
- callbacks are evaluated either as a block or as an expression,
- callbacks may access @Devel::ptkdb::script_args to get resp. modify the command line arguments used to start resp.restart the debugged script,
- current working directory is restored before the callbacks are called,
- callbacks are called independently of the options controlling the restart facility.
Example:
register_user_DB_entry(
sub{warn ' I was there too ...'},
'warn " I was THERE too ..."'
);
- return values are discarded,
- callbacks are evaluated either as a block or as an expression.
'code' Format for code in the text pane (obsolete)
'stoppt' Format applied to the line where the debugger is currently stopped
'breakableLine' Format applied to line numbers where the code is 'breakable'
'nonbreakableLine' Format applied to line numbers where the code is no breakable
'breaksetLine' Format applied to line numbers were a breakpoint is set
'breakdisabledLine' Format applied to line numbers were a disabled breakpoint is set
'search_tag' Format applied to text when located by a search.
'bookmark' Format of line marked as bookmark
Example: Turns off the overstrike on lines that you can't set a breakpoint on and makes the text color green.
textTagConfigure('nonbreakableLine', -overstrike => 0, -foreground => 'green') ;
Example: Adds the $_ and @_ expressions to the active list.
add_exprs('$_', '@_') ;
Arguments:
- ref to instance of the class Devel::ptkdb
- package name of breakpointed package
- filename of breakpointed script
- line number of breakpoint inside the file
Return value
- None
Arguments:
- ref to instance of the class Devel::ptkdb - package name of breakpointed package - filename of breakpointed script - line number of breakpoint inside the file
Return value
- None
ptkdb can be used to debug 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 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.
The debugger ptkdb has its own event loop that runs whenever you've stopped at a breakpoint and entered the debugger. However, it accepts all events that are generated by any perlTk windows and dispatch their callbacks. The problem here is that the application is supposed to be 'stopped', and logically the application should not be able to process events.
A future version of ptkdb will have an extension that will 'filter' events so that application events are not processed while the debugger is active, and debugger events will not be processed while the target script is active. (See also menu item 'Control/Event mask')
One advantage of ptkdb over the builtin debugger(-d or -dt) 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 installation includes Tk.
Change your
#! /usr/local/bin/perl
to
#! /usr/local/bin/perl -d:ptkdb
HINT: You can debug scripts remotely if you're using a unix based Xserver and where you are authoring the script has an Xserver. The Xserver can be another unix workstation, a Macintosh or Win32 platform with an appropriate XWindows package. You may insert in your script insert the following BEGIN subroutine
sub BEGIN {
$ENV{'DISPLAY'} = "myHostname:0.0" ;
}
or set the PTKDB_DISPLAY variable to ``myHostname:0.0'' in your server run time environment.
Be sure that your web server has permission to open windows on your Xserver (see the xhost manpage).
Access your web page with your browser 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.
ptkdb supports multithreading under the limitations set by the Perl debugger itself. Of course, the debugger must be started using the line command option -dt:ptkdb .
Under following restrictions IPC scripts may be analysed with ptkdb:
- during a debugging session ptkdb restricts breakpoints to one process checking the PID.
- forked subprocesses or threads cannot be breakpointed.
- launched child processes run in a separate debugging session, if any is requested by the specified Perl options in its start command.
- ptkdb doesn't know specialized functionalities to support IPC communications. Therefore, ptkdb event loop may collide with IPC flow (i.e. timeouts due to breakpoints).
Basically ptkdb may be used to debug graphic applications under the condition that their event loop doesn't collide with the one of PerlTk. In some cases the method Devel::ptkdb::EnterActions and Devel::ptkdb::LeaveActions could be used to deactivate to ``freeze and restart'' the graphic system during the breakpoint process. This is absolutely precondition to test time dependent graphics like simulations or games. (See also considerations 'Debugging PerlTk Applications' mentioned above).
Since Tkx basically works like PerlTk, supports ptkdb the debugging of Tkx scripts.
- reducing the size of the trace area by means of the environment option PTKDB_TRACE_ARRAY_SIZE,
- temporary deactivating the trace during non-relevant processing phase,
- emptying the trace area at breakpoints which start an interesting process step.
- a DIE-callback at initial time. It simply notice the user about the receiving of the
- an INT-callback at initial time. It should allow a soft termination on receiving the INT signal.
- a local DIE-callback at entry to each breakpoint. It should inform about die signals in registered subroutines.
Remember that subsystem, i.e. Perl/Tk, are not forced to care about existing error handlers!
Breakpoints inside threads are not supported. Thus, the debugging session is restricted to the analysis of code outside threads.
Marco Marazzi, mmarazzi@users.sourceforge.net 2008,2011 Svetoslav Marinov, svetoslavm@users.sourceforge.net 2007 Andrew E. Page, aepage@users.sourceforge.net 1998, 2007
Matthew Persico For suggestions, and beta testing. Tony Brummet For suggestions, and testing.
Please report bugs through the following URL:
http://sourceforge.net/tracker/?atid=437609&group_id=43854&func=browse
http://sourceforge.net/tracker/?atid=437612&group_id=43854&func=browse
http://lists.sourceforge.net/lists/listinfo/ptkdb-user
|
Devel::ptkdb - Perl debugger using a Tk GUI |