This directory documents the XBASIC 6.2.3 source tree (../xbasic-6.2.3/), a
self-hosted BASIC compiler, IDE, and runtime for Linux and Windows (Win32) written by
Max Reason (copyright 1988–2000). The documentation captures how the system is built
and how it achieves cross-platform portability.
| # | Chapter | What it covers |
|---|---|---|
| 00 | Overview | What XBASIC is, target platforms, licensing, distributions, install model, source tree layout, version history |
| 01 | Architecture | Program model, module system, compile pipeline, memory model, exception model, runtime architectures |
| 02 | The Compiler | xcol.x/xcow.x: tokenizer, two-pass pipeline, code emitters (asm/bin), the Xxx* PDE API, function map |
| 03 | Runtime | xrun.x entry sequence, exception loops, xb.def symbol surface, heap (chkmem.c), platform divergence |
| 04 | Libraries | Per-library API maps: xst, xgr, xma, xcm, xin, xgrids, xdis |
| 05 | IDE / GUI Toolkit | The PDE (xit.x) and the GuiDesigner toolkit (xui.x): grids, messages, redraw, form-builder |
| 06 | Cross-Platform Architecture | Source correspondence, FFI via .dec files, constant-folding conditionals, assembly startup, xbiface.c |
| 07 | Build System | Toolchains, OS autodetection, Makefiles, template system, bootstrap order |
| 08 | Language Reference | Types, scoping, statements, operator table, intrinsics, dot commands, grid messages |
| 09 | Version History | The post-6.2.3 forks: 6.3.26-D (Win32 unofficial) and 6.4.5 (Linux xb64 64-bit), per-file version tables, the crtl/ C-runtime experiment |
| 10 | Unification Plan | Proposal for merging 6.3.26-D + 6.4.5 back into one cross-platform tree (6.5.0) |
| 11 | Syscall Surface Survey | Every .s/syscall in the three trees: zero raw syscalls, 6 hand-written .s files, FPU-intrinsic / libc / frame-helper classification, signal & exception model |
| 12 | Rust + LLVM Rewrite Survey | Crates for the 6.5.0 rewrite: inkwell/LLVM pipeline, iced-x86 FPU JIT, rustix/windows-sys FFI, egui+winit GUI, plus what to preserve from 6.3.26-D and 6.4.5 |
| 13 | 6.5.0 Bootstrap Scaffold | Resolved decisions (f64/libm, Win64 first, staged self-hosting), stage plan, and the repo-root Rust workspace layout |
| 14 | Self-Hosting Progress | Full self-hosting: native C code generation, CLI compile modes, cgen.x self-hosting C generator, 3-stage native bootstrap fixed point, cross-platform CI |
| 15 | Stage-2 Contract v0.1 | Baseline accepted subset: VERSION, PRINT, DIM, assignment, FUNCTION/END FUNCTION, integer/float/string literals |
| 16 | Stage-2 Contract v0.2 | $$ constants and ## shared variable tokenization: lexer support, constant definitions, constant references |
| 17 | Stage-2 Contract v0.3 | ## shared system variables: parser, semantic, IR, and runtime support as mutable typed storage |
| 18 | Stage-2 Contract v0.4 | IF/THEN/ELSE/END IF conditional branching: integer-valued condition, no new scope, XB-S009 diagnostic, runtime branch selection |
| 19 | Stage-2 Contract v0.5 | Comparison operators (=, <>, <, >, <=, >=): expression-level binary operators returning Integer TRUE/FALSE, XB-S010 diagnostic, runtime ordering |
| 20 | Stage-2 Contract v0.6 | Function calls with typed parameters, RETURN statements, function call expressions, XB-S011 through XB-S015 diagnostics |
| 21 | Stage-2 Contract v0.7 | Arithmetic operators (+, -, *, /) with precedence, Integer/Float type promotion, XB-S016 diagnostic, runtime division-by-zero error |
| 22 | Stage-2 Contract v0.8 | WHILE/WEND loops: integer-valued condition, body iteration, RETURN propagation through Flow |
| 23 | Stage-2 Contract v0.9 | One-dimensional arrays: DIM a(n), a(i) access, a(i) = value assignment, array storage in TypedSlot |
| 24 | Stage-2 Contract v0.10 | String concatenation via + operator |
| 25 | Stage-2 Contract v0.11 | Built-in string functions: LEN, ASC, CHR$, LEFT$, RIGHT$, MID$ |
| 26 | Stage-2 Contract v0.12 | Boolean operators AND, OR, NOT with bitwise i32 semantics |
| 27 | Stage-2 Contract v0.13 | FOR/NEXT loops with integer counter, inclusive range, optional variable after NEXT |
| 28 | Stage-2 Contract v0.14 | Standalone function call statements: procedure-style calls with output propagation |
| 29 | Stage-2 Contract v0.15 | ELSEIF chains: multi-branch conditionals desugared to nested IF |
| 30 | Stage-2 Contract v0.16 | EXIT FOR / EXIT WHILE: early loop termination via Flow::Break |
| 31 | Stage-2 Contract v0.17 | String functions INSTR, VAL, STR$ for parsing and conversion |
| 32 | Stage-2 Contract v0.18 | Runtime input: READLINE$() and EOF() for stdin-style input buffer |
Living roadmaps of open work (updated as work lands, not fixed chapters):
| Doc | Covers |
|---|---|
| 16 — cgen ↔ CEmitter Sync Roadmap | Keeping the Rust CEmitter and self-hosted cgen.x in sync: behavioral sync locked by tests, plus open items (address helpers int→intptr_t, xb_open file mode 2, byte-identical prelude) |
| 17 — Open-Work Roadmap | Umbrella "everything not done yet": LLVM object emission + LLVM 22 toolchain/CI, x87 JIT, Vec<u8> byte strings, kernel32/function-pointer runtime, legacy corpus test gating, demo/GUI status |
XBASIC is self-hosted: the compiler, IDE, and libraries are all written in XBASIC.
A .x source file is compiled to i486 assembly, then assembled and linked by the
platform toolchain (GNU as + gcc on Linux; spasm + MS link.exe on Windows).
Portability comes from:
- One compiler with two backends —
xcol.x(Linux) andxcow.x(Win32) are ~88.5% identical; both emit i486 assembly. - Stable library APIs over swappable OS backends —
xst/xgr/xinhave platform twins that differ only in the OS-specific layer (X11 vs GDI, libc vs Winsock, signals vs SEH). - Compile-time constant folding instead of a preprocessor —
##XBSystem+$$XBSysLinux/$$XBSysWin32+IF ##CONST THEN/ELSE/END IF. - FFI via
.decfiles —EXTERNAL FUNCTIONdeclarations read by the compiler atIMPORTtime; Win32 API functions are reimplemented in XBASIC on Linux (kernel32.x/user32.x/gdi32.x), so the same source compiles on both platforms. - A shared assembly runtime (
xlib.s,xstart.s,xzzz.s) with per-OS bootstrap for entry points and section boundaries.
For a quick overview: 00 → 01 → 06. For implementation depth: add 02 (compiler),
03 (runtime), and 07 (build). For API-level detail: 04 (libraries), 05 (IDE/GUI),
08 (language reference).
xbasic-6.2.3/
├── Makefile top-level driver (OS autodetect)
├── src/
│ ├── Makefile the real build
│ ├── shared/ platform-neutral XBASIC sources (xui, xma, xcm, xdis, xut, xutpde)
│ ├── linux/ Linux twins (xcol, xit, xst, xgr, xin, xrun, xbiface.c, chkmem.c)
│ ├── win32/ Win32 twins (xcow, xit, xst, xgr, xrun, xbasic.x, xb.def, xb.rc)
│ └── lib/ assembly runtime (xlib.s, xstart.s, xzzz.s, appstart.s)
├── include/ .dec FFI files (kernel32, user32, gdi32, wsock32, shell32,
│ winmm, clib, elf32, xlib, xwin)
├── templates/ linux/ and win32/ template sets (xapp, xdll, syslib, win32api...)
├── help/ .hlp documentation files
├── samples/ example programs
└── COPYING, COPYING_LIB GPL (compiler/IDE) and LGPL (libraries)