Getting started

rvrun is the whole CLI: it takes a riscv64 Linux ELF (or a #! script that names one) plus that program’s arguments. This page builds it and runs the committed fixture — the smallest sequence that exercises the toolchain end to end.

Prerequisites

• An Apple silicon Mac (macOS arm64). The same core runs on arm64 Linux under VM mode; see Direct mode and VM mode.
• Rust stable. The workspace uses edition 2024 (rustc 1.85 or newer).
• Optional: zig 0.17+ to rebuild the committed fixtures (tests/fixtures/build.sh), and hyperfine for benchmarks.

Build

git clone https://github.com/dorian-zhao/champollion.git
cd champollion
cargo build --release -p rvrun

Run a program

The repository includes a small fixture that exercises the pipeline; it prints a single line:

$ ./target/release/rvrun tests/fixtures/hello
hello from riscv64

To run a real program, point rvrun at it. Any riscv64 Linux binary works; a dynamically linked one also requires its userland:

./target/release/rvrun -L /path/to/riscv64-rootfs ./some-program

-L resolves the guest’s absolute paths (its musl dynamic loader, libraries, /etc files) inside that directory first, like qemu-riscv64 -L.

Tracing and profiling

Three environment variables control the diagnostic output:

RVRUN_STRACE=1 ./target/release/rvrun tests/fixtures/hello  # every syscall
RVRUN_STATS=1 ./target/release/rvrun tests/fixtures/hello   # instructions retired, MIPS
RVRUN_PROF=prof.txt ./target/release/rvrun tests/fixtures/hello
tools/jitprof.py prof.txt                                   # hottest blocks

Tests

cargo test        # the whole suite on the Mac
tools/linux.sh    # the same suite on arm64 Linux, in release mode

A change is complete only once both hosts pass.