kaizenkodo/WAFER
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Remove unused stub files: forth/, words/, compiler.rs, primitives.rs, types.rs

Browse Source 
All were planning artifacts never imported or loaded:
- forth/ (4 .fth files): commented-out TODO stubs, never loaded at startup
- crates/core/src/words/mod.rs: empty module with commented-out submodules
- compiler.rs: placeholder, all compiler logic lives in outer.rs
- primitives.rs: placeholder, all primitives registered in outer.rs
- types.rs: StackType/StackEffect defined but never imported anywhere
This commit is contained in:
Oleksandr Kozachuk
2026-04-02 13:52:45 +02:00
parent bf7581ad9e
commit 1c0df608c3
10 changed files with 107 additions and 345 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+105 -82
View File
@@ -2,24 +2,52 @@
**WebAssembly Forth Engine in Rust**
An optimizing Forth 2012 compiler targeting WebAssembly.
An optimizing Forth 2012 compiler targeting WebAssembly. WAFER JIT-compiles each word definition to a separate WASM module and executes it via [wasmtime](https://wasmtime.dev/).
## Status
## Highlights
WAFER is a working Forth system with an optimizing compiler. It JIT-compiles each word definition to a separate WASM module and executes via `wasmtime`. 392 tests passing (380 unit + 1 benchmark + 11 compliance), **0 errors on all 12 tested Forth 2012 word sets** including Floating-Point.
- **200+ words** across 12 Forth 2012 word sets, all at **100% compliance**
- **Optimizing compiler** with 6 IR passes + stack-to-local promotion + consolidation
- **JIT compilation** — each `:` definition compiles to its own WASM module
- **Consolidation mode** — recompile all words into a single optimized WASM module
- **Interactive REPL** with line editing (rustyline)
**Working features:**
## Installation
- Colon definitions with full control flow (IF/ELSE/THEN, DO/LOOP/+LOOP, BEGIN/UNTIL, BEGIN/WHILE/REPEAT)
- 200+ words: stack, arithmetic, comparison, logic, memory, I/O, defining words, system, exceptions, double-cell, strings, floating-point (70+ float words)
- Recursion (RECURSE), nested control structures, loop counters (I, J)
- VARIABLE, CONSTANT, CREATE, DOES>
- Number bases (HEX, DECIMAL), number prefixes ($hex, #dec, %bin)
- Pictured numeric output (<# # #S #> HOLD SIGN)
- Comments (backslash, parentheses), string output (." ...)
- Interactive REPL with line editing
Requires [Rust](https://www.rust-lang.org/tools/install) 1.85+ (edition 2024).
**Example session:**
```bash
cargo install --git https://github.com/ok2/wafer.git wafer
```
This installs the `wafer` binary to `~/.cargo/bin/`.
To install from a local checkout:
```bash
cargo install --path crates/cli
```
## Usage
```bash
# Interactive REPL (type BYE to exit)
wafer
# Run a Forth file
wafer program.fth
# Pipe input
echo ': SQUARE DUP * ; 7 SQUARE .' | wafer
# Consolidation: recompile all words into a single optimized WASM module
wafer --consolidate program.fth
# Consolidation with WASM output
wafer --consolidate -o output.wasm program.fth
```
**Example REPL session:**
```forth
: FIB DUP 2 < IF DROP 1 ELSE DUP 1 - RECURSE SWAP 2 - RECURSE + THEN ;
@@ -31,13 +59,35 @@ VARIABLE COUNTER 0 COUNTER !
BUMP BUMP BUMP COUNTER @ . \ prints: 3
```
## Goals
## Building from source
- **Full Forth 2012 compliance** -- all word sets, 100% test suite pass rate
- **Optimizing compiler** -- constant folding, inlining, peephole optimization, stack-to-local promotion
- **Multi-typed stack** -- type inference uses WASM's native typed stack when possible
- **Self-hosting** -- minimal Rust kernel (~35 primitives), everything else in WAFER Forth
- **Consolidation mode** -- recompile all JIT words into a single optimized WASM module
```bash
git clone --recurse-submodules https://github.com/ok2/wafer.git
cd wafer
cargo build --workspace --release
```
If you already cloned without `--recurse-submodules`, fetch the Forth 2012 test suite with:
```bash
git submodule update --init
```
## Testing
```bash
# All tests (392 currently passing)
cargo test --workspace
# Forth 2012 compliance suite
cargo test -p wafer-core --test compliance
# Optimization benchmark report
cargo test -p wafer-core --test benchmark_report -- --nocapture --ignored
# Lints
cargo clippy --workspace
```
## Architecture
@@ -53,55 +103,40 @@ Forth Source -> Outer Interpreter -> IR -> [Optimize] -> WASM Codegen (wasm-enco
- **IR-based pipeline** with 6 optimization passes (peephole, constant folding, strength reduction, DCE, tail call detection, inlining) plus stack-to-local promotion and consolidation
- **Dictionary**: linked-list word headers in simulated linear memory
## Building
```bash
cargo build --workspace
```
## Running
```bash
# Interactive REPL
cargo run -p wafer
# Run a Forth file
cargo run -p wafer -- file.fth
# Pipe input
echo ': SQUARE DUP * ; 7 SQUARE .' | cargo run -p wafer
```
## Testing
```bash
# All tests (392 currently passing)
cargo test --workspace
# Forth 2012 compliance dashboard
cargo test -p wafer-core --test compliance
# Optimization benchmark report
cargo test -p wafer-core --test benchmark_report -- --nocapture --ignored
# Lints
cargo clippy --workspace
```
## Project Structure
```
crates/
core/ wafer-core: dictionary, IR, codegen (wasm-encoder), outer interpreter
cli/ wafer: CLI REPL and file execution (wasmtime, rustyline)
core/ wafer-core: dictionary, IR, codegen, optimizer, outer interpreter
cli/ wafer: CLI REPL, file execution, consolidation
web/ wafer-web: browser bindings (planned)
forth/ Standard library in WAFER Forth (planned, currently stubs)
tests/ Forth 2012 compliance suite (gerryjackson/forth2012-test-suite submodule)
forth/ Bootstrap definitions loaded at startup
tests/ Forth 2012 compliance suite (git submodule)
```
## Forth 2012 Compliance
Tested against [Gerry Jackson's Forth 2012 test suite](https://github.com/gerryjackson/forth2012-test-suite). 12 of 14 word sets pass at 100%.
| Word Set | Status |
| ------------------ | --------------------------------- |
| Core | **100%** (0 errors) |
| Core Extensions | **100%** (0 errors) |
| Double-Number | **100%** (0 errors) |
| Exception | **100%** (0 errors) |
| Facility | **100%** (0 errors) |
| Floating-Point | **100%** (0 errors) |
| Locals | **100%** (0 errors) |
| Memory-Allocation | **100%** (0 errors) |
| Programming-Tools | **100%** (0 errors) |
| Search-Order | **100%** (0 errors) |
| String | **100%** (0 errors) |
| File-Access | Not started (requires WASI integration) |
| Extended-Character | Not started |
## Implemented Words
### Core (Forth 2012 Section 6.1) -- In Progress
Over 200 words are implemented across the following categories:
| Category | Words |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
@@ -111,36 +146,24 @@ tests/ Forth 2012 compliance suite (gerryjackson/forth2012-test-suite sub
| Logic | `AND OR XOR INVERT LSHIFT RSHIFT` |
| Memory | `@ ! C@ C! +! 2@ 2! HERE ALLOT , C, CELLS CELL+ CHARS CHAR+ ALIGNED ALIGN MOVE FILL CMOVE CMOVE>` |
| Control | `IF ELSE THEN DO LOOP +LOOP I J UNLOOP LEAVE BEGIN UNTIL WHILE REPEAT RECURSE EXIT` |
| Defining | `: ; VARIABLE CONSTANT CREATE DOES> IMMEDIATE` |
| Defining | `: ; VARIABLE CONSTANT VALUE CREATE DOES> IMMEDIATE DEFER` |
| I/O | `. U. .S CR EMIT SPACE SPACES TYPE ." S" ACCEPT` |
| Return stack | `>R R> R@` |
| System | `EXECUTE ' CHAR [CHAR] ['] DECIMAL HEX BASE STATE >IN >BODY ENVIRONMENT? SOURCE ABORT TRUE FALSE BL` |
| Compiler | `LITERAL POSTPONE [ ] EVALUATE ABORT"` |
| Parsing | `WORD FIND COUNT >NUMBER` |
| Exceptions | `CATCH THROW` |
| Double-cell | `D+ D- D. D.R DNEGATE DABS D= D< D0= D0< D>S 2CONSTANT 2VARIABLE 2LITERAL M+ M*/` |
| Strings | `COMPARE SEARCH SLITERAL REPLACES SUBSTITUTE UNESCAPE` |
| Floating-Pt | `F+ F- F* F/ FABS FNEGATE FSQRT FSIN FCOS FTAN FEXP FLOG FMIN FMAX` and 55+ more |
| Case | `CASE OF ENDOF ENDCASE` |
### Not Yet Implemented
## Roadmap
12 word sets at 100% compliance: Core, Core Ext, Core Plus, Exception, Double-Number, String, Search-Order, Memory-Allocation, Programming-Tools, Facility, Locals, Floating-Point. 200+ words including VALUE, DEFER, CASE, DOES>, CATCH/THROW, double-cell arithmetic, string operations, and 70+ floating-point words.
## Compliance Status
Targeting 100% Forth 2012 compliance via [Gerry Jackson's test suite](https://github.com/gerryjackson/forth2012-test-suite).
| Word Set | Status |
| ------------------ | --------------------------------- |
| Core | **100%** (0 errors on test suite) |
| Core Extensions | **100%** (0 errors on test suite) |
| Double-Number | **100%** (0 errors on test suite) |
| Exception | **100%** (0 errors on test suite) |
| Facility | **100%** (0 errors on test suite) |
| File-Access | Pending (requires WASI) |
| Floating-Point | **100%** (0 errors on ak-fp-test) |
| Locals | **100%** (0 errors on test suite) |
| Memory-Allocation | **100%** (0 errors on test suite) |
| Programming-Tools | **100%** (0 errors on test suite) |
| Search-Order | **100%** (0 errors on test suite) |
| String | **100%** (0 errors on test suite) |
| Extended-Character | Pending |
- **File-Access word set** — requires WASI integration for file I/O
- **Extended-Character word set** — Unicode support
- **Browser target** — `wafer-web` crate with wasm-bindgen for a web REPL
- **Self-hosting** — minimal Rust kernel (~35 primitives), everything else in Forth
## License