Getting Started

Helctic is a multi-personality kernel: a native Rust microkernel core paired with a Zig personality layer that translates foreign OS syscall ABIs (Linux, Windows, Darwin, BSD) into the kernel's internal operations.

This page gets you from a clean checkout to a built kernel image.

Early-stage software

Helctic is under active development. The personality architecture is wired and the build toolchain is modern, but large parts of the syscall surface are still stubbed. See the Introduction for an honest status breakdown before you expect to boot a Linux userspace.

Prerequisites

Tool	Version	Purpose
Rust	nightly (pinned in rust-toolchain.toml)	kernel core, build-std
Zig	0.15+	personality layer + btrfs static libs
nasm	any recent	x86/x86_64 trampoline assembly
binutils	target-specific	objcopy for stripping/symbols
Nix	optional	one-command dev shell via nix develop

The Rust toolchain is provided by rustup (not Nix). The dev shell installs the pinned nightly automatically.

Clone

git clone https://github.com/awfixers-stuff/kernel.git
cd kernel

Enter the dev shell (recommended)

nix develop

This provides Zig, nasm, and rustup, and installs the nightly toolchain with rust-src, clippy, and rustfmt on first entry.

Prefer not to use Nix? Install rustup and Zig yourself; the pinned toolchain in rust-toolchain.toml will be selected automatically.

Build

The kernel uses a custom target spec and build-std:

cargo build \
  --bin kernel \
  --target targets/x86_64-unknown-kernel.json \
  --release \
  -Z build-std=core,alloc \
  -Z json-target-spec

Or use the Makefile, which wires the linker script and produces stripped binaries plus a debug-symbol file:

make ARCH=x86_64

Supported architectures: x86_64, i686, aarch64, riscv64.

Toolchain notes

Recent nightlies require -Zjson-target-spec to use the JSON target specs, and soft-float is expressed in the target spec (rustc-abi: x86-softfloat) rather than the old -C soft-float flag.

Test the personality layer

The Zig personality layer ships its own unit tests (personality enum ↔ C header consistency, ELF/PE/Mach-O detection, flag translation):

cd personality
zig build test

Generate the spec docs

The Specification pages are generated from source by the autodoc tool. To regenerate after editing doc comments:

cd docs
bun run gen:specs

Deploying the docs site

The site is built with VitePress and deployed to Cloudflare Pages from the docs/ directory.

Git integration (recommended): create a Pages project from this repo and set:

Setting	Value
Root directory	docs
Framework preset	VitePress
Build command	bun run docs:build
Build output directory	.vitepress/dist

Then attach the custom domain kernel.awfixer.me. Cloudflare rebuilds on every push to main and gives preview deployments for pull requests.

Direct upload / CI: wrangler.toml sets pages_build_output_dir, so:

cd docs
bun run deploy        # builds, then `wrangler pages deploy`
bun run preview:cf    # serve the built site locally via wrangler

Bun on Cloudflare

Cloudflare detects bun.lock and uses Bun automatically. Pin the version with a BUN_VERSION build environment variable if you need a specific release.

Next steps

• Introduction — what Helctic is and its current status
• Architecture — the Rust ↔ Zig boundary
• Personalities — how foreign ABIs are detected & dispatched
• Specification — source-generated API reference