How klange/toaruos works
1. Overall shape
- This repository is the full source tree for ToaruOS: bootloader, kernel, C library, userland libraries, applications, system configuration, and packaging/build tooling.
- It is a self-contained OS rather than an app stack on top of another host OS.
2. Boot path
- boot/ contains the BIOS/EFI loader and menus that select kernel options, load the kernel, and pass the initial ramdisk and boot arguments.
- The bootloader’s job ends once control transfers to the kernel entry points for either x86_64 or aarch64.
3. Kernel core
- kernel/ is the central runtime: process management, memory management, syscall dispatch, VFS, networking, device abstractions, and architecture-specific startup code.
- Architecture code is split under kernel/arch/x86_64 and kernel/arch/aarch64, with separate boot, interrupt, MMU, SMP, and platform support.
4. Kernel subsystems
- Major in-kernel boundaries are sys/ for process/syscall-facing services, vfs/ for filesystem and device-file plumbing, net/ for Ethernet/IP/socket stack, video/ for framebuffer graphics, and audio/ for sound.
- The kernel also hosts loadable drivers in modules/, which plug into hardware support such as storage, network, USB, audio, and filesystems.
5. Device and filesystem model
- User-visible state is exposed through virtual filesystems like /proc, /dev, and pseudo-devices for terminals, pipes, random, and packet exchange.
- Real storage enters through filesystem drivers such as ext2, ISO9660, ramdisk, tmpfs, and tarfs, while runtime configuration and package state live in the staged root filesystem under base/.
6. Userspace ABI boundary
- libc/ provides the C runtime, system call wrappers, startup objects, dynamic loader (dlfcn), pthreads, stdio, math, locale, and other POSIX-ish interfaces.
- This is the key boundary between applications and the kernel: most programs link against libc and talk to the kernel only through syscalls and device files.
7. Shared userland libraries
- lib/ contains higher-level first-party libraries for graphics, widgets, menus, text rendering, compression/image parsing, procfs helpers, line editing, and IPC/windowing support.
- These libraries are used by both CLI and GUI apps, especially anything that draws windows or interacts with the desktop session.
8. Desktop/windowing stack
- The graphical desktop is centered on apps/compositor.c, which is the Yutani compositor/window server.
- Yutani manages window buffers, layout, cursor/input routing, and compositor-side presentation, while clients use lib/yutani.c and related libraries to create and update windows.
9. Session and login flow
- System startup scripts in base/etc/startup.d/ bring up hostname, tmpfs, modules, networking, and then launch the interactive session.
- Login/session programs in apps/ handle console or graphical entry points, and the default desktop/session environment is assembled from the staged home directories and launcher files under base/home/local/Desktop.
10. Applications and utilities
- apps/ is the first-party userland collection: shell, terminal, file browser, package manager, system tools, games, graphics utilities, and many Unix-like command-line tools.
- Several applications are graphical and depend on Yutani; others are terminal utilities that primarily exercise libc, VFS, procfs, and device files.
11. Scripting and extensibility
- Kuroko is used as an embedded dynamic language for various tools and demos, with .krk applications and library integrations under lib/kuroko/.
- Some “applications” are shell scripts or Kuroko scripts in apps/ and base/etc/startup.d/, showing that the runtime supports mixed executable types.
12. Filesystem staging and runtime image
- base/ is not the live OS itself but the staging root used to assemble the bootable image.
- It provides the directory skeleton, config files, default user homes, shared resources, headers, and manpages that are packaged into the ramdisk and ISO image.
13. Build and packaging pipeline
- The top-level Makefile and build/ scripts orchestrate cross-compilation for x86-64 and aarch64, generate dependency metadata, build kernel/libc/libs/apps, and assemble the bootable image.
- util/ contains toolchain, image, and disk-generation helpers; the output path is a ramdisk plus ISO9660 boot image rather than a conventional package repository.
14. Testing and validation
- tests/ contains kernel/userspace validation programs for syscalls, libc behavior, threading, signals, networking, and graphics-related edge cases.
- The GitHub Actions workflows under .github/workflows/ indicate CI builds for both supported architectures, which matters because architecture-specific code paths are substantial.
15. External dependencies and deployment targets
- The project is designed to boot on real hardware, QEMU, and virtualization platforms like VirtualBox/VMware; some drivers and boot behaviors are tuned for those environments.
- Hardware support is mediated through kernel modules and architecture-specific code, while runtime services like networking, display sizing, and absolute mouse support are exposed through the OS’s own drivers and desktop stack.
Main entry points: generic.c Kernel core · Makefile Build system · libc libc · modules Modules
Components 20
Boot path
Firmware/loader code that transfers control into the OS kernel.
- Bootloader · BIOS/EFI loading, kernel selection, boot arguments, and handoff to the kernel.
boot
Kernel
Core privileged runtime, subsystems, and architecture-specific startup code.
- Kernel core · Central kernel runtime for processes, memory, syscalls, and global services.
kernel/generic.c - x86_64 arch · x86_64 bootstrap, interrupts, MMU, SMP, and platform support.
kernel/arch/x86_64 - aarch64 arch · AArch64 bootstrap, interrupts, MMU, SMP, device tree, and board support.
kernel/arch/aarch64 - Syscalls · Process management, signals, ptrace, shared memory, and syscall dispatch.
kernel/sys - VFS · Virtual filesystem, pipes, terminals, procfs, ramdisk, tmpfs, and tarfs plumbing.
kernel/vfs - Network · Ethernet, ARP, IPv4, loopback, and socket handling inside the kernel.
kernel/net - Video · Framebuffer and low-level graphics output from the kernel.
kernel/video - Audio · Kernel audio subsystem and sound device integration.
kernel/audio - Modules · Hardware and filesystem drivers loaded into the kernel at runtime.
modules
Userland
C library, shared libraries, applications, and session tooling.
- libc · C runtime, syscall wrappers, startup objects, dynamic loading, pthreads, and POSIX-ish APIs.
libc - Shared libs · Graphics, text, menus, procfs, line editing, IPC, compression, and widget support for apps.
lib - Compositor · Yutani compositor and desktop presentation manager.
apps/compositor.c - Login & session · Console and graphical login, session launch, and startup coordination.
apps/init.c - Applications · Shell, terminal, file tools, networking utilities, graphics apps, and games.
apps - Scripts · Startup scripts and Kuroko-based tools used for setup, demos, and lightweight applications.
base/etc/startup.d
Image & build
Staging root, packaging, and build pipeline for bootable images.
- Staging root · Packaged filesystem skeleton, configs, default homes, headers, manuals, and shared assets.
base - Build system · Top-level Makefile, per-architecture build rules, and image assembly tooling.
Makefile - Image tools · Toolchain, disk, ramdisk, and generation utilities for building bootable artifacts.
util
Other components
- Tests · Kernel and userspace validation programs for syscalls, libc, threading, networking, and graphics edge cases.
tests
Connections 31
- Bootloader → Kernel core: boot handoff · Loads the kernel and transfers control with boot parameters and init data.
- Kernel core → x86_64 arch: x86_64 runtime · Uses the x86_64 port for bootstrap, interrupts, and memory management.
- Kernel core → aarch64 arch: aarch64 runtime · Uses the AArch64 port for bootstrap, interrupts, and memory management.
- Kernel core → Syscalls: syscall path · Dispatches process and signal-related kernel services.
- Kernel core → VFS: vfs path · Routes file, device, and pseudo-filesystem operations through VFS.
- Kernel core → Network: network path · Provides socket and packet services through the network stack.
- Kernel core → Video: display path · Exposes framebuffer graphics support to userspace and drivers.
- Kernel core → Audio: audio path · Exposes kernel audio services and device integration.
- Kernel core → Modules: driver API · Loads and coordinates hardware/filesystem modules.
- Modules → VFS: storage fs · Ext2, ISO9660, ramdisk, tmpfs, and tarfs drivers plug into the VFS.
- Modules → Network: net hw · Network drivers feed packets and link status into the stack.
- Modules → Audio: sound hw · Audio drivers provide hardware-backed sound devices.
- libc → Syscalls: syscalls · Applications cross the ABI boundary through libc wrappers and startup code.
- libc → VFS: files/devices · Uses file descriptors, procfs, terminals, pipes, and device files.
- Shared libs → libc: built on · Shared libraries depend on the C runtime and syscall wrappers.
- Shared libs → Compositor: windowing · Graphics and Yutani support underpin the desktop/window server.
- Compositor → Video: presentation · Renders windows through kernel video services.
- Compositor → Syscalls: input/events · Consumes input and process services via the kernel ABI.
- Login & session → Compositor: desktop start · Starts the graphical session and desktop environment.
- Login & session → Applications: launches · Invokes shell, login, terminal, and session utilities.
- Scripts → Login & session: startup flow · Boot-time scripts prepare the session and then launch the user environment.
- Staging root → Scripts: staged config · Provides startup scripts, system config, and default user resources.
- Build system → Staging root: assembles · Packages the staged root filesystem into the bootable image.
- Build system → Bootloader: builds · Compiles boot-stage code and links boot artifacts.
- Build system → Kernel core: builds · Compiles the kernel and architecture-specific pieces.
- Build system → libc: builds · Builds the userspace ABI and runtime libraries.
- Build system → Applications: builds · Builds the first-party applications and utilities.
- Image tools → Build system: supports · Provides helper scripts for toolchains, image generation, and disk creation.
- Tests → libc: validates · Exercises libc behavior, threading, signals, and POSIX-like interfaces.
- Tests → Syscalls: validates · Covers syscall and kernel boundary behavior.
- Tests → Network: validates · Exercises networking edge cases.