gw-basic-2026/docs/roadmap.md

Roadmap

Completed

Ahead-of-Time Compiler (v0.16.0)

gwbasic-compile translates tokenized .bas programs to C source, then invokes GCC to produce native executables linked against libgwrt.a.

Pipeline: .bas → gw_crunch() → analysis pass → C codegen → gcc → native binary.

63 of 63 eligible tests pass (100%) via tests/run_compiler_tests.sh. The harness only skips hardware-dependent tests (graphics/sound/timer) and CHAIN/RUN target files that aren't standalone. The compiler now accepts unnumbered direct-mode programs by auto-numbering them.

Language coverage:

• All statements: PRINT, LET, IF/THEN/ELSE, GOTO, GOSUB/RETURN, FOR/NEXT, WHILE/WEND, ON GOTO/GOSUB, ON ERROR GOTO, RESUME/RESUME NEXT, DIM, DEF FN, SWAP, READ/DATA/RESTORE, INPUT/LINE INPUT, OPEN/CLOSE/PRINT#/INPUT#/WRITE#, FIELD/LSET/RSET/GET/PUT, BSAVE/BLOAD, SAVE/LOAD, CHAIN/COMMON, SCREEN, PSET/PRESET, COLOR/LOCATE/CLS, CIRCLE/DRAW/PAINT/PLAY, VIEW/WINDOW/PALETTE, POKE/OUT/WAIT, DEF SEG, RANDOMIZE, CLEAR, MID$ assignment, ERROR, KILL/NAME/FILES/SHELL/MKDIR/CHDIR/RMDIR, ENVIRON, LPRINT/LLIST, WIDTH, KEY
• All operators: + - * / \ MOD ^ AND OR XOR NOT EQV IMP > < = <= >= <> (including string comparison via strcmp)
• All functions: math, string, file, conversion (CVI/CVS/CVD/MKI$/MKS$/MKD$), graphics (POINT/PMAP), system (FRE/ERR/ERL/TIMER/DATE$/TIME$/ENVIRON$/INKEY$)
• Token embedding for complex statements (PRINT USING, DEF FN, graphics, file I/O, MID$ assignment) with selective variable sync
• Division-by-zero detection, RNG matching (gw_rnd), ON ERROR GOTO via setjmp/longjmp

Optimizations:

• Constant folding (compile-time arithmetic on literals)
• Dead code elimination (skip statements after GOTO/END/STOP)
• FOR step=1 elision (var++ instead of step variable, simple comparison)
• Fast-path expression emitter (skip buffering for common case)
• Selective variable sync in delegated statements
• REM-line skip (no runtime check for comment-only lines)

Hardware I/O Simulator (v0.15.0)

Implemented in portio.c / portio.h following the virmem.c dispatch pattern. Emulates 8253 PIT channel 2 (speaker frequency), PPI port B (speaker on/off with continuous tone via PulseAudio), CGA mode/color registers, game port (joystick stub), and COM1 serial (transmitter-ready stub). Default: reads return 0xFF (floating bus), writes discarded.

Also in v0.15.0: 100% token coverage (all 144 GW-BASIC tokens handled), string space pool with compacting garbage collector, RESET, ENVIRON/ENVIRON$, ERDEV/ERDEV$, IOCTL/IOCTL$, LCOPY, DATE$/TIME$ assignment, CALL, COM.

Jupyter Kernel (v0.15.0)

gwbasickernel/ -- Jupyter notebook kernel using the persistent subprocess model with sentinel protocol.

• Inline Sixel graphics -- pure-Python Sixel decoder renders SCREEN commands as inline PNG images in the notebook
• INPUT statement support via Jupyter stdin protocol
• Pygments syntax highlighting for code cells
• Tab completion for all GW-BASIC keywords
• Magic commands: %reset, %timeout, %new

Install: pip install -e . && gwbasickernel-install --user

Compiler Memory Safety (v0.17.0)

--warn, --safe, and --safe=sanitize flags for the ahead-of-time compiler.

• --warn -- static analysis: uninitialized variables, GOTO to nonexistent line, unreachable code detection. Zero runtime cost.
• --safe (implies --warn) -- checked integer arithmetic via gw_int_add/sub/mul/neg (raises Overflow instead of wrapping), enhanced array bounds diagnostics with variable names and line numbers, GOSUB stack overflow diagnostics, ABS/SGN type-preserving codegen, string pool GC pinning infrastructure
• --safe=sanitize -- above plus -fsanitize=address,undefined passed to gcc

DOS / FreeDOS Target (v0.17.0)

Cross-compiles to DOS using OpenWatcom V2. Two targets:

• 16-bit real-mode (Makefile.dos16): 128KB standalone MZ executable, MEDIUM memory model, far-heap TUI screen buffer, no DOS extender required
• 32-bit DOS/4GW (Makefile.dos): 175KB LE executable, flat memory model, requires DOS4GW.EXE extender

Tested on FreeDOS 1.4 via QEMU.

Cross-Language Linking (Levels 1 & 2)

• Level 1 (v0.17.0) -- gwbasic-compile prog.bas --emit-obj --main-name=run_basic produces prog.o with a renamed entry point, so a host C/Fortran project can link BASIC objects alongside its own against libgwrt. From Fortran, declare the entry with bind(c).
• Level 2 -- '$EXTERN FFI pragma -- '$EXTERN NAME(ARGTYPES) AS RET declares a C function callable from compiled BASIC, with INTEGER/SINGLE/ DOUBLE/STRING ⇄ C type coercion at the boundary. Case-preserving C symbol, BASIC-legal call name. See Foreign Functions from BASIC in getting-started.md; test at tests/run_ffi_test.sh. Arbitrary-C-symbol aliasing and string-result comparison are follow-ups (git-bug).

Level 3 (export BASIC routines as C-callable) remains deferred -- see git-bug.

Planned

Actionable planned work is tracked in git-bug (git-bug bug), grouped by priority/theme labels rather than duplicated here. Release and outreach items (FreeDOS package, Show HN writeup, etc.) live in git-bug only; this file keeps the shipped-feature history and the known limitations. Current dev highlights:

Theme	Item	git-bug	Priority
compiler	$EXTERN follow-ups -- aliasing, INSTR/WRITE dispatch, validation	8329647	P2
compiler	--inline-arrays direct array indexing	e6d977c	P2
compiler	-O0..-O3 codegen optimization tiers	fecc17f	P2
compiler	Level 3 -- export BASIC SUBs/FUNCs as C-callable (deferred)	1b7d59c	P2
language	FORTRAN-style WRITE formatted I/O	a6e99af	P2
language	C-style PRINTF / FPRINTF	cd8750c	P2
ide	VS Code extension (+ JetBrains follow-up)	32a637c	P2
stdlib	Numerical/Data stdlib -- NDArray + DataFrame + Plotting (sub-project)	55a9d14	P2

Recently shipped: Level 2 '$EXTERN FFI pragma (56b96e0, closed).

Run git-bug bug show <id> for the full design notes on any item. The numerical/data stdlib (55a9d14) is the main enabler for the Jupyter-kernel data-analysis use case.

Known Limitations

• Static caps -- 32-bit / Linux builds: 1024 variables, 256 arrays, 64 FOR nesting, 128 GOSUB nesting, 64 WHILE nesting. 16-bit real-mode DOS keeps the original modest caps (256 / 64 / 16 / 24 / 16) because the MEDIUM model has a single 64KB DGROUP for all static data.
• CALL/CALLS (machine code execution) raises Illegal function call
• DATE$/TIME$ assignment shifts the program's view of the clock via a process-local offset; the OS time is unaffected (setting the OS clock would require root)
• Device stubs (ERDEV, IOCTL, COM, LCOPY) return defaults