This small guide is intended to illustrate, step by step, how to debug an application written with ugBASIC and compiled for ZX Spectrum (target=zx), using the native tools of the “Speccy” emulator. Keep in mind that the purpose of this guide is not to explain how this tool works in detail but to understand how to use it.

In this guide we are using Speccy, available for Windows and Linux. Speccy emulates 16kB, 48kB, and 128kB versions of Sinclair ZX Spectrum, as well as Spectrum +2, +2A, and +3, as well as Timex Sinclair models. This emulator can load files in .Z80, .SNA, .TAP, .TZX, .FDI, .TRD, and .SCL formats.

The program to be examined with the debugger must be compiled with ugBASIC. The typical makefile command for the ZX Spectrum in tap format could be the following:

 make target=zx output=tap program=test

This command line will produce the assembly (namely app.asm) which, in turn, will be compiled in the target binary format (app.tap). So, the first file can be used as a “reference” in order to identify the ugBASIC instruction while the second file will be actively debugged.

To run the program on the ZX emulator invoke this command line:

 speccy app.tap

Once the emulator is running, you can access the integrated debugger directly from the menu. just select the Hardware menu entry and then the Debugger item.

The screen you see is the operating status of the emulated computer, at the exact moment you stopped it. Therefore, the screen content can be very different from this one and does not contain the program yet.

To get to see the beginning of our program it is necessary to set a specific breakpoint.

You must then press the G key to open a small dialog, where you can enter the breakpoint address.

At this point it is necessary to insert the starting address of the assembly program created with ugBASIC.

On the ZX Spectrum the program is compiled from location 32768 ($8000).

So we must digit the number '8000' and press 'ENTER'.

This will move the debugger to the start of the program.

Finally, at this point it is sufficient to bring the emulator back into execution with the R key, so that the loading is completed and the execution of the program starts from the indicated location.

From this moment on it will be possible to execute the compiled program “step by step” by pressing the ENTER key.