This is the exact root-package feature reference. For procedural setup, prerequisites, Make targets, PGO, and common failures, see Building.
Linux process emulation is a separate binary, rax-user, with no dedicated
Cargo feature. It requires a Linux or macOS host at runtime. A software-only
build uses --no-default-features --bin rax-user; adding smir-jit enables
eligible x86-64 native regions and the opt-in RV64 path (--riscv-jit).
ELF32 i386 compatibility stays interpreted. Enabling KVM or HVF does not
change the process application's CPU adapters. See
Linux programs for its ABI limits.
The root manifest currently declares:
[package]
name = "rax"
version = "0.1.0"
edition = "2024"
autotests = false
[features]
default = ["kvm", "smir-jit"]
kvm = ["kvm-bindings", "kvm-ioctls"]
hvf = []
trace = []
debug = []
profiling = []
x86_64-suite = []
x86-suite = ["x86_64-suite"]
smir-jit = []autotests = false means Cargo integration targets are the explicit [[test]] entries in Cargo.toml. Adding a .rs file under tests/ does not automatically make it a standalone target.
| Feature | Default | Adds to the build | Does not establish |
|---|---|---|---|
default |
— | feature bundle enabling kvm and smir-jit |
a portable host-independent build; use --no-default-features when either backend must be omitted |
kvm |
yes | Linux-target KVM bindings, ioctls, backend code, and x86 hardware-backed execution paths | usable /dev/kvm, permission, virtualization firmware settings, guest compatibility, or instruction-level observability |
smir-jit |
yes | Unix executable-memory runtime, hot-region integration, SMIR native lowerers for admitted host/guest combinations | that a region promoted, that every SMIR operation is lowerable, or that native execution is faster for a given workload |
hvf |
no | Hypervisor.framework backend code | entitlement signing, runtime availability, or support for every host/guest architecture pair |
trace |
no | instruction trace implementation | KVM/HVF per-instruction tracing or complete trace visibility outside the software retirement loop |
debug |
no | GDB Remote Serial Protocol server | correctness of every GDB packet or stepping support for every backend |
profiling |
no | per-mnemonic counters, live output, and JSON export | host performance measurement or visibility into instructions executed outside the instrumented path |
x86_64-suite |
no | generated aggregate x86-64 integration-test target | production runtime capability; this is a test-selection feature |
x86-suite |
no | compatibility alias for x86_64-suite |
an independent test corpus |
cargo build --release --no-default-featuresIncludes the software engines and ordinary command-line VM code without KVM or the native tier. This is the minimum-dependency starting point for the bundled AArch64 guest.
cargo build --release --no-default-features --features smir-jitUse on a supported Unix x86-64 or AArch64 host. JIT admission remains guest-, operation-, state-, and host-feature-dependent.
cargo build --release --no-default-features --features kvmThis selects the hardware backend without including the smir-jit default feature.
cargo build --releaseEquivalent to enabling kvm,smir-jit from the root package. Host target gates still determine whether KVM dependencies and code are active.
cargo build --release --no-default-features --features hvf
codesign -s - -f --entitlements rax.entitlements target/release/raxAdd smir-jit if both the native tier and HVF are desired:
cargo build --release --no-default-features --features hvf,smir-jitcargo build --release --no-default-features \
--features smir-jit,trace,debug,profilingRemove smir-jit when debugging the interpreter or when a native region would complicate reproduction.
cargo test --release --features x86_64-suite --test x86_64The compatibility spelling is:
cargo test --release --features x86-suite --test x86_64Use the canonical x86_64-suite name in new documentation and automation.
Cargo features are only one layer. Availability can also depend on cfg conditions and runtime probes.
The KVM crates are target dependencies for Linux. The useful runtime path further requires x86-64 hardware virtualization and /dev/kvm. A Linux build on another architecture or a container without device access can compile a different subset than the prose suggests.
HVF is a macOS backend. The host architecture constrains the guest path. Apple Silicon is the established AArch64 hardware-assisted route; Intel macOS uses the x86-oriented route. The executable must carry the hypervisor entitlement.
The root manifest describes a Unix W^X runtime and native lowering on x86-64 and AArch64 hosts. Admission is fail-safe: unsupported register, flag, memory, call, width, feature, or control-flow contracts leave execution in the interpreter. The exact eligible set differs by host/guest combination.
Trace, GDB, profiling, and instruction-count snapshots are most complete where the software backend owns retirement. A compiled feature does not turn a hardware backend into an interpreter-equivalent event source.
The root release profile is:
[profile.release]
lto = "fat"
codegen-units = 1
panic = "unwind"
strip = true
[profile.release.build-override]
opt-level = 3panic = "unwind" is part of the C ABI safety contract. rax-capi catches engine panics and reports RAX_ERR_INTERNAL; a root release profile that aborts would prevent containment.
The checked-in Cargo configuration applies:
[target.'cfg(target_arch = "x86_64")']
rustflags = ["-C", "target-cpu=x86-64-v3"]This permits an x86-64-v3 instruction baseline. It is not suitable for older x86-64 CPUs. A local host-native build can use:
RUSTFLAGS='-C target-cpu=native' cargo build --releaseA host-native artifact is not portable and must not be used for an unlabeled benchmark comparison.
The root workspace contains:
capi
and excludes independent packages/directories:
microkernel
tools/asl-parser/asl-parser-rs
_ref
Therefore:
cargo build --workspace --releaseincludes the root package and C API member, but does not build the microkernel or the excluded tools.
The rax-capi crate has its own forwarded feature names. The normative list is in capi/README.md. At present it documents:
| C API feature | Effect |
|---|---|
jit |
native hot-block JIT support exposed to the embedding library |
kvm |
builds KVM capability, although the C backend selector does not yet expose the KVM route |
hvf |
Hypervisor.framework support |
trace |
verbose trace support |
Example:
cargo build -p rax-capi --release --features jitDo not assume root feature names and C API feature names are identical: root uses smir-jit; the C API forwards it as jit.
When reporting a test result, include the feature set. Examples:
cargo test --release
cargo test --release --all-features
cargo test --release --features x86_64-suite --test x86_64
cargo test --release --no-default-features --test arm
Those commands do not select the same code. A passing default-feature test run is not evidence about --no-default-features, and vice versa.