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 

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:

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

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.