TuxSTEP — design document v3.3

The 20th floor of Objective-C application development and the fast lane for porting apps from macOS.

Workspace.app file manager / shell LoginWindow.app login chain Cocoa apps .app bundles Linux apps .app bundles (pkgwrap) AppKit (libs-gui) windows, controls, events Display backend (libs-back) Quartz: libs-opal, libs-quartzcore Apple BSD coreutils /System/Library/Tools/ Foundation (libs-base) CoreFoundation (libs-corebase) libdispatch • libobjc2 • tools-make Apple libsystem (libc, pthread, platform, malloc) /System/Library/Libraries/libSystem.so Linux kernel + drivers KMS, devtmpfs, framebuffer console

The filesystem follows NeXT's four-domain model. Cocoa APIs walk the domains automatically in this order:

Cocoa lookup order User ~/ your prefs, apps, fonts Local /Local/ per-machine apps, sysadmin scope Network /Network/ site-wide, NFS-backed System /System/ the System, drag-and-drop to deploy

Components

Every component traces back to a single upstream source. The integration is the product.

ComponentSource
Linux kernel + drivers + firmwarekernel.org upstream Linux + linux-firmware
BootloaderGRUB upstream, forked as tuxstep/grub (silent boot, familiar boot keys)
System libcApple's libsystem (apple-oss-distributions/Libc + libplatform + libpthread + libmalloc + libclosure)
Mach IPCtuxstep/darlingserver — userspace Mach port broker
Init / service supervisorApple's launchd (apple-oss-distributions/launchd), ported to libsystem; runs as PID 1
Coreutils / shellApple's BSD-derived utilities (file_cmds, shell_cmds, system_cmds, network_cmds, text_cmds)
Compiler toolchainllvm-project — clang, lld, ar, ... cross-built against libsystem
Grand Central Dispatchswift-corelibs-libdispatch (Swift's libdispatch port), built against libsystem
Objective-C runtimelibobjc2 (via Gershwin)
Build systemtools-make / gnustep-make (via Gershwin)
Foundationlibs-base (GNUstep, via Gershwin), rebuilt against libsystem
CoreFoundationlibs-corebase (GNUstep, via Gershwin), rebuilt against libsystem
AppKitlibs-gui (GNUstep, via Gershwin) — windows, controls, events
Quartz / Core Graphicslibs-opal (GNUstep, via Gershwin)
Display backendlibs-back (GNUstep, via Gershwin)
Core Animationlibs-quartzcore (GNUstep, via Gershwin)
Workspace + system appsGershwin — Eau, LoginWindow.app, Workspace.app, system apps
Linux app bundlingpkgwrap — turns any apt package into a self-contained .app bundle (compat layer)

Filesystem layout

/                                       ISO root
│
├── System/                              the entire System
│   └── Library/
│       ├── Kernels/<kver>/              kernel image, initramfs
│       ├── Firmware/                    firmware blobs
│       ├── Modules/<kver>/              kernel modules (post-v0.1; empty in v0.1)
│       ├── Libraries/                   libSystem.so, libobjc2.so, libdispatch.so,
│       │                                libgnustep-base.so, libgnustep-corebase.so
│       ├── Headers/                     Apple + GNUstep headers
│       ├── Tools/                       Apple BSD coreutils, zsh, cc, ld, ar, ...
│       ├── Makefiles/                   gnustep-make
│       └── Private/                     system-internal Unix infrastructure
│           ├── etc/                     passwd, hosts, fstab, ...
│           ├── var/                     logs, state, spool
│           ├── tmp/                     temp files (tmpfs at runtime)
│           ├── dev/                     devtmpfs mount point
│           └── sys/                     sysfs mount point (post-v0.1)
│
├── Network/                             site-wide / NFS-backed (empty in v0.1)
├── Local/                               per-machine sysadmin (empty in v0.1)
└── Volumes/                             mounted external media

v3.3 — generated 2026-04-26. Architectural source of truth: github.com/tuxstep/tuxstep/blob/main/PLAN.md.