Komodo User Guide

Komodo Debugger Functions

The Komodo debugger is a powerful tool for developing high-quality software programs. The Komodo debugger provides the ability to analyze programs on a line-by-line basis, monitor and alter variables and watch output as it is generated. Its features include:

  • breakpoint control
  • stepping
  • watching variables
  • viewing the call stack
  • sending input
  • adding command-line arguments

Komodo's debugger also supports remote debugging, which is used mainly to open and execute a file on a remote machine and debug the file on your local machine with Komodo. This is useful for debugging CGI programs in a live Web server setting, and for systems built using client/server architecture.

This section of the user guide contains general information about the debugger that is applicable to each language. Komodo provides debugging support for Perl, Python, PHP and XSLT. For information about configuring languages and language-specific debugger functions, select a link below:

Notes

  • Perl Debugging on Windows 98/Me requires ActivePerl Build 623 or higher. Restart your machine after you install ActivePerl to ensure that your system's PATH variable is updated with the location of Perl.
  • Python Debugging on Windows 98/Me is not available in this release.
  • Remote Debugging on Windows 98 is not available in this release.
  • Ensure you meet the software prerequisites for debugging, as described in the Installation Guide.

Starting the Debugger

To start the debugger:

  • From the Debug menu, select Start or Step In
    or
  • Press F5 to Start, or F11 to Step In
    or
  • Click the Start or Step In button on the Debug Toolbar

If multiple files are open in the Editor Pane, the program that is currently displayed will be debugged. If no breakpoints have been set, the debugger will run to the end without stopping. If the Output Pane is hidden, Komodo will expand it.

You will be prompted to specify Debugging Options. To suppress display of the Debugging Options dialog, hold down the Ctrl key while clicking the desired debugging button on the Debugging Toolbar or use the desired Keyboard Shortcut.

Note that it is also possible run a program without using the Komodo debugger. Select Debug|Run Without Debugging or press F7.

Top

Debugging Options

When you invoke the debugger, the Debugging Options dialog is displayed. The Debugging Options dialog is used to configure the system environment, command line arguments, CGI environment, and other options for debugging.

(To suppress display of the Debugging Options dialog, hold down the Ctrl key while clicking the desired debugging button on the Debugging Toolbar or use the desired Keyboard Shortcut.

Debugging options for each language "persist" from one debugging session to another. For example, if you configure command-line options and environment variables when debugging a Perl script, the next time you debug a Perl script those same options and variables will be displayed in the Debugging Options dialog. Options will persist across programs and Komodo sessions; every time you change debugging options for a language, those options will remain until they are changed again.

Not all of the debugging options described below apply to all languages. For example, if you are debugging an XSLT program, there are only three options displayed on the "General" tab. The available tabs and fields depend on the value in the Debug this program using drop down list. This value defaults according to the File Associations configured for the file that is currently active in the Editor Pane.

General Tab

  • Enter the script to debug by default, the file that is currently in focus in the Editor Pane will be displayed in this field.
  • Enter command-line argument(s) for the script as required, enter arguments for the script in this field. The arguments entered in this field correspond to arguments entered on the command-line when debugging from the console. Multiple Arguments must be separated with spaces. Note that if you have checked the Simulate CGI Environment box, and entered CGI Input variables of the type GET, the contents of this field will be ignored.
  • Select the input XML file when debugging XSLT programs, specify the name and location of the input XML file in this field.
  • Start in this directory to start in a directory other than the one where the program resides, specify the directory in this field.
  • Warnings when debugging Perl scripts, you may configure the warning level used by the Perl interpreter. The options are:
    • Enable many useful warnings corresponds to Perl's "-w" command line option, and enables a subset of warnings.
    • Enable all warnings corresponds to Perl's "-W" command line option, and enables all warnings. This option is not recommended because it generates many unnecessary warnings that are not useful.
    • Disable all warnings corresponds to Perl's "-X" command line option, and disables all warnings.
  • Select the interpreter to use for debugging when debugging Tcl programs, you may use either the tclsh or the wish interpreter, depending on whether you are debugging a console or a GUI application.
  • Select the directory that contains the php.ini file if more than one version of PHP exists on your system, specify the directory that contains the php.ini file you wish to use.
  • Disable Output Buffering if this option is enabled, output from the interpreter will not be buffered, and thus will be displayed as it occurs.
  • Enable Implicit Flush tells PHP to tell the output layer to flush itself automatically after every output block. If this option is not enabled, output will be buffered.
  • Simulate CGI Environment if this box is checked, two additional tabs will be displayed: CGI Environment and CGI Input. See those topics for information about debugging CGI scripts.
  • Debug in separate console check this box to display the debug process in a console window rather than Komodo's Output Pane. The console window will, as required, both display program output and prompt for program input.

Environment Tab

The Environment tab displays all variables that are configured on your system. You can add new variables, or change the values of existing variables by adding a new variable with the same name but with a different value. (During Komodo debugging sessions, variables configured in this dialog override variables configured on your system.) Variable changes have no effect outside of the Komodo debugger, and are stored for each language from one Komodo session to the next.

The Default Environment Variables pane displays all environment variables that have been declared on your system.

  • To Add New Variables to add a new environment variable, click New, and enter the Variable Name and Variable Value in the Environment Variable dialog. To add one or more directories to the Variable Value field, click Add Path and navigate to the desired directory.
  • To Edit Existing Variables to alter a variable displayed in the Default Environment Variables pane, create a new variable with the same name and the desired value. (User Environment Variables take precedence over Default Environment Variables.) To edit an existing User Environment Variable, select the variable, click Edit, then change as desired.
  • To Delete a Variable select the variable from the User Environment Variables pane and click Delete.

CGI Environment Tab

New to CGI?
Check out the Python Tutorial

The CGI Environment tab is only displayed if the Simulate CGI Environment box is checked on the General tab. The CGI Environment tab displays CGI Environment Variables that would commonly be configured on a Web server. You can alter existing variables and add new variables. Variable changes have no effect outside of the Komodo debugger, and are stored for each language from one Komodo session to the next.

  • To Add New Variables to add a new environment variable, click New, and enter the Variable Name and Variable Value in the Environment Variable dialog. To add one or more directories to the Variable Value field, click Add Path and navigate to the desired directory.
  • To Edit Existing Variables to alter a variable displayed in the Default CGI Environment Variables pane, create a new variable with the same name and the desired value. (User CGI Environment Variables take precedence over Default CGI Environment Variables.) To edit an existing User CGI Environment Variable, select the variable, click Edit, then change as desired.
  • To Delete a Variable select the variable from the User Environment Variables pane and click Delete.

CGI Input Tab

New to CGI?
Check out the Python Tutorial

The CGI Input tab is only displayed if the Simulate CGI Environment box is checked on the General tab. It is used to configure CGI form type and variables for the purpose of simulating CGI input. Note that Komodo's CGI emulation does not generate HTTP Request Headers; rather, it executes the CGI directly by emulating a Web server environment.

  • Request Method select the request method that has been assigned to the form in the CGI program.
  • Post Type select the format in which data is sent from the browser to the server.

Use the Request Variable section of the dialog to create variables that will be processed by your CGI program. These variables will be displayed in the Browser Arguments section of the dialog.

  • In the Type field, specify the type of input associated with the variable.
  • In the Name field, enter the variable name as specified in the CGI program.
  • In the Value field, enter the value for the variable specified in the Name field. To provide a directory path and file, click the Browse Files button and select the desired file. (To accommodate file uploads, select "Multipart" as the form's POST method.)
  • Click Add.

To alter variables: click on the desired variable in the Browser Arguments section of the dialog, make changes in the Type, Name and Value fields, then click Update.

To delete variables: click on the desired variable in the Browser Arguments section of the dialog, and click Delete.

Top

Setting and Clearing Breakpoints

Breakpoints are lines in the program where you want program execution to stop. Breakpoints appear as round green symbols in the left margin of the Editor Pane. Breakpoints turn red only during debugging.

In some files there are two left margins in the Editor Pane.

  • the left-most is for folding blocks of code
  • the right-most is for breakpoints

In other files, there is only one left margin in the Editor Pane. This margin is for breakpoints only.

To set or insert breakpoints:

  • Click in the margin immediately left of the line of code.
    or
  • Press F9

To clear or remove a breakpoint:

  • Click the round green breakpoint symbol immediately left of the line of code.
    or
  • Press F9

To clear or remove multiple breakpoints:

  • From the Debug menu, select Clear All Breakpoints.
    or
  • Press Ctrl+F9

You can also toggle breakpoints using the Editor Pane's Context Menu.

Top

Sending Input to the Program

When your program prompts for input, the method of entering the input depends on whether you are debugging in a console window or in Komodo's Debug Output tab. See Debugging Options for instructions on selecting the console or the Debug Output tab.

Input via the Console If you are debugging in a console window, the program will pause at the point where it requires input. Enter the desired input in the console window, and press Enter to continue.

Input via the Debug Output tab If you are debugging in the Output tab, the program execution will pause at the point where it requires input. Enter the desired input in the Debug Output tab, and press Enter to continue.

Top

Using Debugger Commands

Debugger Command Description

This table lists common tasks and their Komodo commands.

To do this Press this
Run a program

The debugger will run until the program ends.
F7
or
from the Debug menu, select Run Without Debugging
Start the debugger

The debugger will run until it encounters a breakpoint, or until the program ends.
F5
or
from the Debug menu, select Start
or
Press the Go/Continue toolbar button
Step In

The debugger will execute the next unit of code, and then stops at the subsequent line.
F11
or
from the Debug menu, select Step In
or
Press the Step In toolbar button
Step Over

Like Step In, Step Over executes the next unit of code. However, if the next unit contains a function call, Step Over will execute the entire function then stop at the first unit outside of the function.
F10
or
from the Debug menu, select Step Over
or
Press the Step Over toolbar button
Step Out

The debugger will execute the remainder of the current function then stop at the first unit outside of the function.
Shift+F11
or
From the Debug menu, select Step Out
or
Press the Step Out toolbar button
Run to Cursor

The debugger runs until it reaches the line where the cursor is currently located.
Ctrl+F10
Stop execution Shift+F5
or
From the Debug menu, select Stop
or
Press the Stop toolbar button
Toggle breakpoint F9
or
From the Debug menu, select Toggle Breakpoint
Show Current Statement

While the debugger is running, the cursor can be moved from any position in the file to the statement at which the debugger is stopped.
Alt+*
or
From the Debug menu, select Show Current Statement

Top

Debugger Stepping Behavior

When the debugger steps over a statement, it executes that statement and stops at the next statement. If the statement being stepped over calls one or more subroutines, Step Over executes the entire statement without stopping inside any of those subroutines.

Note that the Perl operators "sort", "map", and "grep" behave like other looping constructs with respect to stepping behavior in the debugger. When Komodo has stopped at one of these operators, Step Over will stop at the first statement or expression used within the first argument of these operators.

For example, if you Step Over a statement containing a "foreach", "while", "map", "grep", or "sort" looping construct that evaluates its body five times, you stay inside that loop for five iterations. When you Step Over on the sixth iteration, you exit the loop and stop at the next statement. 

To skip execution of such looping constructs, you can set a breakpoint on the statement following the construct, and Continue until Komodo hits that breakpoint.

Top

Using the Debug Variables Tab

You can view the call stack, see the program variables, and watch variables change while you debug your programs using the Debug Variables tab in the Output Pane.

Viewing the Call Stack

A call stack is a data area or buffer used for storing requests that need to be handled by the program. Komodo's stack stores temporary data such as variables and parameters and operates as a push-down list. This means that each new data moves to the top of the stack and pushes the older data down in a "last-in, first-out" arrangement.

There is one line in this pane per stack frame at any point in the execution of a program.  The calling frame contains the information about a function call, including the filename, the line number, and any parameters or local variables.

To view the call stack:

  1. Open a file.
  2. Start the debugger.
  3. Go to the Output Pane and click the Debug Variables tab.
    The call stack is the topmost window.
Top

Viewing Variables

The Variables section of the Debug Variables tab is divided into two tabs that vary according to the language of the program that is currently being debugged. (Language variations are described below.) Variables with multiple values (such as arrays) are indicated by plus and minus symbols to the left of the variable name.

To Expand or Collapse Variables plus symbols indicate variables with multiple values that can be expanded; minus symbols indicate variables that can be collapsed. Click on the plus or minus symbol to expand or collapse the variable list.

To Change Variable Values double click in the variable's Value field and enter the desired value. (You cannot change the value of nodes in XML documents.)

Perl

While debugging Perl programs, variables are displayed on the Proximity and Register tabs:

  • Proximity tab displays variables defined or referenced near the current point of execution.
  • Register tab displays reserved Perl variables such as $_.

Python, PHP and Tcl

While debugging Python, PHP and Tcl programs, variables are displayed on the Locals and Globals tabs:

  • Locals tab displays variables referenced within the current function. If the program is currently outside of a function, all variables are displayed.
  • Globals tab displays variables used anywhere in the program.

XSLT

While debugging XSLT programs, data nodes and variables are displayed on the Locals and Globals tabs:

  • Locals tab displays data nodes from the input XML document. Only nodes contained in the context of the template specified in the Call Stack field will be displayed.
  • Globals tab displays xsl:param and xsl:variable elements declared at the top level of the program.
Top

Watching Variables

The right-most window on the Debug Variables tab is the Watched Variables pane. You can watch variables, or expressions based on variables. You can type expressions in by hand, you can drag and drop expressions from an editor, or you can drag variables from one of the variable panes immediately to the left. You can change the value of a variable in the Watched Variables pane, and you can remove a variable from the Watched Variables pane.

Watched variables can be added, manipulated and removed regardless of whether the debugger is currently running.

To watch the evolution of one or more variables as the program iterates, do one of the following:

  • Drag a variable from a Proximity/Register or Local/Global window to the Watched Variables pane window
  • Click the Add button above the Watched Variables pane and type a variable name in the dialog
  • Select the variable in the editor (or any other drag-and-drop aware application), then drag and drop the variable into the Watched Variables pane

To enter arbitrary expressions in the Watched Variables pane:

  1. Click the Add button above the Watched Variables pane
  2. Enter an arbitrary expression in the dialog
  3. Press Enter

For Perl, you can type any scalar expression in the Variable Name field of the Watched Variables pane, and watch its value change.

To change the values of variables:

  • Double-click the variable in the Watched Variables pane and specify a value.
    You can currently change values of simple variables only. You cannot change values of variables such as a Python 'a.b[3]' or a Perl '$a{b}->[3]'.

    Note - This function is not available for arbitrary expressions.


  • Double-click the variable in the Proximity/Register or Locals/Globals pane and specify a value in the dialog.

To remove a variable from the Watched Variables pane, click on the variable and click the Delete button above the Watched Variables pane.

Top

Using the Debug Output Tab

The Debug Output tab is located on the left of the Output Pane, which is below the Editor Pane. The Debug Output tab is used to view program output, to send input to the program being debugged, and to preview HTML output.

When your program produces HTML output, click the icon on the right side of the Debug Output tab for an HTML preview. Click the button a second time to display the original HTML code.

You can resize or hide the Output Pane.

Top

Watching Files

When you're debugging a program that writes output to another file, or when you want to watch programs execute, you can watch the output or the log file using Komodo's File Watcher.

This window shows a file as the file is being updated on disk. It has no relationship with variable viewing, except that while debugging it is often useful to watch variables change state and files change content.

To use the File Watcher:

  1. Go to the Tools menu and select Watch File.
  2. Browse to the appropriate file and click OK.
    An Updating File Viewer window appears.
  3. Run your program.
    The output appears in the File Viewer Window.
Top

Stopping the Debugger

To stop the Komodo debugger, do one of the following:

  • Go to the Debug menu and select Stop
    or
  • Click the Stop toolbar button

The Debug toolbar collapses and the Output Pane remains open to display the results of the execution.

Top