Advanced Build Options

CMake options, sanitizers, component configuration, and build customization

Customizing the Disk Image

You can modify the disk image filesystem by creating a sync-local.sh script in the project root:

sync-local.sh

#!/bin/sh

set -e

# Change keyboard layout to German
cat << 'EOF' > mnt/etc/Keyboard.ini
[Mapping]
Keymaps=de
EOF

# Add a file to anon's home directory
cp /somewhere/on/your/system/file.txt mnt/home/anon

This script runs during image creation and can modify files in the mnt/ directory.

See Base/res/keymaps/ for available keyboard layouts.

CMake Build Options

CMake options can be configured using:

Command Line

cmake -B Build/x86_64 -DOPTION_NAME=Value

ccmake (TUI)

ccmake Build/x86_64

cmake-gui

cmake-gui Build/x86_64

Development Options

Sanitizers

Runtime checks for memory corruption, undefined behavior, and other bugs:

• ENABLE_ADDRESS_SANITIZER - Memory corruption checks (Lagom tests)
• ENABLE_KERNEL_ADDRESS_SANITIZER - Memory corruption checks (kernel)
• ENABLE_KERNEL_UNDEFINED_SANITIZER - Undefined behavior checks (kernel)
• ENABLE_KERNEL_UNDEFINED_SANITIZER_ALWAYS_DEADLY - Make UB checks fatal
• ENABLE_MEMORY_SANITIZER - Uninitialized memory checks (Lagom)
• ENABLE_UNDEFINED_SANITIZER - Undefined behavior checks (userland)
• UNDEFINED_BEHAVIOR_IS_FATAL - Make UB sanitizer errors non-recoverable

Example:

cmake -B Build/x86_64 -DENABLE_ADDRESS_SANITIZER=ON

Coverage & Fuzzing

• ENABLE_KERNEL_COVERAGE_COLLECTION - KCOV API for kernel fuzzing
• ENABLE_USERSPACE_COVERAGE_COLLECTION - Coverage for userspace (Clang only)
• ENABLE_FUZZERS - Build fuzzers
• ENABLE_FUZZERS_LIBFUZZER - Clang libFuzzer-based fuzzers
• ENABLE_FUZZERS_OSSFUZZ - OSS-Fuzz compatible fuzzers

Example:

cmake -B Build/x86_64 -DENABLE_FUZZERS_LIBFUZZER=ON

Debug Symbols

• ENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS - Build kernel with -Og -ggdb3
• ENABLE_ALL_DEBUG_FACILITIES - Enable all debug macros + symbols (CI only)
• ENABLE_ALL_THE_DEBUG_MACROS - Enable all debug macros (CI only)

Don’t use ENABLE_ALL_THE_DEBUG_MACROS normally - it clutters output and makes the system very slow.

Example:

cmake -B Build/x86_64 -DENABLE_EXTRA_KERNEL_DEBUG_SYMBOLS=ON

Compile-Time Checks

• ENABLE_COMPILETIME_FORMAT_CHECK - Validate std::format strings (default: ON)
• ENABLE_PCI_IDS_DOWNLOAD - Download PCI device database (default: ON)

Example:

cmake -B Build/x86_64 -DENABLE_COMPILETIME_FORMAT_CHECK=OFF

Build Configuration

Toolchain & Architecture

• SERENITY_TOOLCHAIN - GNU or Clang
• SERENITY_ARCH - x86_64, aarch64, or riscv64
• ENABLE_KERNEL_LTO - Build kernel with link-time optimization
• ENABLE_MOLD_LINKER - Use mold linker (build with Toolchain/BuildMold.sh)

Example:

SERENITY_ARCH=aarch64 Meta/serenity.sh run
# Or directly:
cmake -B Build/x86_64 -DSERENITY_ARCH=x86_64 -DSERENITY_TOOLCHAIN=Clang

Component Selection

• BUILD_<COMPONENT> - Enable/disable specific components (e.g., BUILD_HEARTS)
• BUILD_EVERYTHING - Build all optional components

Example:

cmake -B Build/x86_64 -DBUILD_HEARTS=OFF -DBUILD_BROWSER=ON

See Component Configuration for an interactive tool.

Language & Testing

• ENABLE_JAKT - Build Jakt compiler and Jakt applications
• JAKT_SOURCE_DIR - Path to local Jakt checkout for development
• INCLUDE_WASM_SPEC_TESTS - Include WebAssembly spec tests (requires prettier and wabt 1.0.35+)
• INCLUDE_FLAC_SPEC_TESTS - Include FLAC test suite

Example:

cmake -B Build/lagom -DENABLE_JAKT=ON -DJAKT_SOURCE_DIR=/home/me/jakt

Lagom & Graphics

• BUILD_LAGOM - Build Lagom (host libraries and tools)
• ENABLE_ACCELERATED_GRAPHICS - Use accelerated graphics APIs
• ENABLE_COMPILER_EXPLORER_BUILD - Skip non-library entities (Lagom only)

Example:

cmake -S Meta/Lagom -B Build/lagom -DBUILD_LAGOM=ON

Cache & Network

• SERENITY_CACHE_DIR - Location for downloaded files cache
• ENABLE_NETWORK_DOWNLOADS - Allow downloads during build (default: ON)

Example:

cmake -B Build/x86_64 -DSERENITY_CACHE_DIR=/path/to/cache

Debug Macros

Enable debug output for specific components:

# Enable process debug output
cmake -B Build/x86_64 -DPROCESS_DEBUG=ON

# Enable multiple debug macros
cmake -B Build/x86_64 -DPROCESS_DEBUG=ON -DSCHEDULER_DEBUG=ON

See Meta/CMake/all_the_debug_macros.cmake for a complete list of available debug macros.

Component Configuration

Use the interactive ConfigureComponents tool to select which components to build:

1. Install whiptail

   # Ubuntu/Debian
   sudo apt install whiptail
   
   # Arch
   sudo pacman -S libnewt
   
2. Run configuration tool

   cd Build/x86_64
   ninja configure-components
   

   This will:

   • Prompt for build type selection
   • Allow customization of components
   • Run CMake with selected options
   • Clean old build artifacts

Ninja Build Targets

Special targets available in Build/<architecture>/:

Bootloader images

# Limine bootloader (x86-64)
ninja limine-image

# GRUB for BIOS
ninja grub-image

# GRUB for UEFI
ninja grub-uefi-image

# extlinux bootloader
ninja extlinux-image

SuperBuild Advanced Usage

The SuperBuild manages two separate builds:

1. Lagom - Host tools (in Build/lagom)
2. Serenity - Target OS (in Build/<arch>)

Manual SuperBuild

# Configure SuperBuild
cmake -GNinja -S Meta/CMake/Superbuild -B Build/superbuild-x86_64 \
  -DSERENITY_ARCH=x86_64 -DSERENITY_TOOLCHAIN=GNU

# Build everything
cmake --build Build/superbuild-x86_64

# Run SerenityOS
ninja -C Build/x86_64 setup-and-run

Modifying Child Builds

Serenity Build

# After initial SuperBuild
cmake -B Build/x86_64 -DPROCESS_DEBUG=ON -DBUILD_BROWSER=OFF
ninja -C Build/x86_64 install

Lagom Build

# Build host tests
cmake -S Meta/Lagom -B Build/lagom -DBUILD_LAGOM=ON
ninja -C Build/lagom install

CMake cache variables must be set after the SuperBuild creates the child build directories.

Clang-Based Toolchain

Build SerenityOS with Clang instead of GCC:

1. Build Clang toolchain

   Toolchain/BuildClang.sh
   

   This may slow down or temporarily lock up your system. Set MAKEJOBS to limit parallel tasks:

   MAKEJOBS=4 Toolchain/BuildClang.sh
   
2. Build with Clang

   Meta/serenity.sh run x86_64 Clang
   # Or:
   cmake -B Build/x86_64 -DSERENITY_TOOLCHAIN=Clang
   

Serenity-Aware Clang Tools

The Clang toolchain includes libTooling-based tools:

• clang-format
• clang-tidy
• clangd (optional)

These are installed to Toolchain/Local/clang/bin/ and understand SerenityOS as a valid target.

Building clangd

CLANG_ENABLE_CLANGD=ON Toolchain/BuildClang.sh

Point your editor to the custom clang tools and a compile_commands.json from a Clang build for richer error reporting.

Clang-Format Updates

To get the latest clang-format:

LLVM APT (Recommended)

For Debian-based distributions:

# See https://apt.llvm.org for instructions
sudo apt install clang-format-19

Build from Source

# Build SerenityOS-patched LLVM
Toolchain/BuildClang.sh

# Use the built binary
Toolchain/Local/clang/bin/clang-format

The meta-lint-ci pre-commit hook automatically uses this binary.

Official LLVM

Follow the LLVM documentation

Tests

For information on running tests, see the Running Tests documentation.

The documentation explains:

• Host tests (run with Lagom)
• Target tests (run on SerenityOS)
• Debugging CI test failures

Alternative Virtualization

Beyond QEMU, SerenityOS can run on:

VirtualBox

See VirtualBox Installation Guide

VMware

See VMware Installation Guide

Bare Metal

See Physical PC Installation

WSL2 Performance Notes

If using Windows QEMU with WSL2, accessing ext4 partitions requires the 9P network share at \\wsl$\{distro-name}.

For better performance, copy the disk image to a native Windows partition:

cp Build/_disk_image /mnt/c/serenity/_disk_image
cp Build/Kernel/Kernel /mnt/c/serenity/Kernel

Then set SERENITY_DISK_IMAGE to the Windows path (e.g., D:\serenity\_disk_image).

Quick Reference

Common CMake Commands

# Reconfigure with option
cmake -B Build/x86_64 -DOPTION=Value

# Clean build
ninja -C Build/x86_64 clean
rm -rf Build/x86_64/Root

# Full rebuild
rm -rf Build/x86_64
Meta/serenity.sh rebuild

Environment Variables

SERENITY_ARCH=aarch64      # Target architecture
MAKEJOBS=4                  # Parallel build jobs
SERENITY_CACHE_DIR=/cache   # Download cache location

Useful Ninja Targets

ninja -C Build/x86_64 install          # Build and install
ninja -C Build/x86_64 setup-and-run    # Setup and run QEMU
ninja -C Build/x86_64 check-style      # Run linters
ninja -C Build/x86_64 all_generated    # Build generated code