Tcl Dev Kit tcldebugger_attach Package Reference

Name

debugger_init, debugger_eval, debugger_break, debugger_attached

Synopsis

debugger_init ?host ?port ?cdata???

debugger_eval ?switches? script

debugger_break ?str?

debugger_attached

Introduction

The Tcl command procedures defined below are used to debug remote, embedded, and CGI applications. To establish and maintain a connection with the Tcl Dev Kit Debugger, you must ensure that your script sources the tcldebugger_attach package and calls the debugger_init and debugger_eval procedures.

Use the following package command:

package require tcldebugger_attach

Command Procedures

debugger_init ?host ?port ?cdata???

This command establishes a connection with the debugger that is running on host and listening on port. By default, the host is localhost and the port is 2576. The cdata argument specifies any client data to be transferred to the debugger. If the session using the tcldebugger_attach package is a subordinate session spawned from the main debugger session, the cdata option cannot be empty.

Note: Data specified in the cdata argument is for display only. If cdata is empty, "REMOTE project" will appear in the debugger's status bar.

Once connected, the Tcl Dev Kit Debugger will instrument any files sourced using the source command, or any commands that appear in the argument list of the debugger_eval command. The command returns 1 if the connection succeeds and 0 if it fails.

Note: If your embedded application uses multiple subsequent interpreters (that is, it quits and restarts a Tcl interpreter more than once), each main Tcl script is treated as an individual application and must make a new connection with the Tcl Dev Kit Debugger.

debugger_eval ?switches? script

This command instruments and invokes the specified script. The debugger_eval command makes it possible for a program to explicitly instrument a block of code that otherwise might not be instrumented by the Tcl Dev Kit Debugger. If the script is not currently connected to the debugger, debugger_eval simply evaluates the script argument.

You can wrap your whole script inside the debugger_eval block. Any scripts that you source within a debugger_eval block are also instrumented.

Note: The debugger_eval procedure behaves like the eval command if your application is not currently connected to the Tcl Dev Kit Debugger.

Any initial arguments for debugger_eval that are preceded by a - are treated as switches. The debugger_eval command currently supports the -name switch, which is entered as:

-name myname

When you associate a name with the script, the debugger stores breakpoint information as though the script had been sourced from the file of the given myname. This switch is especially useful for remote debugging, or for evaluating blocks of dynamically generated code that are used multiple times. By creating debugger_eval commands, each with a unique name for each block, you can set breakpoints that persist across invocations. Use - - to indicate the end of a switch. Doing so will cause the argument that follows to be treated as a script, even if it is preceded by a -.

debugger_break ?str?

The debugger_break command causes a break to occur when it is executed. It is as if a breakpoint is set on the line containing the debugger_break command. The difference is that str is evaluated before the break occurs. When the break occurs, a dialog box is displayed. If the str argument is given and is not empty, the value of str is shown in the dialog box. If the script is not connected to the debugger, the debugger_break command has no effect.

debugger_attached

The debugger_attached command returns 1 if the script is connected to the Tcl Dev Kit Debugger. Otherwise it returns 0.

Examples

The sample code below demonstrates the simplest way to establish a remote connection and debug an entire script remotely.

package require tcldebugger_attach
if {[debugger_init remoteMachine 2576] == 0} {
     return "cannot communicate with remoteMachine on port 2576"
}
source main.tcl

The connection is established between the local machine and remoteMachine via port 2576. The debugger is running on remoteMachine and is listening on the default remote debugging port, 2576. See Changing Project Application Settings for more information on how to specify the port that the debugger listens on. The file main.tcl is then sourced, which will cause the contents of the file, and any subsequent sourced files, to become instrumented (unless the preferences set in the debugger indicate otherwise).

The next example shows how to control exactly which commands become instrumented. Establish the connection the same as in the previous example. The commands that create the variables x, y and z will not be instrumented and the debugger will not step through these lines. The commands that create the variables a, b and c are inside debugger_eval. This causes these commands to be instrumented; the debugger will step through these commands.

package require tcldebugger_attach
if {[debugger_init remoteMachine 2576] == 0} {
     return "cannot communicate with remoteMachine on port 2576"
}
set x 1
set y 2
set z 3
debugger_eval{
     set a [expr {$x + 1}]
     set b [expr {$y + 1}]
     set c [expr {$z + 1}]
}

This example is especially relevant when debugging embedded scripts. Simply add the first two lines to the beginning of the script and wrap the existing script in a call to debugger_eval.