evv/gw-basic-2026

Files

Eremey Valetov 20ecdae938 Add --warn and --safe memory safety flags to the compiler

Three progressive levels for gwbasic-compile:

--warn: static analysis warnings (uninitialized variables, GOTO to
nonexistent line, unreachable code detection). Zero runtime cost.

--safe (implies --warn): runtime checked integer arithmetic via
gw_int_add/sub/mul/neg matching real GW-BASIC overflow semantics,
enhanced array bounds diagnostics with variable names and line numbers,
GOSUB stack overflow diagnostics with source line reporting.

--safe=sanitize (implies --safe): passes -fsanitize=address,undefined
to gcc for full memory error detection.

Also: fix pre-existing missing closing paren in array LET-to-integer
codegen, add strpool_pin/unpin infrastructure, add compiler optimization
flags and memory safety sections to roadmap.

72/72 interpreter tests pass. 64/64 eligible compiler tests pass in
--safe mode.

2026-04-09 13:14:26 -04:00

3.7 KiB

Raw Blame History

Getting Started

Dependencies

C11 compiler (GCC or Clang)
CMake 3.10+
PulseAudio development library (libpulse-simple) -- optional, for SOUND/BEEP/PLAY

On Debian/Ubuntu:

sudo apt-get install build-essential cmake libpulse-dev

On Fedora/RHEL:

sudo dnf install gcc cmake pulseaudio-libs-devel

Building

git clone https://github.com/evvaletov/gw-basic-2026.git
cd gw-basic-2026
mkdir -p build && cd build
cmake .. && make

The binary is build/gwbasic.

Usage

Interactive Mode

Running ./gwbasic with no arguments launches the full-screen editor:

$ ./gwbasic
GW-BASIC 2026 0.14.0
(C) Eremey Valetov 2026. MIT License.
Based on Microsoft GW-BASIC assembly source.
Ok
PRINT 2+2
 4
Ok
FOR I=1 TO 5:PRINT I;:NEXT
 1  2  3  4  5
Ok

Use arrow keys to move the cursor freely. Press Enter on any screen line to re-enter it. F1-F10 insert common commands (F2 runs the program).

Running a Program File

./gwbasic tests/programs/prime_sieve.bas

Piped Input

echo '10 FOR I=1 TO 10:PRINT I*I;:NEXT' | ./gwbasic

Direct Mode Expressions

Type expressions and statements at the Ok prompt:

PRINT SIN(3.14159/2)
 1
A$="HELLO WORLD":MID$(A$,7,5)="BASIC":PRINT A$
HELLO BASIC

Command-Line Options

Usage: gwbasic [options] [file.bas]
Options:
  -f, --full         Use full terminal size (default: 25x80)
  -h, --help         Show this help
  --lpt DEVICE|FILE  Printer output destination (default: LPT1.TXT)
                     Use LPT1 or /dev/lp0 for real hardware
  -v, --version      Show version

Ahead-of-Time Compiler

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

Basic Usage

# Emit C source to stdout
build/gwbasic-compile program.bas

# Compile to native executable
build/gwbasic-compile -c --runtime . program.bas

Compiler Options

Usage: gwbasic-compile [options] input.bas
Options:
  -o FILE        Output C source file (default: stdout)
  -c             Compile to executable (invoke gcc)
  -O LEVEL       GCC optimization level (default: 2)
  --keep-c       Keep generated C file (with -c)
  --runtime DIR  Path to runtime headers/library
  --warn         Static analysis warnings
  --safe         Runtime safety checks (implies --warn)
  --safe=sanitize  Above + address/UB sanitizers (with -c)

Memory Safety (`--warn` / `--safe`)

The --warn flag enables compile-time static analysis warnings:

Uninitialized variables -- variables used before their first assignment (via LET, FOR, READ, INPUT)
GOTO/GOSUB to nonexistent line -- jump targets that don't exist in the program
Unreachable code -- lines after unconditional GOTO/END/STOP that are not jump targets

The --safe flag (implies --warn) adds runtime safety checks to the generated C:

Integer overflow detection -- arithmetic on integer (%) variables uses checked functions (gw_int_add, gw_int_sub, gw_int_mul) that raise "Overflow" instead of silently wrapping, matching real GW-BASIC behavior
Enhanced array diagnostics -- subscript errors report the array name, subscript value, line number, and which dimension exceeded its bound
GOSUB stack diagnostics -- stack overflow reports the source line and current depth

The --safe=sanitize flag (with -c) additionally passes -fsanitize=address,undefined to GCC for full memory error detection.

# Warnings only (zero runtime cost)
build/gwbasic-compile --warn program.bas

# Runtime safety checks
build/gwbasic-compile --safe -c --runtime . program.bas

# Full sanitizer build (debugging)
build/gwbasic-compile --safe=sanitize -c --runtime . program.bas

3.7 KiB Raw Blame History