debugger_init ?host ?port ?cdata???
debugger_eval ?switches? script
debugger_break ?str?
debugger_attached
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
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.
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 -.
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.
The debugger_attached
command returns 1 if the script is connected
to the Tcl Dev Kit Debugger. Otherwise
it returns 0.
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
.