Manual on how to make an Akernel OS

01 — DEFINE A SMALL FIRST GOAL

Choose what your OS should do

Start with one testable feature instead of trying to build every operating-system subsystem at once. For example: improve the boot screen, add a serial log, handle a timer interrupt, or read a simple read-only filesystem in a virtual machine.

• Target the existing x86-64 Limine boot path first.
• Write down the expected input, output, and failure behavior for the feature.
• Keep hardware experiments inside an isolated VM and take snapshots before risky tests.
• Do not treat an ELF kernel or test ISO as installable on physical hardware.

INSTALLATION SAFETY

Choc-OS installer status and planned partitions

There is no installer in the current nightly. The kernel cannot accept keyboard input, access disks, create partitions, or write a filesystem. Linux in the build guides means a host used to compile akernel; it is not a Linux guest OS that Choc-OS can install. Do not use this image to install an OS, and do not attach a physical or non-disposable disk to a VM running it.

The proposed first install layout is UEFI boot on GPT with one FAT32 EFI System Partition (ESP) for boot files. No separate root or data filesystem is planned for that first milestone. This is only a design note: the layout has not been implemented or tested, and users must not create or format these partitions based on this page.

Any future installer must stop if it finds existing partitions or contents it cannot identify, require an explicit target selection, and pass disposable-VM tests before release. Do not assume a disk is safe to erase merely because it appears empty in a partitioning tool.

02 — BUILD A KNOWN-GOOD BASELINE

Compile and boot the current scaffold

On Ubuntu or Debian, install the GCC, assembly, ISO, and VM tools:

sudo apt update
sudo apt install -y build-essential gcc-multilib binutils nasm git curl xorriso zip unzip qemu-system-x86
git clone https://github.com/oysterzarskyy/akernel.git
cd akernel
make CC=gcc
make CC=gcc iso-zip
make test-aash
make run-qemu

Record the Git commit, GCC version, and build output. The generated nightly ISO is build/akernel-v1.2.1.067-x86_64.iso; its compressed copy and checksum sit beside it. make run-qemu opens a VM window that stays open after the demo kernel halts; close the window to stop it. The guest has no interactive input yet. See the Ubuntu build guide for detailed prerequisites.

03 — ADD ONE SUBSYSTEM AT A TIME

Keep boot, architecture, and drivers separated

1. 01

   Keep architecture-specific entry code and linker scripts under kernel/arch/. Preserve the boot protocol handoff contract when changing kernel startup.

2. 02

   Put reusable C implementations under kernel/src/ and their public interfaces under kernel/include/akernel/.

3. 03

   Keep output behind a console interface so a later serial or terminal driver can replace the current framebuffer writer. Its built-in 5x7 font covers Latin letters, digits, and common punctuation; add or replace glyph tables in kernel/src/console/framebuffer.c when extending character coverage.

4. 04

   Introduce interrupts, memory management, device drivers, and scheduling as separate milestones, each with its own tests and failure handling.

5. 05

   Do not enable interrupts or access hardware before the required tables, handlers, and device state are initialized.

Kernel packages are currently metadata only. The package guide explains the descriptor fields and the separate ISO/ZIP distribution workflow. AASH is an experimental built-in script interpreter, not userspace; see the AASH guide.

04 — TEST, DOCUMENT, RELEASE

Make changes reproducible

• Build the legacy ELF checks and the Limine ISO after code changes.
• Boot the ISO in QEMU with no physical disk attached and test the feature's expected and failure paths.
• Keep a short record of tested compiler, emulator, architecture, and boot mode.
• Package the ISO with make iso-zip; verify its ZIP and checksum before sharing.
• Describe the image as an experimental VM test build, not as a complete or installable OS.

Before publishing your fork, review licenses for included code and bootloader binaries, document known limitations, and attach source revision information to each artifact. A checksum detects accidental corruption; it does not by itself prove who published a file.