Included debugging tools

The Debug output window

In this window, the output of the Debug statement will be displayed. The Debug statement is a quick and simply way to print messages for debugging purposes.

The debug window will automatically open at the first output is produced by your program. If you then close it, it will not automatically open on subsequent messages, however they will still be logged. You can copy this output to the clipboard or save it to a file. There is also a button to clear the messages from the window.

The Watchlist

The watchlist can be used to track changes in variables of your program in real time, while the program is running. It can only display single variables (no full structures), however, these variables can be a part of structures.

To add a variable, select its procedure (if it is a local variable) or select "--- Main ---" if it is a global variable or part of an array or linked list. Then type the variable name, as you would access it in your source code into the Variable field and press Add.

  Examples:
  MyVariable$                      - add a normal string variable
  Array(1, 5)                      – add an array field
  Structure\subfield[5]\value      – add a variable inside a structure
  MyLinkedList()\structuresubfield – add a variable inside a structured linkedlist

You can also add new watched variables from the VariableViewer, by right-clicking on them and selecting "add to watchlist"

In the list you will see the values of the watched variables. If the value is displayed as "---", it means that this variable is not valid at the current point in the source code. (for example if you watch a local variable, or a linked list element and the list has no current element)

The watched variables are remembered between the debugging sessions, and even saved with the compiler options, so you do not need to re-populate this list all the time.

The Variable Viewer

The Variable viewer allows to examine global and local variables, arrays and linked lists.

In the “Variables” Tab, you can view both the global variables and the local ones of the current procedure (if any).

In the "Arrays" tab, you have a list of all arrays in your program (also both global and local), and the dimensions in which they are currently defined. (-1 means that Dim was not called yet) Click “Update list” to update the top list of arrays and their dimensions.
By right-clicking on an array, you can quickly display its content in the "View Array/List" tab.

In the "Linked Lists" tab, you have a list of all Linked Lists, the number of elements they currently hold ( "-" indicates that NewList was not called yet), as well as the index of the current element of the list. ( "-" indicates that there is no current element) Clicking "Update List" also updates this overview list.
By right-clicking on a list, you can quickly display its content in the "View Array/List" tab.

The "View Array/List" tab allows you to view individual entries of an array or linkedlist. To do so, enter the name of the array or list (just the name, no type or "(" ), select what kind of items to display and press "Display".

"Display all items" simply displays everything. "Display Non-zero items only" will only display those items that do not hold the value 0 or an empty string. This makes viewing large arrays/lists with only few valid items in them simpler. A structure is considered "zero" if all of its items either hold the value 0 or an empty string.

"Display Range" allows you to select the specific range to display by its index. The range can be given for each Array dimension individually, separated by commas. If one dimension is not specified at all, all of its items will be displayed.
Here are a few examples for valid range input:

  "1-2, 2-5, 2" : first index between 1 and 2, a second index between 2 and 5 and a third index of 2.
  "1, 2-5"      : first index of 1 and a second index between 2 and 5.
  "1, , 5"      : first index of 1, any second index and a third index of 5.

By right-clicking on any variable or Array/Linked list field, you can copy that variable, or add it to the watchlist for realtime-tracking of its value.

The Callstack viewer

The callstack viewer shows which nested procedure calls led to the current position in the code. Each entry in the list means one procedure that is currently open. It shows the line and file from which it was called, and the arguments that were used to call the procedure. By clicking on the Variables button for each procedure, you can look at the variables of that instance of the procedure.

This allows to easily trace, from which part of the code, a procedure was called. The callstack view does only automatically update when you stop the program, or use Step to execute single lines. While the program is running, you have to use the Update button to update the view for the current code position.

The "Statistics" tab shows the number of times each procedure in the code was called. You can reset the count for all procedures with "Reset all", or for the currently marked entry with the "Reset" button. Like with the callstack, the updates are not automatic while the program is not stopped. Use the Update button for that.

The Memory Viewer

The memory viewer lets you view a memory area in your program. Enter the range you wish to view (in decimal) into the Range fields and click display. If the memory area is valid for viewing, it will be displayed in the area below. If parts of the area are not valid for reading, you will get an error message.

The type of display can be changed with the combo box in the lower left corner. The following view modes are available:

Hex View
The memory will be displayed like in any hex viewer, giving the memory location in hex display on the left, followed by the hexadecimal byte values, and then the string representation in the right column.

Byte/Character/Word/Long/Quad/Float/Double table
The memory area will be shown as a table of the specified variable type. Whether or not this table is single-column or multi-column can be set in the Preferences. (see “Configuring the IDE”)

String view
This displays the memory area as a string, with any non-string characters displayed in [] (for example “[NULL]” for the 0 byte.) A linebreak is added after newline characters and [NULL] to improve the readability of the output. The memory area can be interpreted as an Ascii, Unicode or Utf8 string.

You can also export the viewed memory area from the memory viewer:

Copy (Text): Copies the displayed area as text to the clipboard.
Save (Text): Saves the displayed area as text to a file.
Save (Raw): Saves the memory area as raw binary to a file.

The Library Viewer

The Library Viewer provides information about the objects that were created by certain libraries. It allows to quickly check which images are currently loaded in the program, or which gadgets are created.

Once the program is started, the combobox on top of the window can be used to select the library to view. The list below will then show all objects of the library that currently exist in the executable along with some additional information on each object. The "Update" button will update this list of objects. Selecting an object in the list will display more detailed information about it in the text area on the left, and if supported by the library also a visual display of the object on the right. (for Images, Sprites, ...)

If the combobox displays "No Information", this means that your executable has used no library that supports this feature.

Currently, the Library Viewer is supported by the following libraries:
Thread
Gadget
Window
File
Image
Sprite
Sprite3D

The Assembly Debugger

The asm debugger is provided for advanced programmers to examine and change the CPU register content and to examine the programs stack for debugging of inline asm code.

The Processor Register view is only available while the program execution is halted. By changing any of the register values and clicking “Set”, you can modify the value in that register.

The Stack trace shows the content of the programs stack given in relation to the ESP register. If the current stack position is not aligned at a 4 byte boundary, there can be no information given about the content of the stack. In this case the stack is shown as a hex display.

If the stack pointer is properly aligned, the stack contents are displayed with comments about the meaning of the contained values. (detailing the pushed registers and other values on a PB procedure call.)

The stack trace is updated automatically when you stop the execution or step though the program, unless you specify otherwise in the Preferences. If you disable the automatic update, there will be an "Update" button displayed to do so manually.

Note: The Assembly debugger is currently not available on MacOSX.

The CPU Monitor

The CPU Monitor displays the CPU and Memory usage of each debugged program that is currently running. It also displays the system-wide total usage and available free resources. By selecting/deselecting the checkbox before each entry, you can select which entries will be shown in the above graph. By double-clicking on an entry, you can select the color for its display.

You can also specify an update interval in which to update the list and graph. The displayed percentage is a the average of usage in the last interval.

You can also set the CPU monitor to remain on top of all other windows (not on the gtk1 version of the IDE on linux).

Note that the Memory usage display for “Total usage” and “Free Resources” display physical memory usage, whereas the memory usage shown for each program is the virtual memory that is used (including swap space on disk).