| <HTML> |
| <HEAD> |
| <TITLE>Internal Debugging Help</TITLE> |
| </HEAD> |
| <BODY> |
| <H2>Insight Internal Debugging Functions</H2> |
| <H3>Overview</H3> |
| <P> 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.</P> |
| |
| <H3>Environment Variables</H3> |
| <P><b>GDBTK_DEBUG</b> - Setting this variable controls the Debug |
| window.</P> |
| <P><b>GDBTK_DEBUG</b> may have the following values:</P> |
| <DL> |
| <DT>0 or unset</DT> |
| <DD>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.)</DD> |
| <DT>1</DT> |
| <DD>The Debug window is listed on the menu, but not opened.</DD> |
| <DT>2</DT> |
| <DD>The Debug window is opened at startup.</DD> |
| </DL> |
| |
| <HR> |
| <P><b>GDBTK_TRACE</b> - This variable determines if tracing is enabled. |
| Tracing may only be enabled at GDBTK startup. Changing <b>GDBTK_TRACE</b> |
| while GDBTK is running has no effect.</P> |
| <P><b>GDBTK_TRACE</b> may have the following values:</P> |
| <DL> |
| <DT>0 or unset</DT> |
| <DD>Tracing is not enabled.</DD> |
| <DT>1</DT> |
| <DD>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).</DD> |
| <DT>2</DT> |
| <DD>Tracing is enabled and started immediately.</DD> |
| </DL> |
| |
| <P><b>GDBTK_DEBUGFILE</b> - 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 |
| <b>GDBTK_DEBUGFILE</b> 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 <b>GDBTK_DEBUGFILE</b> (if it is set and not "stdout"). |
| <P><b>GDBTK_DEBUGFILE</b> may have the following values:</P> |
| <DL> |
| <DT>unset</DT> |
| <DD>No information will be logged.</DD> |
| <DT><i>filename</i></DT> |
| <DD>Debugging information will be logged to <i>filename</i>. |
| <DT>"stdout"</DT> |
| <DD>Debugging information will be written to stdout</DD> |
| </DL> |
| <HR> |
| <H3>Tcl Debugging Functions</H3> |
| <P> All debugging functions have been moved into debug.tcl in the ::debug |
| namespace. "debug" and "dbug" are imported into the global namespace.</P> |
| <P> The following are the standard debug message functions.</P> |
| <pre> |
| # ----------------------------------------------------------------------------- |
| # 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 |
| # ---------------------------------------------------------------------------- |
| </pre> |
| <P> These next functions are used to trace variables, which should not be |
| confused with the functions tracing.<P> |
| <pre> |
| # ---------------------------------------------------------------------------- |
| # 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". |
| # ---------------------------------------------------------------------------- |
| </pre> |
| <P> The following two functions may be used to start and stop tracing |
| programmatically.</P> |
| <pre> |
| # ----------------------------------------------------------------------------- |
| # 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. |
| # ----------------------------------------------------------------------------- |
| </pre> |
| </BODY> |
| </HTML> |