ok
683281363d
Optimizing Forth 2012 compiler targeting WebAssembly with IR-based compilation pipeline, multi-typed stack inference, subroutine threading, and JIT/consolidation modes. Rust kernel with ~35 primitives and Forth standard library for core/core-ext word sets.
1.9 KiB
1.9 KiB
WAFER Project Conventions
What is WAFER?
WAFER (WebAssembly Forth Engine in Rust) is an optimizing Forth 2012 compiler targeting WebAssembly.
Architecture
- Rust kernel (~35 primitives) + Forth standard library (everything else in .fth files)
- IR-based compilation pipeline: Forth -> IR -> type inference -> optimize -> WASM codegen
- Multi-typed stack: use WASM's native typed stack when types are known via inference, fall back to linear memory for dynamic/polymorphic cases
- Subroutine threading via WASM function tables
- JIT mode: per-word WASM modules + shared function table
- Consolidation mode: recompile all words into single optimized WASM module
Code Style
cargo fmtandcargo clippymust pass with no warnings- Every public function needs a doc comment
- Every module needs unit tests
- Use
thiserrorfor error types in core crate,anyhowfor CLI crate - Prefer returning
Resultover panicking
Testing (Critical)
- Specs-driven TDD: Every feature starts with its failing test, then implementation
- Run
cargo test --workspacebefore committing - Forth 2012 compliance:
cargo test --test compliance - Property-based tests with
proptestfor numeric operations and optimizer correctness - Snapshot tests with
instafor IR and WASM output - 100% compliance is mandatory for each implemented word set before moving on
- Never break existing compliance tests
Forth Source (.fth files)
- One file per word set in
forth/ - Document each word with standard stack effect notation:
( before -- after ) - Maximize words written in Forth, minimize Rust primitives
- Boot order: boot.fth -> core.fth -> core_ext.fth -> ... -> prelude.fth
Key Principles
- Maximize Forth, minimize Rust (self-hosting goal)
- Correctness first, performance second
- Test-driven: if it's not tested, it doesn't work
- Every word set at 100% compliance before moving to the next