This document introduces the Ladybird browser project at the repository level: its goals, the major libraries and helper processes it comprises, and how the top-level components relate. For inter-process communication protocols in detail, see Multi-Process Architecture. For the build system and code generation pipeline, see Build System and Code Generation.
Ladybird is an independent, from-scratch web browser written in C++23. It shares no code with any existing browser engine and targets standards conformance with modern web platform specifications. Supported platforms include Linux, macOS, Windows, and Android.
| Directory | Purpose |
|---|---|
AK/ | Core utility library: strings, containers, error handling, streams |
Libraries/ | All shared libraries (LibWeb, LibJS, LibGfx, LibIPC, etc.) |
Services/ | Helper process entry points (WebContent, RequestServer, ImageDecoder, WebWorker, WebDriver) |
UI/ | Platform-specific UI frontends (AppKit on macOS, Qt, Android) |
Meta/ | CMake modules, code generators, and developer scripts (ladybird.py) |
Toolchain/ | vcpkg bootstrap (BuildVcpkg.py) and compiler selection (find_compiler.py) |
Tests/ | Unit and integration tests for AK, LibJS, LibWeb, and LibWasm |
Documentation/ | Build instructions and developer documentation |
The project is organized as a set of C++ libraries. Processes link against exactly the libraries they need.
| Library | Path | Role |
|---|---|---|
AK | AK/ | Strings, containers (Vector, HashMap), Error, streams, JSON, formatting |
LibGC | Libraries/LibGC/ | Garbage collector; all JS and DOM objects live in GC-managed cells |
LibJS | Libraries/LibJS/ | JavaScript engine: parser, Bytecode::Generator, Bytecode::Interpreter, VM |
LibRegex | Libraries/LibRegex/ | Regular expression engine used by LibJS |
LibWeb | Libraries/LibWeb/ | Full web platform: HTML, CSS, DOM, layout, painting, and 50+ Web APIs |
LibWebView | Libraries/LibWebView/ | Process management (Application), embedding API for UI frontends |
LibGfx | Libraries/LibGfx/ | 2D graphics primitives, font metrics, image format interfaces |
LibIPC | Libraries/LibIPC/ | IPC transport over Unix sockets; stubs generated from .ipc files |
LibIDL | Libraries/LibIDL/ | WebIDL type representation consumed by the bindings code generator |
LibMedia | Libraries/LibMedia/ | Media demuxing (Demuxer), PlaybackManager state machine |
LibCrypto | Libraries/LibCrypto/ | Cryptographic primitives used by LibTLS and LibWeb |
LibTLS | Libraries/LibTLS/ | TLS used by RequestServer |
LibHTTP | Libraries/LibHTTP/ | HTTP (wrapping curl) used by RequestServer |
LibWasm | Libraries/LibWasm/ | WebAssembly parser and interpreter |
LibURL | Libraries/LibURL/ | URL parsing and serialization |
Figure: Library dependency graph
Sources: Libraries/LibWeb/Forward.h10-16 Libraries/LibWeb/CMakeLists.txt1-13 AK/CMakeLists.txt1-50
Ladybird separates concerns into distinct OS processes communicating via LibIPC. This isolates rendering (crashes, memory safety) from the UI and from the network stack.
| Binary | Library Stack | Responsibility |
|---|---|---|
Ladybird | LibWebView, LibIPC | Browser UI; spawns and manages all helper processes |
WebContent | LibWeb, LibJS, LibGC, LibGfx | HTML/CSS/JS rendering; one process per tab group |
RequestServer | LibHTTP, LibTLS, LibCrypto | All outbound network I/O (HTTP, HTTPS, WebSocket) |
ImageDecoder | LibGfx | Image decoding in a sandboxed process |
WebWorker | LibJS, LibGC | Dedicated and Shared Web Workers |
WebDriver | LibWeb, LibIPC | W3C WebDriver automation protocol |
Figure: Process architecture and key code entities
Web::Page (in Libraries/LibWeb/Page/Page.cpp) is the central object inside the WebContent process. It owns the frame hierarchy and coordinates layout, painting, and event handling. Web::PageClient is a callback interface implemented by WebContent::ConnectionFromClient that allows Page to communicate results back to the UI process.
Sources: Meta/ladybird.py355-372 Libraries/LibWeb/Forward.h18-32
For the full IPC protocol, see Multi-Process Architecture.
LibWeb is the largest library. Its internal directory structure maps directly onto web platform specifications. The rendering pipeline takes HTML and CSS source through several sequential transformation stages to produce painted pixels.
Figure: LibWeb rendering data flow (key code entities)
The subsystems within Libraries/LibWeb/ are:
| Subsystem | Path in Libraries/LibWeb/ | Key Types |
|---|---|---|
| HTML Parser | HTML/Parser/ | HTMLParser, HTMLTokenizer |
| DOM | DOM/ | Node, Element, Document, ShadowRoot, EventTarget |
| CSS Parsing | CSS/Parser/ | Parser, Tokenizer, RuleParsing.cpp, PropertyParsing.cpp |
| Style Computation | CSS/StyleComputer.cpp | StyleComputer, CascadedProperties, ComputedProperties |
| CSS Selector Engine | CSS/SelectorEngine.cpp | SelectorEngine::matches, Selector, CompoundSelector |
| CSS Values | CSS/StyleValues/ | StyleValue, CalculatedStyleValue, TransformationStyleValue |
| Layout | Layout/ | TreeBuilder, BlockFormattingContext, FlexFormattingContext, GridFormattingContext, LayoutState |
| Painting | Painting/ | Paintable, StackingContext, DisplayListRecorder, DisplayListPlayerSkia |
| JS Bindings | Bindings/ | PlatformObject, Intrinsics, MainThreadVM |
| Animations | Animations/ | Animation, KeyframeEffect, AnimationTimeline |
| Fetch | Fetch/ | Infrastructure::Request, Fetching::Fetching.cpp |
| SVG | SVG/ | SVGElement, SVGFilterElement, SVGPathElement |
| WebGL | WebGL/ | WebGLRenderingContextBase, OpenGLContext |
| IndexedDB | IndexedDB/ | IDBDatabase, IDBTransaction, IDBObjectStore |
| Web Crypto | Crypto/ | SubtleCrypto, CryptoKey, CryptoAlgorithms.cpp |
| Streams | Streams/ | ReadableStream, WritableStream, TransformStream |
| Service Workers | ServiceWorker/ | ServiceWorkerContainer, ServiceWorkerRegistration |
| WebAssembly | WebAssembly/ | Bridge to LibWasm |
| Media Elements | HTML/HTMLMediaElement.cpp | HTMLMediaElement, HTMLVideoElement, HTMLAudioElement |
| Editing | Editing/ | ExecCommand.cpp, Commands.cpp |
| WebAudio | WebAudio/ | AudioContext, AudioNode, BaseAudioContext |
| ARIA | ARIA/ | ARIAMixin, AriaData |
Sources: Libraries/LibWeb/CMakeLists.txt15-1100 Libraries/LibWeb/idl_files.cmake1-450 Libraries/LibWeb/Forward.h56-1400
For deeper coverage:
VM, GC integrationidl_type_name_to_cpp_typeAll dependencies are managed through vcpkg using the manifest at vcpkg.json.
| Dependency | Version (pinned) | Use |
|---|---|---|
skia | 144 | 2D GPU rendering backend; used by DisplayListPlayerSkia |
angle | chromium_7258 | OpenGL ES implementation translating to Metal/Vulkan/D3D |
vulkan | 2023-12-17 | GPU backend on Linux and Windows |
curl | 8.18.0 | HTTP/1.1, HTTP/2, HTTP/3, WebSocket in RequestServer |
ffmpeg | 7.1.1 | Audio/video decoding in LibMedia |
harfbuzz | 10.2.0 | Text shaping |
icu | 78.1 | Unicode, locale, and text segmentation |
openssl | 3.5.3 | TLS certificate handling |
sqlite3 | 3.50.4 | IndexedDB persistent storage |
simdjson | 4.2.4 | Fast JSON parsing |
libavif, libjpeg-turbo, libpng, libjxl, libwebp | various | Image format decoders (in LibGfx and ImageDecoder) |
woff2 | 1.0.2 | Web font (WOFF2) decoding |
Sources: vcpkg.json1-373
The build uses CMake 3.30+ with Ninja. Meta/ladybird.py is the primary developer interface, wrapping CMake configuration, vcpkg dependency bootstrapping, and build/run/test invocations.
Common workflows:
| Command | Action |
|---|---|
./Meta/ladybird.py build | Configure (if needed) and build |
./Meta/ladybird.py run | Build and launch Ladybird |
./Meta/ladybird.py test | Build and run all tests via ctest |
./Meta/ladybird.py debug | Build and launch in gdb or lldb |
./Meta/ladybird.py vcpkg | Ensure vcpkg dependencies are installed |
Build presets defined in CMakePresets.json:
| Preset | Purpose |
|---|---|
Release | Optimized release build |
Debug | Debug symbols, no optimization |
Sanitizer | ASAN + UBSAN; used in CI |
Distribution | Stripped release for packaging |
All_Debug | All targets including optional ones |
Fuzzers | Fuzzing targets for CI |
A Flatpak build manifest is at Meta/CMake/flatpak/org.ladybird.Ladybird.json. See Build System and Code Generation for the full description of CMake structure, code generators (IDL, Properties.json, PseudoClasses.json), and the vcpkg pipeline.
Sources: Meta/ladybird.py141-186 CMakePresets.json1-63 Documentation/BuildInstructionsLadybird.md1-30