Product Documentation

PDK 6.0 Documentation

PDK Debugger

What is the Graphical Debugger?

The Graphical Debugger included with the Perl Dev Kit is a lightweight yet powerful GUI debugger for Perl scripts. To start the debuggger, simply enter perl -d at the command prompt. The Perl Debugger settings, including breakpoints and bookmarks, persist from one session to another.

Some of the key features of the Perl Debugger include:

Proximity Window: Displays scalar variables near the instruction pointer, highlighting relevant items as you step through your code.
Syntax Coloring: Quoted strings, regular expressions, comments, POD, and Perl keywords are color-coded, making it easier to navigate scripts.
Detailed Information: A Call stack, list and hash dumps, several watch windows, 'Quick Eval', and conditional breakpoints all help to focus attention on essential information.

Quick Start

After installing the Perl Dev Kit, start debugging your Perl programs by running Perl with the -d option, as follows:

    perl -d <myprogram>

...where <myprogram> is the Perl program to be debugged.

Configuring the Graphical Debugger

The pdkdebug utility is used to configure the Graphical Debugger, to set the debug listener to local or remote mode, and to install (or uninstall) the debug listener as a service.

For a list of the options available, enter:

    pdkdebug --help

Switching from Local to Remote

To view the current mode of the debug listener, enter:

    pdkdebug --query

To set the debug listener to local mode, enter:

    pdkdebug --local

To set the debug listener to remote mode, enter:

    pdkdebug --remote

Use the --addr and --port switches to specify the address and port on which the service should listen. Specify either the machine name or the IP address for --addr. For example:

    pdkdebug --remote --addr 192.168.1.3 --port 2000

...runs the Graphical Debugger in remote mode, listening on IP address 192.168.1.3, port 2000. These are the same values used in the 'PERLDB_OPTS=RemotePort=<IP>:<Port>' environment variable on the remote machine.

When you change the --addr or --port setting, the pdkdebug service is automatically restarted if it is already running.

To run the debug listener interactively, do not specify the --remote switch. If no hostname is specified for the --addr switch, the debug listener will listen on all interfaces of the local machine. The --port option defaults to 2000 if not specified.

Configuring the Local Machine to Automatically Start the Debugger

Use the pdkdebug utility to configure the local debugger. Usage: pdkdebug [--local] [--remote] [-addr [x.x.x.x]] [--port [portnumber]] [--help] [--install] [--remove]

--local: Debugger is limited to debugging local scripts. Can't be used in conjunction with the --remote option.
--remote: Debugger can debug local and remote scripts. Can't be used in conjunction with the --local option.
--addr [hostname or ip]: The hostname or IP address of the computer running the Graphical Debugger.
--port [port number]: The port number where the Graphical Debugger is listening (default 2000).
--install: Installs the debug listener as a Windows service.
--remove: Uninstalls the debug listener as a Windows service.
--help: Displays the switches available for the pdkdebug utility.

Installing the Debug Listener as a Service

To install the debug listener as a service, enter:

    pdkdebug --install

To manually start the service after installing it, enter:

    net start pdkdebug

To automatically start the service after installing it, enter:

    pdkdebug --install auto

The 'auto' switch causes the service to restart every time the operating system is restarted.

To remove the service, enter:

    pdkdebug --remove

Enabling/Disabling the Graphical Debugger

After the Perl Dev Kit is installed, the PDK's Graphical Debugger becomes the default debugger, replacing the console debugger included with your Perl distribution.

To disable the Graphical Debugger included with the Perl Dev Kit and use the console debugger instead, perform the following steps:

Ensure that the Graphical Debugger is set to local mode. On the command line, enter pdkdebug --query to view the current mode. If necessary, enter pdkdebug --local to set the debug listener to local mode.
Set the debugger to the console debugger included with Perl 5.x. On the command line, enter:
```
    set PERL5DB=BEGIN { require 'perl5db.pl' }
```

Debugger Interface Overview

Pointers

Instruction Pointer: The Instruction Pointer is found in the left margin of the Source window. It points at the line that will be executed next. Use the Step Into, Step Over, Step Out or Run to Cursor commands to advance the position of the pointer.
Current Line Pointer: The Current Line Pointer indicates the currently selected line. Breakpoints or bookmarks are inserted where this pointer is positioned. You can change the position of the pointer using the 'Up' and 'Down' Arrows, as well as the 'Home', 'End', 'Page Up' and 'Page Down' keys. Press the 'Ctrl' key to scroll the window vertically without moving the Current Line Pointer.

Source Window

The source code of the Perl program is displayed in the Source window. Generally, this is the Perl program specified when you started the Perl debugger; however, if another Perl program is called during the execution of the original program, the program that is currently running is displayed in the Source window. The program is displayed line by line, and Perl syntax is colored according to the configuration of the Color tab in the Options dialog box.

To make the source window the active window, click anywhere in the window, or press 'Alt'+'S' or 'F6'.

The left margin displays breakpoint markers, bookmark markers, the Current Line Pointer, and the Instruction Pointer. The margin also displays line numbers (if this option has been enabled on the Source tab in the Options dialog box).

The Current Line Pointer can be moved via the standard keyboard navigation keys: 'Up Arrow', 'Down Arrow', 'Home', 'End', 'Page Up' and 'Page Down'. Press the 'Ctrl' key to scroll the window vertically without moving the Current Line Pointer.

The Current Line Pointer can also be moved by clicking the mouse on the desired line. Right-click or press 'Shift'+'F10' to display a shortcut menu is displayed that contains the following commands: Toggle Breakpoint, Insert Breakpoint, Edit Breakpoints, Run to Cursor and Quick Eval.

Double-clicking a variable in the Source window selects the variable. Right-clicking the selected variable displays a shortcut menu from which you can choose Quick Eval, Copy to Watch or Copy to Clipboard.

Double-clicking a line number in the margin toggles a breakpoint on that line.

On the right side of the Status Bar there are two message boxes. Double-clicking the message on the left displays the Go To Line dialog box. The second message box displays 'Ready' when the debugger is idle, and 'Working' when a program is running.

Watch Window

The Watch window displays one or more Perl expressions in the context of the Perl program that is currently running.

The result of each expression in the Watch window is updated any time a variable, in the context of the Perl program, could potentially change. Updates occur after execution is continued, when a statement is stepped over, or after the Quick Eval dialog box is used. The expressions supported are the same as those supported by the Quick Eval dialog box. Note that these expressions are evaluated from top to bottom and that expressions in the Watch window are evaluated before expressions in the Registers window.

To make the Watch window the active window, either click anywhere in the window or press 'Alt'+'W'.

To add variables to the Watch window, use one of the following methods:

Right-click in the Watch window and click Add Watch on the shortcut menu.
Double-click on or below the entry at the bottom of the list in the Watch window.
Press 'Enter' when the Watch window becomes the active window. The entry at the bottom of the list is highlighted (pressing 'Enter' with a different expression highlighted allows you to edit that particular expression).
Press 'Insert' while the Watch window is active.
Type any character when the Watch window is the active window. Any typed characters are automatically added to the Watch box when it is displayed.

You can also add variables to the Watch window by selecting the variable that you want to add in the Source window, right-clicking it, and then clicking Copy to Watch on the shortcut menu.

Edit a watch by doing any of the following:

On the shortcut menu of the Watch window, click Edit Watch.
Double-click on an existing watch expression in the Watch window.
Press the 'Enter' key when an existing watch expression in the Watch window is highlighted.

Remove a watch by doing any of the following:

Right-click on the watch expression you want to remove, and click Remove Watch on the Watch window's shortcut menu.
Select the watch expression you want to remove, and press the 'Delete'.

Right-clicking the border of the Watch window displays a menu with commands for docking and hiding the window.

Move the Watch window to any position on your screen by clicking the border of the window and dragging it to the desired location. To prevent the window from docking, hold down the 'Ctrl' key while dragging the window.

Proximity Window

The Proximity window looks and behaves much like the Watch and Registers windows, except that you cannot change the list of expressions. Instead, the list is automatically generated by the debugger, which looks at the lines of the Perl program surrounding the current statement. Specify the number of lines above and below the Instruction Pointer to scan for variables by changing the lines above and lines below options in the Watch tab of the Options dialog box.

To make the Proximity window the active window, click anywhere in the window or press 'Alt'+'P'.

Right-click in the Proximity window to display a shortcut menu with commands for hiding the Proximity window and copying the currently selected variable to the Watch window.

Right-click the border of the Proximity window to display a shortcut menu that with commands for enabling docking of the window and hiding the window.

Move the Proximity window to any position on your screen by clicking the border of the window and dragging it to the desired location. To prevent the window from docking, hold down the 'Ctrl' key while dragging the window.

Registers Window

The Registers window looks and behaves exactly like the Watch window. The only significant difference between the two is that the expressions listed in the Registers window are tied to the application instead of the currently active Perl program, making them the same for every Perl program you debug. Any changes made to the list of expressions in this window will be reflected the next time the debugger is run, regardless of the script.

The result of each expression in the Registers window is updated any time a variable, in the context of the Perl program, could potentially change. Expressions are updated after execution resumes, after a statement is stepped over, or after the Quick Eval dialog box is used. The expressions supported are the same types as those supported by the Quick Eval dialog box. Note that the expressions are evaluated from top to bottom and that expressions in the Watch window are evaluated before expressions in the Registers window.

To make the Registers window the active window, click anywhere in the window or press 'Alt'+'W'.

To add variables to the Registers window, use one of the following methods:

Right-click the Registers window, and click Add Watch on the shortcut menu.
Double-click on or below the entry at the bottom of the list in the Registers window.
Press 'Enter' when the Registers window is the active window. The entry at the bottom of the list is highlighted (pressing 'Enter' with a different expression highlighted allows you to edit that particular expression).
Press 'Insert' while the Registers window is active.
Type any character when the Registers window is the active window. Typed characters are automatically added to the Watch box when it is displayed.

Edit a watch by doing any of the following:

On the Registers window shortcut menu, click Edit Watch.
Double-click on an existing watch expression in the Registers window.
Press the 'Enter' key when an existing watch expression in the Registers window is highlighted.

Remove a watch in any of the following ways:

Right-click on the watch expression you want to remove, and on the Registers window shortcut menu, click Remove Watch.
Select the watch expression you want to remove, and press 'Delete'.

Right-clicking in the border of the Registers window displays a menu that lets you hide the window and enable docking of the window.

Move the Registers window to any position on your screen by clicking on the border of the window and dragging it to the desired location. To prevent the window from docking, hold down the 'Ctrl' key while dragging the window.

Tool Bar

The Tool Bar conveniently groups the most commonly used debugger functions. The function of each of the icons and their corresponding shortcut keys are listed below.

Continue ('F5'): Continues execution of the Perl program from the Instruction Pointer. Execution continues until either a break point is reached or the program terminates.
Stop Debugging ('Shift'+'F5'): Halts execution of the Perl program, exiting the ActiveState Perl Debugger.
Show Next Statement ('Alt'+ number): Ensures that the line indicated by the Instruction Pointer is currently visible.
Step Into ('F11'): Continues execution of the Perl program from the Instruction Pointer, stopping at the next statement, but stepping into any subroutines called.
Step Over ('F10'): Continues execution of the Perl program from the Instruction Pointer, stopping at the next statement and stepping over any called subroutines.
Step Out ('Shift'+'F11'): Continues execution of the Perl program from the Instruction Pointer, stopping after the current subroutine has returned.
Run to Cursor ('Ctrl'+'F10'): Continues execution of the Perl program from the Instruction Pointer, stopping when execution reaches the Current Line Pointer.
Insert Breakpoint ('Ctrl'+'F9'): Lets you to enter a breakpoint at an optional condition anywhere in the current file.
Remove All Breakpoints ('Ctrl'+'Shift'+'F9'): Removes all breakpoints set in the active Perl program.
Quick Eval ('Shift'+'F9'): Lets you quickly evaluate any Perl expression in the context of the Perl program you are debugging.
Toggle Watch: Shows or hides the Watch window, which displays Perl expressions that you want to watch while debugging the currently active program.
Toggle Proximity: Shows or hides the Proximity window, which displays Perl expressions that occur around the Current Line Pointer.
Toggle Registers: Shows or hides the Registers window, which displays Perl expressions you want to watch while debugging any Perl program.
Help: To get context sensitive help for the ActiveState Perl Debugger, first click the Help button, and then click on a specific topic of interest.

Debugger Menu Items

File Menu

Exit: Click Exit on the File menu to quit the application. You can also exit by clicking the close box on the right of the application's Title Bar, by clicking Close on the System menu, or by pressing 'Alt'+'F4'.; If the debugger is running, the executing Perl program will not automatically terminate and will probably have to be stopped manually using 'Ctrl'+'C'.; When the application is exited, various application settings are saved to the registry, including:

Edit Menu

Find: Click Find on the Edit Menu, or press 'Ctrl'+'F' or 'Alt'+'F3' to display the Find dialog box.
Go To Line: Click Go To Line on the Edit menu, press 'Ctrl'+'G', or double-click the Current Line Indicator in the Status Bar to display the Go To Line dialog box.
Toggle Breakpoint: Click Toggle Breakpoint on the Edit menu or the Source window shortcut menu, or press 'F9' to remove any breakpoint set at the current line, or insert an unconditional breakpoint at the current line if no breakpoint is currently set.
Insert Breakpoint: Click Insert Breakpoint on the Edit menu or press 'Ctrl'+'F9' to display the Insert Breakpoint dialog box. Clicking the Condition check box lets you to enter a condition, which, if met, causes the program to stop. If the condition is not met, the program continues to execute until it either reaches a valid breakpoint or the program terminates.
Edit Breakpoints: Click Edit Breakpoints on the Edit menu or press 'Alt'+'F9' to display the Edit Breakpoints dialog box.
Toggle Bookmark: Click Toggle Bookmark on the Edit menu or press 'Ctrl'+'F2' to remove the bookmark at the current line, or to set a bookmark at the current line if there is currently no bookmark there. Double-click on a line in the margin to toggle a bookmark.
Next Bookmark: Click Next Bookmark on the Edit menu or press 'F2' to set the current line to the next bookmarked line in the script, wraps to the top of the script if necessary, and beeps if there are no bookmarks in the script.
Previous Bookmark: Click Previous Bookmark on the Edit menu or press 'Shift'+'F2' to set the current line to the previous bookmarked line in the script, wrap to the bottom of the script if necessary, and beep if there are no bookmarks in the script.
Remove All Bookmarks: Click Remove All Bookmarks on the Edit menu or press 'Ctrl'+'Shift'+'F2' to remove all bookmarks from the script.

View Menu

Tool Bar: Click Tool Bar on the View menu to toggle display of the Tool Bar (the menu item is checked only if the Tool Bar is currently shown).
Status Bar: Click Status Bar on the View menu to display the Status Bar if it is currently hidden and hide it if it is currently displayed (The menu item is checked only if the Status Bar is currently shown).
Watch: Click Watch on the View menu to display the Watch window if it is currently hidden and hide it if it is currently displayed (the menu item is checked only if the Watch window is currently shown).
Proximity: Click Proximity on the View menu to display the Proximity window if it is currently hidden and hide it if it is currently displayed (the menu item is checked only if the Proximity window is currently shown).
Registers: Click Registers on the View menu to display the Registers window if it is currently hidden, and hide it if it is currently displayed (the menu item is checked only if the Registers window is currently shown).

Debug Menu

Continue: Click Continue on the Debug menu or press 'F5' to make the currently active Perl program continue executing either until it encounters the next breakpoint or the program is complete. If you do not insert a breakpoint, the program runs to completion, and the debugger is exited.
Stop Debugging: Click Stop Debugging on the Debug menu, or press 'Shift'+'F5' to halt debugging and exit the debugger.
Step Into: Click Step Into on the Debug menu, or press 'F11', to cause the currently active Perl program to execute the next statement. If that statement calls a subroutine, then the current statement advances to the first statement of the subroutine.
Step Over: Click Step Over on the Debug menu or press 'F10' to cause the currently active Perl program to execute the next statement. If that statement calls a subroutine, the execution continues through the subroutine normally (unless a breakpoint is set within that subroutine).
Step Out: Click Step Out on the Debug menu or press 'Shift'+'F11' to cause the currently active Perl program to continue executing until the Instruction Pointer arrives at the end of the currently executing subroutine. If there is no currently executing subroutine, the command works like Continue.
Run To Cursor: Click Run to Cursor on the Debug menu or press 'Ctrl'+'F10' to cause the currently active Perl program to continue executing until the Instruction Pointer arrives at the Current Line Pointer. The Perl script runs to completion and exits the debugger if execution never reaches the Current Line Pointer.
Quick Eval: Click Quick Eval on the Debug menu, or press 'Ctrl'+'E' or 'Shift'+'F9' to evaluate a Perl expression in the context of the Perl program currently being debugged. Type the expression into the Evaluate box and click the Eval button. The result of the Perl expression appears in the Result box. Clicking Add Watch adds the expression to the Watch window. The result of the expression is always treated as a scalar, even if the expression returns an array or hash. If you need to see the contents of an array or hash, assign the array or hash to a temporary variable, and then use the Dump Variable dialog box to view its contents.; Any Perl expression can be successfully evaluated with this dialog box, including assignments, which can be used to change variables. More specifically, any expression that is syntactically correct inside parentheses works with this dialog box. As a result, neither blocks nor multiple statements separated by semicolons are supported. Also, a match or substitution evaluated with this dialog box does not affect the global match variables ($&, $1, etc). To view the results of a match, for example, you must include them in the evaluation in some way, as in /([a-z]+)/, $1.
Dump Variable: Click Dump Variable on the Debug menu or press 'Ctrl'+'D' to display the Dump Variable dialog box. This dialog box displays the contents of the variable specified in the Variable box after the View button is clicked. If there is both a scalar and an array with the same name, both are displayed.; The Dump Variable dialog box displays the contents of a specified variable in the context of the currently executing Perl program. This dialog box calls the dumpvar subroutine provided by Perl 5.x. The text specified in the Variable box can be a scalar, array, hash or even a file handle. The $, @ or % is stripped from the variable before it is passed to dumpvar, so if the specified variable name is used by both an array and a hash, for example, the contents of both the array and the hash are displayed. See the implementation of the dumpvar subroutine for a more complete description of what is supported.
Call Stack: Click Call Stack on the Debug menu or press 'Ctrl'+'T' to display the Call Stack dialog box. This dialog box displays the call stack, or the currently active subroutines at the Current Line Pointer. The currently active subroutines is a list of subroutines that have been called but have not yet returned.; Each entry in the list of subroutine calls includes the name of the subroutine, the arguments that were passed to the subroutine (if any), and the file and line from which the subroutine was called. The Go To Line button is enabled when a subroutine call from the currently active Perl program is selected. Pressing the Go To Line button, or double-clicking a subroutine call item, closes the Call Stack dialog box and sets the current line to the line number specified by the selected subroutine call in the call stack.

Tools Menu

Edit Source: Click Edit Source on the Tools menu to open the currently active Perl script with Notepad. See the "Customize" section for information on how to change the editor and add your own User Tools.
Customize: See Customizing the Debugger.
Options: See Debugger Options Dialog Box.

Help Menu

Help Topics: Click Help Topics on the Help menu or press 'F1' to display the ActiveState Perl Debugger online help.
What's This: Click What's This? on the Help menu to enable context sensitive help. Subsequently clicking in any part of the main window displays a pop-up help window briefly describing the clicked item. Pop-ups are only available for topics covered by the online help.
About Perl Debugger: Click About Perl Debugger on the Help menu to display the About dialog box.

Customizing the Debugger

To customize the Perl Debugger, on the Tools menu, click Customize. The Customize Tools dialog box displays the list of User Tools currently available, and allows you to add, remove or change the list of User Tools. The Edit Source option on the Tools menu is the default tool and can be configured to launch your favorite editor.

You can add up to 16 tools and run them by either selecting the entry from the Tools menu or pressing 'Alt'+'1-9' for tools 1 through 9, 'Alt'+'0' for tool 10, and 'Alt'+'Shift'+'1-6' for tools 11 through 16. The names of the tools currently available are shown in the User Tools list. Selecting a tool displays the Name, Command, Arguments and Initial Directory for that tool.

The four buttons above the User Tools list allow you to add, remove and change the order of the tools. Clicking the Add button or pressing 'Alt'+'N' adds a new tool to the bottom of the list with the name "New Tool".

To add a new tool:

Click the 'New' button, located in the upper right corner of the dialog box, or press 'Alt'+'N'.
Type the name that you want to appear in the Tools menu in the Name text box. Use the & character to indicate which letter you would like to use for a quick access key.
Type the name of the application or command that you want run when the menu selection is chosen. Browse on your computer's disks by pressing the ... button.
Select the arguments you want to append to the command by clicking the button to the right of the text box and selecting one of the choices from the shortcut menu (see below for an explanation of the arguments you can select).
Choose the initial directory for the tool.
Press the Close button to add the new entry to the Tools menu.

The Arguments text box displays the arguments that will be passed to the program specified in the Command text box when the tool is selected from the Tools menu. The following strings with additional information can be passed:

$(SourcePath): The full path of the active Perl program, e.g. c:\scripts\buildbook.pl.
$(SourceDirectory): The directory of the active Perl program, e.g. c:\scripts.
$(SourceName): The name of the active Perl program, e.g. BuildBook.
$(SourceExtension): The extension of the active Perl program, e.g. .pl.
$(CurrentDirectory): The current directory of Windows, e.g. c:\My Documents.
$(CurrentLine): The number of the current line in the active Perl program, e.g. 12.
$(CurrentText): The text of the current line of the active Perl program, e.g. chomp.

You can change the order in which the entries appear on the Tools menu by selecting the entry in the Customize Tools dialog box and clicking either the up or down arrow located in the upper right corner.

To delete an entry, select the entry and either press 'Delete' or press the Delete button located in the upper right corner of the Customize Tools dialog box.

Any changes made take place immediately - there is no way to undo any changes made in this dialog box.

Debugger Options Dialog Box

General Tab

On the Tools menu, click Options, and then click the General tab to view general configurable properties. While editing options in the Options dialog box, click OK to apply the changes. Click Cancel to discard any changes.

Display Splash Screen: This check box controls whether the splash screen displays when you start ActiveState's Perl Debugger.

Reset All Settings: Click this button to discard any changes you have made to the settings, including window placement and breakpoints. This deletes settings not only for the current script, but also any other scripts you have run. (Settings are stored for as many as 100 scripts).

Source Tab

On the Tools menu, click Options, and then click on the Source tab to configure how you view your source. When editing options in the Options dialog box, click OK to apply the changes. Click Cancel to discard any changes. Clicking the Reset All settings button on the General tab returns all of the settings to their defaults.

Set Font: Displays a dialog box from which you can select the font used to display both the Perl source code and the line numbers in the left margin. The default is 10 point Courier.
Tab Size: Used to specify the number of spaces that represent one tab character in the source window. The default is 4.
WatchTips: Determines if WatchTips are displayed. With WatchTips enabled, pointing with the mouse to a variable in the source code displays the contents of that variable in a ToolTip.
BreakTips: Determines if BreakTips are displayed. With BreakTips enabled, pointing with the mouse to a breakpoint in the left margin displays the condition of the breakpoint in a ToolTip. If there is no condition, the ToolTip displays 'Break always', otherwise it displays 'Break when condition', where condition is the condition you have set for that breakpoint.
Display Line Numbers: Determines if line numbers are displayed.

Watch Tab

On the Tools menu, select Options, and then click the Watch tab to view the configurable watch properties. When editing options in the Options dialog box, click OK to apply the changes. Click Cancel to discard any changes. Clicking the Reset All settings button on the General tab returns all of the settings to their defaults.

Set Font: Displays a dialog box from which you can select the font used to display text in the Watch, Proximity and Registers windows, as well as the Quick Eval and Dump Variable dialog boxes. The default font is 10 point Courier.
Reset: Resets the variables listed in the Registers window, returning them to their default values. Default values for the Registers window are: $_, $., $&, $`, $R', and $1 through $9.
Lines Above IP: Specifies how many lines above the Instruction Pointer are scanned for variables to display in the Proximity window.
Lines Below IP: Specifies how many lines below the Instruction Pointer are scanned for variables to display in the Proximity window.

Colors Tab

On the Tools menu, select Options, and then click the Colors tab to view the configurable color properties. When editing options in the Options dialog box, click OK to apply the changes. Click Cancel to discard any changes. Clicking the Reset All settings button on the General tab returns all of the settings to their defaults.

Enable Syntax Coloring is used to set colors for the various categories of syntax in the Perl program. The components are divided into the following categories:

Source applies to Perl source code not modified by any of the categories below.
Margin applies to the margin along the left side of the source window. The foreground color specifies the color of the line numbers, while the background color specifies the color of the margin itself.
Watch sets the foreground and background colors for the Watch, Proximity and Registers windows.
Comment sets the color for any comments contained in your source code. One-line comments start with a # character. Multi-line comments start with an equal sign followed by an alphabetic character; the last line in the comment begins with =cut.
Keyword sets the color for any keywords in your source code. A complete list of keywords is contained in the file perldbpath/keywords.txt, where perldbpath is the path to where you have installed the debugger. You can edit the keywords.txt file to add or remove any keywords you want. Lines beginning with a semicolon in the file are ignored.
String determines the color that single-quoted strings are displayed in. Single-quoted strings start with a non-backslashed single-quote and end with a non-backslashed single-quote. Single-quoted strings can also start with a 'q' not immediately preceded by a letter, number, or variable prefix. The character immediately following the 'q' is used to determine where the string ends - the next non-backslashed instance of that character terminates the string (unless the character is a bracket, in which case the next non-backslashed closing version of the bracket terminates the string).
String also determines the color that double-quoted strings are displayed in. Double-quoted strings can start with a non-backslashed double-quote and end with a non-backslashed double-quote. Double-quoted strings can also start with 'qq'. (The syntax is the same as 'q' for single-quoted strings.)

Remote Debugging

Even though the Perl Debugger is running on a Windows machine, Perl scripts residing on any machine that supports Perl 5.005_03 or later can be debugged, including Linux, Solaris, HP-UX, AIX, etc.

Remote Machine Requirements

The requirements for the remote machine vary according to its version of Perl:

ActivePerl 618 or later: no additional requirements
Perl 5.6.0 or later: libnet module from CPAN or the ActiveState repository
Perl 5.005_03

perl5db.pl, located in the Perl/PDK/Debugger directory. (Replace the Perl/lib/perl5db.pl on the remote machine with this file.)

libnet module from CPAN or the ActiveState repository

Configuring the Remote Machine

The environment variable PERLDB_OPTS must point to the port where the Perl Dev Kit Perl Debugger is running. The format of the environment variable is:

    PERLDB_OPTS=RemotePort=I<IP_or_hostname>:I<Port>

...where IP_or_hostname is the IP address or hostname of the machine where the Perl Debugger resides, and Port is the port used for the connection.

Examples:

    PERLDB_OPTS=RemotePort=192.168.188.20:2000

...tells the remote machine to connect to the Perl Debugger running at IP address 192.168.188.20 on port 2000.

    PERLDB_OPTS=RemotePort=awl.ActiveState.com:2000

...tells the remote machine to connect to the Perl Debugger running at hostname awl.ActiveState.com on port 2000.

Starting the Remote Debug Session

There are two ways to start the debugger:

If you have a telnet (or similar) connection to the remote machine, you can start the debugger by invoking the program on the remote machine with the -d command-line switch.
The Perl script can be automatically invoked by the system when the -d switch is specified on the #! line, as is the case when a Perl script is called from a web server.

Note: Due to a bug in the Windows Me/98/95 command shell, you cannot set PERLDB_OPTS as an environment variable on Windows Me/98/95. This setting must be made in the Windows registry. The registry entry is HKLM\Software\Perl\PERLDB_OPTS.