Documentation

01 — BEFORE YOU BEGIN

Build requirements

Both architecture targets use the same C source, with separate assembly entry points and linker scripts. You will need:

• GNU Make
• GCC with 32-bit compilation support
• GNU binutils with i386 and x86-64 ELF linkers
• NASM
• For the ISO, curl and xorriso; add zip and sha256sum for the ZIP archive

02 — BUILD BY HOST OPERATING SYSTEM

Step-by-step build guides

Choose the instructions for the computer you are building on. Linux distributions have separate package-manager steps; Windows uses WSL 2, and macOS uses a disposable Linux VM. The optional ISO build requires xorriso and downloads a pinned Limine release with checksum verification.

• All build guides and safety notes
• Ubuntu and Debian Linux
• Fedora Linux
• Arch Linux
• Windows 10/11 with WSL 2
• macOS with an Ubuntu VM

03 — INSTALLER AND PARTITION SAFETY

No disk installer is available

The 1.2.1.067 AASH nightly cannot install Choc-OS or modify a disk. Keyboard input, disk drivers, and filesystem support are not implemented. Do not partition, format, or attach a physical disk to this image, including from a virtual machine.

Linux distributions listed in the build guides are host environments for compiling akernel, not guest operating systems that akernel can install. The requested Choc-OS installer and Linux guest installer are not implemented.

The proposed first Choc-OS layout is UEFI with a GPT partition table and a FAT32 EFI System Partition (ESP) containing the boot files. It has no separate root or data filesystem, and this layout is not yet implemented or validated. It is not an instruction to repartition a computer.

A future installer must identify its target explicitly, refuse disks with existing partitions or unrecognized contents, and be tested against disposable blank QEMU disks before any physical-disk support is considered. Until a release explicitly says otherwise, assume every disk-writing action is unsupported and unsafe.

06 — THE SOURCE

Project layout

The Limine ISO target is separate from the legacy entry points: it uses the Limine protocol, requests an RGB framebuffer, displays the system-information screen, and runs the AASH nightly setup preview. The 32-bit and standard 64-bit ELF targets remain loader-dependent.

07 — PACKAGE STATUS

Packages in this version

The current package code is metadata and interface scaffolding. It is not an installer, package repository, or complete runtime service. The fetch renderer is included in the opt-in Limine boot target; package sources are not part of the default make targets.

Both sample package descriptors require kernel 1.1.0 or newer, freestanding ELF builds, and a supported x86 architecture. These checks do not install or execute packages.

See the package guide for archive verification and experimental descriptor examples, or the OS manual for a VM-first development path.

08 — CONTRIBUTE

Make a contribution

1. 01

   Fork the repository and clone your fork.

2. 02

   Create a focused branch, make your changes, and run make.

3. 03

   Commit the files you changed and push your branch to your fork.

4. 04

   Open a pull request against oysterzarskyy/akernel.

git switch -c my-change
make
git add path/to/changed-files
git commit -m "Describe the change"
git push -u origin my-change

09 — PUBLISH

Version 1.2.1 "Slim Jims"

The stable source snapshot and artifact manifest are in the 1.2.1 version record ↗, with binaries in the stable v1.2.1 release ↗. The current experimental 1.2.1.067 AASH nightly prerelease ↗ adds colored ASCII output and a built-in setup preflight, but is not an installer. Find its notes in the nightly version record ↗. Previous records remain available in the 1.2.0nr archive ↗ and the v1.2 beta archive ↗.

See the version 1.2.1 ISO downloads page for current availability and local build instructions, or try the browser loader demo for a simulated preview.

This remains a versioned kernel scaffold, not a complete installable operating system. Clearly label any ISO shared for testing as a VM-test image.

make CC=gcc iso-zip
make test-aash
unzip -t build/akernel-v1.2.1.067-x86_64.zip
sha256sum -c build/akernel-v1.2.1.067-x86_64.zip.sha256

GitHub Actions builds and publishes the static forum and handbook to GitHub Pages using .github/workflows/pages.yml. Set Settings → Pages → Build and deployment → Source to GitHub Actions. The forum API must be hosted separately; see the API setup notes below.

10 — COMMUNITY

Forum API and anonymous accounts

The forum front end is connected to the JSON API in api/server.py. The API assigns a persistent anonymous guest identity using a long-lived HttpOnly cookie. The cookie is not readable by page scripts; the browser sends it automatically with requests. Clearing browser cookies loses access to that anonymous identity, so this is not a recoverable registered account.

GitHub Pages serves static files and cannot run the Python API process. Host the API separately or put it behind a same-origin reverse proxy, then set the akernel-api-base meta value in web/index.html to the API prefix (for example, https://api.example.com/api).

python api/server.py
# Open http://127.0.0.1:8787

For a separately hosted site, configure AKERNEL_ALLOWED_ORIGIN to the exact website origin. Cross-site cookies require HTTPS and these settings:

AKERNEL_ALLOWED_ORIGIN=https://your-site.example
AKERNEL_COOKIE_SAMESITE=None
AKERNEL_COOKIE_SECURE=1

The API currently supports anonymous sessions, listing/filtering discussions, creating discussions, reading a discussion with replies, and posting replies. Data is stored in SQLite at api/forum.sqlite3 by default. Back up this database and put the service behind a production HTTPS reverse proxy before exposing it publicly.