# 快速开始

`rvrun` 即完整的命令行界面：它接收一个 riscv64 Linux ELF（或指向它的 `#!` 脚本）以及该程序
的参数。本页先将其构建出来，再运行仓库自带的程序——这是验证整条工具链可用所需的最小流程。

## 前置要求

- 一台 Apple 芯片的 Mac（macOS arm64）。同一套核心也可以以 VM 模式运行在 arm64 Linux 上；见
  [直接模式与 VM 模式](/zh-CN/concepts/modes/)。
- Rust stable。工作区使用 edition 2024（需要 rustc 1.85 或更新）。
- 可选：用 zig 0.17+ 重新构建自带的测试程序（`tests/fixtures/build.sh`）；基准测试用
  `hyperfine`。

## 构建

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

## 运行一个程序

仓库中包含一个很小的测试程序，用于验证整条流水线；它只打印一行：

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

接下来可以运行真正的程序。任何 riscv64 Linux 二进制均可；若它是动态链接的，还需要对应的
用户态环境：

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

`-L` 会优先在该目录（sysroot）中解析客户程序的绝对路径——动态加载器、库文件、`/etc` 配置——
用法与 `qemu-riscv64 -L` 相同。

## 追踪与剖析

三个环境变量可以启用诊断输出：

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

## 测试

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

一项改动只有在两个宿主平台均通过后才算完成。