WAQ is an ahead-of-time (AOT) compiler that translates WebAssembly binary modules into native machine code using QBE as the backend.
- WASM Binary Parsing: Parse WebAssembly binary modules
- Stack-to-SSA Translation: Convert WebAssembly's stack-based model to QBE's SSA form
- Control Flow Conversion: Transform structured control flow (blocks, loops, ifs) to basic blocks and jumps
- Type Mapping: Map WASM types (i32, i64, f32, f64) to QBE types (w, l, s, d)
- QBE Backend: Generate QBE intermediate language code
# Clone the repository
# (not yet) git clone https://github.com/abilian/waq.git
git clone https://git.sr.ht/~sfermigier/waq
cd waq
# Install dependencies using uv
uv syncWAQ requires the following external tools depending on output format:
| Output | Required Tools |
|---|---|
--emit qbe |
None |
--emit asm |
QBE |
--emit obj |
QBE + assembler (clang/as) |
--emit exe |
QBE + C compiler (clang/gcc) |
.wat input |
wabt (wat2wasm) |
# Compile a WASM file to QBE IL
waq input.wasm -o output.ssa
# Compile a WAT file (automatically converted via wat2wasm)
waq input.wat -o output.ssa
# Compile to assembly
waq input.wasm --emit asm -o output.s
# Compile to object file
waq input.wasm --emit obj -o output.o
# Compile to executable (requires exported wasm_main function)
waq input.wasm --emit exe -o program
# Specify a different entry function
waq input.wasm --emit exe --entry my_main -o program
# For void functions, use --no-print
waq input.wasm --emit exe --entry void_func --no-print -o program
# Target a specific architecture
waq input.wasm --emit exe -t arm64_apple -o programamd64_sysv- x86-64 Linux/BSD (default)amd64_apple- x86-64 macOSarm64- ARM64 Linuxarm64_apple- ARM64 macOS (Apple Silicon)rv64- RISC-V 64-bit
# Run all tests
make test
# Run specific test types
uv run pytest -m unit # Unit tests only
uv run pytest -m integration # Integration tests only
uv run pytest -m e2e # End-to-end tests only# Format code
make format
# Lint and type check
make lint
# Run with coverage
make test-cov
# Multi-version testing via nox
nox -s tests # Run tests on all Python versions
nox -s check # Run linting/type checkingwaq/
├── src/
│ └── waq/ # Main source code
│ ├── compiler/ # Compilation logic
│ ├── parser/ # WASM binary parsing
│ ├── runtime/ # Runtime support
│ └── cli.py # Command-line interface
├── tests/ # Test suite
│ ├── a_unit/ # Unit tests
│ ├── b_integration/ # Integration tests
│ └── c_e2e/ # End-to-end tests
├── notes/ # Technical notes (no documentation yet)
└── runtime/ # Runtime components
The project follows a pyramid testing structure:
- Unit Tests: Fast, isolated tests in
tests/a_unit/ - Integration Tests: Component interaction tests in
tests/b_integration/ - End-to-end Tests: Full workflow tests in
tests/c_e2e/
- Targets Python 3.12+
- Uses Ruff with ALL rules enabled
- Multiple type checkers: ty, pyrefly, mypy
- All files must have
from __future__ import annotations
[Specify your license here - e.g., MIT, Apache 2.0, etc.]
See CONTRIBUTING.md for contribution guidelines.