NAME
TagmaDebug - Interactive TCL Debugger
SYNOPSIS
tagmadebug.tcl [Options] [--] YourScript.tcl
OPTIONS
-c Connect to a TagmaDebug control server.
-H HOST Connect to HOST instead of localhost.
-h Display this text.
-P PORT Connect to PORT instead of 5444.
DESCRIPTION
TagmaDebug is a simple interactive debugger for TCL programs.
When TagmaDebug starts it creates a trace on "__TagmaDebugMain." This
procedure sources the script provided on the command line. The trace on
this procedure basically causes a break on every command. Once the
script completes the procedure "__TagmaDebugComplete" is called. There
is a hidden enter trace on this procedure to ensure the user gets the
debugger prompt one last time.
The unknown command is replaced and the original called. If the original
unknown throws an error it is caught. The error message is displayed and
the debugger is entered. The debugger will not step into unknown.
All output from the debugger is written to stderr. This allows for
redirection of the program or debugger output if desired.
PROMPT
The prompt is composed of flags in curly brackets '{}', the level of
execution, the procedure (if one is executing) and the name of the
debugger.
The flags indicate when certain features are enabled. 'B' indicates the
body of procedures will be displayed. If disabled only the procedure
name and arguments are printed. 'E' indicates enter will continue a
step, the same as typing 'c Enter'. 'P' indicates packages will be
stepped into. 'V' indicates verbose mode is enabled. This will cause
additional output in certain places.
Sample prompt: {E}(1 => foo)Tagma>
This prompt indicates Enter will continue a step and execution is one
level deep in the procedure "foo".
COMMANDS
There are several interactive commands that control the debugger. There
is no line editing and very little nicety.
! Executes a shell command.
= Prints the content of each variable name provided.
a or > Prints the command being executed.
c or Enter Continue execution.
e or [..] Evaluates TCL code. When using [..] The closing ']' is
required.
h or ? Prints the help text.
f or ff Prints the stack frame. ff prints also prints the line and
file, when available.
Prints the Frame #, Level # (as in info level), Procedure
name and command. The command is truncated if it is multiple
lines.
var log Logs all modifications of a variable to stderr.
var break Adds breakpoint for writes to a variable.
var info Prints all variables being watched for.
var clear Clears logging and breaks for variables. Passes the variable
to [string match ...] so globbing can be used.
cmd enter Set a break point for the entering of a command.
cmd leave Set a break point for the leaving of a command.
cmd step Steps through the command. Every command that is executed
inside the command is a breakpoint.
cmd clear Clear break points. Passes the command to [string match ...]
so globbing can be used.
con Connect to a TagmaDebug control server. Optional Host and
port. (Default: localhost and 5444)
p Prints the current level & procedure. When at the top level
'::' is printed for the procedure.
r Restarts the program.
x or q Exit the debugger. Ctrl-D should also have the same effect.
SETTINGS
Settings to control TagmaDebug. These are reflected by the flags inside
{} in the prompt. The flags and settings use the same letter.
B Toggle printing the body of procedures when they are defined.
E Toggle Enter acting as a shortcut to 'c Enter'.
P Toggle stepping into package.
V oggle verbosity. Print extra info, when available.
CONTROL SERVER
NOTE: The shell does not work under Tkcon.
The program server.tcl starts a TCP server. Tagma Debug can connect to
this server for remote control. All debugger output and user input is
sent to comes from the server. The server requires an event loop process
to function. By default if the program is run it starts the server
process, enters the remote debug shell and starts an event loop. The
shell is designed to make debugging similar to using TagmaDebug
directly.
The 'tagma' command is used to control the server and interact with the
debugger. With no options it sends its arguments to the remote debugger.
tagma Options:
-help Print help for the tagma command.
-select Select from connected debuggers. Lists the available and
current connections with no arguments.
-shell Enter an interactive shell. Simulates working directly with
the debugger. If there is no active connection it will wait
for a client to connect. The server must be running before the
shell is started.
-start Start the Tagma server process. (Optional port)
-verbose Control verbose mode. (on/off) Displays the current state with
no arguments.
-- End option processing.
PORTABILITY
TagmaDebug should work with any TCL version 8.4 or later. Testing has
thus far been limited to Tcl 8.5 under Cygwin on Windows 7.
INSTALLATION
Either copy tagmadebug.tcl where you want it or run "make install".
HOME
<https://github.com/LStinson/TagmaDebug>
<http://wiki.tcl.tk/28695>
COPYRIGHT
This script is derived from "TclDebugger by S.Arnold. v0.1 2007-09-09" -
<http://wiki.tcl.tk/19872>. What ever copyright he says his code is
under is what applies to this one. Since it was listed publicly with no
restrictions I am assuming it is free to modify.
AUTHOR
Written by Lorance Stinson AT Gmail....