Breakpoints for FastBasic: A VS Code Debugger Extension

In April 2024, Eric Carr (The Car on AtariAge) showed a Visual Studio Code extension that adds source-level debugging to FastBasic, dmsc's cross-compiled BASIC: breakpoints, single-stepping and viewing or changing variables while the program runs in an emulator. He said he had a choice between spending a few hours chasing a bug in his FastBasic 5 Card game client and spending a few days learning to write a VS Code debugger. He chose the second.

Goals

The author set out three aims:

  1. Make FastBasic easy for newcomers to set up, with a quick path to a working setup on Windows (Altirra) and macOS (Atari800MacX).
  2. Provide a proper step-through debugging experience on both, for bugs that are hard to find with print statements or the Altirra machine-level debugger.
  3. Show the memory address of each variable (e.g. $A800) for people who want to look at it in Altirra.

Stretch goals included debugging on real hardware over FujiNet, using FastBasic's code formatter, and a minifier for 10-liner entries.

How it works

The approach is simple and uses no special emulator hooks:

  • Before compiling, the extension adds a small FastBasic debug routine and a call to it at the start of every non-empty line. At each call the routine checks whether a "step" flag is set or whether the current line number is in the breakpoint list. If so, it stops and sends the line number and a dump of variable memory to VS Code.
  • It reads the .LBL and .LST files produced by the FastBasic compiler to find each variable's address and type.
  • In this first version, the Atari program and VS Code communicate through the emulator's H: host device, which works the same in both supported emulators.

The author also described a faster future design: put an IF 0 THEN check on every line and patch the bytecode from TOK_0 to TOK_1 in memory when a breakpoint is set, so that any number of breakpoints costs nothing between stops. dmsc said he had preliminary work along the same lines for the native Atari IDE, adding one bytecode per line that tests whether execution should stop.

Later developments

The extension, published on GitHub as vscode-fastbasic-debugger, gained a FastBasic syntax grammar (including the new FujiNet N statements) and an Atari-style colour theme. A custom emulator option lets users start Altirra under Wine on a Mac, or another emulator. With FujiNet-PC running in the background, that makes it possible to debug FastBasic programs that use FujiNet. One caveat noted in the thread is that Altirra has to be stopped between debugging sessions.

Getting it

The extension and its README, which covers setup and the custom-emulator option, are at github.com/EricCarrGH/vscode-fastbasic-debugger.

Credits