TIP #86 Version 1.2: Saving [proc] File and Line Number Information in [source]

This is not necessarily the current version of this TIP.

Abstract

This TIP proposes saving the file name and line number information for each user defined [proc] definition contained within a [source]d file, and providing three new subcommands to [info]: [fileproc], [lineproc] and [findproc] that can return this new information.

Rationale

With this change, upon error within a procedure, the filename and absolute (as opposed to relative) line number are printed out when available, even in the case where called from an after or callback invocation. Aside from aiding the user in more easily locating and dealing with errors, the message is machine parseable so that it is possible so that automated processing is possible. For example: automatically bring the user into an editor at the offending line.

Second, a simple/small debugger emulating gdb is being developed that uses this interface. It allows breakpoints on lines, single-stepping and displaying/locating source and even works as a slave under a GUI written in Tk. Ultimately, at some point this debugger could even be included in the core distribution.

Specification

The new [info] subcommands give access to the file name and line number information for a given PROC. Valid syntax is:

  info lineproc PROC ?LINE NEWLINES?
        Get/set the line number and number of newlines for PROC.  In
        get mode, returns the definition line number and number of
        newlines in the message body.  This provides a fairly speedy
        way of determining if a given line number is included in a
        specific proc.

  info fileproc ?PROC ?FILE??
        Get/set the sourced file name for PROC.  If PROC is not
        specified, dump all known sourced files.

  info findproc FILE LINE
        Given a file name and line number, return the PROC name
        containing line number LINE.  A new nonstatic procedure
        TclFindProcByLine() provides this function.

These exhibit the following behavior:

• What does this do when you redefine a proc?

  You get the values from the latest definition.

• What about when you use interp aliases?

  You get an error, as it is not considered a proc.

• And if proc itself gets redefined by someone's special debugger?

  If the definition is not the result of a source, the file/line come back as an empty string.

Changes

Sourced file names are stored in a global hash table. Line numbering information is saved in the Proc structure. The Tcl_Parse structure gets two additional ints which are updated during the parse phase prior to command creation. A temporary lineNum int is also employed for passing the current line number around.

The bulk of the changes occur in generic/tclParse.c where the number of line feeds seen is tracked.

Overhead/Impact

This is a change impacting binary compatibility as it adds to Tcl_Interp.

The runtime footprint of Tcl should not increase by more than a few kilobytes, even for moderately large programs. Most of the space impact occurs in storing the file names, but these are stored only once each for each file sourced, not per interp. A typical example from a large system:

  100 sourced files * 100 bytes = 10K.

The other space overhead adds up to 2 words (8 bytes on a 32-bit platform) per defined procedure, plus an additional 2 words in the Interp structure.

Runtime processing overhead should be negligible.

However, there have been no benchmarks done to validate these assertions.

Reference Implementation

http://dev.browsex.com/tclline.diff.gz

This is a patch against tcl8.4a3. It has been tested lightly against small and large Tcl programs.

There is also an initial version of a debugger: tgdb.

http://dev.browsex.com/tgdb.tgz

tgdb emulates some of the basic commands of gdb (s, n, c, f, bt, break and info locals). The basic tgdb strategy is to determine the line number by looking for the currently executing command:

• When in a function, search in the procedure body

• When at global level, search in the file source starting from reported line.

Although not foolproof, it is accurate enough the majority of the time.

Also bundled is tdb, a GUI front-end to gdb, modified to also work with tgdb. You can test it against the patched Tcl with

  make 
  ./tdb test.tcl 

Once load and run commands are added, tgdb should probably work even with emacs and ddd.

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.