Insight Internal Debugging Functions

Overview

This describes the basic internal functions for debugging Insight. This information is for Insight developers trying to debug Insight, not for users trying to debug other programs.

Environment Variables

GDBTK_DEBUG - Setting this variable controls the Debug window.

GDBTK_DEBUG may have the following values:

0 or unset

The Debug window is not opened and not listed on the menu. (You may still open it by typing Ctrl-U in the source window.)

1

The Debug window is listed on the menu, but not opened.

2

The Debug window is opened at startup.

GDBTK_TRACE - This variable determines if tracing is enabled. Tracing may only be enabled at GDBTK startup. Changing GDBTK_TRACE while GDBTK is running has no effect.

GDBTK_TRACE may have the following values:

0 or unset

Tracing is not enabled.

1

Tracing is enabled, but not started. To start tracing, you need to do so in the Debug Window or from the console. (The command to do this is "tk ::debug::trace_start).

2

Tracing is enabled and started immediately.

GDBTK_DEBUGFILE - This variable contains an optional filename where GDBTK will write all debugging information. This information will include the output of all "debug" and "dbug" commands, as well as tracing, if it is enabled. The value of GDBTK_DEBUGFILE will not change what is displayed in the Debug Window, with one exception; when the Debug Window is opened, it will read the contents of GDBTK_DEBUGFILE (if it is set and not "stdout").

GDBTK_DEBUGFILE may have the following values:

unset

No information will be logged.

filename

Debugging information will be logged to filename.

"stdout"

Debugging information will be written to stdout

Tcl Debugging Functions

All debugging functions have been moved into debug.tcl in the ::debug namespace. "debug" and "dbug" are imported into the global namespace.

The following are the standard debug message functions.

# -----------------------------------------------------------------------------
# NAME:		debug::debug
#
# SYNOPSIS:	debug { {msg ""} }
#
# DESC:		Writes a message to the proper output. The priority of the
#		message is assumed to be "I" (informational). This function
#		is provided for compatibility with the previous debug function.
#		For higher priority messages, use dbug.
#
# ARGS:		msg - Message to be displayed.
# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------
# NAME:		debug::dbug
#
# SYNOPSIS:	dbug { level msg }
#
# DESC:		Writes a message to the proper output. Unlike debug, this
#		function take a priority level.
#
# ARGS:		msg   - Message to be displayed.
#		level - One of the following:
#				"I" - Informational only 
#				"W" - Warning
#				"E" - Error
#				"X" - Fatal Error
# ----------------------------------------------------------------------------

These next functions are used to trace variables, which should not be confused with the functions tracing.

# ----------------------------------------------------------------------------
# NAME:		debug::trace_var
# SYNOPSIS:	debug::trace_var {varName mode}
# DESC:		Sets up variable trace.  When the trace is activated,
#		debugging messages will be displayed.
# ARGS:		varName - the variable name
#		mode - one of more of the following letters
#			r - read
#			w - write
#			u - unset
# ----------------------------------------------------------------------------
# ----------------------------------------------------------------------------
# NAME:		debug::remove_trace
# SYNOPSIS:	debug::remove_trace {var mode}
# DESC:		Removes a trace set up with "trace_var".
# ----------------------------------------------------------------------------
# ----------------------------------------------------------------------------
# NAME:		debug::remove_all_traces
# SYNOPSIS:	debug::remove_all_traces
# DESC:		Removes all traces set up with "trace_var".
# ----------------------------------------------------------------------------

The following two functions may be used to start and stop tracing programmatically.

# -----------------------------------------------------------------------------
# NAME:		::debug::trace_start
# SYNOPSIS:	::debug::trace_start
# DESC:		Starts logging of function trace information.
# -----------------------------------------------------------------------------
# -----------------------------------------------------------------------------
# NAME:		::debug::trace_stop
# SYNOPSIS:	::debug::trace_stop
# DESC:		Stops logging of function trace information.
# -----------------------------------------------------------------------------