Basic4GL, Copyright (C) 2003-2016 Tom Mulgrew
Symbolic Debugger
1-May-2016
Tom Mulgrew
A debugger is a tool that helps you track down and eliminate errors (or "bugs") in program code. Typically you use a debugger to pause the program at a point which you wish to investigate, then analyse the contents of variables at that point. You can also trace through the flow of the program to see exactly which code is executed and the effect it has on the data.
The Basic4GL debugger is integrated directly into Basic4GL itself. It supports the following features:
When Basic4GL starts the debugger displays and buttons are hidden.
To switch between debug mode and normal mode, click the "Basic4GL" menu on the main menu bar then "Debug Mode", OR press the corresponding button on the toolbar OR press Ctrl+D.
Basic4GL will now display the "watch" and "stack" windows along the bottom, and add the "stepping" buttons to the toolbar.
Basic4GL has 3 main states
This is when the program has stopped completely:
This means the Basic4GL program is running.
The program enters this mode when it is paused partway through running.
This happens if either:
While the program is paused:
At time of writing there is an issue with pausing Basic4GL programs running in fullscreen.
Basic4GL does not correct switch back from fullscreen to the editor.
Holding down the "Alt" key and pressing "Tab" a couple of times will often bring the editor back up. Or you may find it easier to debug your program in windowed mode until the screen fixing issue is fixed.
The Go/Stop button (displays a "Go" or "Stop" sign depending on the mode) is used to run the program from the start, or stop it completely so that it can be edited.
The Play/Pause debugging button (displays a play arrow or a pause sign) is used to pause the program or resume it from the position it was paused.
Basic4GL supports these standard functions for stepping through code:
They behave like any other debugger, that is:
"Step over" runs the current line of code and pauses on the next line. If the current line contains a "gosub" call, it will not step into it. Instead it will run the entire gosub routine and return.
For example, for the following program:
dim a, b: a = 10: b = 20 ' 1
gosub Two ' 2
printr a ' 3
end ' 4
Two: ' 5
printr b ' 6
return ' 7Clicking "Step over" once will pause the program on line 2. Clicking it again will pause the program on line 3, despite the fact that lines 6 and 7 were also executed by the "gosub" call (and 20 was printed on the screen).
"Step into" behaves exactly like step over, except
when the current line contains a "gosub" call.
In this case the program is paused on the first line of the
"gosub" routine.
For example, for the previous program, clicking "Step Into" once will pause the program on line 2. Clicking it again will pause the program on line 6. (Then line 7, then line 3.)
"Step out of" is only available if the program has been paused inside a gosub call. "Step out of" will run the rest of the "gosub" routine and pause the program on the instruction immediately after the actual "gosub" call.
So on the above program, clicking "Step into" twice to get to line 6 will make the "Step out of" function available. Clicking "Step out of" will then pause the program on line 3, i.e. the instruction immediately after the "gosub" on line 2.
A "breakpoint" is used to pause a program at a particular line of code. You place the breakpoint on the line (or lines) where you wish to pause the program, and then run it. The program will continue running until it reaches the line (or lines) of code. When it does so, it will pause at the start of the line, before executing any of the code on it.
To place a breakpoint, click on the gray area on the left side of the editor, next to the line where you wish to pause the program. Basic4GL indicates breakpoints with a small red circle. To remove the breakpoint, simply click it again.
You can add a breakpoint at any time, even if the program is
running (except in fullscreen mode obviously). The breakpoint
becomes active from the moment you click it in.
Breakpoints will only work on lines that correspond to executable
code. If you place a breakpoint on a line with no corresponding
code, it will be dithered out to indicate that it is inactive.
Watches display the value of a variable. Watches are only active when the program is stopped or paused, and are displayed in the wide window immediately under the editor (when debug mode is on).
To add a watch, double click the blank line at the top of the watches list and type in the variable or expression you wish to watch. Alternatively you can right click a variable in the editor and choose "Add watch".
Basic4GL will now display the variable/expression, along with it's value, so you can track changes to it (e.g. as you step through lines of code).
You can watch any valid Basic4GL expression, including arithmetic expressions and functions.
Beware of functions that have side effects. For example, placing a watch on "ReadInt (file)" (read an integer from file with handle "file") will advance the current position in the file each time the watch is evaluated, and most likely cause the code that you are debugging to fail.
You can also quickly see the value of a variable by moving the mouse over it in the editor. To quickly see the result of an expression, highlight it first, then move the mouse over it.
Mouse-over hints will not evaluate functions in case they have side effects. To evaluate a function you must add a watch instead.
The "stack display" is displayed at the bottom right, and lists all the active "gosub" and/or function and subroutine calls.
Double clicking an entry causes the editor to jump to the calling line in your program.
The top of the stack display always displays "IP", referring to the current instruction pointer. Double clicking this moves the editor back to where the program was paused.
The following table lists the keyboard shortcuts.
| Function | Shortcut |
| Step over | F10 |
| Step into | F11 |
| Step out of | Shift + F11 |
| Set breakpoint | F9 |
| Run/Pause | F5 |
| Add watch | Ctrl + F5 |