main.c — Notepad

#include "savanxp/libc.h"

int main(void)
{
    puts_out("hello from sdk\n");
    return 0;
}
sdk/hello/main.cLn 1, Col 1

Command Prompt

# Build the system once
$ ./build.sh build

# Compile your program and install it into
# the persistent disk image as /bin/hello
$ ./tools/build-user.sh \
    --source sdk/hello/main.c --name hello

$ ./build.sh run

Inside SavanXP, type hello at the shell. tools/run-user.sh compiles, installs and boots in one step.

Writing software for SavanXP

POSIX programs

Compile ordinary C against SDK v1: files, processes, pipes, pthreads. External apps install straight into the disk image; no kernel rebuild needed.

Native SUN programs

SUN is the native subsystem: programs built with --native run as .sxe images against the NT-style native API, the same one the window manager and the console use.

Ports

Doom, Celeste Classic and FFmpeg are versioned ports with their own build scripts underports/: a working template for bringing your own.

SDK examples…SXE format…Build system…

SavanXP documentation

Design documents, decisions, and specifications. README.md at the repository root covers how to build and run; this directory explains how the system is put together and why.

Anything that has to stay true for the future of the OS lives here, not in a changelog entry. See the rules in AGENTS.md.

Build — build/

  • BUILD_CMAKE.md — the native Bash/CMake build graph, tools, targets, external applications, and persistent-image rules.
  • BUILD_LINUX.md — host packages, QEMU setup, official ports, smoke tests, KVM configuration, and the GitHub Actions CI.

Kernel — kernel/

  • ARCH.md — the architecture boundary: what lives in arch/x86_64 and include/arch/x86_64, the named CPU operations drivers call instead of inline assembly, and what a second architecture would change.
  • KERNEL_NATIVE_API.md — the NT-style kernel API: the native dispatcher boundary, the slice plan, and what stays invariant.
  • KERNEL_SECURITY.md — the kernel trust boundary and audit record.
  • USERS_AND_PERMISSIONS.md — the planned user model: one everyday account, NT-style elevation through a broker and a prompt windowd owns, owner/group/mode in the SxFS inode, and the phases to build it.
  • SECTIONS.md — section objects and views: the grant model, execution as a view permission, W^X, the view and section budgets, and where shared library images belong.
  • SHARED_LIBRARIES.md — the shared-library subsystem: what is built and measured, the decisions and the bugs behind them, and the remaining work as ordered phases with the dependencies between them.
  • SMP_ROADMAP.md — multi-core startup, scheduler locking, and TLB shootdown work.
  • THREADS_ROADMAP.md — threads: what moves from the process to the thread, the decisions taken, and the phases to get there.
  • VIRTIO.md — the virtio-pci transport and its MMIO rules.
  • FILESYSTEMS.md — the VFS, the fs:: registry and what a filesystem driver provides: the system disk as the root, /dev and /rescue in memory and the /disk alias, the rescue system, how a request finds its driver, the rules the VFS enforces for all of them, and what still names SxFS.
  • INPUT.md — the input layer: how drivers register, why registration order decides which keyboard and pointer win, and the keyboard core that turns set 1 key positions into keys, text and modifiers.
  • AHCI.md — the AHCI (SATA, DMA) disk driver: which QEMU port holds what, how a request runs, and what it measured against PIO.
  • BLOCK_WRITEBACK.md — deferred disk writes: the queue's contract, how it keeps write order, when it drains, and what durability it gives up.
  • REAL_HARDWARE.md — what stops SavanXP from booting real 2003-era hardware: the 64-bit-only blockers, the driver gaps QEMU hides, and the routes for reaching a Compaq Evo N1020v. The Compaq-specific work (the i386 port) belongs to the legacy branch.
  • TIME.md — kernel clocks, virtualization, and diagnosis; plus the calendar date: the CMOS RTC, manual setting (date, SET_REALTIME), network sync (ntpsync, SNTP), and the taskbar clock with its calendar popup.

Userland — userland/

  • SYSTEM_LAYERING.md — the layering: the platform, apps on the POSIX SDK, when an app may be a SUN program instead, and the planned Win32 and Linux binary-compatibility subsystems.
  • SUN.md — SUN, the Savan Userland Native API: what it is next to Sx and POSIX, its pieces, the system's own API rather than a Win32 replica, the rules that grow it, its Win32 counterparts as a reading aid, and the slices the Command Prompt drives.
  • NATIVE_APPS.md — how to write a SUN program: headers, connecting a window, manifests, and the worked examples.
  • NIGHTWOOD.md — Nightwood, the forest game: the first game written against SUN and SxGL's second consumer; its rules, its frame and its tests.
  • NATIVE_HEAP.md — malloc for native programs: the allocator's replaceable page source, what a native process has today, the plan.
  • SYSTEM_MONITORING.md — process, memory, and system metrics exposed by the kernel.
  • SXE_FORMAT.md — the executable format, resource sections, generator, stamping, runtime rules, and why SUN programs are named .sxe.

Desktop and graphics — desktop/

  • DESKTOP_ARCHITECTURE.md — the target split between compositord, windowd and desktop (NT model), window roles, global hotkeys, the Task List removal, the move onto the native API, and the phases to get there.
  • WM_SUBSYSTEM.md — the window-manager subsystem, its client protocol, and compositor model.
  • OWNED_WINDOWS.md — ownership rules for dialogs and other windows created by an application.
  • PLATFORM_GRAPHICS.md — SXGFX, SXCHROME and SXGUI-C as platform code: the no-system-call rule, what stays in each subsystem (the window client, the application frame), and the toolkit's host.
  • SXGFX_ROADMAP.md — hardening of the 2D rasterization layer and its planned role in the desktop stack.
  • SXGL.md — SxGL, the 3D rasterizer: the GL 1.1 subset call by call, who presents, and every deliberate difference from the specification.
  • SXGL_ROADMAP.md — why the 3D layer sits beside SxGFX, the design it was built against, and how its batches landed.
  • GRAPHICS_PERF.md — graphics measurements and the interpretation of the performance tables.
  • UI_FONTS.md — the UI, caption and console faces, the rule that every UI font is 1-bit, and how to change a face.
  • DESKTOP_ICONS.md — desktop icons, shortcuts and context menus: the Desktop folder, the .sxlnk format and what "open" means, the icon grid and its keyboard, the desktop's focus in windowd, and context menus in applications (popups owned by any window, sxgui_context_menu_open).
  • DISPLAY_PROPERTIES.md — Display Properties: the wallpaper configuration (desktop.cfg) and how the desktop follows it, the shipped wallpapers, and changing the resolution while the session runs (the session's largest mode, the layout after a change, display.cfg).
  • FILES.md — Files, the file browser: the toolbar, address bar, history and Properties, the toolbar widgets (SXGUI_FLAG_TOOLBAR), the Large Icons and Details views over one widget (SXGUI_ICONVIEW), the per-size icon caches and their RAM, and what is next.
  • ICON_STYLE.md — the Windows 2000 look of the house icon set: the drawing rules, the shared kit and generator, and what is exempt.
  • CONSOLE.md — the Command Prompt: the console host (SUN) and sh as two programs, their handles and control channel, line editing, Ctrl+C without signals, and how the smokes open programs through it.
  • PAINT.md — Paint, the Accessories sketchbook: toolbox layout without widgets, the 8 tools, 8-deep undo, BMP/PNG files, and the selftest plus visual scenario.
  • WEBVIEWER.md — Web Viewer, the in-tree browser prototype: its rendering contract, the CSS subset, and what each milestone leaves out.
  • WEBVIEWER_ROADMAP.md — Web Viewer on NetSurf's MIT libraries (libhubbub, libdom, libcss): what is adopted, the clean-room rule against the GPL core, and the phases up to its own CSS 2.1 layout engine.

Media — media/

  • MEDIA_PLAYER.md — Media Player, the optional FFmpeg backend, playback timing, and the synchronization selftest.
  • AUDIO_DAEMON.md — audiod, the mixing daemon: UDP loopback transport, the slice protocol, and who holds /dev/audio0.
  • MIDI.md — libsxmidi, the General MIDI synthesizer: the SMF parser, the built-in instrument bank, and how the Doom port plays music through it.
  • SXMEDIA.md — withdrawn. What the multimedia layer was, what building it taught, and what has to exist before trying again: a way for one program to use a codec library it was not built with.

Filesystem — fs/

  • SXFS_CHECK.md — the fscheck consistency report: what mounting does not validate, what a leak looks like from the guest, and why there is no repair yet.
  • SXFS_JOURNAL.md — the sparse metadata journal: format, the write order that makes a commit crash-safe, and the snapshot invariant that tells the driver which sectors changed.
  • SXFS_ROADMAP.md — the SxFS work left after format v2, the measured baseline to compare against, and which of it can land without moving the on-disk format.

Networking — net/

  • NETWORKING.md — TCP guarantees, retransmission, windows, fault injection, and the minimal DNS client.

Ports — ports/

  • XASH3D_ROADMAP.md — porting Xash3D FWGS: what the engine needs from the platform, and the order that makes it pay for dlopen and SxGL without pulling in threads or SDL.
  • NETSURF_ROADMAP.md — porting NetSurf as the reference browser Web Viewer is compared against: the license (GPL-2.0-only core, MIT libraries), one shared copy of the libraries, and the steps.

Third-party code — third-party/

Design documents from docs/ in the SavanXP repository