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.

**69 of 69 eligible tests pass (100%).** Zero compile errors.

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.

## Next Up

### Compiler Optimization Flags
- **`--no-gc-check`** -- skip `gwrt_check_line()` per-line calls (no string pool
  GC, no Ctrl+Break check) for maximum throughput
- **`--inline-arrays`** -- emit direct array indexing for statically-DIMmed arrays
  instead of runtime `gwrt_array_elem()` lookup
- **`--fast-math`** -- skip division-by-zero checks, allow unsafe float ops
- **`-O0` through `-O3`** -- compiler-level optimization tiers mapping to different
  sets of codegen optimizations (constant folding, dead code elimination, FOR
  step=1 elision, fast-path expressions)

### IDE Integration
- **VS Code extension** -- syntax highlighting (TextMate grammar), snippets,
  run/debug tasks, integrated terminal runner
- **JetBrains plugin (IntelliJ/CLion)** -- syntax highlighting, code completion,
  run configurations, debugger integration (breakpoints via `STOP`, variable
  inspection), structure view (line number outline)

## Known Limitations

- Maximum 256 variables, 64 arrays, 16 FOR nesting, 24 GOSUB nesting,
  16 WHILE nesting
- `CALL`/`CALLS` (machine code execution) raises Illegal function call
- `DATE$`/`TIME$` assignment accepted but does not modify the system clock
- Device stubs (`ERDEV`, `IOCTL`, `COM`, `LCOPY`) return defaults