Building the Kernel

The NØNOS kernel is a bare-metal x86_64 binary compiled with a custom target specification. This page covers the kernel build process in detail.

---

Overview

┌────────────────────────────────────────────────────────────────┐
│                      KERNEL BUILD FLOW                         │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│   Source Code          Build System            Output          │
│   ───────────          ────────────            ──────          │
│                                                                │
│   ┌─────────┐         ┌─────────────┐        ┌─────────────┐   │
│   │  .rs    │────────▶│   Cargo     │───────▶│   ELF64     │   │
│   │ files   │         │  + build.rs │        │  Binary     │   │
│   └─────────┘         └─────────────┘        └────── ──────┘   │
│                             │                      │
│   ┌─────────┐               │                      │           │
│   │ PQClean │───────────────┘                      │           │
│   │  (C)    │  ML-KEM-768                          ▼           │
│   └─────────┘                               ┌─────────────┐    │
│                                             │   Ed25519   │    │
│   ┌─────────┐                               │   Signing   │    │
│   │ Signing │───────────────────────────────▶             │    │
│   │   Key   │                               └──────┬──────┘    │
│   └─────────┘                                      │           │
│                                                    ▼           │
│                                             ┌─────────────┐    │
│                                             │ kernel.bin  │    │
│                                             │   221 KB    │    │
│                                             └─────────────┘    │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Build Command

make kernel

Or build everything at once:

make nonos

---

Build Configuration

The kernel build uses several critical flags:

Flag	Purpose
-Zbuild-std=core,alloc	Compile core and alloc from source for no_std
-Zbuild-std-features=compiler-builtins-mem	Include memcpy, memset, memcmp intrinsics
--release	Enable optimizations, strip debug info
--target x86_64-nonos.json	Use custom bare-metal target

---

Custom Target Specification

The kernel uses x86_64-nonos.json, a custom target that defines:

{
  "llvm-target": "x86_64-unknown-none-elf",
  "data-layout": "e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-f80:128-n8:16:32:64-S128",
  "arch": "x86_64",
  "os": "none",
  "executables": true,
  "linker-flavor": "ld.lld",
  "linker": "rust-lld",
  "panic-strategy": "abort",
  "disable-redzone": true,
  "features": "-mmx,-sse,+soft-float"
}

Key decisions:

• No red zone | Required for interrupt handlers

• Software float | No SSE/MMX in kernel context

• Abort on panic | No unwinding in bare-metal

---

Build Process

1. Cargo Compilation

Cargo compiles all Rust code using the nightly toolchain with build-std to generate a freestanding binary.

2. PQClean Integration

The build.rs script compiles post-quantum cryptography from PQClean:

• ML-KEM-768 | Key encapsulation (FIPS 203)

• ML-DSA-65 | Digital signatures (FIPS 204)

These are compiled as static libraries and linked into the kernel.

3. Manifest Generation

build.rs generates a manifest embedded in the .nonos.manifest section:

NonOsManifest {
    magic: 0x534F4E4F4E,      // "NONOS"
    version: 1,
    kernel_version: "1.0.0",
    capabilities: CAPABILITY_FLAGS,
    timestamp: BUILD_TIME,
}

4. Signing

The kernel is signed with Ed25519:

1. Compute BLAKE3 hash of kernel binary (excluding signature section)

2. Sign hash with private key from SIGNING_KEY environment variable

3. Embed 64-byte signature in .nonos.sig section

---

Output Binary

Property	Value
Format	ELF64 x86_64
Size	~221 KB (stripped)
Load Address	0x100000 (1 MB)
Entry Point	kernel_main
Sections	.text, .rodata, .data, .bss, .nonos.manifest, .nonos.sig

---

Platform-Specific Configuration

macOS

The Makefile sets SDK paths for cross-compilation:

SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
AR=/Library/Developer/CommandLineTools/usr/bin/ar
CC=/Library/Developer/CommandLineTools/usr/bin/clang

Linux

No additional configuration required. Ensure build-essential is installed.

---

Signing Key Management

Scenario	Key Source
Development	Auto-generated dev_signing_key.bin
CI/CD	SIGNING_KEY environment variable
Production	Hardware security module or secure key storage

For production key generation, see Key Generation.

---

Verification

Verify the build succeeded:

# Check binary exists and size
ls -lh target/x86_64-nonos/release/nonos-kernel

# Inspect sections
objdump -h target/x86_64-nonos/release/nonos-kernel

# View symbols
nm target/x86_64-nonos/release/nonos-kernel | grep kernel_main

---

Troubleshooting

Error	Solution
requires nightly	rustup default nightly
can't find crate for core	rustup component add rust-src
linker not found	rustup component add llvm-tools-preview
macOS linker errors	xcode-select --install

---

Next

• Building the Bootloader | Compile the UEFI bootloader

• Running in QEMU | Test your build

• Symbols & Debugging | Debug with GDB