WAQ - WebAssembly to QBE Compiler
WAQ is an ahead-of-time (AOT) compiler that translates WebAssembly binary modules into native machine code using QBE as the backend.
Features
- 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
Installation
# 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 sync
External Dependencies
WAQ 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) |
Usage
Basic Compilation
# 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 program
Supported Targets
amd64_sysv- x86-64 Linux/BSD (default)amd64_apple- x86-64 macOSarm64- ARM64 Linuxarm64_apple- ARM64 macOS (Apple Silicon)rv64- RISC-V 64-bit
Running Tests
# 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
Development Commands
# 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 checking
Project Structure
waq/
├── 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
Testing
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/
Code Style
- Targets Python 3.12+
- Uses Ruff with ALL rules enabled
- Multiple type checkers: ty, pyrefly, mypy
- All files must have
from __future__ import annotations
License
[Specify your license here - e.g., MIT, Apache 2.0, etc.]
Contributing
See CONTRIBUTING.md for contribution guidelines.
Metadata
Release files for waq 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| waq-0.3.0.tar.gz | 57.8 kB | Without provenance | Details for waq-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| waq-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for waq-0.3.0-py3-none-any.whl |
Total release size: 128.1 kB
Release files / waq-0.3.0.tar.gz
| Download URL | waq-0.3.0.tar.gz |
|---|---|
| Size | 57.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
022441314e0e35762380aa964a65c4a95644a1223dd4b5cbbf3f15a52a089b64
|
|
BLAKE2b-256 checksum How to use checksums |
dc19a9e87558272024ad700ad9f46e7ce065ea866231974d87bf723fce2373aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / waq-0.3.0-py3-none-any.whl
| Download URL | waq-0.3.0-py3-none-any.whl |
|---|---|
| Size | 70.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0193f9192f98a86e49a1b30bba7ba5367ae413fa28974df51f7aaf935252c747
|
|
BLAKE2b-256 checksum How to use checksums |
06e93ecfa981142e55c95130dae54f1fbbad6d60c4783575266f1e78acb21437
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.26 {"installer":{"name":"uv","version":"0.9.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for waq 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.