# Building the Kernel

***

### 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

```bash
make kernel
```

Or build everything at once:

```bash
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:

```json
{
  "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:

```rust
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:

```bash
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:

```bash
# 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