Building VeridianOS

This guide covers building VeridianOS from source for all supported architectures.

Prerequisites

Before building, ensure you have:

Completed the development setup
Rust nightly toolchain installed
Required system packages
At least 2GB free disk space

Quick Build

The easiest way to build VeridianOS using the automated build script:

# Build all architectures (development)
./build-kernel.sh all dev

# Build specific architecture
./build-kernel.sh x86_64 dev

# Build release version
./build-kernel.sh all release

Architecture-Specific Builds

x86_64

Note: x86_64 requires custom target with kernel code model to avoid relocation errors.

# Recommended: using build script
./build-kernel.sh x86_64 dev

# Manual build (with kernel code model)
cargo build --target targets/x86_64-veridian.json \
    -p veridian-kernel \
    -Zbuild-std=core,compiler_builtins,alloc

Output: target/x86_64-veridian/debug/veridian-kernel

AArch64

# Recommended: using build script
./build-kernel.sh aarch64 dev

# Manual build (standard bare metal target)
cargo build --target aarch64-unknown-none \
    -p veridian-kernel

Output: target/aarch64-unknown-none/debug/veridian-kernel

RISC-V 64

# Recommended: using build script
./build-kernel.sh riscv64 dev

# Manual build (standard bare metal target)
cargo build --target riscv64gc-unknown-none-elf \
    -p veridian-kernel

Output: target/riscv64gc-unknown-none-elf/debug/veridian-kernel

Build Options

Release Builds

For optimized builds:

# Using build script (recommended)
./build-kernel.sh all release

# Manual for x86_64
cargo build --release --target targets/x86_64-veridian.json \
    -p veridian-kernel \
    -Zbuild-std=core,compiler_builtins,alloc

Build All Architectures

./build-kernel.sh all dev

This builds debug versions for all three architectures.

Build Flags Explained

-Zbuild-std

Custom targets require building the Rust standard library from source:

core: Core library (no_std)
compiler_builtins: Low-level compiler intrinsics
alloc: Allocation support (when ready)

-Zbuild-std-features

Enables memory-related compiler builtins required for kernel development.

Creating Bootable Images

x86_64 Boot Image

# Create bootable image
cargo bootimage --target targets/x86_64-veridian.json

# Output location
ls target/x86_64-veridian/debug/bootimage-veridian-kernel.bin

Other Architectures

AArch64 and RISC-V use the raw kernel binary directly:

AArch64: Load at 0x40080000
RISC-V: Load with OpenSBI

Build Artifacts

Build outputs are organized by architecture:

target/
├── x86_64-veridian/
│   ├── debug/
│   │   ├── veridian-kernel
│   │   └── bootimage-veridian-kernel.bin
│   └── release/
├── aarch64-veridian/
│   ├── debug/
│   │   └── veridian-kernel
│   └── release/
└── riscv64gc-veridian/
    ├── debug/
    │   └── veridian-kernel
    └── release/

Common Issues

Rust Toolchain

error: failed to run `rustc` to learn about target-specific information

Solution: Install the correct nightly toolchain:

rustup toolchain install nightly-2025-01-15
rustup override set nightly-2025-01-15

Missing Components

error: the component `rust-src` is required

Solution: Add required components:

rustup component add rust-src llvm-tools-preview

Build Cache

If builds fail unexpectedly:

# Clean and rebuild
cargo clean
./build-kernel.sh all dev

Build Performance

Incremental Builds

Rust automatically uses incremental compilation. First build is slow (~2 minutes), subsequent builds are much faster (~30 seconds).

Parallel Builds

Cargo uses all available CPU cores by default. To limit:

cargo build -j 4  # Use 4 cores

Build Cache

The target directory can grow large. Clean periodically:

cargo clean

CI/CD Builds

Our GitHub Actions workflow builds all architectures on every push. Check the Actions tab for build status.

Next Steps

After building successfully:

VeridianOS Developer Guide