English | 简体中文
Veloc is an experimental compiler infrastructure and WebAssembly runtime written in Rust. It combines a typed SSA IR, reusable analyses and optimizations, a compact register-bytecode interpreter, and an x86-64 native code generator in one workspace.
Veloc is under active development. Public APIs and supported WebAssembly features may change without notice.
Veloc uses the nightly toolchain pinned in rust-toolchain.toml. With Rustup installed, Cargo selects and installs it automatically.
git clone https://github.com/veloc-rs/veloc.git
cd veloc
cargo build --workspace --releaseRun the bundled CoreMark WebAssembly module with the interpreter:
cargo run --release -p veloc-wasm --bin veloc-wasm -- run \
crates/veloc-wasm/tests/wasm/coremark.wasm \
--strategy interpreterUse the native x86-64 JIT instead:
cargo run --release -p veloc-wasm --bin veloc-wasm -- run crates/veloc-wasm/tests/wasm/coremark.wasm --strategy jitOn x86-64 Linux, run the full JIT CoreMark regression (checks the validation message and CRCs):
CARGO_INCREMENTAL=0 cargo test --release -p veloc-wasm --test jit \
coremark_validates_under_jit -- --ignored --nocaptureThe run command invokes _start by default using the interpreter. Strategies are
interpreter, jit, fast-jit (Linux x86-64) and auto (currently JIT).
WAT input requires building with --features wat.
--memory-checks auto is the default: native execution uses guard pages on
Linux x86-64 and RV64 with glibc, and software bounds checks elsewhere.
Use --memory-checks software to force explicit checks. On Linux x86-64 with
glibc, interpreter guard pages can also be requested explicitly:
cargo run --release -p veloc-wasm --bin veloc-wasm -- run \
path/to/module.wasm --strategy interpreter --memory-checks guardedGuarded execution installs process-wide SIGSEGV/SIGBUS handlers. Native faults return through a C trap boundary; interpreter guards require Rust unwinding. RV64 guarded stores probe their last byte before writing, preserving memory when an unaligned store would cross into a guard page. Explicit guarded object emission is also available during cross compilation; loading it requires a compatible runtime.
# Print Veloc IR without executing the module
cargo run -p veloc-wasm --features wat --bin veloc-wasm -- emit path/to/module.wat --emit mir
# Write Veloc IR to a file
cargo run -p veloc-wasm --bin veloc-wasm -- emit path/to/module.wasm --emit mir -o module.veloc-mir
# Print interpreter bytecode
cargo run -p veloc-wasm --bin veloc-wasm -- emit path/to/module.wasm --emit bytecode
# Print optimizer statistics and write a Chrome trace
cargo run -p veloc-wasm --bin veloc-wasm -- run path/to/module.wasm \
-O 1 --print-stats --trace-file optimizer-trace.jsonRun cargo run -p veloc-wasm --bin veloc-wasm -- --help for all CLI options.
The CLI has three commands: run, emit, and inspect. Direct file invocation,
--output-ir, and --compile-only are no longer supported. -O0 and -O1
select both MIR and native-code pipelines; other levels are rejected.
All --dump-* options print diagnostics to stderr and continue the requested
command. emit writes only the requested product, without linking imports or
instantiating the module (including its start function).
# Call an export with typed arguments
veloc-wasm run add.wasm --invoke add --arg i32:1 --arg i32:2
# Pass WASI arguments and explicitly selected environment entries
veloc-wasm run app.wasm --env MODE=fast -- input.txt
# Query the same target declarations used by code generation
veloc-wasm inspect cpus --target riscv64
veloc-wasm inspect features --target riscv64
# Cross-compile an ELF object without loading it
veloc-wasm emit module.wasm --emit object --target riscv64 --cpu c908 -o module.oText products default to stdout; -o - explicitly selects stdout. Object emission
requires -o. Objects reference Veloc's runtime ABI and are not standalone executables.
The library uses Config.codegen.opt_level as its single optimization setting;
Engine::new and Engine::with_config return Result.
WebAssembly Experimental C frontend
│ │
└──────────────┬─────────────────────┘
▼
Veloc typed SSA IR
│
┌─────────┴──────────┐
│ analyses │ optimizations
│ use-def/liveness │ constant folding/DCE
└─────────┬──────────┘
▼
┌─────────┴──────────────┐
▼ ▼
register-bytecode interpreter LIR and x86-64 backend
│ │
▼ ▼
execution ELF object / JIT
WebAssembly and C source are translated into the same Veloc middle-level IR (MIR). From there, the runtime can compile MIR into compact bytecode or lower it through low-level IR (LIR) to native x86-64 code.
| Crate | Purpose |
|---|---|
veloc |
Top-level facade for the IR, interpreter, and code generator. |
veloc-mir |
Typed SSA IR, builders, data-flow graph, text format, and validator. |
veloc-lir |
Machine-facing IR, operand schemas, register identities, and stage markers. |
veloc-analyzer |
Use-def and liveness analyses. |
veloc-optimizer |
Pass management, metrics, constant folding, and dead-code elimination. |
veloc-interpreter |
IR-to-bytecode compiler and register-bytecode runtime. |
veloc-codegen |
Target-independent LIR pipeline and x86-64 backend. |
veloc-spec |
Typed cross-IR value-rule compiler sharing OpSpec contracts, plus target descriptions and instruction selection. |
veloc-wasm |
WebAssembly translator, runtime, CLI, linker, JIT, and WASI support. |
veloc-c |
Experimental C parser and IR frontend. |
veloc-wasm-spec |
WebAssembly specification test runner. |
Build and test the complete workspace:
cargo build --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targetsRun focused interpreter and WebAssembly tests:
cargo test -p veloc-interpreter
cargo test -p veloc-wasmThe specification runner accepts either a .wast file or a directory from the upstream WebAssembly specification tests:
cargo run --release -p veloc-wasm-spec -- \
/path/to/wasm-spec/test/core \
--strategy interpReplace interp with jit to exercise the native backend.
To use the pinned testsuite submodule, for example the integer suite:
git submodule update --init crates/veloc-wasm/tests/testsuite
CARGO_INCREMENTAL=0 cargo run -p veloc-wasm-spec -- \
crates/veloc-wasm/tests/testsuite/i32.wast --strategy jit --opt-level 1 --verboseThe runner reports skipped stack-exhaustion assertions separately. Passing CoreMark does not imply full WebAssembly conformance: the complete floating-point suites still require additional lowering, including min/max and saturating conversions.
Veloc is suitable for compiler and runtime experimentation, but is not yet a stable production toolchain. Current priorities include broader WebAssembly coverage, more x86-64 instructions and ABI support, additional optimization passes and targets, completion of the C frontend, and API stabilization.
Issues and pull requests are welcome.
Veloc is available under the MIT License.