Debugger

Printable Version

Debugger
  1. Overview
  2. Interface
    1. Menu and Toolbars
    2. Main text editor panel
    3. File browser panel
    4. Variable overview panel
    5. Additional information panel
  3. Tutorial
    1. Setup
    2. Debugging
    3. Stepping
  4. Keyboard short-cuts



Overview

 The debugger lets you test and run your scripts by setting break points inside your code and analyzing the situation once reaching them. With its help you can avoid adding custom debug print calls to check for the assignment of variables or if a certain part of the code got reached. It is easy to use and follows known conventions for debugging environments.

The user interface is divided in the following sections:

You can move around each panel by dragging and dropping the corresponding title bar. You can resize the panel by pulling its borders. You can close panels you don't need by using the cross symbol on the upper right corner and make them reappear again through the View-menu.

To actually use the remote debugger's functionality see section Tutorial.

Most actions described here require use of the left mouse button, for the remainder of the text clicking a button means using the left mouse button.
In the last section the available keyboard short-cuts are listed.

User Interface

Menu and Toolbars

 The file menu lets you open and save files, create and switch between projects and exit the application. The view menu lets you show hidden parts of the user interface. There is also the option to reset the complete window layout. With the debug menu you can control your debugging sessions (see section Debugging for details). The help menu finally directs you to further information on our website.
The most common operations are directly accessible in the toolbars.

Main text editor panel

 The text editor panel shows you all currently opened source code files. You can toggle between different source files by clicking on the tabs at the top of the panel. To close a specific source file press the cross in this row on the right edge of the panel.
If you have opened many files you can use the arrows on the left and right side to move the currently shown tabs or use the small down arrow to directly jump to a specific file.
The editor behaves like a regular text editor that in addition automatically highlights script commands. You can use it to directly write your source code.

The most important part in conjunction with debugging is the setup of breakpoints. To set a break point press the left mouse button on the grey vertical bar to the right of the line numbers. A red dot will appear and signal the presence of the break point. Click on it again to remove it. Please be aware that you can only set breakpoints in source code lines that represent a script statement.

File browser panel
The file browser shows you the project directory tree. It only shows files with the following extensions: .lua, .xml and .i3d files. In the file browser you can open files for editing.
If you made changes to files outside of the debugger you have to refresh this view in the context menu. You can access the context menu with a right mouse button click.

Variable overview panel

 This panel shows you all variables and its assigned values in the current state.
There are two tabs with global and local variables. Global variables are accessible from any code part. Whenever you create a new variable that is not directly stored inside a table or specified as local, a new global variable is generated. Local variables are either parameters passed to a function or newly created variables with the local keyword.
Both tabs show a list with the variable name, its assigned value and its type. The contents of tables can be opened by using the + symbol in the variable list. For these contents a string representation of each key is used as name. If the key is a table its content is not visible.

Additional information panel

Callstack tab
While debugging, the callstack tab shows you the stack of functions called, that result in the current position in the code. The topmost list item specifies the current position in the code.
Each item in the list states the source code file and the position inside this file where the function call happened. Double clicking on an item results in opening this source code file at the specified position inside the text editor panel, the line is also marked by a green arrow on the left side.

Breakpoint tab
This tab shows a list of all set breakpoints. Double clicking on an item results in opening this source code file at the specified position inside the text editor panel, the line is also marked by a green arrow on the left side.

Output tab
The output tab shows the engine logging output. The output of your print commands is also shown there.
Script error messages are printed in this log as well. Double clicking on an item results in opening this source code file at the specified position inside the text editor panel, the line is also marked by a green arrow on the left side.

Tutorial

Setup

 To create a new remote debugger project use the file menu with File / New Project.... In the window that appears you have to specify the project settings.
  • Name: Name of the project
  • Location: Location where the project file is saved
  • Source Base: Directory that is used as the root for all source files in the project
  • Debug Port: TCP/IP port number
  • Command line: Command to run the application
  • Working Directory: Directory where to run the application
  • In most cases the fields for Location, Source Base and Working Directory will show the same value.

To be able to debug your program the debugger has to connect to the running application. The easiest way to manage this is by specifying the -autoConnectDebugger command line option in the XML-file for your application. The XML-entry should look similar to this line:
<cmdline>game.exe -script scripts/main.lua -name test -autoConnectDebugger</cmdline>
The mentioned command line option is added by default if you start the application within the debugger. You can still use the debugger without the autoConnectDebugger command line option by pressing F10 in the engine application. The status line at the bottom of the debugger will indicate the status of the connection to the game application.

Debugging

 An important part of debugging are breakpoints. Whenever the script code execution reaches a code line with a breakpoint the execution paused. You can set breakpoints inside the text editor panel by clicking next to the code line number. A red dot will appear to show the position of the breakpoint. The code will be stopped before execution of the script statement in the current line. Please note that only lines with script statements can be used for breakpoints. To remove a breakpoint you can click on the red dot again.
 To control a debugging session you can use the Debug-toolbar, the corresponding menu items or keyboard shortcuts.
To start a debugging session you need to launch the engine application. You can do this with the Start and Stop-commands.
Once a breakpoint is reached during execution of the script code the engine application pauses. Now you can inspect the current engine state with the help of the variable, the callstack and the output panel.

You can also pause the engine application at any point in time without a breakpoint with the Break all-command. This command is useful when you need to know what the engine application currently does.

To let the program continue use the Continue-command.

Stepping

 To further analyze the control flow of the script code and the change of variables you can also step the application on a line by line basis with the help of the Step into, Step over, and Step out commands.
The functionality provided is, in short words:
  • Step out - stop at the next script statement after the statement that called the current function
  • Step into - stop at the first script statement of the function to be called
  • Step over - stop at the next script statement in the current function
The current position in your code is always highlighted by a yellow arrow next to the line numbers. If you opened other files and don't know where the engine execution stopped you can always use the callstack and double click on its first entry and the code file will open in the text editor panel with the current line marked with a green arrow.

The following screenshots show an example situation.
The program is stopped at line 19 of the test.lua file. In the local variables panel we see that the two parameters of the function and the newly set variable with the parameter z are available. The callstack tells us, that we are currently in line 19, but also that the current function was called in line 9 from the current file. And again this function was called from line 52 of the main.lua source file.

If we want to continue debugging we could use the Step into command which would lead us to line 27, the first line with a statement of the called function third(). The Step over command would result the engine application to pause at line 21. And the Step out command would finally run the same code but stop at line 11.
Please note that line number 20 and 26 are no script statements and therefore you cannot set breakpoints on such lines.

Keyboard short-cuts
Key Function
Ctrl-S Save
Ctrl-Alt-S Save all
F5 Start/Continue debugging
Ctrl-F5 Start without debugging
F6 Stop debugging
F7 Break all
F10 Step over
F11 Step into
Shift-F11 Step out