ptkdb is a debugger for perl that uses the perlTk user interface. It is compatable with unix versions of perlTk and Win32 versions. REQUIREMENTS ptkdb requires perl5.004 or greater and Tk400.202 or better. INSTALLATION You can use the MakeMaker interface: perl Makefile.PL make make install Or you can install the file by hand: mkdir /usr/local/alpha/lib/perl5/site_perl/Devel cp ptkdb.pm /usr/local/alpha/lib/perl5/site_perl/Devel/ptkdb.pm Or you can use the provided installation script which has a perlTk user Interface: perl install_ptkdb.pl The ptkdb.pm module can be installed in the Devel directory in anypace within INC list. You may also install it into a Devel directory that is local to a script that you are debugging. Example: /usr/local/lib/perl5/sun4-solaris/5.00404/Devel or /usr/local/lib/perl5/site_perl/Devel The install_ptkdb.pl script will provide you with a list of directories that ptkdb.pm can be installed into. USE: Once installed you can invoke ptkdb as follows: perl -d:ptkdb my_script.pl NOTE: DO NOT invoke it like this: perl -d:ptkdb.pm myscript.pl You will get an error like this: syntax error at myscript.pl line 0, near "use Devel::ptkdb." Execution of myscript.pl aborted due to compilation errors. Expressions Expressions are entered in the entry line at the bottom of the window. They are displayed in a hierarchical list on the right side of the window. Arrays, hash refs and objects are decomposed and displayed. To enter an expression type the expression in the text entry field at the bottom of the window and press CR or < Alt >-E or select "Enter Expression" from the Data menu. If there is an active selection it will be entered as the expression unless anything is in the text entry field. Breakpoints Breakpoints are inserted at the insertion point in the text window. Each breakpoint appears as a separate check box control. Toggling the control "off" will disable the breakpoint; it can be reactivated by toggling it back "on". Breakpoints can be made to be conditional by entering an expression on the text entry line. The condition will be annotated to the line. If there is an active selection then that will be used as the controlling expression. File Menu Open... Presents a selection dialog with a list of files that are part of the script being debugged. Selecting one and pressing okay, or double cliking the selection will open that file and put it into the code window. You can then add or delete breakpoints accordingly. Save Config... 'Saves' the configuration of the debugger. If you use the default name provided with the selection of the "Save Breakpoints And Expressions..." menu item your breakpoints and expressions will be re-loaded autmatically the next time your script is invoked. NOTE: If your source file(s) that contains saved breakpoints has changed since the breakpoints were last saved the debugger will prompt you to see if you want to reload them. If the line that the breakpoint was on is long longer 'breakable' the breakpoint is removed. If you're debugging myscript.pl and you select "Save Config..." the dialog will prompt you with a default name of myscript.ptkdb. To enable this feature you need to have the Data::Dumper module installed. Restore Breakpoints and Expressions Selecting this will open up a 'prompt'. Enter the name of the file that you saved with the "Save Configuration". This will restore your breakpoints and expressions that were saved in the file. These breakpoints will be automatically restored when you restart the script if you used the default name given by the "Save Config?" prompt. Goto Line... "Goto Line" works in the following fashion. Selecting "Goto Line..." or one of its accelerators will bring up a dialog box. enter the line you wish to goto in the entry box and press either CR or the Okay button. The text window will scroll to that location. The entered text will highlight itself allowing you to delete it simply by entering a new number. The dialog goes away when you press the "Dismiss" button. Find Text... "Find Text..." works in the following fashion. Selecting "Find Text..." or one of its accelerators will bring up a dialog box. enter the text that you wish to search for and press either the CR or the "Okay" button. If the search was successful the code window will scroll to the found text highlight it. Forward, backward, and regular expression searches are supported. The entered text will highlight itself allowing you to delete it simply by entering a new number. The dialog goes away when you press the "Dismiss" button. Quit Causes the debugger and the script that it's running to exit. Control Menu Run Runs the script until the script exits or until the next breakpoint. Run To Here Runs to where ever the insertion cursor is Set Breakpoint Sets a breakpoint on the line with the insertion cursor Clear Breakpoint Clears a breakpont on the line with the insertion cursor Clear All Breakpoints Removes all of the breakpoints Step Over Steps over the next line or subroutine call. Step In If the next line is a subroutine call, steps into the subroutine. If it is not a subroutine call, it steps over the line. Return Runs until the current subroutine completes or reaches a breakpoint. Data Menu Enter Expression Enters an expression in the "Enter Expr:" entry and puts into the expression window. Delete Expression Deletes the selected expression in the expression window. Delete All Expressions Deletes all of the existing expressions Expression Evaluation Window Selecting this option will open up a window for you to evaluate expressions in the context of where the debugger is currently stopped. Enter a valid perl expression in the top pane and press the 'Eval...' button. The result of the expression is placed into the lower pane. If you have the Data::Dumper module installed the text of the result will be formatted for you. Use Data Dumper for Eval Window This allows you to disable the use of Data::Dumper for formatting the results of expressions. If Data::Dumper is not installed it will be disabled. Stack Menu This menu allows you to 'walk' back up the stack of subroutine calls. Selecting an item from this menu will set the code window to look at the subroutine listed and highlight the subroutine call made. Using Control C to stop a running script. You can force a script to enter the debugger by issuing SIGINT to the script process. SIGINT is typically given by using "Control-C" on the terminal window. NOTE: For some scripts this means that the terminal window, typically an Xterm on UNIX systems or a shell in Win95/NT, will have to be the selected window. Issuing a Control-C to the debugger window may not work. Installation by ptkdb.pm or install_ptkdb.pl Click on one of the two links above. The text of the script will appear in your browser. Select "Save As..." from the File menu and save the script. If you have write access to your perl5/lib directory you can copy ptkdb.pm into the Devel/ directory. If you don't have access you can create a Devel directory in a directory that is in one of your @INC directories, or the local directory of the script being debugged. The installation script can find and install these for you. Environmental Variables These variables can be used to control the appearence of the ptkdb interface. PTKDB_STOP_TAG_COLOR Sets the color used for hilighting the line where the debugger has stopped. PTKDB_BREAKPOINT_TEXT_COLOR Sets the color used for hilighting expressions attached to conidtional breakpoints. PTKDB_CODE_FONT Font used in the code window. Standard X Font spec. Use the xfontsel utility to select one that's right for you. PTKDB_CODE_FONT_STOPPED Font used to highlight text where the debugger has stopped the program PTKDB_EXPRESSION_FONT Font used in the expression list window. Defaults to the same font specified for PTKDB_CODE_FONT. PTKDB_BUTTON_FONT Font used for the front panel buttons PTKDB_LINENUMBER_FORMAT Format(printf style %05d recommended) that will format the line numbers for the text window. The default value is "%05d ". To disable line numbers set PTKDB_LINENUMBER_FORMAT to a single space " ". PTKDB_EVAL_FONT Font used for the expression evaluation window. PTKDB_SIGINT_DISABLE Disables ptkdb's catching of a control-c when set to a non-zero value. PTKDB_EVAL_DUMP_INDENT Controls the 'Indent' value for Data::Dumper if it's available for use. Defaults to one. A value of 3 will add comments to arrays to show their indices.