Building

Relevant source files

• Cargo.toml 
• build.rs 
• src/main.rs 
• tools/xtask/src/cli.rs 
• tools/xtask/src/commands.rs 
• scripts/README.md 
• scripts/build/rpi5.sh 
• kernel/Cargo.toml 
• docs/operations/build.md 
• docs/reference/generated/artifacts.md 
• firmware/shrike/rp2040/build-uf2.sh 
• firmware/shrike/rp2040/flash-uf2.sh 

The build is driven by Cargo plus a typed command surface, cargo xtask. The root package (axiomos) is both the host-side QEMU runner (src/main.rs) and the image assembler (build.rs), which builds the kernel and every userspace binary for the target architecture as artifact dependencies.

Build flow

cargo xtask

cargo xtask is an alias for run --locked --package xtask --. The grammar below comes from tools/xtask/src/cli.rs and the usage text in commands.rs.

build, run, deploy, bench and debug all take a target, an optional --dry-run, and trailing arguments after -- that are forwarded to the underlying implementation. --dry-run prints the delegated command instead of running it.

cargo xtask build rpi5 --dry-run
cargo xtask run x86_64 -- --headless --smp 2

x86_64 via plain Cargo

cargo build              # debug
cargo build --release    # release
cargo run                # build then boot in QEMU
cargo run -- --no-run    # build only; prints KERNEL_BINARY, BOOTABLE_ISO, DISK_IMAGE

The default feature set is x86_64_deps, which pulls the x86_64 builds of the kernel (with cloud-profile) and all userspace crates.

AArch64 and Raspberry Pi 5

The AArch64 image uses --no-default-features --features aarch64_deps:

cargo build --release --target aarch64-unknown-none \
  --no-default-features --features aarch64_deps

scripts/build/rpi5.sh wraps the two-stage process for the Pi; see Raspberry Pi 5.

Cargo features

Root Cargo.toml features:

Kernel features (kernel/Cargo.toml) that you pass for the Pi build via scripts/build/rpi5.sh:

Managed-runtime image

managed-runtime is a separate opt-in image configuration, described in Managed runtime. In it, init runs only the installer and no legacy diagnostic workloads, and signed bundles are uploaded after boot with rk runtime instead of being baked in with AXIOM_SIGNED_BPF_STARTUP_PATH. The build still needs AXIOM_BPF_TRUSTED_KEY_PATH.

# x86_64 (QEMU)
cargo build --release --features managed-runtime
# opt-in QEMU userspace ABI probe
cargo run --locked --release --features managed-syscall-probe -- --headless --smp 1 --mem 1G

For the Pi, pass managed-runtime in the kernel feature list; see Raspberry Pi 5. Software and host testing only: physical qualification has not been run and actuation is disabled (Qualification).

Signed versus unsigned BPF

Without bpf-unsigned-development, the kernel includes the production trust key with include_bytes!(env!("AXIOM_BPF_TRUSTED_KEY_PATH")), so AXIOM_BPF_TRUSTED_KEY_PATH must be set at build time. The Pi and virt scripts check that the file exists and is exactly 32 bytes. With the feature, the trust module takes a different path and no key is needed. In that mode init spawns sched_switch_export_demo and sched_switch_bridge_demo instead of signed_bpf_loader.

An optional signed startup program can be baked into the rootfs: set AXIOM_SIGNED_BPF_STARTUP_PATH to a signed container and build.rs copies it to /var/lib/rkbpf/programs/startup.rbpf.

Environment variables

What build.rs produces

Shrike RP2040 firmware

firmware/shrike/rp2040/build-uf2.sh builds the Shrike firmware UF2. With no argument it builds the default image (shrike_rp2040.uf2). With --runtime it enables the fpga-runtime feature, requires the pinned FPGA image firmware/shrike/fpga/forgefpga/axiomos_r04_mcu.bin in the flash-contract check, writes shrike_rp2040_runtime.uf2, and includes the bitstream in the SHA-256 sidecar. flash-uf2.sh UF2 MOUNT [fpga-bitstream] verifies the sidecar and flash contract before copying. The generated artifact table lists the runtime UF2 as experimental, for unloaded qualification.

Artifacts

Per docs/reference/generated/artifacts.md:

Do not select artifacts by newest timestamp. Use the paths reported through AXIOM_ARTIFACT_PATHS or --no-run.

Scripts layout

scripts/README.md states that scripts are focused process adapters behind cargo xtask.