Building

Toolchain

Helctic pins a Rust nightly toolchain via rust-toolchain.toml:

[toolchain]
channel = "nightly"
components = ["rust-src", "clippy", "rustfmt"]

rust-src is required because the kernel builds the standard library from source (-Z build-std). The toolchain is provided by rustup; the Nix dev shell installs it on first entry rather than pinning a Nix-provided Rust.

You also need Zig 0.15+ (personality + btrfs static libraries), nasm (x86/x86_64 trampoline), and a target objcopy for stripping symbols.

Targets

Custom target specs live in targets/:

Arch	Spec
x86_64	targets/x86_64-unknown-kernel.json
i686	targets/i686-unknown-kernel.json
aarch64	targets/aarch64-unknown-kernel.json
riscv64	targets/riscv64-unknown-kernel.json

The x86 specs disable SIMD and use the soft-float ABI — expressed in the spec via "rustc-abi": "x86-softfloat" plus +soft-float features (the old -C soft-float flag was removed from rustc).

Build commands

With cargo directly

export RUST_TARGET_PATH="$PWD/targets"
cargo rustc \
  --bin kernel \
  --target targets/x86_64-unknown-kernel.json \
  --release \
  -Z build-std=core,alloc \
  -Z json-target-spec \
  -- \
  -C link-arg=-T -C link-arg=linkers/x86_64.ld \
  -C link-arg=-z -C link-arg=max-page-size=0x1000

-Z json-target-spec is required on recent nightlies to use JSON target files.

With make

make ARCH=x86_64          # produces kernel + kernel.sym
make ARCH=aarch64
make ARCH=riscv64
make ARCH=i686

The Makefile wires the per-arch linker script (linkers/<arch>.ld) and runs objcopy to split debug symbols from the stripped image.

The build pipeline

1. build.rs runs first:
   • Determines the arch from CARGO_CFG_TARGET_ARCH (works with custom JSON specs, no rustc shell-out).
   • Assembles the trampoline with nasm (x86/x86_64).
   • Runs zig build in personality/ and btrfs/, linking the resulting libpersonality.a and libbtrfs.a.
2. cargo + build-std compiles core/alloc and the kernel.
3. Linker applies the architecture linker script.
4. objcopy produces the final stripped kernel and a kernel.sym.

Linting & formatting

./clippy.sh                 # clippy against x86_64-unknown-none
cargo fmt -- --check

CI

GitHub Actions builds all four architectures, runs clippy/fmt, and (on tags) packages .tar, .deb, and .rpm artifacts. Jobs run on Blacksmith runners (blacksmith-4vcpu-ubuntu-2404).