kdos

The KDOS Book

A complete description of KDOS: what it is, how to install and run it, how it works from firmware handoff to the panel clock, how it is built from source, and how to extend it. This page is the book’s front matter: a preface, reading paths for four kinds of reader, and the full table of contents. Every chapter it lists describes the system as it is in this source tree.

Preface

KDOS is a Linux distribution for x86_64 machines, compiled in this repository from upstream source with a musl C library, no systemd and no Xorg server. Its desktop is its own, every surface of it drawn as a grid of character cells with no GUI toolkit under it. The graphical applications people expect are ported natively on top of it, each with the toolkit it is written in (GTK, Qt, KDE Frameworks, wxWidgets, FLTK or Tk), or run beside it in containers called boxes.

The book is written for people: anyone deciding whether to try KDOS, installing it, looking after a machine that runs it, or building and changing it. It assumes a working knowledge of Linux (a shell, files and permissions, what a kernel, a boot loader and a package manager are) and nothing about KDOS itself. The chapters for developers also assume that you can read C and shell, and that you have compiled a program from source before.

The book moves from a bird’s-eye view to depth. Part I says what KDOS is, how it differs from other distributions and why it chose differently. Part II uses the system as a person sitting at it would. Part III opens the running system and explains each mechanism, starting with a map of the whole. Part IV documents, one chapter each, the programs KDOS writes itself. Part V turns to the build: it tells the story of a build from git clone to a bootable image once, then documents each part of the build machinery, the recipe format, the libraries and the test harnesses. Part VI is reference: lookup tables, statements of state and the glossary.

Each chapter opens with a paragraph that says what it covers, who it is for and what to read first, and closes with a See also list. Within a chapter the order runs from concept to mechanism to detail, so a reader can stop at the depth they need. The conventions the book follows are listed under Conventions below.

How to read this book

Four paths through the book, depending on why you are here. Each names its chapters in the order that suits that job; the numbers are the chapter numbers in the Contents.

Understanding the whole system

For a newcomer who wants to go from what KDOS is to how every part of it works, read the book front to back. The shortest route that still covers the whole system is:

Ch 1, Why KDOS, and ch 2, How KDOS differs
Ch 3, Principles, and ch 4, Decisions
Ch 7, The desktop, and ch 8, Applications
Ch 12, Architecture overview, then chapters 13 to 19 in order
Ch 20, The programs, and any program chapter that interests you
Ch 30, How KDOS is built
Ch 44, Status, and ch 43, Known gaps

Installing and using KDOS

For someone who wants an image on hardware and a working desktop:

Ch 1, Why KDOS: what the system is and what it deliberately lacks
Ch 5, Getting started: build an image, write a medium, boot it
Ch 6, Installation: the installer, page by page
Ch 7, The desktop: panel, menus, windows and keyboard shortcuts
Ch 8, Applications: which applications are native, and the catalogue and boxes for the rest
Ch 9, Theming, and ch 11, Accessibility
Ch 43, Known gaps: what does not exist, before you depend on it

Administering a KDOS machine

For the person who looks after an installed machine: services, hardware, updates and diagnosis.

Ch 10, Administration: the tasks, each as a command or a file
Ch 28, The kdos command: status, doctor and the other subcommands
Ch 13, Boot and init: which program owns each step of a boot
Ch 15, Packaging: what kpkg does, the binary host and updates
Ch 16, Packs and boxes: what installing an application does
Ch 17, The security model: what is protected, and what is not
Ch 26, The daemons: the root daemons and what each allows
Ch 40, Configuration, and ch 41, Filesystem and IPC

Building and extending KDOS

For a developer who builds the distribution, adds or changes a port, or writes desktop software:

Ch 3, Principles: the rules every change is judged against
Ch 12, Architecture overview: how the pieces fit together
Ch 30, How KDOS is built: the build as one story
Ch 31, Developing: the first build, and the loops that avoid one
Ch 32, The build system: phases, the chroot, snapshots, build plans
Ch 33, Writing ports, and ch 34, Build troubleshooting
Ch 35, The C libraries, and ch 18, The design language
Ch 36, Writing desktop software: drawing a KDOS surface
Ch 37, Testing: what each harness proves, and what it cannot
Ch 42, Repository layout, and ch 38, The ports catalogue

Forty-five chapters in six parts.

Part I — Introduction

What KDOS is and who it is for, how it compares with the ways other distributions solve the same problems, the rules every part of it is built to, and the close choices argued in full. These chapters stay at the level of ideas and link to the chapters that describe each mechanism.

Why KDOS: what KDOS is, the four properties that define it, who should run it, the trade you accept, what is deliberately absent, and what is not built from source
How KDOS differs: KDOS compared point by point with other distributions: the C library, the userland, init, the display stack, packages, reproducibility, applications, updates and hardware support
Principles: the rules that constrain every change, each with the failure it prevents and the price it charges
Decisions: the choices where an alternative was reasonable (the compositor fork, native applications beside the catalogue, packs, musl, the source archive, -march and more), and why the alternative lost

Part II — Using KDOS

Getting a machine running and living on it: building and booting an image, installing it, the desktop, applications, the look of the system, administration and accessibility. These chapters are written for the person at the keyboard and name the file behind each behaviour.

Getting started: from a clone to a running desktop: building an image, trying it in a virtual machine, writing a medium, booting, logging in, keeping a live session’s changes, and installing
Installation: the installer page by page, the root filesystem, encryption, A/B root slots, unattended installs and every file the installer writes
The desktop: the panel, the Start menu, windows, keyboard shortcuts, notifications, files, the clipboard, locking, displays and removable media
Applications: which applications are ported natively, then finding, installing, launching, updating and removing boxed applications, carrying a set to another machine, and managing boxes
Theming: the eight accents, fonts, the phosphor pass, wallpaper, the boot menu and consoles, and theming inside a box
Administration: services, users, storage, networking, the firewall, hardware, updates and diagnosis, then each user’s backups, mail, passwords and input methods
Accessibility: braille and speech at a text console, the magnifier, larger text, a boxed application’s own assistive stack, and what the desktop does not expose

Part III — Architecture

How the running system is put together, from a map of the whole to each mechanism in turn: the boot path, the session, host packaging, packs and boxes, security, the visual specification and the window model. The overview comes first because every later chapter in the part expands one region of it.

Architecture overview: the three rings, power-on to a drawn window, the host and a box, a running process map, the root daemons, the two packaging systems and where state lives
Boot and init: Limine, microcode, the initramfs and its splash, A/B slot selection, unlocking an encrypted root, rcS, the console and the login
The session: what a login starts: the session bus, audio, portals, the supervised chrome, capture, the clipboard, input methods and a box’s environment
Packaging: the ports tree, its shelves and its phases, where sources come from, kpkg, what a build verifies, reproducible packages, the binary host, deltas and vulnerability tracking
Packs and boxes: the two lanes, the catalogue, the pack format, installing and mounting, composition, the box, grafts and data packs
The security model: setuid binaries, system accounts, root daemons, the firewall, polkit, containers, signing, untrusted bytes, and what is not protected
The design language: the character grid as a specification: the frame, chrome, shared keys, colour, the pointer contract, touch, glyph tiers and pictures
The window model: the rules libkwm keeps with the compositor: focus, tiling, placement, windows that belong to other windows, the edge search and occupancy

Part IV — Programs

A chapter for each program KDOS writes itself, from the compositor and the panel to the installer and the command-line front door. Software built from upstream ports is documented by its upstream; these chapters cover only what this repository writes.

The programs: every KDOS binary, what it does, and every name it answers to
kdos-comp: the compositor: configuration, bindings, decorations, frame pacing, the phosphor pass, idle and lock, its sockets, box identity and working on its code
kdos-shell: one binary under 55 names and 54 surfaces: the panel, the Start menu, the file chooser, settings, device managers, notifications, the store and the small surfaces
kdos-res: the resource monitor: its eleven pages, keys, acting on a process through kdos-resctl, identity by box, and what it refuses to infer
kdos-term: the terminal: keys, the two clipboards, the paste guard, per-window fonts, hyperlinks, prompt marks, the escape layer and three picture protocols
kdos-appbox: kdos-appbox, kdos-box and xdg-open: the launch path, launcher generation, the open path, box profiles, warmup and storage drivers
The daemons: the five root daemons, the per-box Wayland socket, the portal backend and the lock screen, and how to add a root daemon
kinstall: the installer’s reference: keys, pages, install steps, answer files, dry-run dumps, LVM, encryption, the applications step and its design
The kdos command: the front door to a KDOS machine, every subcommand, and the eleven other names the same binary answers to
kdos-bb: the forked AAlib demo: running it, and what it establishes about frame pacing, synchronized output, timing to music and audio

Part V — Building and developing

How KDOS comes into existence and how to change it. The part opens with the whole build told as one story, then documents the everyday commands, the build orchestrator, the recipe format, the failures that recur, the C libraries, desktop software and the test harnesses.

How KDOS is built: the build as one continuous story, from git clone through fetching, the cross toolchain, the phases and the chroot, to a bootable ISO
Developing: what a development machine needs, the first build, every make target, rebuilding one thing, working without a build, and cutting a release
The build system: the thirteen phases and their package lists, where kpkg looks for a port, the phase environment, the chroot, syncing fs/, the orphan sweep, the packaging steps, snapshots, build plans and kdosbuild
Writing ports: the recipe format, canonical build shapes, a worked example, adding a port end to end, vendoring, checking for new versions and publishing sources
Build troubleshooting: recurring fetch, build and push failures, indexed by the message you see, each with its cause and fix
The C libraries: the seventeen libk* libraries, the dependency direction, and the invariants each one keeps
Writing desktop software: building a KDOS surface: the frame protocol, roles, input, drawing, chrome, pictures, and testing without a screen
Testing: preflight, the self-test, goldens, fixtures, the QEMU rig, checking the sources, docscheck, and what is not tested

Part VI — Reference

Lookup tables and statements of state: every port, command, configuration key, path and socket, the layout of the source tree, what does not exist, how mature each part is, and the vocabulary of the book.

The ports catalogue: every port KDOS can build, by shelf and by src/ area, with the phase that builds it, the libraries shipped as the application-developer platform, and the ports named in more than one list
Command index: every command the tree installs, where it lives and which chapter documents it
Configuration: every configuration file and key, with its default and when a change takes effect
Filesystem and IPC: KDOS-owned paths, every socket and its verbs, files used as an interface, and environment variables
Repository layout: the source tree directory by directory: the port repositories, the shelves of ports/core and the areas of src/, the script/ directory, the library rule, where upstream sources are, and what git ignores
Known gaps: what KDOS does not do, or has not been shown to do, and what to do instead
Status: the maturity of each subsystem and the evidence behind each verdict
Glossary: the vocabulary the book uses, defined once, and the words it avoids

Conventions

Links between chapters are relative, so the book reads the same in a clone, in a pager and on a web forge. Every chapter opens with a paragraph saying what it covers, who it is for and what to read first, and closes with a See also list. Terms carry the meaning the glossary gives them; a chapter defines a term at first use or links the glossary entry.

Commands are shown in fenced code blocks, and paths, keys, flags and program names in code. Tables hold lookup data; prose holds explanation. Where a chapter states a count or a measurement, it says what was counted or measured, and every such number was taken from the tree at the time of writing. The book describes the system as it is: it records no history, and a behaviour that changes changes its page in the same commit.

The KDOS version string appears in three places and nowhere else: the repository README, which names the release line; Status, which says what each subsystem’s maturity rests on; and fs/etc/os-release. A version number anywhere else in the book belongs to an upstream component, not to the system.