Getting Started

Prerequisites#

Before building Helix, you need several tools installed on your system. Helix targets bare-metal x86_64 and requires a nightly Rust toolchain with specific components.

Required Tools#

Operating System Support#

Helix development is supported on:

• Linux (Ubuntu 22.04+, Fedora 38+, Arch) — primary development platform
• macOS (with Homebrew) — fully supported, QEMU via brew install qemu
• Windows (WSL2) — use Ubuntu WSL, native Windows not directly supported

Install Rust Nightly#

Helix uses Rust nightly features extensively: allocator_api, naked_functions, abi_x86_interrupt, negative_impls, and more. The exact nightly version is pinned in rust-toolchain.toml.

# Install rustup if you don't have it
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# The rust-toolchain.toml in the repo auto-selects the correct nightly
# Just clone and cargo will handle the rest

The workspace's rust-toolchain.toml specifies:

[toolchain]
channel = "nightly"
components = ["rust-src", "rustfmt", "clippy", "llvm-tools-preview"]
targets = ["x86_64-unknown-none"]

Install System Dependencies#

# Ubuntu / Debian
sudo apt update
sudo apt install -y qemu-system-x86 xorriso mtools grub-pc-bin \
  grub-efi-amd64-bin nasm build-essential curl git

# Fedora
sudo dnf install -y qemu-system-x86 xorriso mtools nasm gcc make curl git

# Arch Linux
sudo pacman -S qemu-system-x86 xorriso mtools nasm base-devel curl git

# macOS (Homebrew)
brew install qemu xorriso nasm

Optional Tools#

---

Installation#

Clone the Repository#

git clone https://github.com/helix-os/helix.git
cd helix

Repository Layout#

The Helix workspace is a Cargo workspace containing 20+ crates:

Verify Your Setup#

# Check Rust nightly is available
rustc --version
# Should show: rustc 1.xx.0-nightly (...)

# Check QEMU
qemu-system-x86_64 --version

# Make build scripts executable
chmod +x scripts/*.sh

Using Docker (Alternative)#

Helix ships with a Dockerfile and docker-compose.yml for reproducible builds:

docker-compose build
docker-compose run helix-dev

Using Nix (Alternative)#

A flake.nix is provided for Nix users:

nix develop

---

Building the Kernel#

Quick Build#

./scripts/build.sh

This compiles the helix-minimal-os profile targeting x86_64-unknown-none, links it into a bootable ELF binary, and places the output at build/output/helix-kernel.

Build with Cargo Directly#

cargo build --package helix-minimal-os \
  --target x86_64-unknown-none --release

Build Variants#

Understanding the Build Pipeline#

1. Cargo compiles the workspace with target x86_64-unknown-none
2. The profiles/minimal/ crate is the binary entry point (kernel_main)
3. It links against helix-core, helix-hal, helix-execution, helix-memory, helix-modules, helix-userspace, helix-fs, helix-relocation, and helix-nexus
4. A custom linker script positions the kernel at the correct virtual address
5. The Limine bootloader protocol provides the initial handoff
6. Output: build/output/helix-kernel (ELF64)

Check Kernel Size#

size build/output/helix-kernel
# Or: objdump -h build/output/helix-kernel

---

Running in QEMU#

Quick Run#

./scripts/run_qemu.sh

Builds the kernel (if needed) and launches QEMU.

Manual QEMU Command#

qemu-system-x86_64 \
  -machine q35 \
  -cpu qemu64 \
  -m 256M \
  -serial stdio \
  -no-reboot \
  -kernel build/output/helix-kernel

QEMU Flags Reference#

Expected Boot Output#

[BOOT] Helix OS v0.1.0 - Minimal Profile
[BOOT] CPU: x86_64, cores: 1
[BOOT] Memory: 256 MiB total
[HEAP] Kernel heap initialized (4 MiB)
[MEM]  Physical memory manager ready
[INT]  IDT installed, interrupts enabled
[SCHED] Round-robin scheduler active
[FS]   HelixFS initialized
[NEXUS] NEXUS AI framework active
[KERN] === Helix Kernel Started ===
helix>

Debug Mode with GDB#

Terminal 1:

./scripts/run_qemu.sh --debug

Terminal 2:

gdb build/output/helix-kernel
(gdb) target remote :1234
(gdb) break kernel_main
(gdb) continue

---

First Modification#

Add a Custom Boot Message#

Open profiles/minimal/src/main.rs and find kernel_main. Add:

The kprintln! macro writes to serial port COM1 — QEMU redirects this to your terminal.

Rebuild and Test#

./scripts/build.sh && ./scripts/run_qemu.sh

Ideas for Further Exploration#

• Change heap size — modify the HEAP_SIZE constant in main.rs (default: 4 MB)
• Add a shell command — implement ShellCommand in subsystems/userspace/src/shell.rs
• Write a kernel module — use the v2 module API (see Module Development docs)
• Enable NEXUS features — toggle feature flags in profiles/minimal/Cargo.toml

---

Project Structure#

Layered Architecture#

Crate Reference#

Configuration Files#

---

Development Workflow#

VS Code Integration#

The repository includes full VS Code support:

• tasks.json — Build, Run QEMU, Tests, Format, Clippy, Docs
• launch.json — GDB debug configurations
• Recommended extensions — rust-analyzer, CodeLLDB

Common Commands#

Testing Strategy#

1. Unit tests — run on host Linux/macOS, test pure logic:

   cargo test --target x86_64-unknown-linux-gnu --lib
   

2. Integration tests — run inside QEMU:

   ./scripts/test.sh
   

Pre-Commit Checks#

make pre-commit
# Runs: fmt check → clippy → unit tests → build

---

Next Steps#

You now have Helix building and running. Continue with:

• Architecture — the modular kernel design philosophy
• Core — kernel orchestrator, IPC, and syscall framework
• Modules — writing hot-reloadable kernel modules
• Subsystems — scheduling, memory management, and DIS