helix.toml Reference
Complete configuration schema, build profiles, Cargo workspace layout, and the 12-step build pipeline.
Documentation
Configuration Schema
Every Helix kernel profile is configured through a helix.toml file. The only profile with a helix.toml today is profiles/minimal/. This is the actual file from the repository:
profiles/minimal/helix.toml
toml
1
[profile]
2
name = "minimal"
3
version = "1.0.0"
4
description = "Minimal OS for embedded systems"
5
target = "embedded"
6
7
[profile.arch]
8
primary = "x86_64"
9
supported = ["x86_64", "aarch64", "riscv64"]
10
11
[profile.features]
12
multicore = false
13
hot_reload = false
14
userspace = false
15
networking = false
16
filesystem = false
17
graphics = false
18
19
[memory]
20
min_ram_mb = 4
21
max_ram_mb = 64
22
heap_size_kb = 256
23
stack_size_kb = 16
24
virtual_memory = false
25
26
[scheduler]
27
module = "round_robin"
28
time_slice_ms = 10
29
priority_levels = 8
30
load_balancing = false
31
32
[console]
33
backend = "serial"
34
baud_rate = 115200
35
early_console = true
36
37
[modules]
38
static = ["helix-scheduler-round-robin"]
39
dynamic = []
40
41
[boot]
42
entry = "kernel_main"
43
early_init = ["console", "memory", "interrupts"]
44
late_init = ["scheduler"]
45
cmdline = "quiet loglevel=3"
46
47
[debug]
48
level = "minimal"
49
symbols = false
50
stack_traces = true
51
panic_behavior = "halt"
52
53
[build]
54
opt_level = "s"
55
lto = true
56
panic = "abort"
57
strip = true
Options Reference
| Section | Key | Type | Default | Description |
|---|---|---|---|---|
profile | name | String | — | Profile identifier |
profile | target | String | "embedded" | Target use-case |
profile.arch | primary | String | "x86_64" | Primary target architecture |
profile.arch | supported | Array | ["x86_64"] | All supported architectures |
profile.features | multicore | Bool | false | Enable SMP support |
profile.features | hot_reload | Bool | false | Enable runtime module swap |
profile.features | userspace | Bool | false | Enable ring-3 transition |
memory | heap_size_kb | Integer | 256 | Kernel heap in KB |
memory | stack_size_kb | Integer | 16 | Per-thread stack in KB |
memory | virtual_memory | Bool | false | Enable paging |
scheduler | module | String | "round_robin" | Scheduler implementation |
scheduler | time_slice_ms | Integer | 10 | Default time quantum |
console | backend | String | "serial" | Output backend |
console | baud_rate | Integer | 115200 | Serial baud rate |
boot | entry | String | "kernel_main" | Kernel entry function name |
debug | panic_behavior | String | "halt" | "halt" · "reboot" · "dump" |
build | opt_level | String | "s" | "0" · "1" · "2" · "3" · "s" · "z" |
build | lto | Bool | true | Link-Time Optimization |
build | strip | Bool | true | Strip debug symbols |
Profiles Directory
There are 4 profile directories in the repository:
| Directory | Purpose | Contents |
|---|---|---|
profiles/minimal/ | The only runnable kernel profile | helix.toml, linker.ld, linker_pie.ld, src/ (main.rs, boot.rs, framebuffer.rs, filesystem.rs, nexus.rs) |
profiles/limine/ | Limine-specific linker script | linker.ld (352 lines, PIE + KASLR + HHDM) |
profiles/uefi/ | UEFI-specific linker script | linker.ld (339 lines, PIE + RELRO) |
profiles/common/ | Shared base linker script | linker_base.ld (350 lines, included by others) |
Cargo Workspace
The root Cargo.toml defines the workspace with 14 member crates:
Cargo.toml (workspace root)
toml
1
[workspace]
2
resolver = "2"
3
4
members = [
5
# Boot Infrastructure
6
"boot/multiboot2",
7
"boot/limine",
8
"boot/uefi",
9
10
# Hardware Abstraction Layer
11
"hal",
12
13
# Kernel Core
14
"core",
15
16
# Subsystems
17
"subsystems/execution",
18
"subsystems/memory",
19
"subsystems/dis",
20
"subsystems/userspace",
21
"subsystems/relocation",
22
"subsystems/nexus",
23
24
# Module System
25
"modules",
26
27
# Module Implementations
28
"modules_impl/schedulers/round_robin",
29
30
# Benchmarks
31
"benchmarks",
32
33
# Filesystem
34
"fs",
35
36
# OS Profiles (only minimal is runnable)
37
"profiles/minimal",
38
]
39
40
[workspace.dependencies]
41
helix-hal = { path = "hal" }
42
helix-core = { path = "core" }
43
helix-execution = { path = "subsystems/execution" }
44
helix-memory = { path = "subsystems/memory" }
45
helix-userspace = { path = "subsystems/userspace" }
46
helix-modules = { path = "modules" }
47
helix-benchmarks = { path = "benchmarks" }
48
spin = "0.9"
49
bitflags = "2.4"
50
log = "0.4"
51
hashbrown = "0.14"
52
static_assertions = "1.1"
53
cfg-if = "1.0"
54
55
[workspace.package]
56
version = "0.1.0"
57
authors = ["Helix OS Contributors"]
58
edition = "2021"
59
license = "MIT OR Apache-2.0"
60
repository = "https://github.com/helix-os/helix"
Build Profiles
Cargo.toml (build profiles)
toml
1
[profile.dev]
2
panic = "abort"
3
opt-level = 0
4
debug = true
5
lto = false
6
codegen-units = 256
7
8
[profile.release]
9
panic = "abort"
10
opt-level = 3
11
lto = "fat"
12
codegen-units = 1
13
strip = "symbols"
14
15
[profile.release-with-debug]
16
inherits = "release"
17
debug = true
18
strip = "none"
19
20
[profile.production]
21
inherits = "release"
22
lto = "fat"
23
codegen-units = 1
Toolchain
rust-toolchain.toml
toml
1
[toolchain]
2
channel = "nightly-2025-01-15"
3
4
components = [
5
"rust-src", # Required for -Zbuild-std
6
"rustfmt", # Code formatting
7
"clippy", # Linting
8
"llvm-tools-preview", # objcopy, objdump, size
9
]
10
11
targets = [
12
"x86_64-unknown-none", # Primary: x86_64 bare metal
13
"aarch64-unknown-none", # Future: ARM64
14
"riscv64gc-unknown-none-elf", # Future: RISC-V
15
"x86_64-unknown-linux-gnu", # Host: tests & tools
16
]
Build Commands
The build system uses a 12-step LFS-inspired pipeline orchestrated by scripts/build.sh.
terminal
bash
1
# Build the kernel (release, 12-step pipeline)
2
./scripts/build.sh
3
4
# Build with debug symbols (DWARF info)
5
./scripts/build.sh --debug
6
7
# Create bootable ISO
8
./scripts/build.sh --iso
9
10
# Run in QEMU (builds first)
11
./scripts/run_qemu.sh
12
13
# Run with GDB debug server
14
./scripts/run_qemu.sh --debug
15
16
# Run all tests
17
./scripts/test.sh
18
19
# Unit tests only (host target)
20
cargo test --target x86_64-unknown-linux-gnu --lib
21
22
# Format + lint
23
cargo fmt --all
24
cargo clippy --all-targets --all-features -- -D warnings
25
26
# Generate documentation
27
cargo doc --no-deps --document-private-items
28
29
# Show kernel binary size
30
size build/output/helix-kernel
The 12 build steps:
| Step | Name | Description |
|---|---|---|
| 0 | Prepare Environment | Validate toolchain, create build dirs |
| 1 | Build Bootloader | Compile boot protocol crate |
| 2 | Build Kernel Core | Compile helix-core |
| 3 | Build Memory Subsystem | Compile helix-memory |
| 4 | Build Scheduler | Compile helix-execution + DIS |
| 5 | Build I/O Subsystem | Compile drivers and I/O |
| 6 | Build Module System | Compile helix-modules |
| 7 | Build Communication Layer | Compile IPC + syscalls |
| 8 | Build System Interface | Compile helix-userspace |
| 9 | Build Userland Framework | Compile userspace tools + shell |
| 10 | Test All | Run cargo test on host target |
| 11 | Package Kernel | Link final ELF, strip, create ISO |