Once you start Debugger and choose File | New Project... from menu, you are able to select the debugging mode. In this case, we select Local Debugging and load the server code:

What this means is that the debugger will launch the server code (server.tcl) locally on the same computer, where it is run. The project may be saved, allowing us to keep your breakpoints and watch variables for later usage.

Once the code is loaded, you will be able to start interacting with it. Debugger offers typical scenario for this kind of application features:

If there are more details, the code (server.tcl) will not simply be executed. The debugger will modify it transparently, enabling the debugging process to take place—this mechanism is called instrumentation. By default, all the code would be instrumented, but you have the possibility of explicitly excluding some of its parts. You may do this on the second tab of new project wizard (or later in File | Project Settings...):

For example, you can precisely define which procedures should be left uninstrumented, or even ignore entire source files. The excluded code will still be executed of course, but you won't be able to use debugging features like setting breakpoints inside it. You may wonder why to bother yourself with such exclusions: for example, it would improve the performance of your code, or allow you to omit some parts like loading some libraries.

The following screenshot shows the Debugger with loaded and started server.tcl code:

The upper toolbar contains buttons for stepping the application, stopping / and restarting it, and for displaying various additional windows, consecutively:

The upper left pane holds the list of available stack frames. The right pane contains all variables and their values for the selected stack frame. It also offers you the possibility of creating a variable breakpoint (marked with the letter V), by clicking on the left margin of the variable:

Double clicking on any variable from this pane will open an additional Data Display window, where you can easily display the value of the variable in different formats (Hex, Octal, Unicode and so on).

It is worth noting that the version of the Debugger we used, at the time of writing, had problems when a breakpoint was defined for the array variable. Once the execution of that variable came to modification, the error can't read "counter": variable is array was shown.

The debugger may also fail when some core Tcl commands are renamed or redefined. For example, the comm package renames the vwait command that causes an appropriate warning once executed in Debugger.

The main pane displays the code for selected stack frame. By clicking on the left margin, you are able to define line breakpoints denoted by a dot (as shown in line 10 in the example screen). Once the server was launched and the breakpoint was defined, we executed the client code that caused the server::incrementCounter procedure to be executed. As a result, the execution was stopped at line 10. The yellow arrow on the left points to the line where the execution is currently stopped. Once you decide to continue the execution with stepping functionality, you will notice the arrow moves to next line.

The client code (presented at the paragraph describing Inspector) attempts to increase the value for the counter named testC. However, once the average value is retrieved, it is calculated only from the first two counters. Quick debug action helps solve this issue:

Having declared a breakpoint at line 10, all we have to do is to wait until the name argument has the value testC. Once this happens, we can step to the next line, and using the Eval Console we can quickly check whether the if condition is fulfilled or not. As you can see, it is not fulfilled, and a quick look at the counter variable in the Variables pane proves that indeed the counter testC was never initialized. Once we return to client code, we check for the following:

comm::comm send $id ::server::initCounter "testB"

This line is missing indeed. This example 'bug' is trivial, as the client code is short and simple, but in the case of a complex application the odds of missing such a command may be pretty high.

Remote debugging does not differ significantly from the local mode. The main difference is that the debugger and application are communicating via the TCP/IP network protocol.

The architecture of remote debugging is interesting: it is the debugged application's responsibility to connect to the debugger that is configured to listen on some specific port (let's use 1999 as an example value):

In order to connect (attach) to the listening debugger, the application must be modified. Tcl Dev Kit comes with the tcldebugger_attach package that offers all requisitive commands for the application to attach to the debugger. This package must be accessible for the debugged code, so you will probably have to copy it to the target machine.

You may either modify the application code itself or create some wrapper code that will do all that is necessary, and run the original script (see the User Guide for details). We choose second example as it is more elegant. Assuming that our original server code is stored in server.tcl file, we will create a new script with the following content:

package require tcldebugger_attach
debugger_init 127.0.0.1 1999
source server.tcl

As you can notice, basically only one command is required to enable remote debugging:

debugger_init host port

The host parameter is the address of the machine where Debugger listens on the specified port.

If you were to decide to modify the original server.tcl script, the start would be the same, but additionally you would have to encapsulate all the server code into the debugger_eval procedure call:

package require tcldebugger_attach
remote debuggingaboutdebugger_init 127.0.0.1 1999
debugger_eval {
namespace eval ::server {}
proc ::server::initCounter {name} {
#body of the procedure
}
proc ::server::incrementCounter {name value} {
#body of the procedure
}
proc ::server::getAvg {} {
#body of the procedure
}
package require comm
comm::comm config -local 0 -port 1991
vwait forever
}

Once the application is attached to the debugger, you can interact with it in the normal way, identical to local mode, but in this case the interaction is transparently over the network.

The package also offers you the ability to programmatically define breakpoints with the debugger_break command, which behaves similar to a line breakpoint. For example, lets add it to the ::server::incrementCounter command:

proc ::server::incrementCounter {name value} {
variable counter
if {[info exists counter($name)]} {
debugger_break

incr counter($name) $value

When the execution hits this line of code, the result is as follows:

Note that you are still able to define breakpoints in the normal way, using the GUI. Usage of debugger_break may be particularly useful in the case of dynamically-generated code, where you wouldn't be able to set a breakpoint otherwise.

If the debugger is not started and is not listening then the application will continue its operations in the normal way, and debugging related commands will have no effect.

The Tcl Dev Kit Debugger is a simple but powerful tool that provides all the necessary functionality typical for this kind of application. Although it lacks some sophisticated options like conditional breakpoints (stop the execution only if some condition is met; for example, variable name has value testC), and in some circumstances it may fail (described in User Guide), there is no doubt it is the best Tcl debugger currently available.

The ability of remote debugging is especially important in the case of network programming, which is essence of this book. What's more, the debugger also offers the ability to perform code profiling, analyze the code coverage, and identify Hot Spots, that is the code fragments that have been executed multiple times. These features allow you to focus on the most critical parts of the application, and fine-tune and optimize the performance of them. For example, you may be dealing with the long running processes of a server application that are handling large volume of data, and reducing the CPU usage or response time may be a matter of life and death.