Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ptkdb(3)	      User Contributed Perl Documentation	      ptkdb(3)

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

DESCRIPTION
	 ptkdb is a debugger for perl that uses	perlTk for a user interface.
	 Features include:

	   Hot Variable	Inspection
	   Breakpoint Control Panel
	   Expression List
	   Subroutine Tree

SYNOPSIS
       To debug	a script using ptkdb invoke perl like this:

	   perl	-d:ptkdb myscript.pl

Usage
	   perl	-d:ptkdb 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
	    $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 (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. 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.

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 B<Enter Expr>	entry, or by Alt-E when	text is
	  selected in the code pane.

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

	       B<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 "Okay" button sends	the
	   window to the line number entered.  item 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.  item 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.  item	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::ptkdb::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. 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.

       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 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.
	   */
	   /* 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 scrollars 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 Dismiss"	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
       PTKDB_BRKPT_COLOR
	   Sets	the background color of	a set breakpoint

       PTKDB_DISABLEDBRKPT_COLOR
	   Sets	the background color of	a disabled breakpoint

       PTKDB_CODE_FONT
	   Sets	the font of the	Text in	the code pane.

       PTKDB_CODE_SIDE
	   Sets	which side the code pane is packed onto.  Defaults to 'left'.
	   Can be set to 'left', 'right', 'top', 'bottom'.

	   Overrides the Xresource ptkdb*codeside: side.

       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_EVAL_DUMP_INDENT
	    Sets the value used	for Data::Dumper 'indent' setting. See man Data::Dumper

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

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

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.

       There is	a system ptkdbrc file in $PREFIX/lib/perl5/$VERS/Devel/ptkdbrc

       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.

       textTagConfigure(tag, ?option?, ?value?)
	   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. Currently the	following tags are in
	   effect:

	       'code'		    Format for code in the text	pane
	       '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.

	    Example:

	    #
	    # Turns off	the overstrike on lines	that you can't set a breakpoint	on
	    # and makes	the text color yellow.
	    #
	       textTagConfigure('nonbreakableLine', -overstrike	=> 0, -foreground => "yellow") ;

       add_exprs(@exprList)
	   Add 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('$_', '@_') ;

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.

       Ptkdb has its own event loop that runs whenever you've stopped at a
       breakpoint and entered the debugger. However, it	can accept events that
       are generated by	other 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.

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

       Change your

	 #! /usr/local/bin/perl

       to

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

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

KNOWN PROBLEMS
       Breakpoint Controls
	   If the size of the right hand pane is too small the breakpoint
	   controls are	not visible.  The breakpoints are still	there, the
	   window may have to be enlarged in order for them to be visible.

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

AUTHOR
       Andrew E. Page, aepage@users.sourceforge.net

ACKNOWLEDGEMENTS
       Matthew Persico	  For suggestions, and beta testing.

BUG REPORTING
       Please report bugs through the following	URL:

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

perl v5.32.1			  2004-04-01			      ptkdb(3)

NAME | DESCRIPTION | SYNOPSIS | Usage | Code Pane | Notebook Pane | Menus | Options | Environmental Variables | FILES | NOTES | KNOWN PROBLEMS | AUTHOR | ACKNOWLEDGEMENTS | BUG REPORTING

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Devel::ptkdb&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help