Debugger - KidneyThief/TinScript1.0 GitHub Wiki
The TinScript Debugger is a fully featured debugging tool, connecting remotely to any TinScript application through the threaded winsock2 socket implementation included in the /external library within this depot.
The application itself is developed using Qt 5.0.1, and has the benefits of using the familiar features of Qt, including a configurable layout through a framework of tabbed and docking widgets.
The debugging features for each component are described below. While they are fairly standard, there are three features that may be of particular interest:
- While execution is halted upon triggering a breakpoint, the Console is still active, and capable of sending commands to the target for immediate execution. See the Console for more details.
- Conditional breakpoints and tracepoints are supported. See Breakpoints for more details.
- Data breakpoints are supported. See Watches for more details.
- Install Qt 5.0.1 or later from: http://qt-project.org/
- To use this VS2010 solution, under your computer properties, set a system environment variable to the Qt directory below /bin and /include:
- e.g. set QT_ROOT = "E:\_DEV\Qt\5.0.1\msvc2010"
- Also *append* the /bin to your PATH environment variable
- e.g. Path=E:\_DEV\Qt\5.0.1\msvc2010\bin;...
- Open the solution: /TinScript/TinQTConsole/TinQTConsole.sln
- Build the solution, and either:
- Run through the debugger
- Copy both the TinQTConsole.exe from the /Release, and the "TinScript Default Layout" from the solution directory, and run from your preferred location
There are several drop down menus, but the two most significant are:
- Debug
- While several debugging features have associated buttons, this menu contains a complete set of debugging actions, and displays their shortcut keys.
- Screenshot: Menu: Debug
- Scripts
- This menu contains options to open a script, go to a line, or search the current script.
- The bottom of this menu is dynamically populated with each script that the target has executed.
- Screenshot: Menu: Scripts
- The Toolbar, below the menu, contains the following:
- "File" line edit, set to script currently being viewed, but you can enter the name of a script to view (or hit 'return' to refresh as well.
- Run / Step / Step In buttons, for actions to take when hitting a breakpoint.
- Note: The shortcuts for these are the same as the Visual Studio defaults, F5, F10, F11, and shift+F11 (for Step Out).
- "Find" line edit, will search the current script for the entered string.
- Ctrl + F, to focus entry, and F3 to search again.
- The "find" status is displayed after the line edit.
- Screenshot: Toolbar
- The Status Bar, found at the bottom of the debugger, contains the following:
- Connection status
- Will display "Connected", "Not Connected", and "Breakpoint" status.
- Target root directory
- Because this debugger is a separate remote application, it's probably not located in the same directory as the target executable. However, for the purpose of communicating which scripts the target is executing, it sets its own root directory to match the target.
- Note: This means that locally, the debugger must have access to an up-to-date directory of scripts identical to the target.
- Target IP and Connect / Disconnect button.
- IP:127.0.0.1 is always for your local machine.
- Screenshot: Status Bar
- Connection status
This is your window into the target:
- The "Output" window on the debugger reflects all Print() messages executed on the target.
- While the debugger is connected, the "Input" line edit at the bottom sends commands directly to the target, as if they had been typed into the target directly.
- NOTE: Even while the target is halted during a breakpoint, commands send from the debugger are executed immediately. This is a substantial debugging advantage, as you can execute anything from "ListObjects();", to modifying any variable or member, to calling functions and methods "out of sequence" in an effort to find a problem.
- Screenshot: Console
This is where you can view the text of scripts. The script being viewed will always have it's file name displayed in the Toolbar. In addition to just viewing a script, this window is used for two other reasons:
- Breakpoints:
- Double-clicking a line in the script will set or remove a breakpoint, reflected in the Breakpoints window.
- A line with a breakpoint is preceded with a 'B' for an enabled breakpoint, and a 'b' for an existing but disabled breakpoint.
- Current instruction (IP)
- The line currently being executed (while we're halted after hitting a breakpoint) is preceded with a '==>', and highlighted.
- Screenshot: Source View
When a line containing a breakpoint is about to be executed, the execution is halted, and the stack of calling functions is visible in this window.
- Each entry in the Callstack is of the following format:
- [ <object ID> ] <namespace>::<function name> <filename>@<line number>
- The <object ID> will be '0' and the <namespace> will be '_global', for global functions (not methods).
- Double-clicking any entry in the call stack will open up the file and line in the Source View
- Screenshot: Call Stack
There are two types of breakpoints:
- Breakpoint at a location
- If set, execution is halted when the specified script file and line number are reached.
- These are displayed with an "enabled" checkbox, followed by the <filename>: <line number> location.
- Data breakpoints
- If set, execution is halted when the specified variable or member is written to.
- These are displayed with an "enabled" checkbox, followed by _watch:<variable>
- Conditional expression:
- Also with its own "enabled" checkbox, this is an expression (not a full statement) that, if when evaluated is 'true', will cause execution to be halted. If the condition is evaluated to 'false', execution continues even if the breakpoint is enabled.
- Tracepoint statement:
- Can be toggled - this is a full syntactically correct statement block.
- Tracepoints are executed regardless of whether the breakpoint is enabled - this allows a stream of output (assuming the the statement block contains a Print() statement) without halting execution.
- In addition, the Tracepoints can be set to only execute when the Condition (if it exists) evaluates to 'true'.
- For both Tracepoints and Conditionals for a location breakpoint, local variables and the 'self' keyword are supported.
- For Data Breakpoints, you are not restricted from using local variables, but because there is no specific location, use of them may result in a compilable expression.
- Note: If the variable or member is modified *outside* the execution of a script (e.g. from code), the execution will halted and the debugger will break on the next statement executed, regardless of where it is. The location will probably be unrelated, but the data breakpoint still be highlighted.
- Screenshot: Breakpoints
There are two windows used to display the value of variables and members:
- Autos
- When a breakpoint is hit, in addition to the current call stack being sent, a complete list of all local variables for each function on the call stack is also sent, populating the Autos window.
- If the variable is of type "object", then you'll get the entire tree of members for that object, if it exists.
- Double-clicking on an entry in the call stack will not only display the script location in the Source View, but will filter the Autos window to the local variables for that function.
- Watches
- This is where expressions that resolve to a variable or member are added, and are re-evaluated each time you step or break in the debugger.
- Pressing Ctrl + W will open the dialog to enter a variable watch expression.
- Pressing Ctrl + Shift + W will open the same dialog, but populate it with a variable currently selected in either the Watches or Autos windows.
- The "Break On Write" checkbox, if enabled, is how a Data Breakpoint is added. If the watch expression, after being sent to the Target, does in fact resolve to a valid variable or member, An corresponding entry in the Breakpoints window will appear.
- Screenshot: Variable Watches
