1.  Backtrace

Decoding a Tcl error traceback can be very tedious. This is particularly true in larger applications involving hundreds of lines of backtrace and dozens of stack levels. Therefore Mod provides a facility that automatically decodes stack tracebacks, presenting them in one-level-per-line format. Th can also optionally stop the program right at an error, before the stack unwinds in a traceback. (note: this facility is for handling runtime errors, and presumes program files have already sourced without error.)

Mod handles background errors by unwinding the stack backtrace into a one per line listing which can then be used to navigate through source code involved in an error. Here a couple of screenshots. The first is a real-error screenshot and the other the install demo-error screenshot. Clicking on any given level, a Mini-EDitor (Med) will popup displaying the file/line of error. Med provides only rudimentary capabilities, however, it does support save and so allows immediate editing and fixing of problems.

One issue with debugging Tcl is that it normally does not collect file or line information associated with procs. Mod allows forcing this collection by adding the following to the top of your program (or setting it from command-line).

 set ::env(TCL_CHECK) 1

When not using TCL_CHECK or Weld, Mod instead falls back to show just the proc definition.

The backtrace window should look like:

Clicking on any line should open a Mini-Editor window (see below).

2.  Stop At Error

It is also possible to stop a program right at the point of error, to allow direct introspection of the running program and evaling commands within the proc errors context. Note this will stop the program prior to unwinding of the stack.

There are two ways to do this: Selecting the trap option from Run-Tcl, or running with an application containing:

 set ::env(TCL_CHECK) 10

A key advanatage of this is that you may examine variable values and program state right at the point of error. Med also provides a Stack-Dump and access to the Console via it's File menu.

For example: to reproduce the error from the screenshot above with Ted under Unix/bash, use:

   TCL_CHECK=10 ./ted.tcl ted.tcl

Then select the menu /User/Test/Invoke-Error.

3.  Pausing A Program

It is sometimes desirable to pause a running program right inside a proc, allowing inspection of the runtime state. This can be acheived using the .Stop directive while running a program while running with TCL_CHECK=1. An example of inspecting is provided in Ted via /User/Test/Invoke-Stop. eg.

    proc Invoke-Stop {_} {
        # Demo of pausing a program for inspection.
        set j 1
        .Stop first
        incr j
        .Stop second
    }

If Ted was run with checking on, this should open a window something like:

As shown, Tcl commands can be executed in the command input at bottom. Closing the window will resume execution, pausing again at the next .Stop.

© 2008 Peter MacDonald