# 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](/concepts/modes/).
- 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

```sh
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:

```console
$ ./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:

```sh
./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:

```sh
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

```sh
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.