快速入门

从零环境到内核跑起来,大约 15 分钟 · 对应仓库文档 docs/guides/getting-started.md

§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交叉编译用户态程序
可选whiptailmake menuconfig 交互配置
可选gdb(riscv64-unknown-elf-gdb)make debug 内核调试
可选e2fsprogsmkfs.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 targetQEMU 机型
riscv64(默认)make buildriscv64gc-unknown-none-elfvirt
x86_64PLATFORM=x86_64 make build 或 make build-x86x86_64-unknown-noneq35
aarch64PLATFORM=aarch64 make buildaarch64-unknown-nonevirt (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    # ⑥ 打包最小根文件系统镜像
_guest 侧测试用例源码以 tarball 归档于 userspace/probes/probes.tar.gz,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,确定性调试用
注意:GUI 入口是 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 kaniKani 符号执行(按 harness)157 个 proof harness
make spinSPIN 并发模型检查4 个模型
make miriMiri 未定义行为检测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 foundapt / 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 faultmake clean && make build,确认内核版本一致
配置不生效cargo clean 后重build,并 cat kernel/src/config.rs 核对生成结果

§9下一步