



	advanced \| search help

Reference

Tcl Dev Kit

Getting Started

TclApp

Compiler

Debugger

Managing Projects

Opening a File

Controlling Your Application

Using Breakpoints

Navigating Code

Displaying Code and Data

Manipulating Data

Error Handling

STDIN, STDOUT and STDERR

Code Profiling and Coverage

Setting Preferences

About Instrumentation

Remote Debugging

Using Custom Interpreters

Cross Reference Tool

Checker

Service Manager

Inspector

Package Editor

TEA Package Management

Virtual Filesystem Explorer

Reference

Tutorials

MyASPN >> Reference >> Tcl Dev Kit

Debugger

The Tcl Dev Kit Debugger provides a variety of features that help you to find and fix bugs in Tcl scripts quickly. These features include:

Stepping functions for evaluating single Tcl commands, or running to the current cursor position in the code
Display of variable values for all accessible stack frames
Full stack information and navigation around the stack and source code when the application is stopped
Line-based and variable-based breakpoints
An Eval Console in which you can enter code for the application to evaluate dynamically when the application is stopped
Code coverage and profiling
The ability to interrupt code to determine the execution status of the application that you are debugging
The ability to communicate with remote and embedded applications
The ability to debug multiple processes

Overview

This section lists the platforms and Tcl versions that the Tcl Dev Kit Debugger supports. It then describes how to start the Tcl Dev Kit Debugger and provides a tour of the Tcl Dev Kit Debugger main window.

Supported Tcl Versions

The Tcl Dev Kit Debugger can debug any Tcl/Tk script running in a Tcl version 7.6 and Tk version 4.2 or later interpreter. This includes any extensions to those interpreters that do not radically redefine any standard Tcl commands.

Important: Renaming or radically redefining any standard Tcl commands may cause the Tcl Dev Kit Debugger to fail. An example of a radical redefinition of the proc command would be to redefine it to take four arguments instead of three. In particular, avoid altering the Tcl commands listed below:

array	break	catch	cd	close	concat	continue
eof	error	eval	event	exit	expr	fconfigure
file	fileevent	flush	for	foreach	gets	global
if	incr	info	lappend	lindex	linsert	list
llength	lrange	lreplace	lsearch	namespace	open	proc
puts	pwd	read	regexp	regsub	rename	return
set	string	switch	trace	unset	uplevel
upvar	variable	vwait	while

Starting the Tcl Dev Kit Debugger

To run the Tcl Dev Kit Debugger on a Windows system, select Tcl Dev Kit Debugger from the Tcl Dev Kit program group on the Windows Start menu, or double-click the tcldebugger.exe file (the default location is C:\Tcl\bin). Alternatively, enter tcldebugger.exe at the command prompt. To enable Code Profiling and Coverage, select File|Project Settings and choose one of the options on the Coverage & Profiling tab.

To run the Tcl Dev Kit Debugger on a Unix system, enter tcldebugger at the shell prompt.

The Tcl Dev Kit Debugger Main Window

The main window is made up of the following components:

Toolbar
Stack Frames display
Variable display
Code display
Result display

The menus and toolbar in the main window are used run, step through, interrupt, kill, or restart your code. You can change the appearance of the Tcl Dev Kit Debugger by toggling the display of elements in the main window from the View menu:

Toolbar - Select View|Toolbar.
Result display - Select View|Result.
Status bar - Select View|Status.
Line numbers - Select View|Line Numbers.

The Toolbar

The function of each button is described in the following sections.

When you hover the mouse over a toolbar button, a description of the functionality appears as a pop-up below the mouse pointer and on the left side of the status bar.

The Stack Frames Display

The Stack Frames display shows the most recent stack levels and highlights the current location in your code when the application is stopped. If you select a stack level, the Tcl Dev Kit Debugger shows the code and variable values for that stack level in the Code display and the Variable display. When the application encounters a breakpoint, the last stack frame is automatically selected and highlighted in the Stack Frame display. The call stack includes an entry for each distinct scope or body of code. It displays stack frame information in this format: stack level, Tcl command, and relevant arguments. Stack level 0 indicates the global level. Stack level 1 indicates that a procedure is invoked from level 0; stack level 2 indicates that a procedure is invoked from stack level 1, and so on.

Note: If your code is in an event loop when you click the Pause button, no code is shown in the Code display and the top level in the stack frame displays "event."

The following example shows a sample stack frame:

0 global
0 source myScriptFile
1 proc myProc arg1 arg2 arg3
2 namespace eval myNamespace
3 proc myproc3
0 uplevel
1 proc myproc3 args

In this example, the stack level is reset to 0 by the uplevel command; the uplevel command can be called explicitly in your source code or implicitly by a callback. As with any other procedure call, the namespace eval command creates a new level.

You can navigate through the application by clicking on specific stack frames, which affects both the Variable and Code displays. When you double-click any part of a stack frame, the Code display scrolls to and highlights the current command in that stack frame. For example, if you want to see the code that caused a stack frame to be created, you can double-click the frame directly above the frame in question. In addition to highlighting the current command, if the last stack frame is selected, the Tcl Dev Kit Debugger indicates the current command with a yellow Run Arrow in the Code bar. The Tcl Dev Kit Debugger also indicates the current command with a green triangular History Arrow in the Code bar. When you click a stack frame, the Variable display shows the variables in that stack frame. For example, if you want to see global variables, you can double-click any Level 0 stack frame. If you click directly on an argument in a proc stack frame, the Variable window scrolls to and highlights the selected argument.

The Variable Display

The Variable display shows all of the existing variables in the selected stack frame. The value of each variable is updated whenever the application is stopped. The value for each array appears as an ellipsis (...). You can expand and contract the display of the array by clicking the ellipsis. When an array is expanded, each index is listed with its corresponding value.

To set a variable breakpoint, click the breakpoint margin to the left of the variable display. The application will stop whenever the variable is modified. See Manipulating Breakpoints for more information.

When a variable value exceeds the size of the display, double-click the variable to open the Data Display window, which will show the entire value. See Displaying Data for more information.

Variable Value Formats

In each of the windows where variable values are displayed (the Variable pane, the Data Display window and the Watch Variables window), you can configure the format in which the variable values are displayed. Right-click the variable in the Variable pane and select the desired format. The following formats are supported:

String: As Hex
String: As Octal
String: As Unicode
Integer: As Hex (must be an integer)
Integer: As Octal (must be an integer)
Integer: As Bits (must be an integer)

If the chosen format is not appropriate for the specified variable (for example, selecting Integer: As Hex for a variable that contains a non-numeric string), the format transformation will not be performed.

When specifying the format for variable values, note that the format specified in either the Variable pane or the Watch Variables window will be inherited by the Data Display window (depending on which source was used to call the Data Display window).

If the message "No variable info for this stack" appears in the Variable display, it means that the stack level that is highlighted in the Stack display is hidden. Stack levels are hidden as a result of calls to Tcl commands like vwait and uplevel. When vwait is called, it creates a new stack, and all of the non-zero levels of the old stack are hidden until the vwait call returns. When uplevel is called with the absolute level for x, all of the levels of the old stack that are greater than x are hidden until the uplevel call returns.

The Code Display

The Code display shows exactly one Tcl code source at a time. A code source is a file opened from the File menu, a file that has been sourced by the application, or a chunk of code dynamically created at runtime by commands such as eval. The Window menu lists all the open files, allowing you to select the file you want to view. You can also select a code source to view from the Breakpoint and Procedures windows. See Using Breakpoints and Finding Procedures.

When the application is stopped, an arrow or triangle appears in the code bar indicating the current command with highlighted text. For example, in the Tcl Dev Kit Debugger main window, the portion of the code that is highlighted is code that is about to be executed and it is also indicated by the yellow run arrow in the code bar. Code is also highlighted if it is found using the Find command. See Going to a Specified Line for information on commands that you can use to move through and search for specific portions of code.

If you see the message "No Source Code..." in the Code display, there are two possible reasons:

If your application is in the event loop when you click the Pause button, the Tcl Dev Kit Debugger cannot display code because no code is being evaluated.
The Tcl Dev Kit Debugger cannot display code for the first stack level labeled "global" because your application's code is sourced by code internal to the Tcl Dev Kit Debugger.

The Status Bar

The status bar is located at the bottom of the Tcl Dev Kit Debugger. The section on the left displays the information about the state of the debugger session. If you hover the mouse pointer over a toolbar button, this section of the status bar will display a usage tip for the button.

Errors and warnings are indicated by the red and yellow icons in the middle of the status bar. The background color of these icons is configured in the debugger preferences.

To the right of the errors and warnings icons, an asterisk ("*") will be displayed if the current code source is uninstrumented. See About Tcl Dev Kit Instrumentation for more information.

The far right portion of the status bar displays the current file name and path and line number.

The Result Display

The Result display shows the result and completion code of the most recently executed Tcl command. The Result display is not a scrolling window; the Tcl Dev Kit Debugger displays only as much of the result as can fit in the Result display. You can double-click on the result to display it in the Data Display window (see Displaying Data).

Note: The performance of the Tcl Dev Kit Debugger can decrease if your application produces particularly long results (for example, reading a large file into a variable) and you have the Result display visible. If you want to increase performance in cases like this, toggle off the Result display by selecting View|Result.

Top

Managing Projects

You can manage multiple projects with the Tcl Dev Kit Debugger. The Tcl Dev Kit Debugger saves project information in files with the .tpj extension. Projects store a variety of information about an application including:

the name of the initial Tcl script
the interpreter
any command-line arguments you pass to the script
the current working directory
any line breakpoints you have set
any variables in your watch list

The file format for debugger projects changed after the first version of the Tcl Dev Kit. Version 1 .tpj files can still be opened by the debugger; changes to version 1 projects will still be stored in the version 1 format. However, information about variable value formatting cannot be stored in version 1 project files. New projects use the latest .tpj format.

By default, when the Tcl Dev Kit Debugger starts, it automatically reloads the last project you had open. You can change this behavior as described in Startup and Exit Preferences.

Note: You must have a project open to perform any debugging actions.

Creating a New Project

To create a new project:

Select File|New Project. If you have a project already open, Tcl Dev Kit Debugger prompts you to save that project.

The Tcl Dev Kit Debugger Project window will open.

Select Local Debugging to debug a Tcl script running normally on your system. Select Remote Debugging only to debug a remote, embedded, or CGI Tcl application. See Debugging Remote, Embedded, and CGI Applications for information on remote debugging.
In the Script field, type the path and name of the Tcl script to run, or click the Browse button next to the field to locate the Tcl script.
(Optional) In the Script Arguments field, type any script arguments you want to pass to the script when you run it under the debugger.
(Optional) In the Working Directory field, type the full path of the directory that you want to use for the working directory inside the Tcl/Tk script. If you don't specify a working directory, the Tcl Dev Kit Debugger uses the directory that contains the Tcl script you are debugging.
In the Interpreter field, type the path and name of the Tcl interpreter or click the Browse button next to the field to locate the interpreter. You can use the standard Tcl interpreter or a custom Tcl shell. You can also choose one from the drop-down list, which contains a list of Tcl interpreters set by your project defaults.

Note: The Tcl Dev Kit Debugger works properly with most custom Tcl interpreters. However, if your interpreter doesn't accept as its first command-line argument a Tcl script to execute or if it doesn't pass subsequent command-line arguments to the script using the standard argc and argv Tcl variables, then you must take special steps to use your interpreter with the Tcl Dev Kit Debugger. See Using Custom Tcl Interpreters with the Tcl Dev Kit Debugger for more information.

Tip: If there are one or more interpreters you commonly use, you can change your default project settings to include them in the Interpreter drop-down list:

Bring up the default project settings, as described in Setting Default Project Settings.
Type the path and name of the Tcl interpreter or click the Browse button next to the field to locate the first interpreter you want to appear in the drop-down list.
Repeat for each interpreter that you want to add to the list.
Save your default project settings.

The interpreters you specify are now available for all new projects you create afterwards.

The Instrumentation and Errors tabs allow you to fine tune the Tcl Dev Kit Debugger's control over your application as you debug it. See Changing Project Settings for information on these tabs.
Click the OK button to apply your choices and close the Project window, the Cancel button to cancel your choices and not open the new project, or the Apply button to apply your choices and keep the Project window open.

Once you create your new project, the Tcl Dev Kit Debugger displays the Tcl script file you specified in the Code display of the main window. The Tcl Dev Kit Debugger does not run the script until you tell it to do so, as described in Controlling your Application.

Opening an Existing Project

There are two ways that you can open an existing project in the Tcl Dev Kit Debugger:

Select File|Open Project, and select the project file you want to open from the file browser displayed.
Select File|Recent Projects and select the project file you want to open.

If you already have a project open, the Tcl Dev Kit Debugger asks if you want to save that project.

When you open an existing project, the Tcl Dev Kit Debugger restores all of the project settings and breakpoints in effect when you saved the project. The Tcl Dev Kit Debugger also displays the Tcl script file that you were viewing when you saved the project.

Saving a Project

To save a project, select File|Save Project. The first time you save a project, specify the file name and location for your project. The Tcl Dev Kit Debugger saves your project settings and any breakpoints and any watch variables you have set.

To save a project with a different name, select File|Save Project As.

Closing a Project

To close a project, select File|Close Project. If you made changes, the Tcl Dev Kit Debugger asks if you want to save the project before closing it.

Closing a project closes the project file and clears all the Tcl Dev Kit Debugger displays.

Changing Project Settings

To change the settings of the current project, select File|Project Settings. The Tcl Dev Kit Debugger displays the Project window. From this window you can change the script, interpreter, instrumentation, error, and coverage and profiling settings for a project as described in the sections below.

Note: Changes that you apply to your project settings while your application is running don't take effect until the next time you restart your application.

Changing Project Application Settings

The Application tab lets you select basic application settings such as the Tcl script to debug and the Tcl interpreter to use. The contents of the Application tab depend on the Debugging Type option you select:

Local Debugging
Debug a Tcl script running normally on your system.
Remote Debugging
Debug a remote, embedded, or CGI Tcl application. See Debugging Remote, Embedded, and CGI Applications for information on remote debugging.

If you select the Local Debugging option, the Application tab appears as shown below.

You can change the following Local Debugging settings for a project:

Script Type - the pathname of the Tcl script to run, or click the Browse button next to the field to locate the Tcl script. You can also select the script from the drop-down list, which lists scripts that you have used recently in this project.
Script Arguments - Type any script arguments you want to pass to the script when you run it under the debugger. You can also select the arguments from the drop-down list, which lists the arguments that you have specified recently in this project.
Working Directory - Type the full path of the directory that you want to use for the working directory inside the Tcl/Tk script. If you don't specify a working directory, the Tcl Dev Kit Debugger uses the directory that contains the Tcl script you are debugging. You can also select the working directory from the drop-down list, which lists the working directories that you have used recently in this project.
Interpreter - Type the path and name of the Tcl interpreter or click the Browse button next to the field to locate the interpreter. You can use a standard Tcl interpreter or a custom Tcl shell. You can also choose one from the drop-down list, which contains Tcl interpreters that have been installed in the standard locations on your computer and any other Tcl interpreters that you have previously specified for this project.

If you select the Remote Debugging option, the Application tab appears as shown below.

The only application setting you can change when debugging remotely is the TCP port that the Tcl Dev Kit Debugger uses to communicate with the remote application. This is the port that you need to pass to debugger_init when starting your debugging session from a remote application. See Debugging Remote, Embedded, and CGI Applications for information on remote debugging.

Note: Changes that you apply to your project settings (by clicking either the OK or Apply button) while your application is running don't take effect until the next time you restart your application.

Changing Project Instrumentation Settings

The Instrumentation tab lets you select files and classes of procedures that the Tcl Dev Kit Debugger should and should not instrument. Instrumenting a file gives the Tcl Dev Kit Debugger control over its execution, and allows you to set breakpoints, single-step through the file, and perform other debugging tasks. If a file is not instrumented, you can't perform debugging tasks while your application is executing the file (or procedures defined in that file). For more information about instrumentation, see About Tcl Dev Kit Instrumentation.

Some cases of when you would want to control which files are instrumented and which files are not include:

When you use a common Tcl script library for several projects in your organization. In this case, you would most likely debug the library separately and then instruct the Tcl Dev Kit Debugger not to instrument the library when you later debug individual projects that use that library.
When you debug large applications. Instrumenting a script takes time and slows the execution of your application. To minimize the overhead of debugging, it is more efficient to instrument and debug portions of your application separately.

The top half of the Project Instrumentation dialog determines the files that the Tcl Dev Kit Debugger instruments. (By default, all files are instrumented.) The first list box identifies a set of files to instrument, and the second list box identifies a subset of exceptions that are not instrumented. File name patterns follow the "string match" pattern conventions. (See the Tcl "string manual page" in the ActiveTcl User Guide for more information on pattern syntax.) Whenever your application sources a script file, the Tcl Dev Kit Debugger compares the file name against the patterns you specify in this dialog to determine whether to instrument it. For example, setting the pattern "app*.tcl" in the first list box and "*GUI.tcl" in the second list box causes the Tcl Dev Kit Debugger to instrument files such as appMain.tcl and appStats.tcl, but not instrument a file named appGUI.tcl. The patterns will match file names in both absolute and relative paths.

To add a pattern to a list box, type the pattern in the String Match Pattern field, and then click the Add button next to the appropriate list box. To remove a pattern from the list, click the file or pattern to highlight it, then click the Remove button.

Note: If you delete all patterns in the first list box and then apply the setting (by clicking either the OK or Apply button), the Tcl Dev Kit Debugger automatically adds the pattern "*" to the first list box. If the Tcl Dev Kit Debugger didn't do this, then you could accidentally cause the Tcl Dev Kit Debugger not to instrument any files, in which case you couldn't control your application with the debugger.

The lower half of the Project Instrumentation dialog provides finer control of the instrumentation of procedures and control structures in a script file:

Instrument Dynamic Procs - Instrument procedures that you create dynamically. For example, selecting this check box instruments procedures created by the eval command.
Instrument Auto Loaded Scripts - Automatically instrument auto-loaded scripts. You might want to turn this option off if you are using only standard Tcl extensions.
Instrument [incr Tcl] - Instrument all your [incr Tcl] classes and methods.
Instrument TclX - Instrument control structures in the TclX package, such as the loop command.
Instrument Expect - Instrument the control structures in the Expect package, such as the expect command.

Changing Project Startup and Exit Settings

Use the Startup & Exit tab to specify how the Tcl Dev Kit Debugger handles subprocesses.

Automatically add all spawnpoints to any newly loaded script - When debugging multiple processes, the Tcl Dev Kit Debugger detects lines in the script containing spawn commands and automatically sets spawnpoints in the debugger's main window.
Automatically kill a spawned sub-session when its application completes - When debugging multiple processes, the Tcl Dev Kit Debugger will automatically close the debugger's connection with a subprocess when the script for that subprocess has run.

Changing Project Error Settings

The Errors tab lets you specify how the Tcl Dev Kit Debugger handles errors in your Tcl script:

Always Stop on Errors - The Tcl Dev Kit Debugger notifies you each time it encounters an error in the script (The Tcl Dev Kit stops execution of your script even if your script catches the error).
Only Stop on Uncaught Errors - The Tcl Dev Kit Debugger notifies you only when it encounters an error not caught by the script (The Tcl Dev Kit stops execution of your script only if your script does not catch the error).
Never Stop on Errors - The Tcl Dev Kit Debugger does not notify you about any errors in the application.

Note: For more information on how the Tcl Dev Kit Debugger handles errors, see Error Handling.

Changing Project Coverage and Profiling Settings

The Coverage & Profiling tab lets you choose to run the Tcl Dev Kit Debugger with coverage or profiling or neither. By default, new debugger projects run with neither coverage nor profiling. To change the setting, select File|Project Settings, and click the Coverage & Profiling tab. The setting specified here will determine what type of results are displayed in the Code Coverage and Profiling dialog box (Edit|Code Coverage). Select one of the following options:

Neither coverage nor profiling - No lines are highlighted during debugging and no results are reported in the Code Coverage & Profiling dialog box.
Plain coverage - Depending on the options specified in the Code Coverage & Profiling dialog box, lines of either covered or uncovered code will be highlighted, and details about files for which the debugger has collected coverage information will be displayed in the Code Coverage and Profiling dialog box. When you select this option, the Calls tab displays a table indicating the number of calls to each line in each file executed by the debugger, along with the file names and line numbers.
Profiling - This option produces the same results as the "Plain coverage" option (described above), and, additionally, the table on the Calls tab reports the time required for the system to execute commands. This information is contained in columns representing the minimum, maximum, and average time spent on an executed command, relative to the entire run. All times are in microseconds.

For more information see Code Profiling and Coverage.

Setting Default Project Settings

You can change any of the default project settings so that new projects you create have those settings. Changing the default project settings doesn't affect any existing projects you might have.

For example, if you commonly use a set of packages that you don't want the Tcl Dev Kit Debugger to instrument, you could set those files in the default project settings. Then, any new project you create would pick up those instrumentation settings by default.

To set the default project settings:

If you have a project already open, select File|Close Project to close that project.
Select File|Default Project Settings. (The Tcl Dev Kit Debugger displays this option only if you have no projects currently open.) The Tcl Dev Kit Debugger displays the Default Project Settings window. This window has the same tabs and settings available as in the Project window.

Set the default project settings just as you set an individual project's settings. See Changing Project Settings for a description of all project settings.
After changing the default project settings, click the OK button to save your choices and close the Default Project Settings window, the Cancel button to cancel your choices and close the Default Project Settings window, or the Apply button to apply your choice and keep the Default Project Settings window open.

Top

Opening a File

Opening a file in the Tcl Dev Kit Debugger gives you the opportunity to create or check existing line-based breakpoints in the file before the file is sourced in the application. Breakpoints cause the application to stop before a line of code is executed so that you can examine the state of the application that you are debugging. See Using Breakpoints.

To open a file:

Select File|Open File.
Type the full path and name of the file or browse and click the file that you want to open.

The file that you opened appears in the Tcl Dev Kit Debugger. You can view it using the scroll bars and menus.

Tip: You can open a file at any time, even when an application is already running. When you open a file, the Tcl Dev Kit Debugger reloads the file if the file has not been sourced by the running application or if no application is running. If the application is running and has sourced the file, modifications to that file cannot be seen in the Code display until that file is sourced again or the file is reopened after the application is terminated.

Top

Controlling Your Application

This section describes how to use the basic features of the Tcl Dev Kit Debugger.

Running Code with the Tcl Dev Kit Debugger

Click the Run button to run your code with the Tcl Dev Kit Debugger. When the application stops, the Tcl Dev Kit Debugger indicates the line of code that it is processing with an arrow and highlights the portion of the line that it is about to execute.

Once the application is running, it stops at these events:

At breakpoints. For information about breakpoints, see Using Breakpoints.
If an error is detected, the Tcl Dev Kit Debugger stops on the line of code that generated the error, and the code that caused the error is highlighted. See Error Handling.
If you click the Run to Cursor icon in the toolbar, the application runs to the line where you placed your cursor.

Run to Cursor

The Run to Cursor button lets you to create a temporary breakpoint that is automatically removed the next time the Tcl Dev Kit Debugger stops. When your application is stopped, you can move the cursor to the line of code where you want to stop, and press the Run To Cursor button.

Note: If the application stops for any reason, such as encountering another breakpoint or reaching the line containing the cursor, the temporary breakpoint is removed. The operation of the Run to Cursor feature is similar to those of line-based breakpoints. If the cursor is not set, or if it is on a line that is either empty or contains only comments or curly braces, clicking the Run to Cursor button is equivalent to clicking the Run button. The application stops just before evaluating the first command on the line regardless of where you place the cursor on a line of code.

Stepping through Code

The Tcl Dev Kit Debugger offers four ways of stepping through your scripts: Step In, Step Out, Step Over, and Step To Result. When your application is stopped, you can step from the current command, indicated by the yellow run arrow in the code bar. To use the stepping features, click the corresponding button on the toolbar when your application is stopped. See The Toolbar for a description of the buttons.

Note: If the application stops for any reason, such as encountering an error or breakpoint, after any of the Step buttons is pressed, the step is considered to be completed.

Stepping In

The Step In feature provides the finest granularity at which you can stop and inspect your application. Stepping in causes the application to stop just before executing the next instrumented command. Stepping in is useful for following the control flow of your application as it sources files, calls procedures, and evaluates command substitutions.

For example, if your application is stopped on the command

myProc [incr x 5]

you can Step In and stop the application before it evaluates the subcommand incr x 5. You can Step In again to stop the application on the first line of code in the body of the myProc procedure.

The following list describes the rules of behavior for the Step In function:

If the current command contains subcommands, the application stops just before evaluating the first subcommand.
If the current command is a call to an instrumented procedure, and any existing subcommands have been evaluated, the application stops on the first line of code in the body of the procedure.
If the current command is a call to the source command, and any existing subcommands have been evaluated, the application stops on the first line of code in the sourced file.
If the current command is not a call to an instrumented procedure, and any existing subcommands have been evaluated, the application stops on the first instrumented command called by the current command.
If the current command does not call any instrumented code, then the Step In function behaves like the Step Over function.

Stepping Out

Stepping out causes the application to stop before executing the next command after the current stack level or body of code returns. The Step Out feature is useful for backing out of code you are no longer interested in inspecting. For example: if you are stopped in the body of the myProc procedure in the following application:

1 source someFile.tcl
2 myProc [incr x 5]
3 myNextProc $x

and you would like to progress to the myNextProc $x command, you can Step Out of the myProc procedure, and then Step In the myNextProc procedure.

The following list describes the rules of behavior for the Step Out function:

If the current command is in the body of a procedure, the application stops before executing the next command after the procedure returns.
If the current command is at the global level of a file that has been sourced, the application stops before executing the next command after the code in the sourced file is evaluated.
If the current command is at the global level of the main script file, clicking the Step Out button behaves like clicking the Run button.

Stepping Over

Stepping over causes the application to stop just before executing the next command after the current command in your application is fully executed. The Step Over feature is useful for following the application as it progresses through a body of code at the current stack level. For example, suppose you are stopped on line 1 in the following application:

1 source someFile.tcl
2 set x 1
3 myProc [incr x 5]
4 puts $x

If you Step Over the source command, the application stops at set x 1. If you continue to click Step Over, myProc [incr x 5] becomes the new current command, followed by puts $x.

The following list describes the rules of behavior for the Step Over function:

If the current command is a call to an instrumented procedure, the application stops before the executing the next command after the procedure returns.
If the current command is a call to the source command, the application stops before the executing the next command after the code in the sourced file is evaluated.
If the current command is the last one at the current stack level or in the current body of code, Step Over behaves like Step Out.

Stepping to Result

Stepping to Result executes the current command and stops execution. After using Step to Result, the Tcl Dev Kit Debugger highlights the command just executed and displays the result and return code of that command in the Command Results display of the debugger main window.

The Step to Result feature is useful for examining the results of nested commands. For example, suppose you click Step In at line 3 in the following application:

1 source someFile.tcl
2 set x 1
3 myProc [incr x 5]
4 puts $x

If you click Step to Result, your application executes the subcommand and stops. You can then examine the result of the subcommand before continuing. By comparison, clicking Step In again at this point would execute the subcommand [incr x 5] and immediately Step In to myProc, and clicking Step Over would execute both the [incr x 5] subcommand and the call to myProc before stopping.

Interrupting the Application

Clicking the Pause button causes the Tcl Dev Kit Debugger to interrupt the application while it is running. You can interrupt the application at any time; when you interrupt, an implicit breakpoint is added to the next command to be executed in the script. The application stops as it would at any other breakpoint, and you can then interact with the application.

Note: If your code is in an event loop when you click the Pause button, no code is shown in the Code display and the top level in the stack frame displays "event."

Note: If your application is executing uninstrumented Code or is in a long-running command, the Tcl Dev Kit Debugger may not be able to stop the application immediately.

Killing the Application

Clicking the Stop button causes the Tcl Dev Kit Debugger to end the application's process. When you kill the application that you are debugging, information about its state is no longer available. You can then restart the application or launch another application.

Note: You cannot terminate remote applications using the Stop button. You can terminate a remote application by interrupting the application and typing "exit" in the Eval Console. See Manipulating Data.

Restarting the Application

Click the Restart button to terminate the current application and then restart the same application. This is equivalent to killing the application and immediately restarting it. When you restart an application, the Tcl Dev Kit Debugger automatically reloads the main script. This is useful if you have modified the script to fix a bug and want to start the application over to test the change.

If you have modified files other than the main script and wish to set or change breakpoints in those files, you can open them by selecting File|Open File rather than viewing the stale files from the Window menu.

Quitting the Tcl Dev Kit Debugger

To quit the Tcl Dev Kit Debugger, select File|Exit, or click the Close button in the Tcl Dev Kit main window.

Top

Using Breakpoints

A breakpoint causes the application to stop so that you can examine its state. You can add breakpoints in an application at any time. Using breakpoints, you can obtain information, such as variables and their values, the current call stack, and valid procedure names. Tcl Dev Kit supports two types of breakpoints: "line-based" and "variable".

Line-based Breakpoints

Line-based breakpoints let you to specify a line of code where the application should stop. Line-based breakpoints cause the Tcl Dev Kit Debugger to stop before executing each command and subcommand on the specified line. Line-based breakpoints are persistent across runs of the application and debugger sessions.

The Tcl Dev Kit Debugger does not stop at line-based breakpoints that are set in uninstrumented lines of code, blank lines, comment lines, and lines that contain only curly braces. However, variable breakpoints can be triggered if the variable is modified in uninstrumented code. See About Tcl Dev Kit Instrumentation for information.

Variable Breakpoints

Variable breakpoints cause the application to stop when the variable is modified. Variable-based breakpoints are not stored in the application after you close it, or when the variable is removed, unset, or goes out of scope, for example: a local variable in a procedure goes out of scope when the procedure returns.

Note: The Variable breakpoints track the unique location where the variable is stored in memory rather than the name of the variable. You can not set a variable breakpoint until the variable exists in the application.

Manipulating Breakpoints

You can create breakpoints in the main Debugger window. To set a line-based breakpoint, click the code bar in the left margin in the Code display. The line-based breakpoint appears as a small stop sign, and causes the application to stop just before the line is executed.

To create a Variable breakpoint, click the left margin in the Variable display adjacent to the variable. The breakpoint appears as a large "V" in the Variable display. The "V" also appears in the code bar of the Code display when the variable breakpoint is triggered causing the application to stop. The variable breakpoint triggers when the value of the variable changes. You can also create and disable breakpoints from the Breakpoints submenu (Debug|Breakpoints) or in the Breakpoints window.

To delete a breakpoint, click the breakpoint in the Code or Variable display.

Viewing Breakpoints in the Breakpoints Window

To display the Breakpoints window, click the "B" in the toolbar or select View|Breakpoints. The Breakpoints window displays line-based and variable breakpoints, as shown in The Breakpoints Window.

The line-based breakpoints in the Breakpoints window indicate the file and line number where the breakpoint has been set. To select a breakpoint, click the line to the right of the breakpoint in the Breakpoints window to highlight it. You can delete, disable, and enable breakpoints:

To delete a breakpoint, select the line in the Breakpoints window and click the Remove button.
To disable a breakpoint, click the breakpoint in the Breakpoints window.

The disabled breakpoint is shown as a hollow stop sign for a line-based breakpoint or hollow "V" for a variable-based breakpoint.

To enable a disabled breakpoint, click it in the Breakpoints window.

Disabling and enabling breakpoints can be helpful when you want to keep all of your breakpoints but may not want to use all of them at the same time.

Note: You can select multiple breakpoints to be disabled or enabled by clicking the breakpoints while pressing the Ctrl key.

You can perform the following actions on a selected breakpoint:

Click the Show Code button to show the code at a line-based breakpoint.

Clicking this button causes the Tcl Dev Kit Debugger to display the code containing the corresponding line in the Code display.

Click the Remove button to remove a selected breakpoint.

You can click the Remove All button to remove all of the breakpoints.

The information for a variable breakpoint in the Breakpoints window appears in the form of two sets. The first set contains the variable name followed by the absolute stack level at which the variable breakpoint was created. The second set contains information regarding the last time the variable breakpoint was triggered. If the second set is empty, the variable breakpoint has never been triggered. Otherwise, the second set contains the name and stack level of the variable that triggered the variable breakpoint. In most cases, the second set will not differ from the first set. However, when a variable is aliased by the global and upvar commands, any instance of that variable can trigger the variable breakpoint. The second set is helpful when you have an aliasing bug in your code.

The following is an example of an aliased variable a whose variable breakpoint gets triggered by a variable named x:

1 proc foo {} {
2     upvar #0 a x
3     set x 52
4 }
5 set a 50
6 puts "global var a is set"
7 set a 51
8 foo

If you stop this application on line 6, you can create a variable breakpoint for the global variable a. If you open the Breakpoints window, you will see the following:

{a: 0} {: }

If you continue to run the application, the variable breakpoint is triggered on line 7. The following appears in the Breakpoints window:

{a: 0} {a: 0}

If you continue to run the application again, the variable breakpoint is triggered once more on line 3. The following appears in the Breakpoints window:

{a: 0} {x: 1}

Top

Debugging Multiple Processes

The Tcl Dev Kit Debugger can debug subprocesses (and threads) that are "spawned" from a debugging session. These subprocesses are launched by modifying your script and and setting "spawnpoints" at appropriate positions within the script. Spawnpoints are set similarly to breakpoints. If spawnpoints have been set, green arrows are displayed in the margin at the left of the Tcl Dev Kit Debugger's main window.

Set and remove spawnpoints by right-clicking in the left margin in the Tcl Dev Kit Debugger's main window. Alternatively, select Debug|Breakpoints, and choose one of the spawnpoints options:

Add All Spawnpoints Adds spawnpoints at all lines containing thread::create, spawn and exec commands.
Add Spawnpoint Adds a spawnpoint to the current line (as indicated by the cursor).
Disable Spawnpoint Disables a spawnpoint on the current line (as indicated by the cursor).

When you run the debugger with spawnpoints set, a new Code display tab is launched for each spawned subprocess/thread. Once a subprocess has been spawned, you can debug it as you would a regular session in the Tcl Dev Kit Debugger. To close the connection between the debugger and a subprocess, select Debug|Stop or click the Close active debugger connection button on the toolbar.

Note: It is not possible to have multiple projects open in the debugger, with separate debugging sessions for each. The new sessions can only be subprocesses of the main session. Furthermore, data is not shared between sessions. Each session has its own breakpoints and file information. Only breakpoints and spawnpoints in the main session are saved and restored.

Spawning a New Session

If you want to spawn a new session, you must modify the main script in a debugger project by adding the following proc command, along with a spawn command for each subprocess that you want to debug. Spawnpoints (indicated by green arrows) are then set at these lines. So, in the example shown below, the spawnpoints are set on the lines containing the spawn commands for subprocess1.tcl and subprocess2.tcl.

  proc spawn {cmd args} {
       return [eval [linsert $args 0 \
          exec [info nameofexecutable] $cmd]]
  }
  
  puts "Running the profiled multipliers in parallel"
  
  spawn [file join [file dirname [info script]] subprocess1.tcl]
  spawn [file join [file dirname [info script]] subprocess2.tcl]
  
  puts "Launch complete"

Note that the command name, signature, and functionality have to match the definition of spawn.pdx, which is wrapped in tcldebugger.exe. Use the Virtual Filesystem Explorer to view the contents of this file. The virtual path is /tcldebugger.exe/debugger/.

Although the spawn procedure described above is the simplest and most effective way to debug a subprocess, there is an alternative method that makes it possible to invoke subprocesses in remote locations. This method requires that you create a main script containing the exec command and modify the script that you want to debug. Set a spawnpoint in the Tcl Dev Kit Debugger's main window at the line containing the exec command.

Create a main script similar to the following:

puts "launch"

exec C:\Tcl\bin\<TclInterpreter$gt; C:\<DirectoryName>script.tcl

puts "OK"

modify the script to be debugged similarly to the following:

package_require tcldebugger_attach
if {[info exists ::env(DEBUG_INFO)]} {
     foreach {host port cdata}  $::env(DEBUG_INFO) break
     debugger_init $host $port $cdata
}

debugger_eval {
     <your code>
}

Top

Navigating Code

The Tcl Dev Kit Debugger provides utilities that help you navigate to specific portions of the code that you are debugging, including the Procedures window, the Goto command, the Find command, and the Window menu.

Going to a Specified Line

Select Edit|Goto Line.
Type a line number in the text box.
Click the Goto Line button.

The Tcl Dev Kit Debugger highlights the specified line.

Tip - You can also use the Goto What drop-down list to move up or move down the lines in your code from the insertion cursor. Select Move Up Lines or Move Down Lines and type the number of lines that you want to move.

Using the Find Utility

Select Edit|Find.
Type a code fragment or other string in the text box to locate that string. You can choose among several find options:

Select Match whole word only to find those strings that match the entire string that you typed. This option looks for white space as a delimiter. For example, if you searched for the string "sea", you would find all instances of "sea" but would not find "seashore".
Select Match case to find strings that match the case of the string that you typed. For example, with Match case selected, searching for the string "sea" will not match "Sea".
Select Regular expression to find strings that match the one you typed using the search format for regular expressions. If you do not select this checkbox, it will perform searches that match all characters exactly.
Select Search all open documents to find matching strings in all files that are currently open. The Window menu displays a list of all open files. If you don't select this option, the Tcl Dev Kit Debugger searches only the current file (the one shown in the Code display).

Click to select the Direction for the search: Up or Down.
Click Find Next or press the Enter key to begin a search.

The Tcl Dev Kit Debugger highlights the code that matches the string that you typed. If the string is not found, the Code Display does not change. You can find subsequent matching strings by clicking the Find Next button or pressing the <F3> key.

Finding Procedures

You can use the Procedures window to view the list of procedures that have been defined in your application. To open the Procedures window, click the "P" button on the toolbar in the main Tcl Dev Kit Debugger window, or select View|Procedures.

In order for procedures associated with the current application to be displayed in the Procedures window, the Tcl Dev Kit Debugger must be active. To view procedures, set a breakpoint, and then run the debugger.

To narrow down the list, you can type a pattern in the text box and click Search. The default pattern is an asterisk ("*"), which lists all of the defined procedures in the application. Pattern strings can be one or more characters and follow the search conventions that are used with the Tcl glob command. The matches for the string are shown in the display area of the Procedures window. This is useful for finding specific procedures if you have large applications with many procedures. For example, if you type "tcl*" in the text box of the Procedures window, tclLog, tclMacPkgSearch, and all other procedures beginning with "tcl" are displayed in the display area of the Procedures window.

You can display both instrumented and uninstrumented procedures by selecting Show Uninstrumented Procs. Uninstrumented procedures are indicated by asterisks in the display area of the Procedures window. For more information, see About Tcl Dev Kit Instrumentation.

When you select a procedure from the list, you can perform any of the following actions on it:

Show Code - Display the code where the procedure is defined, or the body of the procedure if the procedure is dynamically defined.
Instrument - Instrument a selected procedure.
Uninstrument - Uninstrument a selected procedure.

Finding Errors

The Tcl Dev Kit Debugger detects errors according to the criteria described in Error Handling. Using the Syntax errors dialog box, you can view a summary list of errors and warnings that have been encountered up to the current debugging point.

Note that errors and warnings will not necessarily prevent users from running the script. Errors such as false positives incorrectly detected by the Tcl Dev Kit Checker will have no effect at run-time, whereas runtime or instrumentation errors may prevent the application from running.

To open the Syntax errors dialog, select View|Syntax errors, or press Alt + F5.

Lines containing syntax errors and warnings are colored in the code display window according to the configuration of the debugger preferences.

To display the code causing a syntax error in the code display, select the error and click Show Code.

Using the Window Menu

Select the Window menu to display all of the files that are open in the Tcl Dev Kit Debugger.

Top

Displaying Code and Data

The Tcl Dev Kit Debugger provides several windows in which you can display and monitor specific aspects of the application that you are debugging. These include the Watch Variable window, and the Data Display window. For information on the Breakpoints window, see Viewing Breakpoints in the Breakpoints Window.

Watching Variables

To open the Watch Variables window, click the "W" button on the toolbar. Alternatively, select View|Watch Variables.

The Watch Variables window displays variable names and values at the stack level that is selected in the Stack Frames display. The values in the Watch Variables window are updated each time the application stops, and also each time you select a new stack level in the Stack Frames display in the main window. If a variable name or value is not defined at the selected stack level, then "<No Value>" appears instead of a value.

To add a variable name to the Watch Variables window:

Type the variable name in the text box of the Watch Variables window.
Click Add or press the Return key.

The variable name and the current value of the variable are displayed in the variable list.

To remove a specific variable, click the line, then click the Remove button. To remove all variables, click the Remove All button.

To invoke the Data Display window, which displays the full unabbreviated value of a variable, click the desired variable then click the Data Display button. Alternatively, double-click the desired variable.

The Watch Variables window is useful for observing variables in different stack levels that have the same name. For example, suppose the following script is stopped just before executing line 10:

1 proc bar {x} {
2 puts $x
3 }
4 
5 proc foo {y} {
6 baz [expr {$y + 3}]
7 }
8 
9 set x 2
10 foo $x

The stack display is shown below:

0 global 
0 source sample.tcl 
1 proc foo y 
2 proc bar x

If you are watching the variable named x, you will see the value change as you select different stack levels. At level 2, x has the value 5. At level 1, x is not defined, so "<No Value>" is displayed. At level 0, x has the value 2.

Variable Value Formats

String: As Hex
String: As Octal
String: As Unicode
Integer: As Hex (must be an integer)
Integer: As Octal (must be an integer)
Integer: As Bits (must be an integer)

When you add a variable to the Watch Variables window, select the desired display format from the drop-down list, then press Add. If "No Transformation" is selected, the variable value format will not be transformed.

Once a variable has been added to the list, you cannot change the display format. However, you can add the same variable more than once, specifying a different format each time. If you specify the same variable and variable format twice, the combination will only be displayed once.

When you add an array variable to the Watch Variables window, you cannot specify the variable value format for individual elements. (The format will be inherited from the setting in the Variable pane.) To transform individual elements, add the array variable with the specific element, rather than the entire array variable. For example, if you specify the array "foo", elements in the array will be displayed in the same format as in the Variable pane. However, if you specify "foo(bar)", you may specify the variable value format for the "bar" element in the "foo" array.

Displaying Data

The Data Display is used to see the full unabbreviated value of a variable, which can be helpful if you are looking at long strings.

To open the Data Display window, double-click a variable in the Variable display in the main window, or double-click a variable in the Watch Variable window. Alternatively, select View|Data Display.

By default, the variable that was highlighted when the Data Display window was invoked will be displayed. To display a different variable, double-click the desired variable in the Variable pane or the Watch Variables window. Alternatively, type the variable name in the Data Display window and click Display.

The variable is linked to the stack level that is highlighted in the Stack display at the time the variable is entered in the Data Display window. Once the variable is entered, changing the stack level in the Stack display will not affect the value of the variable. The value that is displayed for the variable is updated each time the application stops. If "<No Value>" appears, it means that either the variable was unset or the stack level attached to the variable has returned. Like variable breakpoints, a variable in the Data Display is associated with a location in memory. Once "<No Value>" appears, the previous memory location is no longer reserved for that particular variable, so "<No Value>" for the variable will reappear.

Variable Value Formats

In each of the windows where variable values are displayed (the Variable pane, the Data Display window and the Watch Variables window), you can configure the format in which the variable values are displayed. Select the desired format from the Display drop-down list. The following formats are supported:

String: As Hex
String: As Octal
String: As Unicode
Integer: As Hex (must be an integer)
Integer: As Octal (must be an integer)
Integer: As Bits (must be an integer)

The variable value format is inherited from either the Variable pane or the Watch Variables window, depending on where the Data Display window was invoked. To specify a different format, select the desired format from the Display drop-down list.

View As Menu

Use the drop-down View As menu to select the format for the variables. The Tcl Dev Kit Debugger attempts to match the display to the variable type. For example, if the variable is scalar, it will display with line wraps, and if it is an array, it will display as an array. You can view the variable with the following formats:

Line wrap - Wrap the line when it exceeds the length of the display window, which is the default display for scalar variables.
Raw data - Does not modify the display.
List - The Tcl Dev Kit Debugger treats the variable value as a Tcl list, extracts the elements of the list, and displays each element on a separate line.
Array - Each element is displayed as a separate item with a name and value.

Note: Ordered lists can be displayed as arrays.

Top

Manipulating Data

To open the Eval console, click the "E" button on the toolbar, or select View|Eval Console.

The Eval console is used to pass commands to an application or to call procedures. Any time that the application is paused (either at a breakpoint or as a result of a debugger command like "Step Over" or "Step Out") you may enter commands in the Eval console to be evaluated by the application.

Use the Stack Level drop-down list to select the stack in which you want to evaluate commands. (The deepest stack level is selected by default when the Eval Console windows is invoked.) You may also change the current stack level by using the keyboard shortcuts Ctrl + Plus (to move to the next higher stack level) and Ctrl + Minus (to move to the next lower stack level). The stack levels correspond to the numerical levels displayed in the Stack Frames window.

The Eval Console maintains a command history. To invoke a command previously entered in the Eval Console, use the Up Arrow key (or Ctrl + p) to scroll through previous commands. Use the Down Arrow key (or Ctrl + n) to scroll through commands subsequent to the current command.

Top

Error Handling

The Tcl Dev Kit Debugger detects all errors in the application including runtime and parsing errors.

Parsing Error Handling

A parsing error is an error that is caused by code that is not syntactically valid. An example of a parsing error is a script that is missing a close brace. The Tcl Dev Kit Debugger detects parsing errors during instrumentation, whenever a file is sourced or a procedure is created dynamically by the application.

When a parsing error occurs, the Tcl Dev Kit Debugger cannot understand the script's control flow following the error, and cannot continue instrumenting the code. The Tcl Dev Kit Debugger displays a dialog box in which you choose to either quit the application or continue the application with the partially instrumented script. If you choose to continue debugging the partially instrumented script, the same error appears as a runtime error if the code is executed. See About Tcl Dev Kit Instrumentation for details on the implications of continuing despite the parsing error.

Runtime Error Handling

An example of a runtime error is an attempt to read a non-existent variable. The Tcl Dev Kit Debugger detects all runtime errors, including both those caught and those not caught by a Tcl script. How the Tcl Dev Kit Debugger handles runtime errors depends on the Error settings that you specify for your project. See Changing Project Error Settings for more information on specifying your project Error settings. If you have set:

Always Stop on Errors - The Tcl Dev Kit Debugger notifies you each time it encounters an error in the script.
Only Stop on Uncaught Errors - The Tcl Dev Kit Debugger notifies you only when it encounters an error not caught by the script.
Never Stop on Errors - The Tcl Dev Kit Debugger does not notify you when it encounters errors in the application. Your application handles errors in the same manner as it would if it were not running under Tcl Dev Kit Debugger.

When the Tcl Dev Kit Debugger detects a runtime error in accordance with the rules above, it stops execution of your application and displays a dialog box such as the one shown in the Tcl Dev Kit Debugger Tcl Error Dialog.

You have the choice of either delivering the error or suppressing the error:

Deliver Error - The application continues and the error is handled in the normal fashion for Tcl. Clicking this button is equivalent to having run the script without any debugger interference.
Suppress Error - The Tcl Dev Kit Debugger suppresses the error, and continues executing the application. The behavior in this case is as if no error had occurred. You can continue to run or step through the application.

While your application is stopped, you can examine your Tcl script, view and change variable values, set breakpoints, and use all the other features of the Tcl Dev Kit Debugger. If you single-step or run your application without first selecting whether to deliver or suppress the error, the Tcl Dev Kit Debugger delivers the error if your application catches it and suppresses it otherwise.

Use the Syntax errors dialog to view a list of all the errors contained in the current program. Also, lines containing syntax errors and warnings are colored in the code display window according to the configuration of the debugger preferences. If you hover the mouse pointer over a line containing a syntax error or warning, the text of the error will be displayed in the Status Bar in the bottom left corner.

Top

STDIN, STDOUT and STDERR

The Eval Console displays output written to STDOUT or STDERR. When a program calls for input via a [gets] or [read stdin] statement, the Eval Console will display an (STDIN) % prompt where data for STDIN can be entered. (Each subsequent [gets] or [read stdin] statement will generate a new prompt, and will require new input.) The code line which called for input will be indicated in the code display window.

The Eval Console window is opened automatically when STDOUT or STDERR is generated, or when STDIN input is required.

Top

Code Profiling and Coverage

The Tcl Dev Kit Debugger includes a tool for analyzing code coverage. Coverage and Profiling settings are specified on the Coverage & Profiling tab in the Project dialog box (File|Project Settings). For more about Coverage and Profiling options, see Changing Project Coverage and Profiling Settings.

Code Coverage and Profiling has three components:

Coverage Analysis - highlights code that has not been executed by the debugger, depending on the setting in the Code Coverage and Profiling dialog box (View|Code Coverage).
Profiling - highlights code that has or has not been executed by the debugger, and reports the time required for the system to execute individual commands.
Hot Spots - highlights code that has been run multiple times, making it easier to determine areas where code performance can be optimized.

Coverage information is collected as the debugger runs. The code displayed in the debugger is updated as each line is processed. If you have configured Coverage and Profiling to "Highlight Uncovered Code...", each line that has not been processed will highlighted in green (the default color). If you have configured Coverage and Profiling to "Highlight Covered Code...", each line that has been processed will be displayed in a shade of orange (the default color); lines that have been processed a number of times will be highlighted with a darker color. The more times a line has been processed, the darker the color.

Select View|Code Coverage, or click the "Code Coverage" button on the toolbar, to open the Code Coverage and Profiling dialog. If you have set breakpoints in the file, coverage or profiling coloration will be updated in the code display pane as the debugger stops at each breakpoint. The pane that displays the source code will be colored to indicate either "covered" (code lines that have been processed) or "uncovered" (code lines that have not been processed) based on the selection in the Code Coverage and Profiling dialog.

The coverage function stores the coverage and profiling analysis from the last time the debugger was run in the current session. Unless you manually clear the coverage information (using the Clear All Coverage button in the Code Coverage and Profiling dialog), you will be asked if you wish to save the coverage information from the last debugger run.

Code Coverage and Profiling Dialog

Files tab displays all files for which the debugger collected coverage information.
Calls Tab If the "Plain coverage" option is specified in the project settings, this tab displays the number of calls to each line in each file executed by the debugger, along with the file names and line numbers. Lines are color-coded according to the number of times they were executed. The darker the color, the greater the number of times the line was executed. If the "Profiling" option is specified in the project settings, data about the time required for the system to execute commands is displayed in the "Min", "Avg", "Max", and "Total". Times shown are in microseconds. To change the order of the columns, click the desired column heading.

Function Buttons

Highlight Uncovered Code for Selected File Each line of code in the Code Display that has not been processed will be displayed with a green background.

Highlight Covered Code for Selected File Each line of code in the Code Display that has been processed will be displayed in orange. Lines that have been processed multiple times will be highlighted with a darker shade. The darker the shade, the more times the line has been processed.

Show Code When a file is selected on the Files tab, or a call selected on the Calls tab, click the Show Code button to shift the code display in the debugger to the desired file or call.

Clear Selected Coverage When multiple files are displayed on the Files tab, you can clear the coverage display for one or more files, rather than clearing the display for all files. Select the file for which you wish to clear coverage, then click Clear Selected Coverage. Coverage will be cleared regardless of whether covered or uncovered code has been selected for display.

Clear All Coverage To clear all coverage information, click Clear All Coverage. Coverage will be cleared regardless of whether covered or uncovered code has been selected for display.

Save Data To export coverage information for the project, click Save Data. This will create a file in CSV (comma separated values) format in the specified directory. The file contains the following columns:

NrCallsToCmd - Number of calls to the described command
Filename - File containing the command
CmdLine - Line number where the command occurs
Min - Minimum amount of time spent on the executed command
Avg - Average amount of time spent on the executed command
Max - Maximum amount of time spent on the executed command
Total - Accumulated amount of time spent on the executed command
CmdCharIndex - Numerical position of the first character in the command
CmdLength - Length of the command in characters

For more information about Code Coverage and Profiling, see the Coverage Analysis Tutorial and the Hotspot Analysis Tutorial.

Top

Setting Preferences

You can specify preferences to customize the Tcl Dev Kit Debugger. To modify Preferences, select Edit|Preferences. Click the tabs to select your preferences for Appearance, Windows, Instrumentation, and Startup and Exit, and Browser preferences.

Appearance Preferences

You can choose the following Appearance preferences:

Type - The name of the font used to display code, stack frames, variables, etc.
Size - The size of the font used to display code, stack frames, variables, etc.

Tip: The Tcl Dev Kit Debugger attempts to optimize your font and size preferences. If you type a font that is unavailable, the Tcl Dev Kit Debugger finds the most similar font on your computer and substitutes it. ActiveState recommends that you only use fixed-width fonts.

Note: Small font sizes can cause misalignment of the symbols in the Code Bar and their corresponding lines of code. If you experience problems, increase the font size.

Highlight - The color the Tcl Dev Kit Debugger uses when it stops to highlight the next command it will execute.
Highlight On Error - The color the Tcl Dev Kit Debugger uses to highlight a command in which it finds an error.
Highlight On Result - The color the Tcl Dev Kit Debugger uses to highlight code it just executed after a Step To Result
Highlight Syntax Error - The color the Tcl Dev Kit Debugger uses as the background color for the syntax error counter below the code display.
Highlight Syntax Warning - The color the Tcl Dev Kit Debugger uses as the background color for the syntax warning counter below the code display.
Highlight Not Executed Code - The color the Tcl Dev Kit Debugger uses to highlight uncovered code.
Highlight Profiled Code - The color the Tcl Dev Kit Debugger uses to highlight covered code.

After changing the Appearance tab settings, click the OK button to save your choices and close the Preferences window, the Cancel button to cancel your choices and close the Preferences window, or the Apply button to apply your choices and keep the Preferences window open.

Window Preferences

You can modify the following Windows preferences:

Screen Buffer Size - The number of lines of output retained by the Eval console.
History Buffer Size - The number of commands retained in the Eval console history buffer.
Tab Size - The number of characters between each tab stop.
Use tooltips - The pop-up hint boxes that describe components of the interface.

After changing the Windows tab settings, click the OK button to save your choices and close the Preferences window, the Cancel button to cancel your choices and close the Preferences window, or the Apply button to apply your choices and keep the Preferences window open.

Startup and Exit Preferences

The Startup preference controls the Tcl Dev Kit Debugger's behavior when you start the debugger:

Reload the Previous Project on Startup - the Tcl Dev Kit Debugger reloads the project you had open when you last exited the Tcl Dev Kit Debugger

The Exit preferences control the Tcl Dev Kit Debugger's behavior when you quit the debugger:

On exit, ask if the application should be killed - The Tcl Dev Kit Debugger prompts you to kill the application when you exit the debugger.
On exit, always kill the application - The Tcl Dev Kit Debugger always kills the application when you exit the debugger.
On exit, always leave the application running - The Tcl Dev Kit Debugger leaves the application running when you exit the debugger.
Warn Before Killing the Application - The Tcl Dev Kit Debugger always prompts you when you are about to perform an action that would kill the application.

After changing the Startup & Exit tab settings, click the OK button to save your choices and close the Preferences window, the Cancel button to cancel your choices and close the Preferences window, or the Apply button to apply your choices and keep the Preferences window open.

Browser Preferences

The Tcl Dev Kit Debugger uses a Web browser to display the ActiveState Web site when you click on the ActiveState URL in the About Tcl Dev Kit Debugger window.

You can select one of the following choices for your Web browser with Tcl Dev Kit:

Use default browser - The Tcl Dev Kit Debugger uses the default browser on your system.
Choose an alternative browser - On Windows, you see the pathname of your default browser. You can enter the pathname of an alternative browser here.

After changing the Browser tab settings, click the OK button to save your choices and close the Preferences window, the Cancel button to cancel your choices and close the Preferences window, or the Apply button to apply your choices and keep the Preferences window open.

Top

About Tcl Dev Kit Instrumentation

When you begin running an application, the Tcl Dev Kit Debugger transparently processes the specified Tcl/Tk script. It modifies the code to enable communication between the Tcl Dev Kit Debugger and the script. This process is known as instrumentation. The Tcl Dev Kit Debugger launches the application with the instrumented script in place of the original script. The instrumentation was designed to be as unobtrusive as possible. However, you can expect some slowdown in applications as a result of the instrumentation.

You can specify which procedures to instrument in the Procedures window; see Finding Procedures. You can also specify files and classes of procedures to leave uninstrumented; see Changing Project Instrumentation Settings. In addition to the files and procedures that you tell the Tcl Dev Kit Debugger not to instrument, there are also some instances of dynamically created code that the Tcl Dev Kit Debugger cannot instrument. These include "if" statements with computed bodies and callbacks from Tcl commands. When the application is executing uninstrumented code, it cannot communicate with the Tcl Dev Kit Debugger. If you want to interrupt or to add a breakpoint to the script while uninstrumented code is executing, the application cannot respond until it reaches the next instrumented statement.

The Tcl Dev Kit Debugger indicates that a procedure or file is uninstrumented by listing the procedure or file name preceded by an asterisk ("*") in the Procedures window, Windows menu, and the Code display status bar.

Top

Debugging Remote, Embedded, and CGI Applications

In some cases, the Tcl Dev Kit Debugger can't directly launch your application. Some examples where this is often true include CGI applications, embedded applications, and applications that must run on a system other than your debugging system.

For applications such as these, the Tcl Dev Kit Debugger supports remote debugging. In remote debugging sessions, your application starts as it normally would and then establishes a special connection to the Tcl Dev Kit Debugger. You can then use the Tcl Dev Kit Debugger to perform all debugging tasks as you would in a local debugging session.

To debug a remote application, you must perform the following steps:

Modify your Tcl script to work with the Tcl Dev Kit Debugger (using tcldebugger_attach).
Create a remote debugging project in the Tcl Dev Kit Debugger.
Launch your application as you normally would. Your application establishes a connection to the Tcl Dev Kit Debugger and you can begin your debugging session.

The following sections describe how to perform these tasks.

Modifying a Tcl Script for Remote Debugging

For your application to establish and maintain communication with the Tcl Dev Kit Debugger, you must modify your application to use the tcldebugger_attach package, which is contained in the lib subdirectory of your Tcl Dev Kit installation. Use the following package command:

  package require tcldebugger_attach

Your script must call the debugger_init procedure and, optionally, the debugger_eval and debugger_break procedures. You can modify your script in one of two ways: create a new "wrapper" script that sources your existing script, or modify your existing script.

Remote Debugging Procedures

The following procedures are available for remote debugging:

The debugger_init procedure makes the initial connection with the Tcl Dev Kit Debugger.
The debugger_eval procedure instruments Tcl code so the Tcl Dev Kit Debugger can control the application while script is evaluated.
The debugger_break procedure causes your remote application to break in much the same way as if it had encountered a breakpoint.
The debugger_attached procedure returns the connection status of the Tcl Dev Kit Debugger.

For more information about these commands see the Tcl Dev Kit Command-Line Reference.

Creating a "Wrapper" Script for Remote Debugging

If you decide to create a new script, that script should load the tcldebugger_attach package, and then source the file that was originally the main script of your application. This new script becomes the main script of your application. Your new main script may look like the following:

# Source the tcldebugger_attach package

package require tcldebugger_attach

# Assume the variables $host and $port respectively contain
# the name of the machine on which the Tcl Dev Kit Debugger is
# running and the port on which it is listening.

debugger_init $host $port

# Assume $myOriginalMainScript contains the path of your
# original script.

source $myOriginalMainScript

Modifying an Existing Script for Remote Debugging

If you decide to modify your existing script, you must change it to load the "tcldebugger_attach" package and call the debugger_init procedure. Once debugger_init is called, other files sourced by the script will automatically be instrumented. If you want the Tcl Dev Kit Debugger to instrument code in the file that calls debugger_init, the code that you wish to instrument must be encapsulated in a call to the debugger_eval procedure. See About Tcl Dev Kit Instrumentation for more details on instrumentation.

Your new main script may look like t