快速入门
§1环境要求
Rux 在普通 Linux 主机上开发与运行,不需要专用硬件。
| 类别 | 依赖 | 用途 |
|---|---|---|
| 必装 | rustup / rustc (stable 或 nightly) | 内核本体是纯 Rust(no_std) |
| 必装 | QEMU ≥ 5.0 | 系统模拟(qemu-system-riscv64 / qemu-system-x86_64 / qemu-system-aarch64) |
| 必装 | riscv64-linux-gnu-gcc | 交叉编译用户态程序 |
| 可选 | whiptail | make menuconfig 交互配置 |
| 可选 | gdb(riscv64-unknown-elf-gdb) | make debug 内核调试 |
| 可选 | e2fsprogs | mkfs.ext4 -d 制作根文件系统镜像 |
# Ubuntu / Debian
sudo apt-get install gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu \
qemu-system-riscv e2fsprogs
# Arch Linux
sudo pacman -S riscv64-linux-gnu-gcc
§2获取代码与工具链
git clone https://github.com/topkernel/Rux
cd Rux
# 添加 Rust 交叉目标
rustup target add riscv64gc-unknown-none-elf
rustup target add riscv64gc-unknown-linux-musl
仓库的 toolchain/ 目录携带自建 musl libc 交叉工具链(Ubuntu 不提供 gcc-riscv64-linux-musl 包):运行 make sdk 即可构建出 toolchain/riscv64-rux-linux-musl/(头文件 + libc.a + musl-gcc 包装器),它是编译用户态程序的前置。x86_64 的 musl sysroot 以 tarball 形式随仓库分发,make user 会按需自动恢复。
§3构建
内核
| 架构 | 命令 | Rust target | QEMU 机型 |
|---|---|---|---|
| riscv64(默认) | make build | riscv64gc-unknown-none-elf | virt |
| x86_64 | PLATFORM=x86_64 make build 或 make build-x86 | x86_64-unknown-none | q35 |
| aarch64 | PLATFORM=aarch64 make build | aarch64-unknown-none | virt (gic-version=3) |
其他档位:make -C build build-release(release 优化)、make bin(生成发布二进制)、make clean。内核配置在 Kernel.toml,构建期由 build.rs 编译为 kernel/src/config.rs —— 详见内核配置。
完整用户态栈
make build # ① 内核
make sdk # ② musl libc SDK(用户程序的前置)
make user # ③ 用户态程序(Rust std + musl;自动先 sdk + probes)
make toybox # ④ toybox 200+ 命令行工具
make mrsh # ⑤ POSIX shell
make rootfs # ⑥ 打包最小根文件系统镜像
make user / make test 会通过 scripts/extract-probes.sh 幂等恢复到 test/ —— 不需要手工干预。§4运行
最小系统(mrsh shell)
make run
内核不存在时自动构建,随后进入串口控制台的 /bin/sh。可以体验 ls /、toybox cat /proc/cpuinfo、echo "Hello Rux!"。
Ubuntu 桌面(24.04 默认 / 22.04 GNOME 链,x86_64 + KVM)
make ubuntu-run
构建 x86_64 release 内核并以 SDL 窗口启动完整 Ubuntu 24.04 桌面(systemd 255,多用户 + 图形目标,串口登录 root / rux;2026-11-16 用户指令起为默认)。22.04 GNOME 链经覆盖变量启动:
UBUNTU_IMG=work/gnome-x86.img UBUNTU_INIT=/sbin/runit make ubuntu-run # 22.04 GNOME 桌面链
SMP=1 make ubuntu-run # 单核(默认 SMP=4)
ACCEL=tcg make ubuntu-run # 关 KVM(默认 KVM)
THREAD=single make ubuntu-run # 单线程 TCG,确定性调试用
make ubuntu-run(部分旧文档提到的 make gui 已不作为入口)。另:共享镜像一律以 -snapshot + file.locking=off 启动,不写坏镜像本体。OpenHarmony
make oh-image # 从镜像仓装配 OH 镜像(symlink,OH_IMAGES 可覆盖)
make oh-run # 构建 + GTK 窗口启动 OpenHarmony launcher
OH 启动与 Ubuntu 同形:make oh-image && make oh-run(跟踪驱动 scripts/test/run-oh.sh);无人值守形态是 scripts/test/debug/oh-boot.sh(串口落盘、QEMU monitor 走 unix socket 供截图)。移植计划见 docs/development/openharmony-port-plan.md。
§5启动成功的标志
最小系统启动,串口应依次出现:
OpenSBI v0.9 横幅
Rux ASCII banner
console [ok] trap [ok] mm [ok]
sched [ok] fs [ok] driver [ok] smp [ok]
init: loading /bin/sh
$ _
Ubuntu 启动则依次出现 systemd 255 各单元就绪、multi-user/graphical 目标达成与串口登录提示符的日志;22.04 GNOME 链(覆盖变量)另见帧缓冲分辨率与登录界面就绪,随后 SDL 窗口显示桌面。
§6跑测试
内核自带套件
make test # riscv64(默认)
PLATFORM=x86_64 make test # x86_64
PLATFORM=aarch64 make test # aarch64
所有断言在 QEMU guest 内运行(内核 crate 无法承载宿主侧 #[cfg(test)])。当前基线:riscv64 1584/1584(2026-11-20)、x86_64 1263/1263(2026-11-01,76 个测试文件),覆盖 memory / process / fs / ipc / signal / network / driver / syscall 八大类。
LTP 兼容性测试
make ltp # 宿主侧构建 LTP(需 sdk;1838 个官方二进制)
# 在 Rux shell 里:
cd /test/linux-ltp
./run_quick.sh
形式验证(四层)
| 命令 | 验证内容 | 规模 |
|---|---|---|
| make verify | 同步检查 + property-based 测试 | 1104 个 proptest |
| make kani | Kani 符号执行(按 harness) | 157 个 proof harness |
| make spin | SPIN 并发模型检查 | 4 个模型 |
| make miri | Miri 未定义行为检测 | nightly |
GUI 有 CI 式像素/串口验证:python3 test/ubuntu-gui/verify.py --runs 2 --smp 4(每次启动 23 项检查)。
§7内核配置
make config # 查看当前配置(cat Kernel.toml)
make menuconfig # TUI 交互配置(12 个大类)
Kernel.toml 的常用段:[memory](kernel_heap_size / physical_memory / page_size)、[smp](max_cpus)、[network](eth_mtu)、[printk](log_level)、[performance](opt_level / lto)。改完自动触发重编译;生成产物 kernel/src/config.rs 禁止手改。以仓库当前 Kernel.toml 为准(个别键的默认值随 lane 需求调整,如内核堆大小)。
§8排错速查
| 症状 | 处理 |
|---|---|
| error: target not found | 重跑两条 rustup target add |
| riscv64-linux-gnu-gcc: command not found | apt / pacman 安装交叉工具链(见 §1) |
| qemu: unsupported machine / could not load bootloader | 升级 QEMU ≥ 5.0(内含 OpenSBI),或手动 -bios 指定 |
| fs: ext4 mount failed | 按序 make sdk && make user && make toybox && make rootfs |
| 测试超时 | 结束残留 QEMU 进程后重试;或换 release 构建 |
| Load/Store access fault | make clean && make build,确认内核版本一致 |
| 配置不生效 | cargo clean 后重build,并 cat kernel/src/config.rs 核对生成结果 |