Userland Architecture

SerenityOS userspace components, services, and applications

The SerenityOS userland comprises all user-space components including system services, applications, utilities, and libraries. Everything is built from scratch with a cohesive design philosophy.

Userland Overview

The userland is organized into distinct categories in the Userland/ directory:

Userland/
├── Libraries/       # ~80 system libraries (LibGUI, LibWeb, LibGfx, etc.)
├── Services/        # System services (WindowServer, AudioServer, etc.)
├── Applications/    # GUI applications (~50 apps)
├── Utilities/       # Command-line utilities (~200 tools)
├── Games/           # Built-in games
├── Demos/           # Demonstration programs
├── Applets/         # Taskbar applets
├── DevTools/        # Development tools (HackStudio, Profiler)
├── Shell/           # The SerenityOS shell
└── DynamicLoader/   # Runtime dynamic linker

System Services

System services are long-running daemon processes that provide core functionality:

WindowServer

Primary Responsibilities:

• Window management and compositing
• Input event distribution
• Desktop rendering
• Multi-monitor support
• Theme management

The WindowServer is the compositor that manages all GUI windows, handles mouse/keyboard input, and renders the desktop environment.

AudioServer

Primary Responsibilities:

• Audio mixing and playback
• Sound device management
• Per-application volume control
• Audio format conversion

Manages all audio output, mixing multiple streams from different applications.

LoginServer

Primary Responsibilities:

• User authentication
• Session management
• Login screen
• User switching

Handles user login, authentication, and session initialization.

SystemServer

Primary Responsibilities:

• Service lifecycle management
• Boot process coordination
• Service dependencies
• System initialization

The init system that starts and manages all other system services.

Complete Service List

Core Services

• SystemServer: Init system and service manager
• LoginServer: User authentication and sessions
• WindowServer: GUI compositor and window manager
• Taskbar: Desktop taskbar and system tray

Media Services

• AudioServer: Audio mixing and playback
• ImageDecoder: Image decoding service (IPC-based)

Network Services

• RequestServer: HTTP/HTTPS request handling
• WebContent: Isolated web rendering process
• WebWorker: Web Worker execution
• WebDriver: Browser automation protocol
• WebServer: HTTP server daemon
• LookupServer: DNS resolver
• DHCPClient: DHCP client
• NetworkServer: Network configuration
• TelnetServer: Telnet server

Desktop Services

• NotificationServer: Desktop notifications
• Clipboard: System clipboard manager
• FileSystemAccessServer: Filesystem access mediation
• FileOperation: File copy/move operations
• ConfigServer: Configuration management

System Services

• CrashDaemon: Crash report collection
• LaunchServer: Application launcher and file associations
• DeviceMapper: Device management
• KeyboardPreferenceLoader: Keyboard layout loader
• SpiceAgent: QEMU SPICE integration

Other Services

• SQLServer: SQL database server
• ChessEngine: Chess AI engine
• EchoServer: Echo protocol server (testing)

Applications

SerenityOS includes a rich set of GUI and CLI applications:

GUI Applications

Productivity

• TextEditor: Multi-format text editor with syntax highlighting
• Spreadsheet: Spreadsheet with JavaScript integration
• Calendar: Calendar and scheduling
• Mail: Email client
• FileManager: Graphical file browser
• PixelPaint: Raster graphics editor

Internet

• Browser: Full web browser with LibWeb engine
  • JavaScript (ES2021+ support)
  • WebAssembly
  • CSS3
  • DOM APIs
• BrowserSettings: Browser configuration

Development

• HackStudio: Integrated development environment
  • C++ code editing
  • Project management
  • Debugger integration
  • Git integration
• Debugger: Standalone debugger
• Profiler: Performance profiler
• HexEditor: Binary file editor
• GMLPlayground: GUI Markup Language tester

System

• Terminal: Terminal emulator
• SystemMonitor: Process and resource monitor
• DisplaySettings: Display configuration
• ThemeEditor: Theme customization
• Assistant: Application launcher (like Spotlight)
• About: System information

Utilities

• Calculator: Desktop calculator
• Clock: World clock
• CharacterMap: Unicode character browser
• FontEditor: Bitmap and vector font editor
• 3DFileViewer: 3D model viewer
• ImageViewer: Image viewer
• VideoPlayer: Video player
• SoundPlayer: Audio player

Command-Line Utilities

SerenityOS provides ~200 Unix-like command-line utilities in Userland/Utilities/:

File Operations

ls, cp, mv, rm, mkdir, rmdir, cat, touch
find, grep, diff, patch, tar, gzip, zip
chmod, chown, ln, readlink, stat

Games and Demos

Games

• Solitaire
• Minesweeper
• Chess
• 2048
• Snake
• Pong
• Breakout
• Conway’s Game of Life

Demos

• CatDog (desktop pet)
• Eyes (follows cursor)
• Starfield
• Fire
• Mandelbrot
• WidgetGallery

Applets

• Audio applet
• Clock applet
• Network applet
• Keyboard applet
• ResourceGraph

Development Tools

HackStudio IDE

HackStudio is the native IDE for SerenityOS development:

Features

• C++ syntax highlighting and code completion
• Project management with multiple build configurations
• Integrated debugger with breakpoints and variable inspection
• Git integration (status, diff, commit)
• Terminal integration
• TODO list tracking
• Class browser

Language Support

• C++: Full support with LibCpp parsing
• JavaScript: Syntax highlighting
• HTML/CSS: Web development support
• GML: GUI Markup Language
• Markdown: Documentation editing

Profiler

The Profiler application provides performance analysis:

• Kernel-level profiling support
• Per-function timing breakdown
• Call graph visualization
• Flame graph generation
• Symbol resolution
• Sampling profiler with low overhead

Debugger

Standalone Debugger with:

• Process attachment and control
• Breakpoint management
• Single-stepping execution
• Memory inspection
• Register viewing
• Disassembly view

Shell

The SerenityOS Shell (Userland/Shell/) is a custom shell implementation:

Features

• POSIX-like shell syntax
• Job control (background jobs, fg/bg)
• Pipes and redirections
• Command history
• Tab completion
• Shell scripting
• Globbing (wildcards)

Built-in Commands

• cd, pwd, exit
• history, export, unset
• alias, jobs, fg, bg
• source, time

Advanced Features

• Function definitions
• Control flow (if/else, for, while)
• Variables and substitution
• Arithmetic expansion
• Process substitution

Dynamic Loader

The DynamicLoader (Userland/DynamicLoader/) is the runtime linker:

• ELF Loading: Loads dynamically-linked executables
• Symbol Resolution: Resolves symbols across shared libraries
• Relocation: Applies relocations for position-independent code
• Lazy Binding: Defers symbol resolution until first use
• RPATH Support: Library search path configuration

Application Lifecycle

Typical application execution flow:

┌─────────────────────────────────────────────┐
│  1. User launches application               │
│     (via GUI or command line)               │
└────────────────┬────────────────────────────┘
                 |
                 v
┌─────────────────────────────────────────────┐
│  2. LaunchServer handles file associations  │
│     or direct execution                     │
└────────────────┬────────────────────────────┘
                 |
                 v
┌─────────────────────────────────────────────┐
│  3. Kernel: fork() + execve()               │
│     - Creates new process                   │
│     - Loads executable                      │
└────────────────┬────────────────────────────┘
                 |
                 v
┌─────────────────────────────────────────────┐
│  4. DynamicLoader (if dynamic)              │
│     - Loads shared libraries                │
│     - Resolves symbols                      │
└────────────────┬────────────────────────────┘
                 |
                 v
┌─────────────────────────────────────────────┐
│  5. Application initialization              │
│     - serenity_main() entry point           │
│     - Connect to system services via IPC    │
│     - Create GUI windows (if GUI app)       │
└────────────────┬────────────────────────────┘
                 |
                 v
┌─────────────────────────────────────────────┐
│  6. Event loop execution                    │
│     - Process events from WindowServer      │
│     - Handle user input                     │
│     - Perform application logic             │
└─────────────────────────────────────────────┘

Security in Userland

Userland applications benefit from kernel security features:

pledge() Usage

Applications use pledge() to limit their capabilities:

// Browser restricts its main process
TRY(Core::System::pledge("stdio recvfd sendfd unix rpath"));

Common pledge promises:

• stdio: Basic I/O
• rpath, wpath, cpath: File read/write/create
• inet: Network access
• unix: Unix domain sockets
• proc: Process control
• exec: Execute other programs

unveil() Usage

Applications use unveil() to restrict filesystem access:

// Only allow reading from specific directories
TRY(Core::System::unveil("/res", "r"));
TRY(Core::System::unveil("/usr/lib", "r"));
TRY(Core::System::unveil(nullptr, nullptr));  // Lock

Process Isolation

• WebContent Isolation: Browser renders web pages in separate processes
• ImageDecoder Isolation: Image decoding happens in isolated service
• Capability-Based Security: Services only granted necessary permissions

Modern C++ Patterns

Userland code extensively uses modern C++ patterns:

serenity_main() Entry Point

#include <LibMain/Main.h>

ErrorOr<int> serenity_main(Main::Arguments arguments)
{
    // No traditional int main(argc, argv)
    // Better error handling with ErrorOr<>
    TRY(Core::System::pledge("stdio rpath"));
    
    auto app = TRY(GUI::Application::create(arguments));
    // ...
    return app->exec();
}

Further Reading

Library Architecture

Explore the userland library ecosystem

IPC Architecture

Learn how services communicate

Event Loop System

Understand the event-driven architecture

Coding Patterns

Common coding patterns in SerenityOS