Getting started

From a bare environment to a booting kernel in ~15 minutes — mirrors docs/guides/getting-started.md

§1Requirements

Rux develops and runs on an ordinary Linux host — no special hardware.

ClassDependencyPurpose
Requiredrustup / rustc (stable or nightly)the kernel itself is pure Rust (no_std)
RequiredQEMU ≥ 5.0system emulation (qemu-system-riscv64 / x86_64 / aarch64)
Requiredriscv64-linux-gnu-gcccross-compiling userspace programs
Optionalwhiptailthe make menuconfig TUI
Optionalgdb (riscv64-unknown-elf-gdb)make debug kernel debugging
Optionale2fsprogsmkfs.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

ArchitectureCommandRust targetQEMU machine
riscv64 (default)make buildriscv64gc-unknown-none-elfvirt
x86_64PLATFORM=x86_64 make build or make build-x86x86_64-unknown-noneq35
aarch64PLATFORM=aarch64 make buildaarch64-unknown-nonevirt (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
Guest-side test-case sources are archived as userspace/probes/probes.tar.gz; make user / make test restore them into 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
Note: the GUI entry point is 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)

CommandWhat it verifiesScale
make verifysync checks + property-based tests1104 proptests
make kaniKani symbolic execution (per harness)157 proof harnesses
make spinSPIN concurrency models4 models
make miriMiri UB detectionnightly

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

SymptomFix
error: target not foundre-run the two rustup target add commands
riscv64-linux-gnu-gcc: command not foundinstall the cross toolchain (apt / pacman, §1)
qemu: unsupported machine / could not load bootloaderupgrade to QEMU ≥ 5.0 (ships OpenSBI) or point -bios manually
fs: ext4 mount failedin order: make sdk && make user && make toybox && make rootfs
test timeoutskill leftover QEMU processes and retry; or use a release build
Load/Store access faultmake clean && make build, confirm the kernel version matches
configuration not taking effectcargo clean, rebuild, check cat kernel/src/config.rs

§9Next steps