ptkdb(3)

NAME
Devel::ptkdb - Perl debugger using a Tk GUI

SYNOPSIS
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

DESCRIPTION
ptkdb is a source debugger for Perl scripts that uses perlTk for a user interface.

It provides a wide spectrum of functionalities

Source Code Debugging
Auto-stepping
Conditional Breakpoints
Hot Variable Inspection
Proximity window
Breakpoint Control Panel
Expression List
Expression Evaluation Window
Package and Subroutine Tree
Breakpoint trace
Breakpoint filter
Customization by file .ptkdbrc and by Environment Variables
Full session control : Save, Restore and Restart
Persistent Bookmarks

  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 $ENV{'PTKDB_BRKPT_COLOR'} (Defaults 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 $ENV{'PTKDB_DISABLEDBRKPT_COLOR'}(Defaults to Green).

Cursor Motion
    If you place the cursor over a variable or select it (i.e. $myVar, @myVar, %myVar or even $main::myvar) and pause for a while, ptkdb will evaluate the current value of the variable and pop a balloon up with the evaluated result.

    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.

  Notebook Pane
The Notebook pane contains these pages :

        - Expression's page          'Exprs',
        - Packages and subroutines  'Sub',
        - Breakpoints definitions  'BrkPts',
        - ptkdb log items          'Log'.

Exprs
    This page contains three frames:

    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.

Subs
    This page displays a list of all the packages invoked with the script hierarchially. At the bottom of the hierarchy are the subroutines within the packages. Double click on a package to expand it. Subroutines are listed by their full package names.

BrkPts
    This page 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.

Log Displays the ptkdb log items. This page is optional and depends on the options PTKDB_VERBOSE, which suppress the log items at all, and PTKDB_USE_LOG_PAGE.

MENUS

  File Menu

About...
    Presents a dialog box telling you about the version of ptkdb. It recovers your OS name, version of Perl, version of 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...
    Requires Data::Dumper. 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.

    NOTE: You may find this preferable to using

Restore Config...
    Requires Data::Dumper. Prompts for a filename to restore a configuration saved with the "Save Config..." menu item.

Goto Line...
    Prompts for a line number. Pressing the "OK" 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.

Tabs
    Set a list of tab positions for the code pane.

Close windows and Run
    Close the debugger's main windows and continue the process. This function requires that all breakpoint has been previously cleared by means of Control/Clear All breakpoints .

Quit
    Causes the debugger to terminate the debugging session.

  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.

Pass Thru
    Instructs ptkdb to deactivate all breakpoints of the current file and then to run the script.

Set breakpoint filter
    The breakpoint filter allows while stepping in/over to do an action depending on a set of conditions. When all given conditions meet, then the action is done. Actually, the action may be either a breakpoint or an entry in the DB-trace. The filter itself may be activated/deactivated at any time during the debugging session. The conditions are: the file name, the package name, the line number and an boolean expression. Defined breakpoints are not affected by the filter. The filter arguments remain valid while the debugging session and are propagated on session restart.

    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'.

Set Breakpoint
    This menu item sets a breakpoint on the line at the insertion cursor.

Clear Breakpoint
    This menu item removes a breakpoint on the at the insertion cursor.

Clear All Breakpoints
    This menu item removes all breakpoints of the current file actually defined.

Activate All Breakpoints
    This menu item activates all breakpoints of the current file.

Deactivate All Breakpoints
    This menu item deactivates all current breakpoints of the current file.

Event mask
    This menu item opens the dialog to enter the event mask for the mainloop of ptkdb itself. This may be important for applications which deal with asynchronous callbacks which has been set i.e. by means of the module After.

    Default value is 'ALL', which allows all kinds of TK-Events.

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.

Autostep
    This item immediately turns on/off the autostep mode.

    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.

Set autostep delay time
    This item sets up the dialog to change the value of the autostep delay time. This value defines the speed of the auto-stepping flow.

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. Doing that it first rebuild the command line arguments and then it issues a modal dialog to stop the process. This stop allows the user to do some actions to restore test data on disks, which possibly has been changed during the debugging session. (See also chapter FILES , items 'register_user_window_init' and 'register_user_window_end').

    CAUTION: This feature will not work properly on debugging sessions 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::ptkdb::stop_on_warning = 1 ;

    to a .ptkdbrc file

Allow calls/messages on expr
    This options prevents the watching of expression like &main::thisSub() which may corrupt the test environment when called at each breakpoint. Since ptkdb cannot analyze if a given calls is a danger for the session flow, the user itself is responsible for the correct setting of this option.

Stop On restart
    This option instructs ptkdb to stop at the time of session restart. When the debugged process doesn't change the external resources while the debugging session, it is useful to deactivate this option.

  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. An expression can be deleted either by pressing Delete key or <CTRL-D> combination.

Delete All Expressions
    Delete all expressions in the expression window.

Show DB trace
    Shows in a text windows the last 256 breakpoints. To open the file named in a trace entry select the line and press the button 'open'.

    Please note that the dialog content get not (yet) refreshed automatically. Thus, press the button 'Refresh' to update the shown trace.

Expression Eval Window
    Pops up a two pane window. Expressions of virtually unlimited 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. If Data::Dumper is available it will be used to format the resulting text. Undo is enabled for the text in the upper pane.

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

DB trace expressions
    This item enables or disables the tracing of the expressions into the DB trace area.

DB trace subroutines
    This item enables or disables the tracing of the called subroutines into the DB trace area.

DB trace is active
    This menu item enables or disables the tracing into DB-trace. The debugging may get very slow due to the DB-trace when a large amount of data get recorded i.e. during recursive traverse of trees. So, it may be useful to deactivate the trace during the process of non-relevant blocks of the debugged scripts.

Display variable at cursor position
    Enable or disable the display of the Balloon showing the variable under the cursor position.

Show Proximity Window
    Enable or disable the display of the proximity analysis.

Use Data::Dumper for Eval Window
    Enables or disables the use of Data::Dumper for formatting the results of expressions in the Eval window.

  Stack Menu
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.

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

Add Bookmark
    Adds a bookmark to the bookmark list.

Edit Bookmarks
    Edits the bookmark list.

Save Bookmarks
    Saves the bookmarks list

List of the bookmarks
    Opens the corresponding file in the code window and show the recorded line.

  Tools menu

Options
    Shows the content of the Hash %ENV, which saves all options used by ptkdb.

  Windows Menu

Code pane
    Set the focus to the Code pane.

Quick entry
    Set the focus to the Quick entry window

Expression entry
    Set the focus to the Expression entry

  Help menu

Home page
    Connect o the ptkdb home page.

Feature request
    Connect to the tracker page for enhancements requests.

Bugs report
    Connect to the bug tracker page.

Mailing list
    Connect to the ptkdb usr's info page.

About
    Shows the About-Dialog.

  Statusbar
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

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.
        */
        /* 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

ENVIRONMENTAL VARIABLES

DISPLAY
    See option PTKDB_DISPLAY below.

HOME
PTKBD_ALLOW_CALLS_IN_EXPR_LIST
    This option allows you to enter in the expression list a call to a subroutine or a message to an object. Such expression may be very dangerous for the debugging session. Messages and subroutines are designed to be called under specific conditions. This is not given when the call or the message happens on any breakpoint. Obviously, this restriction doesn't apply to strict read-only subroutines or methods.

PTKDB_AUTOSTEP_DELAY_TIME
    This option specifies the time pdtdb should delay the continuation of the process while stepping forward in autostep mode. The default value is 1500 msec. While the debugging session the delay time may be changed by means of a dialog issued by menu item 'control/set autostep delay time'. A value of 0 msec will suppress the autostep mode.

PTKDB_BALLOON
    This flag activates resp. deactivates the display of the variable at the cursor position. Default is ON.

PTKDB_BALLOON_BACKGROUND
    Background color of the Balloon. Default value is '#CCFFFF' .

PTKDB_BALLOON_MSG_MAX_LENGTH
    The value of this option limits the max length of the displayed data on the expression's balloon.

    Default value is 256 chars.

PTKDB_BALLOON_TIME
    This option specify the delay the cursor must be on a variable in order to display the variable's content on a balloon. Default value is 300 millisec.

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

PTKDB_BOOKMARKS_COLOR
    Sets the background color of a bookmarked line. Default value is "#CEFFDB" (lightgreen).

PTKDB_BRKPT_COLOR
    Sets the background color of a set breakpoint. Default value is 'red' .

PTKDB_BUTTON_FONT
    Font definition for almost all Buttons in ptkdb dialogs.

PTKDB_DISABLEDBRKPT_COLOR
    Sets the background color of a disabled breakpoint. Default value is 'green'.

PTKDB_CODE_FONT
    Sets the font of the Text in the code pane. This value defaults to ().

PTKDB_CODE_SIDE
    Sets which side the code pane is packed onto. It can be set to 'left', 'right', 'top', 'bottom'. Default value is 'left'.

    Overrides the Xresource ptkdb*codeside: side.

PTKDB_DECORATE_CODE
    This option specifies the initial state applied to the decoration of the code windows. It can be turned ON/OFF while the debugging time at any time by means of the menu checkbutton 'Data/Decorate code'. The decoration process consists of the use of foreground colors to emphasize variables depending on their type : scalar, array, hash, reference and glob.

    Default is 0 (disabled).

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

PTKDB_ENTRY_CLASS
    Sets the class name for the entry widgets : may be 'entry' or 'browseentry'. Default is 'browseentry'.

PTKDB_EVAL_FONT
    Sets the font used in the Expression Eval Window

PTKDB_EVAL_DUMP_INDENT
    Sets the value used for Data::Dumper 'indent' setting. See man Data::Dumper

PTKDB_EXPRESSION_FONT
    Sets the font used in the expression notebook page.

PTKDB_GEOMETRY
    Geometry argument for the ptkdb main window, Default value is 800x600.

PTKDB_ICONIFY
    This option let ptkdb iconify its main window when it pass the control back to the application.

PTKDB_LINENUMBER_FORMAT
    Sets the format of line numbers on the left side of the window. Default value is %05d. useful if you have a script that contains more than 99999 lines.

PTKDB_LOG_INTO_STDERR
    This option allows to print the ptkdb log items into the stream STDERR instead of stream STDOUT.

PTKDB_USE_LOG_PAGE
    This option allows to suppress the creation of the page 'Log' onto the Notebook pane of ptkdb. Default value is 1.

PTKDB_VERBOSE
    This option allows to suppress any log items of ptkdb. When this option if off then the option USE_LOG_PAGE is turned off too.

PTKDB_RESTART_STATE_FILE
    This options saves the file name of the ptkdb state file. This option is used by ptkdb itself to save/restore the session's state while the session restart process.

PTKDB_SCROLLBARS_ONRIGHT
    A non-zero value sets the scrollbars of all windows to be on the right side of the window. Useful for Windows users using ptkdb in an XWindows environment.

PTKDB_PROXIMITYWINDOWINITIALDEPTH
    This options specifies the depth of the items on the proximity window at refresh time. A value of zero (the default value) means that all items remain closed. This depth is applied each time the window is refreshed by ptkdb itself.

PTKDB_SHOWPROXIMITYWINDOW
    This options activates respectively deactivates the display of the proximity. The proximity consists of the variables involved in the line of the current breakpoint. Remember that the proximity is always analysed.

PTKDB_SIGDIE_DISABLE
    Set this option to non-zero to disable the ptkdb DIE callback. The callback simply logs the caught die-exception in DB trace and onto the STDOUT stream (see subroutine DB::dbDie). This mechanism doesn't work on Perl/Tk scripts which uses the Tk::Error module.

PTKDB_SIGINT_DISABLE
    Use the callback DB::dbint_handler for interrupts of type INT.

PTKDB_STOP_TAG_COLOR
    Set the color that highlights the line where the debugger is stopped

PTKDB_STOP_TAG_FONT
TMP or TEMP or TMPDIR or TMP_DIR or HOME
    Path to locate the state file during the restart process.

PTKDB_TRACE_ARRAY_SIZE
    Size of the array saving the ptkdb trace. Default value is 512 items.

PTKDB_TRACE_EXPRESSIONS
    This option activates or deactivates the tracing of the watched expressions into the DB trace area. Default is 0 (don't trace). This option may be turned on/off by means of menu item 'Data/DB trace expressions'.

PTKDB_TRACE_SUB_ACTIVE
    This option activates the trace of subroutine calls into DB-trace. Default value is 0 (don't trace). This option may be turned on/off by means of menu item 'Data/DB trace subroutines'.

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 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.

    Variables

    - $DB::no_stop_at_start

    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> .

    brkpt(?fname?, ?list of lines?)

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

    condbrkpt(?fname?, ?list of (?line?, ?expr?)?)

    Sets conditional breakpoints in fname on pairs of (line,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(?list of names?)

    This command sets a breakpoint on each subroutine name found in the list. 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(?list of regexp?)

    This command uses ?list of regexp? to set breakpoints. Sets breakpoints on every subroutine that matches any of the listed regular expressions.

    register_user_window_init(?list of callbacks?)

    This command registers a list of subroutine references or eval-strings that will be called whenever ptkdb sets up it's windows

    Example:

            register_user_window_init(
                    sub{warn ' I was there...'},
                    'warn " I was THERE..."'
                    );

    register_user_window_end (?list of callbacks?)

    This command registers a list of subroutine references or eval-strings that will be called when ptkdb terminates the debugging session.

    Coding notes about registered window init and end subroutines

    - callbacks take no argument list,

    - return values are discarded,

    - callbacks are evaluated either as a block or as an expression.

    register_user_restart_entry (?list of callbacks?)

    Coding notes about registered window init and end subroutines

    - callbacks take no argument list,

    - 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.

    register_user_DB_entry(?list of callbacks?)

    This command registers a list of subroutine references or eval-strings that will be called whenever ptkdb enters from debugged code into breakpoint processing.

    Example:

            register_user_DB_entry(
            sub{warn ' I was there too ...'},
            'warn " I was THERE too ..."'
            );

    register_user_DB_leave(?list of callbacks?)

    This command registers a list of subroutine references or eval-strings that will be called whenever ptkdb leaves breakpoint processing and returns to the debugged code.

    Coding notes about registered DB entry and leave subroutines

    - callbacks take the argument list ($package,$filename,$line),

    - return values are discarded,

    - callbacks are evaluated either as a block or as an expression.

    textTagConfigure(tag, ?option?, ?value?)

    This command allows the user to format the text in the code window. The option value pairs are the same values as the option for the tagConfigure method documented in Tk::Text. Actually, the following tags are in effect:

            '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') ;

    add_exprs(?list of expr?)

    This command adds a list of expressions to the 'Exprs' window. NOTE: use the single quote character \' to prevent the expression from being "evaluated" in the string context.

    Example: Adds the $_ and @_ expressions to the active list.

            add_exprs('$_', '@_') ;

  Other customizations

Callback EnterActions
    This method of package Devel::ptkdb is called at the beginning of each breakpoint processing. It may be overwritten in order to perform some particular processing with the actual application data.

    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

Callback LeaveActions
    This method of package Devel::ptkdb is called at the and of each breakpoint processing, that means just before the control goes back to Perl code. Like the callback mentioned above it may be overwritten in order to perform some particular post-processing of the actual application data.

    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

NOTES

  Debugging perlTk Applications
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')

  Debugging CGI Scripts
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.

  Debugging multithread
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 .

  Debugging IPC
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).

  Debugging graphic application other than PerlTk.
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.

KNOWN PROBLEMS

Breakpoint Controls
    Usually the notebook widget shows the expression page. Though, when a breakpoint is set in the text window, the notebook widget switches to the breakpoint page. When the next breakpoint is shown, the expression page is automatically redisplayed. When the list of breakpoints is large, the page switching may take a little bit time ...

Breakpoint trace
    The trace should allow to record what happened during the session. So, the recorded expressions can be used to inspect the state of variables at the various breakpoints. This has a major drawback. When the recorded data get large, then the time to build up the trace display get dramatically long. I experienced setup times of many seconds for a trace of about 150K. Clearly, this problem may be controlled in several ways:

    - 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.

Debugging exceptions
    ptkdb sets up these callbacks as simple error handlers :

    - 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!

Balloons and Tk400
    The Balloons in Tk400 will not work with ptkdb. All other functions are supported, but the Balloons require Tk800 or higher.

Multithreading scripts
    The debugging sessions of multithread-scripts must be started with -dt:ptkdb.

    Breakpoints inside threads are not supported. Thus, the debugging session is restricted to the analysis of code outside threads.

Forked subprocesses
    ptkdb has been changed in order to ignore the flow of forked processes. Though, it is quite easily to implement a customized functionality , for instance to record the subprocess flow in a persistent trace stack.

Perl/Tk
    Analysis of Perl/Tk scripts may be shaky due to the interference of the additional TK-activities and resource of the ptkdb itself.

AUTHOR
Marco Marazzi, mmarazzi@users.sourceforge.net 2008,2011 Svetoslav Marinov, svetoslavm@users.sourceforge.net 2007 Andrew E. Page, aepage@users.sourceforge.net 1998, 2007

ACKNOWLEDGEMENTS
Matthew Persico For suggestions, and beta testing. Tony Brummet For suggestions, and testing.

BUG REPORTING
Please report bugs through the following URL:

http://sourceforge.net/tracker/?atid=437609&group_id=43854&func=browse

FEATURE REQUEST
http://sourceforge.net/tracker/?atid=437612&group_id=43854&func=browse

MAILING LIST
http://lists.sourceforge.net/lists/listinfo/ptkdb-user

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 6563:
    You can't have =items (as at line 6569) unless the first thing after the =over is an =item