ONCRIX
Home / Docs

Documentation & getting started

Build ONCRIX from source, run it in QEMU, find your way around the ten-crate workspace, and learn how to contribute.

Before you start

Prerequisites

ONCRIX is built with a nightly Rust toolchain and runs on bare-metal targets, so you need the right components, the bare-metal target, and an emulator to run it.

You will need:

  • Rust nightly — edition 2024, rust-version 1.85. The kernel is #![no_std] #![no_main] and uses inline assembly for architecture-specific code.
  • Toolchain components — rustfmt, clippy, rust-src (needed to build core/alloc for a bare-metal target) and llvm-tools.
  • The bare-metal target — x86_64-unknown-none, the primary build target.
  • QEMU — to boot the resulting kernel image. (aarch64 is a secondary target and riscv64 a tertiary one.)
Install the toolchain and target
# nightly toolchain with the components ONCRIX needs
$ rustup toolchain install nightly --component rustfmt,clippy,rust-src,llvm-tools

# add the primary bare-metal build target
$ rustup target add x86_64-unknown-none

Get the source

Clone & build

Clone the repository and build the whole workspace. Kernel-space crates depend only on core and alloc, so the dependency surface stays small.

Clone and build the workspace
# clone the repository
$ git clone https://github.com/kernalix7/oncrix
$ cd oncrix

# build every crate in the workspace
$ cargo build --workspace

Quality gate

Verify

ONCRIX enforces a zero-warning policy. Formatting, lints, and the build all have to be clean before changes land — run all three with one line.

Format check, lint, and build
$ cargo fmt --all -- --check ; \
  cargo clippy --workspace -- -D warnings ; \
  cargo build --workspace

The cargo clippy --workspace -- -D warnings step is the heart of the zero-warning policy: any clippy warning is promoted to a hard error, so the workspace must lint perfectly clean. cargo fmt --all -- --check verifies formatting without rewriting files, and the final build confirms every crate still compiles. This same one-liner runs locally as the pre-commit check and again in CI.

Boot it

Run in QEMU

The kernel builds for x86_64-unknown-none and boots to userspace under emulation — the same path CI exercises on every change.

ONCRIX is a microkernel: the kernel keeps only scheduling, memory management, and IPC, while drivers, filesystems, and services run as user-space processes. Building for x86_64-unknown-none produces a bare-metal kernel image that QEMU can boot. CI includes a QEMU boot integration test that validates the kernel boots all the way to userspace, so a green pipeline means the system actually starts, not just that it compiles.

Running locally. The exact QEMU invocation (machine type, image path, and flags) lives in the repository and can change as the boot protocol evolves. Rather than copy a command that may drift, see the repository README and the scripts/ directory for the current, authoritative run command.

Find your way around

Project layout

The workspace is split into ten focused crates. Architecture-specific code stays behind the HAL, and kernel-space crates depend only on core and alloc.

CrateDirectoryRole
kernelcrates/kernel/Microkernel core — scheduler, IPC, memory core
mmcrates/mm/Virtual memory and the page allocator
vfscrates/vfs/Virtual filesystem layer
processcrates/process/Process and thread management
ipccrates/ipc/Channels, shared memory, message queues
syscallcrates/syscall/POSIX-compatible system call interface
halcrates/hal/Hardware abstraction layer
driverscrates/drivers/User-space device drivers
bootloadercrates/bootloader/Boot protocol and early initialization
libcrates/lib/Shared libraries and common utilities

Project documentation lives in the docs/ tree, organized in a Linux-style structure with subfolders for each audience — see the reference links below.

Go deeper

Reference documentation

The docs/ tree on GitHub is grouped by audience. Start with whichever matches what you are building.

  • admin-guide — operating and administering an ONCRIX system.
  • arch — architecture and design of the microkernel and its subsystems.
  • core-api — the kernel and core-service programming interfaces.
  • driver-api — writing user-space device drivers against the HAL and IPC.
  • filesystems — the VFS layer and filesystem implementations.

You can also browse the whole tree at github.com/kernalix7/oncrix/tree/main/docs.

Send a patch

Contributing

Contributions follow a small set of conventions so history stays readable and main stays green.

Commit messages use Conventional Commits — prefix each subject with feat:, fix:, docs:, refactor:, test:, or chore:.

Branches are named by intent: feature/<name> for new work and fix/<name> for fixes. Pull requests are squash-merged into main, which is kept always-stable and passing CI.

Before you commit, run the same checks CI runs:

  • cargo fmt --all -- --check — formatting is clean.
  • cargo clippy --workspace -- -D warnings — zero clippy warnings.
  • cargo build --workspace — every crate builds.

A few engineering rules apply throughout the codebase: kernel-space crates depend only on core and alloc; every unsafe block is wrapped in a safe abstraction with a documented // SAFETY: invariant; production paths use Result<T, E> with ? rather than unwrap() or expect(); and every source file carries the Apache-2.0 license header.

Get the source on GitHub ↗ Read the architecture →