-
Notifications
You must be signed in to change notification settings - Fork 1
This package provides dynamic debugging support for Tcl 8.5 or higher. It provides mainly commands to run Tcl files or scripts and to step through them, to define breakpoints, and to access variables in the context of the debugged code.
DDT instrumentalizes the debugged code by inserting debugging helper commands. This is transparent (=invisible) to the user except he checks the procedure bodies for example with 'info body'. DDT uses the "unsupported" disassemble function of Tcl 8.5 and 8.6 to analyse the code to debug, to identify potential program execution stop locations.
DDT exposes the following API commands.
Configure DDT, or return the current configuration. If no argument is provided the current configuration is returned. If a single argument referring a configuration parameter is provided the configuration for this parameter is returned. Pairs of parameter names and values need to be provided if a new configuration needs to be defined. The available configurations are described in section Configuration.
| Parameters | Description |
|---|---|
| [args] | Configuration definition list |
Returns the configuration if no new configuration is defined
ddt::Configure -BreakCallback DebugGuiUpdate
ddt::Configure -InitVars {argv0 {} argv {}} -InitScript "package require Tk"
ddt::Configure -Mode disable
Starts the execution of a file or of a script. If breakpoints are defined the debug environment is initialized. If the configuration -SI is set the file or script is executed by a slave interpreter that is created.
The two arguments allow using this command in 2 ways.
- A file is provided but not a script: The file is executed.
- A file and a script is provided. The script is executed. The file name is just used as identifier.
| Parameters | Description |
|---|---|
| FileName | File name (can also be a fictitious identifier) |
| [Script] | If provided this script will be executed |
Result returned by the file/script
ddt::Cont, ddt::Step, ddt::Stop, ddt::SetBP
Continues the execution of the program that is stopped on a breakpoint.
Returns always the execution state 'cont'.
ddt::Run, ddt::Step, ddt::Stop, ddt::SetBP
Performs a single step in a program that is stopped on a breakpoint.
Returns always the execution state 'step'.
ddt::Run, ddt::Cont, ddt::Stop, ddt::SetBP
Forces the callback function to be re-executed. A refresh of the application UI's status can be forced in this way.
Returns always the execution state 'refresh'.
Stops the execution of a program that is currently either running or stopped on a breakpoint.
Returns always the execution state 'stop'.
ddt::Run, ddt::Cont, ddt::Step, ddt::SetBP
Evaluates a command sequence in the context of the executed procedure of the debugged program. Returns the result of the command sequence. This command can be used by the callback function to inspect the status of the debugged program or procedure. However, this command cannot be used by functions that are interactively executed (e.g. via buttons).
| Parameters | Description |
|---|---|
| args | Command sequence |
Result returned by the command sequence, or any error generated by it
Evaluates a command sequence in the context of the executed procedure of the debugged program. Returns always an empty string. This command can be used by the callback function as well as by a function that is interactively executed (e.g. via buttons).
| Parameters | Description |
|---|---|
| args | Command sequence |
-
Set or delete a breakpoint in a specified file at a specified line. If no condition is explicitly specified, or if the condition is 1, a non conditional breakpoint is defined. If the condition is 0 or '' an eventually defined breakpoint is deleted. The provided condition will be used in all other cases as a dynamic breakpoint condition.
| Parameters | Description |
|---|---|
| FileName | File to apply the breakpoint definitions |
| LineNbr | Line to which the breakpoint definition |
| [Condition] | Optional condition |
Returns the new breakpoint condition
Returns for a specified file the breakpoint definitions. If no line is specified GetBP returns for all breakpoint for the file, otherwise only the ones for the specified line. The returned breakpoint definitions is a list composed by pairs of line numbers and breakpoint conditions.
| Parameters | Description |
|---|---|
| FileName | File for which the breakpoint definitions have to be returned |
| [LineNbr] | If defined only the breakpoint definitions are returned only for this line |
Breakpoint definition list
Swaps a breakpoint in a specified line of a specified file. If no breakpoint (conditional or non conditional) exists, a non conditional breakpoint will be created. Otherwise the existing breakpoint will be deleted.
| Parameters | Description |
|---|---|
| FileName | File for which the breakpoint definitions needs to be applied |
| LineNbr | Line for which the breakpoint definition needs to be applied |
Returns the new breakpoint condition
dt::GetBP, dt::SetBP
Returns for a specified file the possible breakpoint locations. If a line is specified GetBPLocations returns the breakpoint locations just for this line.
| Parameters | Description |
|---|---|
| FileName | File for which the breakpoint locations have to be returned |
| [LineNbr] | If defined: Line for which the breakpoint locations have to be returned |
Breakpoint location list
Returns the execution state of the currently debugged file or script. The following states exist:
- "" (initialization state)
- cont (continuous running)
- step (single instruction execution)
- stop (stop request)
- refresh (refresh request),
- exec (command sequence execution request)
- stopped (state while the Brk instruction is executed)
Returns the current execution state.
DDT is configured via the ddt::Configure command. The configuration is stored by DDT inside the Config array variable. DDT uses the following configurations:
Callback function configuration. Defines the callback function that will be called each time the execution of the debugged program is stopped.
ddt::Configure -BreakCallback DebugGuiUpdate
Slave interpreter setting. If set to 1 (default) a slave interpreter will be used, if set to 0 the master interpreter will be used.
ddt::Configure -UseSI 1
Initialization variable definition. The variable initializations, defined as pairs of variable names/values, will be executed in the context of the debugged program prior to the program start.
ddt::Configure -InitVars {argv0 "" argv ""}
Initialization script. The defined script will be executed in the context of the debugged program prior to the program start.
ddt::Configure -InitScript {}
Enables/disables debugging. Valid settings are 'enable' (default), and 'disable'.
ddt::Configure -Mode enable
Here is some information about the internal variables. The following array variables contain information about the instrumentalized source scripts and files. All of them are using the source identifier as array index.
| Description | |
|---|---|
| DisassembleInfo | Disassemble information of the source |
| SourceScript | Source script |
| SourceIScript | Instrumentalized source script |
| CommandPosListN | List of character positions that correspond to a command begin |
| CommandPosListRC | List of line/column positions that correspond to a command begin |
Registered source files and breakpoints.
| Description | |
|---|---|
| SourceFiles | Source file name list |
| BP | Breakpoint array |
The following variables contain information about the execution state of the program being debugged.
| Description | |
|---|---|
| ExecSourceId | Source identifier |
| ExecLineNbr | Currently executed line number |
| ExecState | Execution state (see <ddt::GetExecState>) |
Internal commands used by DDT.
Initializes, or re-initializes all variables used internally by DDT. The source file list and the defined breakpoints will be kept unless a full initialization is performed.
| Parameters | Description |
|---|---|
| [FullInit] | A full initialization will be performed if set to 1 |
-
Returns the source identifier for a file. The source identifier is an integer.
| Parameters | Description |
|---|---|
| FileName | File name (can also be a fictitious identifier) |
Source identifier
Returns the source (e.g. script) designated by the file name.
| Parameters | Description |
|---|---|
| FileName | File name (can also be a fictitious identifier) |
Source script
Get the instrumentalized source script of a file or of a script. This command can be used in 2 ways.
- Just a file is provided but not a script: In this case the file content is read, instrumentalized and returned.
- A file and a script is provided. The provided script is instrumentalized and returned in this case. The file name is used as identifier to cache instrumentalized source script.
| Parameters | Description |
|---|---|
| FileName | File name (can also be a fictitious identifier) |
| [Script] | If provided this script will be instrumentalized |
Instrumentalized source script
ddt::Run, ddt::Instrumentalize, ddt::GetSourceId, ddt::GetSource
Tcl source command patch. This command instrumentalizes the sourced files and execute them then in debug mode if the following conditions are satisfied:
- Currently executed code is part of the debugged program (not part of the debug environment)
- Sourced file is not sourced from a package
- The source command is not called with the -encoding option
- The sourced file is not pkgIndex.tcl If one of these conditions is not satisfied, source_debug will source the file via the normal source command.
| Parameters | Description |
|---|---|
| args | Arguments normally provided to source |
Return value normally provided by source
ddt::package_debug, ddt::info_debug
Tcl package command patch. This command keeps track about packages that are going to be loaded. This information is used by the patched source command (ddt::source_debug) to disable the instrumentalization of sourced files if they are sourced by the package command.
| Parameters | Description |
|---|---|
| args | Arguments of the package command |
Return value of the package command
ddt::source_debug, ddt::info_debug
Patches the info command. The 'info script' command doesn't work for scripts that are sourced in debug mode (e.g. executed as instrumentalized script). This patch corrects this behaviour.
| Parameters | Description |
|---|---|
| args | Arguments to the info command |
Return value of the info command
ddt::source_debug, ddt::package_debug
Identifies the command positions in a command's last argument. BuildCommandPositionsCmdString extracts the scripts provided as last arguments to a commands (ex 'proc', 'foreach' and 'namespace eval' and evaluates the position of the commands contained inside the script. BuildCommandPositionsCmdString calls BuildCommandPositions to get the command positions, after removing the {} or "" that encloses the scripts.
| Parameters | Description |
|---|---|
| CmdString | Command string that has as last argument a script |
| SrcId | Source identifier of the script |
| Offset | Position offset, used for the analysis of sub-scripts |
-
ddt::BuildCommandPositions, ddt::Instrumentalize
Identifies the positions of the commands that are present in a script. These positions are stored inside the array variables CommandPosListN and CommandPosListRC.
To identify the command position BuildCommandPositions uses the outputs from Tcl's ::tcl::unsupported::disassemble command. This output is stored inside the array variable DisassembleInfo.
BuildCommandPositions is recursively called for code sections that are not byte compiled (e.g. proc, namespace, foreach). The optional argument Offset defines the offset position of the sub script inside the full script. Parameters:
| Description | |
|---|---|
| Script | Script for which the command positions have to be analysed |
| SrcId | Source identifier of the script |
| [Offset] | Position offset, used for the analysis of sub-scripts |
-
ddt::BuildCommandPositionsCmdString, ddt::Instrumentalize
Instrumentalizes a file or a script. This command can be used in 2 ways.
- Just a file is provided but not a script: In this case the file content is read and instrumentalized.
- A file and a script is provided. The provided script is instrumentalized in this case and the file name is just used as identifier.
| Parameters | Description |
|---|---|
| FileName | File name (can also be a fictitious identifier) |
| [Script] | If provided this script will be instrumentalized |
File/script source identifier
Initializes the run environment for the slave program. If an execution in a slave interpreter is required, this one is created. Then, the initialization variables are defined and the initialization scripts executed. If debugging is required, e.g. if break points are set, the patched commands (source, package, info) are activated. If debugging is required and if the execution happens by a slave interpreter the required set of debug commands are created in the ::ddt namespace of the slave interpreter.
| Parameters | Description |
|---|---|
| [DebugSupport] | Indicates if debugging is required |
-
ddt::RunEnvironment_Stop, ddt::RunEnvironment_Resume, ddt::RunEnvironment_Distroy
Switches the run environment into non-debugging mode
-
-
ddt::RunEnvironment_Init, ddt::RunEnvironment_Resume, ddt::RunEnvironment_Distroy
Resumes the debugging mode of the run environment
-
-
ddt::RunEnvironment_Init, ddt::RunEnvironment_Stop, ddt::RunEnvironment_Distroy
Destroys the debugging run environment
-
-
ddt::RunEnvironment_Init, ddt::RunEnvironment_Stop, ddt::RunEnvironment_Resume
This procedure will be inserted in front of each command inside the debugged source files and scripts. It will need to decide if a continuously executed program needs to stop due to a breakpoint that is set or because a program sequence is executed in single step mode. Brk will call an application specific callback function that allows inspecting the status of the debugged program or procedure. By calling the procedure Refresh, Brk will explicitly call this callback function. By calling the procedure Exec, Brk will execute a command sequence in the context of the debugged program/procedure.
| Parameters | Description |
|---|---|
| SrcId | Source identifier of the script |
| LineNbr | Line where this break command is inserted |
| [ColNbr] | Optional column where this break command is inserted. Only defined if not at the first location in the line. |
Log the information provided as argument. This procedure is implemented in the ddc namespace of the slave interpreter. It calls LogDirect that will perform the log inside the main interpreter.
| Parameters | Description |
|---|---|
| args | The list elements are concatenated |
-
Logs the information provided as argument in the context of the main interpreter. LogDirect will be aliased from the main interpreter to the slave interpreter.
| Parameters | Description |
|---|---|
| args | The list elements are concatenated |
-