Getting Started

Relevant source files

• README.md 
• CONTRIBUTING.md 
• rust-toolchain.toml 
• Cargo.toml 
• docs/operations/build.md 
• ci/manifests/targets.toml 

axiomOS is a bare-metal Rust kernel with runtime-programmable behavior through verified eBPF programs. This section walks through the toolchain, how to build the images, how to boot them in QEMU, and how to put the kernel on a Raspberry Pi 5.

Supported targets

The target manifest in ci/manifests/targets.toml classifies them more conservatively: x86_64 QEMU/OVMF is supported, Raspberry Pi 5 is supported after HIL, AArch64 virt is experimental (kernel check only), and the RISC-V demo is experimental standalone. The Shrike RP2040 firmware (thumbv6m-none-eabi) is supported after HIL; the ForgeFPGA safety gate is built with the vendor toolchain. See Shrike RP2040 and FPGA.

Prerequisites

Rust toolchain

The toolchain is pinned in rust-toolchain.toml to a dated nightly. rustup installs it automatically on first cargo invocation in the repository.

The channel is deliberately not floating: a bare nightly once let a new clippy rule silently turn the lint job red. Bump it deliberately. A nightly is required because the root manifest uses artifact dependencies (artifact = "bin"), enabled via bindeps = true in .cargo/config.toml.

System tools

The root build.rs assembles a root filesystem image and, for x86_64, a bootable ISO. A clean machine without these tools fails inside build.rs.

Optional: GDB or LLDB for --debug; cargo-binutils if you need rust-objcopy.

# Debian/Ubuntu example from CONTRIBUTING.md
sudo apt update && sudo apt install -y xorriso qemu-system

Pinned external inputs

ci/manifests/build-inputs.env pins the inputs that build.rs fetches:

BPF trust key

Kernels are signed-only by default. The kernel embeds a 32-byte Ed25519 public key at compile time from the path in AXIOM_BPF_TRUSTED_KEY_PATH (kernel/src/bpf/trust.rs), and scripts/build/rpi5.sh and scripts/run/virt.sh refuse to run without it. The bpf-unsigned-development feature compiles that requirement out; see Building.

First run

# Build and run in QEMU (x86_64)
cargo run
 
# Raspberry Pi 5 build (kernel8.img with embedded ext2 rootfs)
cargo xtask build rpi5

The cargo xtask alias is defined in .cargo/config.toml as run --locked --package xtask --. Per docs/operations/README.md, cargo xtask is the canonical interface and scripts under scripts/ are its implementation helpers.

Where to go next