Debugging
BasinC provides many advanced systems for debugging your programs. Debugging is the process by which you determine where a program is not performing as it should, and narrow down the exact "fix" needed to get it working properly. 99% of the time, this is due to an error on the User's part - a typographic (spelling) error, or a misunderstanding of how the underlying system works in particular circumstances.
This chapter deals with the methods you have at your disposal to track down bugs, and fix them.
There is one caveat - the more debugging systems you enable, the slower a program will execute. BasinC will have to take time away from the emulation of the Spectrum BASIC in order to update the various sources of information you have asked for, which can result in choppy sound and inconsistent program speed even on the fastest of systems.
Stepping and tracing
One of the most simple debugging tools is the Program Trace. This can be enabled from the Run Menu in the Editor, and will update the editor window as statements execute in real time. This is quite rapid, and its use is of arguable value, but some people find that it's necessary to be able to "watch" how their program executes.
Another good method to use is to suspend the operation of your program, without actually stopping it. The beauty of an emulated system is that you can halt execution and yet maintain the ability to resume as though the program never stopped - the emulated computer has no idea that any interruption has occurred.
This can be useful - once the program is "halted" then you can elect to step through the code one statement at a time, and monitor the program flow and variable contents as you do. BasinC provides three methods of doing this:
- Single Stepping which will advance one line at a time - each statement will be executed and then control will be returned to the user with the program hlated once more.
- Step Over which will run emulation until the next statement is ready to run. Although on the surface this looks very much like Single-Stepping, the difference can be seen when you step over a GO SUB statement. The entire subroutine will be executed as normal, and the program halted when the subroutine RETURNs.
- Run To which will allow the program to run until the line that the editor cursor is currently resting on is ready to execute.
For more information, see the Run menu.
Breakpoints
The user can suspend operation using the Run Menu in the Editor, but you'd be hard pressed to accurately stop just where you want to. This is where Breakpoints and Watches come in very handy indeed.
At their simplest, breakpoints are "flags" attached to a statement which, when the statement is about to be executed, tell the emulation to suspend operations and return control to the user. You can then use the various other tools to examine what is going on - look at variables, the memory, the GO SUB stack and suchlike.
Breakpoints in the editor show up as a red bar on a statement:
Breakpoints in BasinC can get a lot more complex than this, however.
You can create a breakpoint by simply double-clicking a statement in the Editor. However, if you open the Breakpoints Window, you can get advanced properties of the breakpoint and attach conditions and logging options to it. With a condition attached, you can tell BasinC to suspend program operation only when that condition evaluates to "true", or a non-zero result.
The condition is simply an expression. Whenever that statement is due to be executed, the condition is evaluated, and if a non-zero result obtained then execution is suspended. Similarly, a log of the breakpoint can be added to the Log Window, the text of which is also an expression, which returns a string result. For instance, you can add a log to a breakpoint which sends the contents of a variable to the Log Window. This can be useful for tracking the state of a variable as the program executes - the breakpoint does not always have to suspend execution.
Note: You should be aware that when executing a USR command (running a machine code program) then BasinC will not allow you to suspend operation until that command has completed - i.e., the program executes a RET opcode, and drops back to BASIC. If your machine code program enters an infinite loop, your only recourse is to use the Force BREAK menu item in the Run Menu.
Watches
Watches are another type of debugging tool, loosely related to breakpoints, but much more flexible. They are a list of expressions (or other types of data, such as variable contents, system variable states, memory states etc) which are updated after every statement executes. The Watch Window is constantly updated as the program runs, to reflect the state of these watches.
Watches may have associated conditions. The program halts when the value of the expression satisfies the condition.
- To create a watch, use the Add Watch window.
- To view the values of watches, or delete them, use the Watch List window.
Alternatively, you can watch variables - and edit their values - in the Variables window and System Variables window.
Debugging memory
If necessary, you can work with memory directly.
If your program is running out of memory and you don't know why (which is a common problem with programs that use subroutines for recursive calculations, such as a flood-fill routine) then a handy tool is the Memory Map. This shows a graphical representation of the emulated memory state, updated in real-time, which provides visual feedback as to how your memory is being used. It is easy to see if the GO SUB stack is eating up memory from a mismatched or absent RETURN statement.
For closer inspection of the emulated memory state, you have the Memory Viewer. This window, while reminiscent of a regular file hex-editor, is a powerful tool which you can use to see how your variables are being used, how they are stored in-memory, even how the current program is arranged. You can use it to quickly jump to the representation of any statement in the program, view the memory pointed to by any System Variables, and edit any memory in the random access memory (RAM) range.
REM directives
You can use REM directives to activate certain features during the running of a program, such as logging messages to the log window or speeding up the program through the tediously slow bits.
Code Profiling
Code profiling is not strictly debugging - though many would see a slow program in need of optimisation as a "bug". Code profiling involves timing each statement of your code, the results of which can be compared to other statements to see which ones take the longest time - and therefore may need re-writing or moving to another location in the program, in order to speed them up,
You can enable code profiling by using the Run Menu.
For more information on Code Profiling, see the help for the Profile Results window.
See also: