SerenityOS Build Guide: A C++ Unix-Like System for x86, Arm, and RISC-V

SerenityOS is a graphical, Unix-like operating system built entirely from scratch. Every component—from the kernel and window server to the web browser—is written in C++ without the use of third-party libraries. While it embraces the aesthetic of a late-1990s desktop, it is designed for modern x86_64, Arm, and RISC-V hardware architectures.

Recent Changes

• AK: Optimized fast paths were added for common type formatting.
• Base: Users can now toggle desktop wallpaper visibility within the Display Settings.
• Kernel: The compiler flag -fno-sanitize-recover=undefined has been set as the default.
• Ladybird: Web content now renders specifically within the sRGB color space.
• Userland: Implemented stricter validation for MBR partition table alignment.
• Toolchain: The build process now generates driver-aarch64.o for native GCC builds.

Core Features The system is powered by a modern, preemptive 64-bit kernel. Security is a fundamental design principle, incorporating hardware protection, restricted userland capabilities, W^X memory, pledge and unveil sandboxing, (K)ASLR, OOM resilience, and dedicated process isolation for web content. It also features a native, comprehensive TLS stack.

System services include dedicated servers for windows, logins, and audio, all communicating via a high-performance IPC layer. SerenityOS maintains a high degree of POSIX compliance, providing LibC, a native shell, standard Unix utilities, pseudo-terminals, and a /proc-style virtual filesystem. It also features native support for mounting ext2 filesystems.

The network stack supports IPv4, TCP, and UDP, alongside built-in applications for DNS, HTTP, Gemini, IMAP, and NTP. Developer tools are extensive, including kernel-assisted profiling, a crash reporter, an interactive GUI playground for exploring system internals, a hex editor, and the HackStudio integrated development environment (IDE).

File format support is broad, covering PNG, JPEG, MP3, WAV, ZIP, and PDF. The user interface adheres to a strict, unified design language that supports swappable themes and custom bitmap or vector fonts. Built-in entertainment includes Solitaire, Minesweeper, 2048, and Chess. Everyday productivity is handled by a suite of GUI applications: a spreadsheet with JavaScript support, a text editor, a terminal emulator, a pixel-art paint program, and a media player. Additionally, over 300 popular open-source software ports are available; these require no external dependencies and are built from source directly within the Serenity environment.

Building SerenityOS

Debian / Ubuntu

Install the necessary packages using the following command:

sudo apt install build-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-gui qemu-system-x86 qemu-utils ccache rsync unzip texinfo libssl-dev zlib1g-dev

Optional: Install fuse2fs to enable building disk images without requiring root privileges.

A modern compiler is required (GCC 13+ or Clang 17+):

sudo apt install gcc-13 g++-13
# Alternatively, for Clang 19:
sudo apt install libclang-19-dev clang-19 llvm-19 llvm-19-dev

Ensure QEMU 6.2 or newer is installed. If your distribution provides an older version, you can run Toolchain/BuildQemu.sh after installing these additional build dependencies:

sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libslirp-dev libspice-server-dev

CMake version 3.25.0 or later is mandatory. The build script will automatically compile CMake from source if your system version is outdated.

Windows

Development is supported via WSL2. Please consult the project's official Windows documentation for specific configuration details.

Arch Linux / Manjaro

Install the required tools using pacman:

sudo pacman -S --needed base-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu-desktop qemu-system-aarch64 ccache rsync unzip

SerenityOS (Self-Hosted)

If you are building SerenityOS from within SerenityOS itself, install these ports first:

bash cmake curl e2fsprogs gawk genext2fs git ninja patch python3 qemu rsync

When using LLVM, include the llvm port. For those using GCC, ensure gcc, gmp, and mpc are installed.

Running the Build

From the root of the project directory, execute:

Meta/serenity.sh run

This command handles the entire process: compiling the operating system, generating a disk image, and booting the environment in QEMU. Note that the initial run will download and compile the cross-compiler toolchain; subsequent builds will complete significantly faster.

To compile the system without launching the virtual machine, use:

Meta/serenity.sh build

Installing Ports

To add software such as curl from the ports collection, navigate to the specific port's directory and execute the package script:

cd Ports/curl
./package.sh

Once the compilation is complete, the software will be available within the filesystem the next time you boot SerenityOS.