Project goals
Status: I (FreakySneaky787, the author of YAK) decided the direction on 2026-10-26 (learning platform, see "Direction" and
docs/ROADMAP.md); I released 1.0.0 on 2026-10-27 against the criteria below (the outside reader of "Understanding" was not yet found – I decided not to wait for it; it stays open for 1.0.x). 1.1.0 (2026-11-06) adds the course chapters 1–20; the kernel itself is the one of 1.0.0. Changes to this file need my agreement.
Name
YAK – Yet Another Kernel. (My decision of 2026-10-26, replacing the earlier working name KernelTry; it matches
the repository name yak-kernel.)
Purpose
YAK is a self-contained operating system for studying how a modern operating system kernel is built and works, hands-on, and for developing it further. It runs in QEMU (BIOS and UEFI).
Audience
Primarily self-learners and hobby kernel developers (my decision of 2026-10-26); computer science students and anyone interested in operating system architecture are welcome too.
Direction (1–2 years)
YAK becomes a learning platform: an English course on its own website in which learners rebuild the
kernel chapter by chapter, each chapter a runnable, tested state on its own branch. The kernel in main stays the
reference implementation. New kernel features are added only when they carry a chapter. Details: docs/ROADMAP.md.
What makes it different
- Understandable documentation – every subsystem is explained (
docs/LEARN.md), every design decision has a reason (docs/DESIGN.md), every bug has a story (docs/BUGS.md). - Traceable kernel paths – walkthroughs that follow one action (a key press, a syscall, a page fault, a pipe) through the code, with file references.
- Reproducible tests – one command (
make check) runs unit tests, test kernels and end-to-end shell sessions under BIOS and UEFI; the suite also runs with 1–4 CPUs and without modern CPU features. - Room to experiment – guided experiments ("change X, expect Y") and short guides for extending the system (a new syscall, a new program, a new test).
Honest scope: YAK implements the concepts of modern kernels (x86-64 long mode, SMP, APIC, UEFI, SMEP/SMAP,
XSAVE, TCP) in simplified form. It is not POSIX-compatible and has no fork/exec, mmap or virtual file system.
First release (1.0)
A reliable, text-based x86-64 operating system with
- a shell (
/bin/sh: pipes, redirection, scripts, control flow, jobs), - a persistent file system (FAT32 on a SATA disk),
- isolated user programs (ring 3, one address space per process),
- multitasking (preemptive SMP scheduler, threads, signals),
- networking (e1000, IPv4, UDP, TCP, DHCP, DNS, HTTP client and server).
All of these exist as of stage 7 (M38). Release 1.0 is therefore about reliability, documentation and the
experience of a first-time reader, not about new features. Stage 8 in docs/PROGRESS.md turns this into milestones.
Release criteria (definition of done)
| Area | Criterion |
|---|---|
| Entry point | README.md explains what YAK is, shows a screenshot, lists host packages and gets a new reader from clone to a running shell |
| Legal | LICENSE (GNU GPL v3 or later, chosen by me on 2026-10-26, replacing ECPL v1.2) applies to the whole repository except third-party assets |
| Reproducibility | the Rust toolchain is pinned; a dependency check names missing host tools; make check passes on a fresh Fedora and Ubuntu host (checked by CI on every push, M47) |
| Reliability | make check passes N times in a row (N agreed in stage 8) with 1, 2 and 4 CPUs and with KERNEL_CPU=qemu64; a soak test runs for a fixed time without failure; every syscall rejects invalid arguments without crashing the kernel |
| Known limits | every open item is either fixed or listed as a documented limitation |
| Understanding | at least three end-to-end walkthroughs with file references |
| Experimenting | at least three guided experiments with an expected result, and guides for adding a syscall, a program and a test |
Not goals of the first version
- replacing Linux or being POSIX-compatible,
- a full desktop / graphical user interface,
- supporting as much real hardware as possible (QEMU is the reference machine),
- performance competitive with production kernels,
- becoming the base of a desktop operating system – YAK is a kernel to learn from; features that do not carry a chapter of the course are not added.
Working rules that follow from the goals
- New features must come with a test and a
LEARN.mdsection – an unexplained feature does not serve the purpose. - Prefer clear code over clever code; when a simplification is made, say so in
DESIGN.md. - Third-party crates stay limited to
limineandspin(from scratch is part of the point).