Getting started
§1Requirements
Rux develops and runs on an ordinary Linux host — no special hardware.
| Class | Dependency | Purpose |
|---|---|---|
| Required | rustup / rustc (stable or nightly) | the kernel itself is pure Rust (no_std) |
| Required | QEMU ≥ 5.0 | system emulation (qemu-system-riscv64 / x86_64 / aarch64) |
| Required | riscv64-linux-gnu-gcc | cross-compiling userspace programs |
| Optional | whiptail | the make menuconfig TUI |
| Optional | gdb (riscv64-unknown-elf-gdb) | make debug kernel debugging |
| Optional | e2fsprogs | mkfs.ext4 -d for rootfs images |
# 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
§2Code and toolchains
git clone https://github.com/topkernel/Rux
cd Rux
# add the Rust cross targets
rustup target add riscv64gc-unknown-none-elf
rustup target add riscv64gc-unknown-linux-musl
The toolchain/ directory carries a self-built musl cross toolchain (Ubuntu ships no gcc-riscv64-linux-musl package): make sdk builds toolchain/riscv64-rux-linux-musl/ (headers + libc.a + a musl-gcc wrapper), the prerequisite for userspace builds. The x86_64 musl sysroot ships as a tarball that make user restores on demand.
§3Building
The kernel
| Architecture | Command | Rust target | QEMU machine |
|---|---|---|---|
| riscv64 (default) | make build | riscv64gc-unknown-none-elf | virt |
| x86_64 | PLATFORM=x86_64 make build or make build-x86 | x86_64-unknown-none | q35 |
| aarch64 | PLATFORM=aarch64 make build | aarch64-unknown-none | virt (gic-version=3) |
Other modes: make -C build build-release (optimized), make bin, make clean. Configuration lives in Kernel.toml, compiled by build.rs into kernel/src/config.rs — see Kernel configuration.
The full userspace stack
make build # ① the kernel
make sdk # ② the musl libc SDK (prerequisite for userspace)
make user # ③ userspace programs (Rust std + musl; runs sdk + probes first)
make toybox # ④ toybox, 200+ command-line tools
make mrsh # ⑤ a POSIX shell
make rootfs # ⑥ pack the minimal rootfs image
test/ via scripts/extract-probes.sh — no manual steps.§4Running
The minimal system (an mrsh shell)
make run
Builds if needed, then enters the serial console at /bin/sh. Try ls /, toybox cat /proc/cpuinfo, echo "Hello Rux!".
Ubuntu desktop (24.04 default / the 22.04 GNOME chain, x86_64 + KVM)
make ubuntu-run
Builds the x86_64 release kernel and boots the full Ubuntu 24.04 desktop in an SDL window (systemd 255, multi-user + graphical targets, serial login root / rux; the default since the 2026-11-16 user directive). The 22.04 GNOME chain boots via the override:
UBUNTU_IMG=work/gnome-x86.img UBUNTU_INIT=/sbin/runit make ubuntu-run # the 22.04 GNOME desktop chain
SMP=1 make ubuntu-run # single core (default SMP=4)
ACCEL=tcg make ubuntu-run # disable KVM (KVM by default)
THREAD=single make ubuntu-run # single-threaded TCG for deterministic debugging
make ubuntu-run. Shared images boot only with -snapshot + file.locking=off — the image itself is never written.OpenHarmony
make oh-image # wire the OH images from the store (symlinks, OH_IMAGES overrides)
make oh-run # build + boot the OpenHarmony launcher in a GTK window
OH boots with the same shape as Ubuntu: make oh-image && make oh-run (the tracked driver scripts/test/run-oh.sh); the unattended form is scripts/test/debug/oh-boot.sh (serial to file, the QEMU monitor on a unix socket for screenshots). Porting plan: docs/development/openharmony-port-plan.md.
§5Markers of a successful boot
Minimal system, in order on serial:
OpenSBI v0.9 banner
Rux ASCII banner
console [ok] trap [ok] mm [ok]
sched [ok] fs [ok] driver [ok] smp [ok]
init: loading /bin/sh
$ _
Ubuntu: systemd 255 units reaching ready, the multi-user/graphical targets hit, and the serial login prompt; the 22.04 GNOME chain (override variables) additionally shows the framebuffer resolution and login-screen-ready lines — then the SDL window shows the desktop.
§6Running the tests
The in-kernel suite
make test # riscv64 (default)
PLATFORM=x86_64 make test # x86_64
PLATFORM=aarch64 make test # aarch64
All assertions run inside the QEMU guest. Current baseline: riscv64 1584/1584 (2026-11-20), x86_64 1263/1263 (2026-11-01, 76 test files) across memory / process / fs / ipc / signal / network / driver / syscall.
LTP
make ltp # build LTP on the host (needs sdk; 1,838 official binaries)
# inside the Rux shell:
cd /test/linux-ltp
./run_quick.sh
Formal verification (four layers)
| Command | What it verifies | Scale |
|---|---|---|
| make verify | sync checks + property-based tests | 1104 proptests |
| make kani | Kani symbolic execution (per harness) | 157 proof harnesses |
| make spin | SPIN concurrency models | 4 models |
| make miri | Miri UB detection | nightly |
The GUI has a CI-style verifier: python3 test/ubuntu-gui/verify.py --runs 2 --smp 4 (23 checks per boot).
§7Kernel configuration
make config # view (cat Kernel.toml)
make menuconfig # TUI configuration (12 categories)
Common Kernel.toml sections: [memory] (kernel_heap_size / physical_memory / page_size), [smp] (max_cpus), [network] (eth_mtu), [printk] (log_level), [performance] (opt_level / lto). Changes trigger a rebuild; the generated kernel/src/config.rs is never hand-edited. The repository's current Kernel.toml is authoritative (a few defaults move with work-lane needs, e.g. kernel heap size).
§8Troubleshooting
| Symptom | Fix |
|---|---|
| error: target not found | re-run the two rustup target add commands |
| riscv64-linux-gnu-gcc: command not found | install the cross toolchain (apt / pacman, §1) |
| qemu: unsupported machine / could not load bootloader | upgrade to QEMU ≥ 5.0 (ships OpenSBI) or point -bios manually |
| fs: ext4 mount failed | in order: make sdk && make user && make toybox && make rootfs |
| test timeouts | kill leftover QEMU processes and retry; or use a release build |
| Load/Store access fault | make clean && make build, confirm the kernel version matches |
| configuration not taking effect | cargo clean, rebuild, check cat kernel/src/config.rs |
§9Next steps
- Contributing — the workflow, merge gates, the debugging toolbox, and the "first task" path for newcomers.
- Testing — LTP, stability and stress; Performance and Security are standalone sections.
- Architecture & design — every subsystem with mechanisms and measured numbers.
- Command reference — the common commands on one page.