# Technical Documentation: LadybirdBrowser/ladybird > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/LadybirdBrowser/ladybird) ### Overview (README.md) # Ladybird [Ladybird](https://ladybird.org) is a truly independent web browser, using a novel engine based on web standards. > [!IMPORTANT] > Ladybird is in a pre-alpha state, and only suitable for use by developers > ## Features We aim to build a complete, usable browser for the modern web. Ladybird uses a multi-process architecture with a main UI process, several WebContent renderer processes, an ImageDecoder process, and a RequestServer process. Image decoding and network connections are done out of process to be more robust against malicious content. Each tab has its own renderer process, which is sandboxed from the rest of the system. At the moment, many core library support components are inherited from SerenityOS: - LibWeb: Web rendering engine - LibJS: JavaScript engine - LibWasm: WebAssembly implementation - LibCrypto/LibTLS: Cryptography primitives and Transport Layer Security - LibHTTP: HTTP/1.1 client - LibGfx: 2D Graphics Library, Image Decoding and Rendering - LibUnicode: Unicode and locale support - LibMedia: Audio and video playback - LibCore: Event loop, OS abstraction layer - LibIPC: Inter-process communication ## How do I build and run this? See [build instructions](Documentation/BuildInstructionsLadybird.md) for information on how to build Ladybird. Ladybird runs on Linux, macOS, Windows (with WSL2), and many other \*Nixes. ## How do I read the documentation? Code-related documentation can be found in the [documentation](Documentation/) folder. ## Get in touch and participate! Join [our Discord server](https://discord.gg/nvfjVJ4Svh) to participate in issue and development discussions. Please read [Getting involved with Ladybird](Documentation/GettingStartedContributing.md) if you're new to Ladybird and want to help. Before opening an issue, please see the [issue policy](CONTRIBUTING.md#issue-policy) and the [detailed issue-reporting guidelines](ISSUES.md). The project participation guidelines can be found in [`CONTRIBUTING.md`](CONTRIBUTING.md). ## License Ladybird is licensed under a 2-clause BSD license. --- ### Documentation README (`Documentation/README.md`) # Ladybird Documentation Ladybird development moves quickly, so some of these might be out of date. Please let us know if something here is wrong. If you have any questions that are not answered here or in the [FAQ](FAQ.md), you are welcome to ask on [Discord](../README.md#get-in-touch-and-participate). ## Building and Running * [Build Instructions](BuildInstructionsLadybird.md) * [Advanced Build Instructions](AdvancedBuildInstructions.md) * [Troubleshooting](Troubleshooting.md) * [Testing](Testing.md) * [Profiling the Build](BuildProfilingInstructions.md) ## Configuring Editors * [Android Studio](EditorConfiguration/AndroidStudioConfiguration.md) * [CLion](EditorConfiguration/CLionConfiguration.md) * [Emacs](EditorConfiguration/EmacsConfiguration.md) * [Helix](EditorConfiguration/HelixConfiguration.md) * [NVim](EditorConfiguration/NvimConfiguration.md) * [Qt Creator](EditorConfiguration/QtCreatorConfiguration.md) * [Vim](EditorConfiguration/VimConfiguration.md) * [VS Code](EditorConfiguration/VSCodeConfiguration.md) ## Development * [Project Participation](../CONTRIBUTING.md) * [Code Policy](CodePolicy.md) * [Coding Style](CodingStyle.md) * [Common Patterns](Patterns.md) * [Guidelines for Text in UI](HumanInterfaceGuidelines/Text.md) * [EventLoop](EventLoop.md) * [Smart Pointers](SmartPointers.md) * [String Formatting](StringFormatting.md) ## Browser/LibWeb * [General Architecture](ProcessArchitecture.md) * [Omnibox Design](Omnibox.md) * [LibWeb: From Loading to Painting](LibWebFromLoadingToPainting.md) * [LibWeb: Browsing Contexts and Navigables](BrowsingContextsAndNavigables.md) * [How to Add a CSS Property](CSSProperties.md) * [How to Add an IDL File](AddNewIDLFile.md) * [LibWeb Code Style & Patterns](LibWebPatterns.md) * [Investigating Websites with WebDriver](WebDriver.md) * [CSS Generated Files](CSSGeneratedFiles.md) * [Media Pipeline Design](MediaPipelineDesign.md) --- ### Documentation AddNewIDLFile (`Documentation/AddNewIDLFile.md`) # Adding a new IDL file Ladybird's build system does a lot of work of turning the IDL from a Web spec into code, but there are a few things you'll need to do yourself. For the sake of example, let's say you're wanting to add the `HTMLDetailsElement`. 1. Create `LibWeb/HTML/HTMLDetailsElement.idl` with the contents of the IDL section of the spec. In this case, that would be: ```webidl [Exposed=Window] interface HTMLDetailsElement : HTMLElement { [HTMLConstructor] constructor(); [CEReactions] attribute boolean open; }; ``` 2. Add the IDL file to [`LibWeb/idl_files.cmake`](../Libraries/LibWeb/idl_files.cmake). 3. Forward declare the generated class in [`LibWeb/Forward.h`](../Libraries/LibWeb/Forward.h): - `HTMLDetailsElement` in its namespace. --- ### Documentation AdvancedBuildInstructions (`Documentation/AdvancedBuildInstructions.md`) # Advanced Build Instructions This file covers a few advanced scenarios that go beyond what the basic build guide provides. ## Ninja build targets The `Meta/ladybird.py` script provides an abstraction over the build targets which are made available by CMake. The following build targets cannot be accessed through the script and have to be used directly by changing the current directory to `Build/release` and then running `ninja `: - `ninja check-style`: Runs the same linters the CI does to verify project style on changed files - `ninja lint-shell-scripts`: Checks style of shell scripts in the source tree with shellcheck - `ninja all_generated`: Builds all generated code. Useful for running analysis tools that can use compile_commands.json without a full system build When testing is enabled, the default build also compiles the main Rust workspace's test binaries and Flap's test targets on supported platforms. It does not run them. Use `ninja rust-tests` to compile just these Rust tests, or `ctest -R '^(RustWorkspace|Flap)$' --output-on-failure` to run the suites. ## CMake build options There are some optional features that can be enabled during compilation that are intended to help with specific types of development work or introduce experimental features. Currently, the following build options are available: - `ENABLE_ADDRESS_SANITIZER`: builds in runtime checks for memory corruption bugs (like buffer overflows and memory leaks) in Lagom test cases. - `ENABLE_MEMORY_SANITIZER`: enables runtime checks for uninitialized memory accesses in Lagom test cases. - `ENABLE_UNDEFINED_SANITIZER`: builds in runtime checks for [undefined behavior](https://en.wikipedia.org/wiki/Undefined_behavior) (like null pointer dereferences and signed integer overflows) in Lagom and Ladybird. - `UNDEFINED_BEHAVIOR_IS_FATAL`: makes all undefined behavior sanitizer errors non-recoverable. This option reduces the performance overhead of `ENABLE_UNDEFINED_SANITIZER`. - `ENABLE_COMPILER_EXPLORER_BUILD`: Skip building non-library entities in Lagom (this only applies to Lagom). - `ENABLE_FUZZERS`: builds [fuzzers](../Meta/Fuzzers/README.md) for various parts of the system. - `ENABLE_FUZZERS_LIBFUZZER`: builds Clang libFuzzer-based [fuzzers](../Meta/Fuzzers/README.md) for various parts of the system. - `ENABLE_FUZZERS_OSSFUZZ`: builds OSS-Fuzz compatible [fuzzers](../Meta/Fuzzers/README.md) for various parts of the system. - `ENABLE_ALL_THE_DEBUG_MACROS`: used for checking whether debug code compiles on CI. This should not be set normally, as it clutters the console output and makes the system run very slowly. Instead, enable only the needed debug macros, as described below. - `ENABLE_COMPILETIME_FORMAT_CHECK`: checks for the validity of `std::format`-style format string during compilation. Enabled by default. - `ENABLE_JS_JIT`: builds the optimizing JIT for JavaScript. Enabled by default on x86-64 and AArch64 Linux and macOS, the platforms it generates code for. Without it, LibJS runs JavaScript in its interpreter alone, and the interpreter is built without the feedback collection and tier-up checks that only the JIT needs. See [the configuration of the JIT](../Libraries/LibJS/JIT/ARCHITECTURE.md#13-configuration). - `INCLUDE_WASM_SPEC_TESTS`: downloads and includes the WebAssembly spec testsuite tests. In order to use this option, you will need to install `prettier` and `wasm-tools`. - `INCLUDE_FLAC_SPEC_TESTS`: downloads and includes the xiph.org FLAC test suite. - `LADYBIRD_CACHE_DIR`: sets the location of a shared cache of downloaded files. Should not need to be set manually unless managing a distribution package. - `ENABLE_NETWORK_DOWNLOADS`: allows downloading files from the internet during the build. Default on, turning off enables offline builds. For offline builds, the structure of the LADYBIRD_CACHE_DIR must be set up the way that the build expects. - `ENABLE_CLANG_PLUGINS`: enables Clang plugins which analyze the code for programming mistakes. See [Clang Plugins](#clang-plugins) below. Many parts of the codebase have debug functionality, mostly consisting of additional messages printed to the debug console. This is done via the `_DEBUG` macros, which can be enabled individually at build time. They are listed in [this file](../Meta/CMake/all_the_debug_macros.cmake). To toggle or change a build option, see the [CMake Cache Manipulation](#cmake-cache-manipulation) section below. ## CMake Cache Manipulation CMake caches variables and options in the binary directory. This allows a developer to tailor variables that are `set()` within the persistent configuration cache. There are three main ways to manipulate the cache: - `cmake path/to/binary/dir -DVAR_NAME=Value` - `ccmake` (TUI interface) - `cmake-gui` Options can be set via the initial `cmake` invocation that creates the binary directory to set the initial cache for the binary directory. Once the binary directory exists, any of the three options above can be used to change the value of cache variables. For example, boolean options such as `ENABLE_` or `_DEBUG` can be enabled with the value `ON` and disabled with `OFF`: ```console # Reconfigure an existing binary directory with process debug enabled $ cmake -B Build/ladybird -DPROCESS_DEBUG=ON ``` For more information on how the CMake cache works, see the CMake guide for [Running CMake](https://cmake.org/runningcmake/). Additional context is available in the CMake documentation for [variables](https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#variables) and [set()](https://cmake.org/cmake/help/latest/command/set.html#set-cache-entry). ## Tests For information on running host and target tests, see [Testing](Testing.md). The documentation there also contains useful information for debugging CI test failures. ## Clang-format updates Some OS distributions don't ship bleeding-edge clang-format binaries. Below are 2 options to acquire an updated clang-format tool, in order of preference: 1) If you have a Debian-based (apt-based) distribution, use the [LLVM apt repositories](https://apt.llvm.org) to install the latest release of clang-format. 2) Compile LLVM from source as described in the LLVM documentation [here](https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code). ## Clangd Configuration The repository has a `.clangd` configuration file in the root directory. One of the configuration stanzas in that file specifies the location for a compilation database. Depending on your build configuration (e.g. Release, Debug, Sanitizer), the path to the compilation database in that file may not be correct. You may edit the `.clangd` file to point at your build directory. ## Clang Plugins Clang plugins are used to validate the code at compile time. Currently, they are used to detect JavaScript-related garbage collection faux pas, such as neglecting to visit a garbage-collected type. In order to enable Clang plugins, you will need Clang's development headers installed. For example, on Ubuntu this is the `libclang-dev` package. When Clang plugins are enabled, it is recommended to have the following environment variable set for ccache: ```bash export CCACHE_COMPILERCHECK="%compiler% -v" ``` By default, ccache will include the plugins themselves in file hashes. So if a plugin changes, the hash of every file will change, and you will be stuck with an uncached build. This setting will prevent ccache from using plugins in the file hashes. ## Building the Flatpak Ladybird has an in-tree Flatpak manifest that can be used to build a Flatpak package for Ladybird. The recommended way to build the Flatpak is to use the `flatpak-builder` tool, which is available in most distributions. See the [Flatpak setup documentation](https://flatpak.org/setup/) on how to configure your environment for user Flatpak builds, and to configure the Flathub repo. The Ladybird Flatpak manifest at `Meta/CMake/flatpak/org.ladybird.Ladybird.json` can be built with the following command: ```bash flatpak-builder --user --force-clean --install-deps-from=flathub \ --ccache --repo=Build/repo --install Build/flatpak \ Meta/CMake/flatpak/org.ladybird.Ladybird.json ``` This command will build the Flatpak bundle and install it into the local Flatpak repository at `Build/repo`. Expect this to take a long time, as it will download and build all the dependencies of Ladybird as well. `flatpak-builder` will drop caches and build files in `.flatpak-builder`, as well as in the two subfolders `Build/repo` and `Build/flatpak`. The Flatpak can be run with the following command: ```bash flatpak run --user org.ladybird.Ladybird ``` In order to debug the Flatpak, you can pass the `--devel` and `--command=sh` flags to `flatpak run`. This will drop you into a shell in the Flatpak sandbox: ```bash flatpak run --user --command=sh --devel org.ladybird.Ladybird ``` ## Debugging without any optimizations It’s possible that when trying to inspect certain frame variables in your debugger, you’ll get an error similar to the following: > error: Couldn't look up symbols: __ZN2AK6Detail10StringBaseD2Ev > Hint: The expression tried to call a function that is not present in the target, perhaps because it was optimized out by the compiler. If you do run into such an error, the rest of this section explains how to deal with it. > [!WARNING] > You probably only want to make the build-file change described below while you’re in the middle of examining the state of a particular build in your debugger — and then you’ll want to revert it after you’re done debugging. You otherwise probably don’t want to have the build-file change in place while you’re running WPT tests or in-tree tests and checking the results. 1. At your command-line prompt in your shell environment, copy and paste the following: ```diff $ patch -p1 <`` and related elements. An Agent holds a stack of Execution Contexts, with the topmost entry being the running execution context. Each Execution Context holds a Realm and a specific script's context, including the current function and any state required to pause and resume the execution for that context. The Realm holds the Global Object for the Execution Context, and any ECMAScript or host-specific intrinsics required to create the desired environment for code to run in. More loosely, an Agent is a specification artifact that somewhat maps the execution of a JavaScript script or module to a native thread of execution. But the specification does so in a way that allows a host/embedder to choose to switch out which Agent is currently executing its running execution context on that native thread, and which Realm within that Agent owns the running execution context. SharedArrayBuffers and Atomics add a special kind of wrinkle to the ECMAScript specification. Defining how that work required the formalization of a memory model, similar to what C++11 and C11 and Java 5 had to do before them. The Agent Cluster is the formalism that ties the memory model back to the execution model. As described in the specification, an Agent Cluster is a set of Agents that can communicate via shared memory. The exact mechanism is unspecified, but the hard rule is that all Agents within a particular Agent Cluster must observe the same order of reads and writes to SharedArrayBuffers and as a result of ECMAScript Atomic objects. The net result of all this memory model and atomic specification language is that loosely, an Agent models a "candidate execution" of some code module that can execute on a thread, and any suspended execution contexts from things like generators or async that are part of that module and its dynamic imports. An Agent Cluster models the interaction of agents that share the ability to communicate via shared memory. The simplest reading of this is that the specification authors had in mind the type of memory sharing that threads within the same process have in native code execution. So an Agent Cluster loosely models a collection of Agents (read: threads) that execute independently of each other within the same implementation defined manner for sharing memory between different threads (read: process). ### HTML Execution Model: Global Scopes The Document Object Model (DOM) specifications are written in such a way that implementers can create language bindings for any language to access the page. However, experience has shown that the most popular way to script web content in modern web browsers is through JavaScript bindings. As such, the HTML specification is specifically tailored to meet the constraints of JavaScript execution in its scripting APIs and related concepts. Great care is taken to ensure that JavaScript written by different authors cannot interfere with each other, and that arbitrary scripts cannot exfiltrate information about the page content to third-party destinations. The HTML specification therefore has a section on [Agents and Agent Clusters](https://html.spec.whatwg.org/multipage/webappapis.html#agents-and-agent-clusters) at the start of the section on how scripting behaves on the Web platform. TODO: Finish this section ## HTML Navigation: Juggling Origins ### Global Scopes, Browsing Contexts, Browsing Context Groups, Navigables, and Traversable Navigables TODO: - Agents defined by the HTML Spec - Global Objects (Global Scopes) defined by the HTML Spec - Agents and Browsing Context Groups - Navigables and their relationship to Browsing Contexts - Walk through construction of a browser tab, its traversable navigable, and its navigation both same and cross-origin - Walk through construction of a browser tab with a nested browsing context and what happens when the nested context within its navigable container navigates on its own --- ### Documentation BuildInstructionsLadybird (`Documentation/BuildInstructionsLadybird.md`) # Ladybird browser build instructions ## Build Prerequisites Qt6.10+ development packages, nasm, additional build tools, and a C++23 capable compiler are required. > [!NOTE] > Some distributions still package a Qt6 older than 6.10; for example, Debian 13 (trixie) ships Qt 6.8 — so configuring against it fails. If your Qt6 is older than 6.10, install a newer one from a newer distribution release, or directly from the [Qt online installer](https://www.qt.io/download-open-source), and then point the build to it using `CMAKE_PREFIX_PATH`. A Rust toolchain is also required. You can install it via [rustup](https://rustup.rs/). We currently use gcc-14 and clang-21 in our CI pipeline. If these versions are not available on your system, see [`find_compiler.py`](../Meta/Utils/find_compiler.py) for the minimum compatible version. CMake 3.30 or newer must be available in $PATH. --- ### Debian/Ubuntu: ```bash sudo apt install autoconf autoconf-archive automake build-essential ccache cmake curl fonts-liberation2 git glslang-tools libdrm-dev libgl1-mesa-dev libncurses-dev libpulse-dev libtool libxcb-icccm4-dev nasm ninja-build pkg-config python3-venv qt6-base-private-dev qt6-positioning-dev qt6-tools-dev-tools qt6-wayland tar unzip zip ``` #### CMake 3.30 or newer: - Recommendation: Install `CMake 3.30` or newer from [Kitware's apt repository](https://apt.kitware.com/): > [!NOTE] > Kitware’s apt repository is Ubuntu-only. ```bash # Add Kitware GPG signing key wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null # Optional: Verify the GPG key manually # Use the key to authorize an entry for apt.kitware.com in apt sources list echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/kitware.list # Update apt package list and install cmake sudo apt update -y && sudo apt install cmake -y ``` #### C++23-capable compiler: - Recommendation: Install clang from [LLVM's apt repository](https://apt.llvm.org/): ```bash # Add LLVM GPG signing key sudo wget -O /usr/share/keyrings/llvm-snapshot.gpg.key https://apt.llvm.org/llvm-snapshot.gpg.key # Optional: Verify the GPG key manually # Use the key to authorize an entry for apt.llvm.org in apt sources list echo "deb [signed-by=/usr/share/keyrings/llvm-snapshot.gpg.key] https://apt.llvm.org/$(lsb_release -sc)/ llvm-toolchain-$(lsb_release -sc)-21 main" | sudo tee -a /etc/apt/sources.list.d/llvm.list # Update apt package list and install clang and associated packages sudo apt update -y && sudo apt install clang-21 clangd-21 clang-tools-21 clang-format-21 clang-tidy-21 lld-21 -y ``` - Alternative: Install gcc from [Ubuntu Toolchain PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test): ```bash sudo add-apt-repository ppa:ubuntu-toolchain-r/test sudo apt update && sudo apt install g++-14 libstdc++-14-dev ``` ### Arch Linux/Manjaro: ``` sudo pacman -S --needed autoconf-archive base-devel ccache cmake curl git less libgl libpulse nasm ninja python qt6-base qt6-positioning qt6-tools ttf-liberation tar unzip xcb-util-wm zip ``` ### Fedora or derivatives: ``` sudo dnf install autoconf-archive automake ccache cmake curl git glslang libdrm-devel liberation-sans-fonts libglvnd-devel libtool nasm ncurses-devel ninja-build patchelf perl-FindBin perl-IPC-Cmd perl-lib perl-Time-Piece pulseaudio-libs-devel qt6-qtbase-private-devel qt6-qtpositioning-devel qt6-qttools-devel qt6-qtwayland-devel tar unzip xcb-util-wm-devel zip zlib-ng-compat-static ``` ### openSUSE: ``` sudo zypper install autoconf-archive automake ccache cmake curl gcc14 gcc14-c++ git liberation-fonts libglvnd-devel libpulse-devel libtool nasm ncurses-devel ninja qt6-base-private-devel qt6-positioning-devel qt6-tools-devel qt6-wayland-devel tar unzip xcb-util-wm-devel zip ``` If one or more of the base repository packages are flagged as having an out-of-date version during the build process, you may need add the `devel:tools:building` repository. For example, on Leap 15.6, the `autoconf` package might be version 2.69, whereas the `gperf` package requires 2.70 to build. For Leap 15.6, run the following command to add this repo (you will need to adjust the URL for other openSUSE versions): ``` sudo zypper addrepo https://download.opensuse.org/repositories/devel:tools:building/15.6/devel:tools:building.repo sudo zypper refresh ``` Below is an example printout that might be received depending which versions of autoconf are available for installation: ``` > sudo zypper install autoconf Loading repository data... Reading installed packages... 'autoconf' is already installed. There is an update candidate for 'autoconf' from vendor 'obs://build.opensuse.org/devel:tools', while the current vendor is 'SUSE LLC '. Use 'zypper install autoconf-2.72-80.d_t_b.1.noarch' to install this candidate. Resolving package dependencies... Nothing to do. > sudo zypper install autoconf-2.72-80.d_t_b.1.noarch ``` The build process requires at least python3.7; openSUSE Leap only features Python 3.6 as default, so it is recommendable to install the package `python312` and create a virtual environment (venv) in this case. A virtual environment can be created in your home directory and once the `source` command is issued `python3 --version` will show that the current version is python 3.12 within the virtual environment shell session. ``` python3.12 -m venv ~/python312_venv source ~/python312_venv/bin/activate python3 --version ``` This virtual environment can be created once and reused in future shell sessions by sourcing the generated file `~/python312_venv/bin/activate` again. ### Void Linux: ``` sudo xbps-install -Su # (optional) ensure packages are up to date to avoid "Transaction aborted due to unresolved dependencies." sudo xbps-install -S git bash gcc python3 curl cmake libtool zip unzip linux-headers make pkg-config autoconf automake autoconf-archive nasm ncurses-devel MesaLib-devel ninja pulseaudio-devel qt6-base-private-devel qt6-position-devel qt6-tools-devel qt6-wayland-devel xcb-util-wm-devel ``` ### NixOS or with Nix: A Nix development shell is maintained [here](https://github.com/nix-community/nix-environments/tree/master/envs/ladybird), in the [nix-environments](https://github.com/nix-community/nix-environments/) repository. If you encounter any problems building with Nix, please create an issue there. ### macOS: Xcode 15 or clang from homebrew is required to successfully build ladybird. ``` xcode-select --install brew install autoconf autoconf-archive automake ccache cmake libtool nasm ninja pkg-config qt ``` If you wish to use clang from homebrew instead: ``` brew install llvm@21 ``` > [!NOTE] > It is recommended to add your terminal application (i.e. Terminal.app or iTerm.app) to the system list of developer tools. > Doing so will reduce slow startup time of freshly compiled binaries, due to macOS validating the binary on its first run. > This can be done in the "Developer Tools" section of the "Privacy & Security" system settings. ### Windows: WSL2 is the supported way to build Ladybird on Windows. A native build is also possible, however it is still experimental, and there are several issues. #### WSL2 - Create a WSL2 environment using one of the Linux distros listed above. Ubuntu or Fedora is recommended. - Install the required packages for the selected Linux distro in the WSL2 environment. WSL1 is known to have issues. If you run into problems, please use WSL2. MinGW/MSYS2 are not supported. ##### Clang-CL (experimental) > [!NOTE] > There are still windows specific issues and the functionality is limited. In order to get pkg-config available for the vcpkg install, you can use Chocolatey to install it. To install Chocolatey, see `https://chocolatey.org/install`. Then Install pkg-config using chocolatey. ``` choco install pkgconfiglite -y ``` In a VS command prompt build using ladybird.py: ``` py Meta\ladybird.py build ``` ### Android: On a Unix-like platform, install the prerequisites for that platform and then see the [Android Studio guide](EditorConfiguration/AndroidStudioConfiguration.md). Or, download a version of Gradle >= 8.0.0, and run the ``gradlew`` program in ``UI/Android`` ### FreeBSD ``` pkg install autoconf-archive automake autoconf bash cmake ccache curl gmake gn libdrm libtool libxcb libxkbcommon libX11 libXrender libXi nasm ninja patchelf pkgconf pulseaudio python3 qt6-base qt6-positioning tar unzip zip ``` > [!NOTE] > `zip`, `unzip`, and `tar` are required by the vcpkg bootstrap step. If any of these are missing, > the build will fail with a Python `CalledProcessError` traceback rather than a clear error message. ## Build steps ### Using ladybird.py The simplest way to build and run ladybird is via the ladybird.py script: ```bash # From /path/to/ladybird ./Meta/ladybird.py run ``` On macOS, to build using clang from homebrew: ```bash CC=$(brew --prefix llvm)/bin/clang CXX=$(brew --prefix llvm)/bin/clang++ ./Meta/ladybird.py run ``` You may also choose to start it in `gdb` using: ```bash ./Meta/ladybird.py gdb ladybird ``` The above commands will build a Release version of Ladybird. To instead build a Debug version, run the `Meta/ladybird.py` script with the value of the `BUILD_PRESET` environment variable set to `Debug`, like this: ```bash BUILD_PRESET=Debug ./Meta/ladybird.py run ``` Note that debug symbols are available in both Release and Debug builds. If you want to run other applications, such as the JS REPL or the WebAssembly REPL, specify an executable with `./Meta/ladybird.py run `. To launch an existing binary without configuring, preparing dependencies, or building, use `--no-build`: ```bash ./Meta/ladybird.py run --no-build ./Meta/ladybird.py run --no-build js --evaluate 'console.log(1 + 1)' ./Meta/ladybird.py run --no-build --preset Debug js ``` Put `--no-build` before the executable name; arguments after the name are passed to the executable. The command uses the selected preset's existing build and retains the usual runtime environment, including sanitizer options. It does not update the binary or change its build configuration. ### The User Interfaces Ladybird will be built with one of the following browser frontends, depending on the platform: * [Android UI](https://developer.android.com/develop/ui) - The native UI on Android. * [Qt](https://doc.qt.io/qt-6/) - The UI used on all other platforms. ### Build error messages you may encounter The section lists out some particular error messages you may run into, and explains how to deal with them. #### Unable to find a build program corresponding to "Ninja" This error message is a red herring. We use vcpkg to manage our third-party dependencies, and this error is logged when something went wrong building those dependencies. The output in your terminal will vary depending on what exactly went wrong, but it should look something like: ``` error: building skia:x64-linux failed with: BUILD_FAILED Elapsed time to handle skia:x64-linux: 1.6 s -- Running vcpkg install - failed CMake Error at Build/vcpkg/scripts/buildsystems/vcpkg.cmake:899 (message): vcpkg install failed. See logs for more information: Build/release/vcpkg-manifest-install.log Call Stack (most recent call first): /usr/share/cmake-3.30/Modules/CMakeDetermineSystem.cmake:146 (include) CMakeLists.txt:15 (project) CMake Error: CMake was unable to find a build program corresponding to "Ninja". CMAKE_MAKE_PROGRAM is not set. You probably need to select a different build tool. -- Configuring incomplete, errors occurred! See logs for more information: Build/release/vcpkg-manifest-install.log ``` If the error is not immediately clear from the terminal output, be sure to check the specified `vcpkg-manifest-install.log`. for more information. ### Resource files Ladybird requires resource files from the ladybird/Base/res directory in order to properly load icons, fonts, and other theming information. These files are copied into the build directory by special CMake rules. The expected location of resource files can be tweaked by packagers using the standard CMAKE_INSTALL_DATADIR variable. CMAKE_INSTALL_DATADIR is expected to be a path relative to CMAKE_INSTALL_PREFIX. If it is not, things will break. ### Custom CMake build directory The script Meta/ladybird.py and the Release preset in CMakePresets.json both define a build directory of `Build/release`. For distribution purposes, or when building multiple configurations, it may be useful to create a custom CMake build directory. The install rules in UI/cmake/InstallRules.cmake define which binaries and libraries will be installed into the configured CMAKE_PREFIX_PATH or path passed to ``cmake --install``. Note that when using a custom build directory rather than Meta/ladybird.py, the user may need to provide a suitable C++ compiler (see [Build Prerequisites](BuildInstructionsLadybird.md#build-prerequisites)) via the CMAKE_C_COMPILER and CMAKE_CXX_COMPILER cmake options. ``` cmake --preset Release -B MyBuildDir # optionally, add -DCMAKE_CXX_COMPILER= -DCMAKE_C_COMPILER= cmake --build --preset Release MyBuildDir ninja -C MyBuildDir run-ladybird ``` ### Building with limited system memory The default build mode will run as many build steps in parallel as possible, which includes link steps; this may be an issue for users with limited system memory (or users building with fat LTO in general). If you wish to reduce the number of parallel link jobs, you may use the LAGOM_LINK_POOL_SIZE cmake option to set a maximum limit for the number of parallel link jobs. ``` cmake --preset Release -B MyBuildDir -DLAGOM_LINK_POOL_SIZE=2 ``` ### Running manually The Meta/ladybird.py script will execute the `run-ladybird` and `debug-ladybird` custom targets. If you don't want to use the ladybird.py script to run the application, you can run the following commands: To automatically run in gdb: ``` ninja -C Build/release debug-ladybird ``` To run without ninja rule on non-macOS systems: ``` ./Build/release/bin/Ladybird ``` To run without ninja rule on macOS: ``` open -W --stdout $(tty) --stderr $(tty) ./Build/release/bin/Ladybird.app # Or to launch with arguments: open -W --stdout $(tty) --stderr $(tty) ./Build/release/bin/Ladybird.app --args https://ladybird.dev ``` ### Debugging with CLion Ladybird should be built with debug symbols first. This can be done by adding `-DCMAKE_BUILD_TYPE=Debug` to the cmake command line, or selecting the Build Type Debug in the CLion CMake profile. After running Ladybird as suggested above with `./Meta/ladybird.py run ladybird`, you can now in CLion use Run -> Attach to Process to connect. If debugging layout or rendering issues, filter the listing that opens for `WebContent` and attach to that. Now breakpoints, stepping and variable inspection will work. ### Debugging with Xcode or Instruments on macOS If all you want to do is use Instruments, then an Xcode project is not required. Simply run the `ladybird.py` script as normal with a debug-style build. The build automatically signs the app bundle with the entitlements from `Meta/DebugEntitlements.plist`, which includes `get-task-allow` for debugger and Instruments attachment. Now you can open the Instruments app and point it to the Ladybird app bundle. Building the project with Xcode is not supported. The Xcode project generated by CMake does not properly execute custom targets, and does not handle all target names in the project. --- ### Documentation BuildProfilingInstructions (`Documentation/BuildProfilingInstructions.md`) # Build profiling instructions There are three ways you can get information about compile times: 1. Just using `time ninja install` instead of `ninja install` to time it overall. 2. Reading ninja's log files to get a per-file compile time. 3. Enabling GCC or Clang flags to get a more detailed per-file breakdown of times for compiler passes within a file. ## Ninja log files Ninja produces a handy log file that includes a per-cpp-file compilation time. This is useful for discovering which files take the most time, and so are good targets for speeding up the overall build time. A python3 script named `ninjatracing` converts the ninja log file into a JSON format that's readable by several profile viewers. ### Prerequisites `ninjatracing` is available on [GitHub](https://github.com/nico/ninjatracing/blob/master/ninjatracing) It requires `python3`, available at `python`. You can either create the symlink yourself, or just modify the ninjatracing file to say `python3` instead of `python`. You also need to make sure `ninjatracing` is marked as executable, and available from your PATH (or somewhere convenient where you can manually call it from). ### Usage First, we need to clean the build (and `ccache` if present) to make sure every file gets compiled and gives a meaningful time reading. ```console ninja clean ccache --clear ``` Then, execute ninja as normal: ```console ninja ``` The log will be written to `.ninja_log` in the current directory by default. To convert it to the more useful JSON file, call `ninjatracing` from the directory you called ninja from: ```console ninjatracing .ninja_log > trace.json ``` You can then drag-and-drop the file onto [Speedscope](https://www.speedscope.app/) or any other compatible flamegraph visualizer. ## GCC/Clang Adding the `-ftime-report` flag to GCC will cause it to output a breakdown for each file it compiles, which looks like this:
GCC -ftime-report output ``` /* Detailed source-code truncated for AI context efficiency. */ ```
Depending on whether you understand the internals of the compiler, this may or may not be helpful to you! Generally, this is not recommended. Clang also supports `-ftime-report`, but I have not tested the output for it. To add the flag, edit the `CMakeLists.txt` in the ladybird root directory, and add `add_compile_options(-ftime-report)` to the list of compile options that start around line 220. Additionally, you can add `-ftime-report-details` too, which again I have not tested. --- ### Documentation CSSGeneratedFiles (`Documentation/CSSGeneratedFiles.md`) # CSS Generated Files We generate a significant amount of CSS-related code, taking in one or more .json files in [`Libraries/LibWeb/CSS`](../Libraries/LibWeb/CSS) and producing C++ code from them, located in `Build//Libraries/LibWeb/CSS/`. It's likely that you'll need to work with these if you add or modify a CSS property or its values. The generators are found in [`Meta/Generators`](../Meta/Generators). They are run automatically as part of the build, and most of the time you can ignore them. ## Properties.json Each CSS property has an entry here, which describes what values it accepts, whether it's inherited, and similar data. This generates `PropertyID.h`, `PropertyID.cpp`, `GeneratedCSSStyleProperties.h`, `GeneratedCSSStyleProperties.cpp` and `GeneratedCSSStyleProperties.idl`. Most of this data is found in the information box for that property in the relevant CSS spec. The file is organized as a single JSON object, with keys being property names, and the values being the data for that property. Each property will have some set of these fields on it: (Note that required fields are not required on properties with `legacy-alias-for` or `logical-alias-for` set.) | Field | Required | Default | Description | Generated functions | |-------------------------------------|----------|------------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `affects-layout` | No | `true` | Boolean. Whether changing this property will invalidate the element's layout. | `bool property_affects_layout(PropertyID)` | | `affects-stacking-context` | No | `false` | Boolean. Whether this property can cause a new stacking context for the element. | `bool property_affects_stacking_context(PropertyID)` | | `animation-type` | Yes | | String. How the property should be animated. Defined by the spec. See below. | `AnimationType animation_type_from_longhand_property(PropertyID)` | | `inherited` | Yes | | Boolean. Whether the property is inherited by its child elements. Only applicable to longhand properties. | `bool is_inherited_property(PropertyID)` | | `initial` | Yes | | String. The property's initial value if it is not specified. | `NonnullRefPtr property_initial_value(PropertyID)` | | `legacy-alias-for` | No | Nothing | String. The name of a property this is an alias for. See below. | | | `logical-alias-for` | No | Nothing | An object. See below. | `bool property_is_logical_alias(PropertyID);`
`PropertyID map_logical_alias_to_physical_property(PropertyID, LogicalAliasMappingContext const&)` | | `longhands` | No | `[]` | Array of strings. If this is a shorthand, these are the property names that it expands out into. | `Vector longhands_for_shorthand(PropertyID)`
`Vector expanded_longhands_for_shorthand(PropertyID)`
`Vector shorthands_for_longhand(PropertyID)` | | `max-values` | No | `1` | Integer. How many values can be parsed for this property. eg, `margin` can have up to 4 values. | | | `multiplicity` | No | `"single"` | String. Category for whether this property is a single value or a list of values. See below. | `bool property_is_single_valued(PropertyID)`
`bool property_is_list_valued(PropertyID)` | | `percentages-resolve-to` | No | Nothing | String. What type percentages get resolved to. eg, for `width` percentages are resolved to `length` values. | `Optional property_resolves_percentages_relative_to(PropertyID)` | | `positional-value-list-shorthand` | No | `false` | Boolean. Whether this property is a "positional value list shorthand". See below. | `bool property_is_positional_value_list_shorthand(PropertyID)` | | `quirks` | No | `[]` | Array of strings. Some properties have special behavior in "quirks mode", which are listed here. See below. | | | `requires-computation` | Yes | | String. When a property's value needs to be run through the computation process. See below. | `bool property_requires_computation_with_inherited_value(PropertyID)`
`bool property_requires_computation_with_initial_value(PropertyID)`
`bool property_requires_computation_with_cascaded_value(PropertyID)` | | `valid-identifiers` | No | `[]` | Array of strings. Which keywords the property accepts. See below. | `bool property_accepts_keyword(PropertyID, Keyword)` | | `valid-types` | No | `[]` | Array of strings. Which value types the property accepts. See below. | `bool property_accepts_type(PropertyID, ValueType)` | | `needs-layout-for-getcomputedstyle` | No | `false` | Boolean. Whether this property requires up-to-date layout before it could be queried by getComputedStyle() | `bool property_needs_layout_for_getcomputedstyle(PropertyID)` | ### `animation-type` The [Web Animations spec](https://www.w3.org/TR/web-animations/#animation-type) defines the valid values here: | Spec term | JSON value | |-------------------|---------------------| | not animatable | `none` | | discrete | `discrete` | | by computed value | `by-computed-value` | | repeatable list | `repeatable-list` | | (See prose) | `custom` | ### `legacy-alias-for` (Not to be confused with `logical-alias-for` below.) [Legacy name aliases](https://drafts.csswg.org/css-cascade-5/#legacy-name-alias) are properties whose spec names have changed, but the syntax has not, so setting the old one is defined as setting the new one directly. For example, `font-stretch` was renamed to `font-width`, so `font-stretch` is now a legacy name alias for `font-width`. ### `logical-alias-for` (Not to be confused with `legacy-alias-for` above.) Logical aliases are properties like `margin-block-start`, which may assign a value to one of several other properties (`margin-top`, `margin-bottom`, `margin-left`, or `margin-right`) depending on the element they are applied to. `logical-alias-for` should be an object with two fields, both of which are required: | Field | Description | |-----------|-------------------------------------------------------------------------------------------------------------------------------------| | `group` | String. Name of the logical property group this is associated with. (See [LogicalPropertyGroups.json](#logicalpropertygroupsjson).) | | `mapping` | String. How this relates to the group. eg, if it's the block end value, `block-end`. | ### `multiplicity` The three possible values are `"single"`, `"list"`, and `"coordinating-list"`. Most properties represent a single "thing", possibly made of multiple parts. For example, `border` takes a color, style and thickness, but it's still a single border. Others are a list: `background` takes multiple layers, separated by commas; `counter-increment` doesn't have commas but also is a list of counters that are incremented. Lists can also be [coordinating list properties](https://drafts.csswg.org/css-values-4/#linked-properties), in which case they are marked as `coordinating-list` instead of `list`. ### `positional-value-list-shorthand` Some shorthand properties work differently to normal in that mapping of provided values to longhands isn't necessarily 1-to-1 and instead depends on the number of values provided, for example `margin`, `border-width`, `gap`, etc. These properties have distinct behaviors in how they are parsed and serialized, having them marked allows us to implement this behavior in a generic way. ### `quirks` The [Quirks spec](https://quirks.spec.whatwg.org/#css) defines these. | Spec term | JSON value | |------------------------------|----------------------| | The hashless hex color quirk | `hashless-hex-color` | | The unitless length quirk | `unitless-length` | ### `requires-computation` There are three ways the specified value of a property on an element can be determined: - Inherited, e.g. it is an inherited property and no value has been specified, or the `inherit` keyword has been specified - Initial, e.g. it is _not_ an inherited property and no value has been specified, or the `initial` keyword has been specified - Cascaded, a value has been cascaded for this element based on the styles We then turn that specified value into a computed value by running the computation (see `StyleComputer::compute_value_of_property`). Depending on the property, we know that for some of the above cases the computed value is guaranteed to be the same as the specified value, by specifying the cases where it _isn't_ we can limit running the computation process to only when required. | Value | Behavior | | --------------------- | ------------------------------------------------------------------------------------------------------------- | | `always` | Always runs the computation process, regardless of how the specified value was determined | | `non-inherited-value` | Only run the computation process if the specified value was determined based on the initial or cascaded value | | `cascaded-value` | Only run the computation process if the specified value was determined based on a cascaded value | | `never` | Always skip the computation process | ### `valid-identifiers` A list of CSS keyword names, that the property accepts. Consider defining an enum instead and putting its name in the `valid-types` array, especially if the spec provides a name to a set of such keywords. Some properties have [legacy value aliases](https://drafts.csswg.org/css-cascade-5/#css-legacy-value-alias), where one keyword is parsed as another. These are supported as `"foo>bar"`, to make `foo` an alias for `bar`. ### `valid-types` The `valid-types` array lists the names of CSS value types, as defined in the latest [CSS Values and Units spec](https://www.w3.org/TR/css-values/), without the `<>` around them. For numeric types, we use the [bracketed range notation](https://www.w3.org/TR/css-values-4/#css-bracketed-range-notation), for example `width` can take any non-negative length, so it has `"length [0,∞]"` in its `valid-types` array. For ``s, the excluded identifiers are placed within `![]`, for example `"custom-ident ![all,none]"`. ## LogicalPropertyGroups.json A set of matching CSS properties can be grouped together in what's called a ["logical property group"](https://drafts.csswg.org/css-logical-1/#logical-property-group). For example, all of the `margin-*` properties are in the `margin` group. This data is used to map logical properties (such as `margin-block-start`) into their physical counterparts (like `margin-top`) at runtime, depending on the writing direction. We don't generate any code directly from this file. Instead, it's used as part of generating the PropertyID code. The file is a single object where the keys are the names of the logical property groups, and their values are objects mapping physical dimensions, sides, or corners to the relevant property. Which keys are there depends on the group - for example the `size` group has `width` and `height`. ## Descriptors.json Descriptors are basically properties, but for at-rules instead of style. The overall structure is a JSON object, with keys being at-rule names and the values being data about those at-rules. The main part is the data about the descriptors that the at-rule can have. The generated code provides: - An `AtRuleID` enum, mostly used as a parameter for parsing descriptors, as multiple at-rules may have descriptors with the same name. - `FlyString to_string(AtRuleID)`, mostly for debug logging. - A `DescriptorID` enum, listing every descriptor. - `Optional descriptor_id_from_string(AtRuleID, Utf16View)` for getting a DescriptorID from a string, if it exists in that at-rule. - `Utf16FlyString const& to_string(DescriptorID)` for serializing descriptor names. - `bool at_rule_supports_descriptor(AtRuleID, DescriptorID)` to query if the given at-rule allows the descriptor. - `RefPtr descriptor_initial_value(AtRuleID, DescriptorID)` for getting a descriptor's initial value. ### At-rule fields Each at-rule object has the following fields. Both are required. | Field | Description | |----------------------|----------------------------------------------------------------------------------------------------------------------| | `spec` | String. URL to the spec that defines this at-rule. | | `descriptors` | Object, with keys being descriptor names and values being objects of their properties. See below. | | `custom-descriptors` | Object, the configuration for custom descriptors (i.e. --foo). Omission means that custom descriptors are disallowed | ### Descriptor fields Each descriptor object can have the following fields: | Field | Default | Required | Description | |------------------------------------------|---------|----------|--------------------------------------------------------------------------------------------------------| | `allow-arbitrary-substitution-functions` | `false` | No | Boolean. Whether this descriptor supports arbitrary substitution functions | | `allow-css-wide-keywords` | `false` | No | Boolean. Whether PropertyID based parsing should include CSS-wide keywords (e.g. `initial`, `inherit`) | | `initial` | Nothing | No | String. The descriptor's initial value if none is provided. | | `legacy-alias-for` | Nothing | No | String. The name of a different descriptor that this is an alias for. | | `syntax` | N/A | Yes | Array of strings. Each string is one option, taken from the spec. | | `FIXME` or `NOTE` | Nothing | No | Strings, for when you want to leave a note. | ### Custom descriptor fields Each custom descriptor object has the following fields | Field | Default | Required | Description | |------------------------------------------|---------|----------|--------------------------------------------------------------------------------------------------------| | `allow-arbitrary-substitution-functions` | `false` | No | Boolean. Whether this descriptor supports arbitrary substitution functions | | `allow-css-wide-keywords` | `false` | No | Boolean. Whether PropertyID based parsing should include CSS-wide keywords (e.g. `initial`, `inherit`) | | `syntax` | N/A | Yes | Array of strings. Each string is one option. | | `FIXME` or `NOTE` | Nothing | No | Strings, for when you want to leave a note. | ## Keywords.json This is a single JSON array of strings, each of which is a CSS keyword, for example `auto`, `none`, `medium`, or `currentcolor`. This generates `Keyword.h` and `Keyword.cpp`. All keyword values used by any property or media-feature need to be defined here. The generated code provides: - A `Keyword` enum as used by `KeywordStyleValue` - `Optional keyword_from_string(StringView)` to attempt to convert a string into a Keyword - `StringView string_from_keyword(Keyword)` to convert a Keyword back into a string - `bool is_css_wide_keyword(StringView)` which returns whether the string is one of the special "CSS-wide keywords" ## Enums.json This is a single JSON object, with enum names as keys and the values being arrays of keyword names. This generates `Enums.h` and `Enums.cpp`. We often want to define an enum that's a set of a few keywords. `Enums.json` allows you to generate these enums automatically, along with functions to convert them to and from a Keyword, or convert them to a string. These enums also can be used in property definitions in `Properties.json` by putting their name in the `valid-types` array. This helps reduce repetition, for example the `border-*-style` properties all accept the same set of keywords, so they are implemented as a `line-style` enum. The generated code provides these for each enum, using "foo" as an example: - A `Foo` enum for its values - `Optional keyword_to_foo(Keyword)` to convert a `Keyword` to a `Foo` - `Keyword to_keyword(Foo)` to convert the `Foo` back to a `Keyword` - `StringView to_string(Foo)` to convert the `Foo` directly to a string ## PseudoClasses.json This is a single JSON object, with selector pseudo-class names as keys and the values being objects with fields for the pseudo-class. This generates `PseudoClass.h`. Each entry has the following properties: | Field | Required | Default | Description | |----------------------|----------------------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `argument` | Unless `legacy-alias-for` is specified | Nothing | A string containing the grammar for the pseudo-class's function parameters - for identifier-style pseudo-classes it is left blank. The grammar is taken directly from the spec. | | `legacy-alias-for` | No | Nothing | Use to specify that this should be treated as a [legacy selector alias](https://drafts.csswg.org/selectors/#legacy-selector-alias) for the named pseudo-class. | The generated code provides: - A `PseudoClass` enum listing every pseudo-class name ## PseudoElements.json This is a single JSON object, with pseudo-element names as keys and the values being objects with fields for the pseudo-element. This generated `PseudoElement.h` and `PseudoElement.cpp`. Each entry has the following properties: | Field | Required | Default | Description | |----------------------|----------------------------|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `alias-for` | No | Nothing | Use to specify that this should be treated as an alias for the named pseudo-element. | | `function-syntax` | No | Nothing | Syntax for the function arguments if this is a function-type pseudo-element. Copied directly from the spec. | | `implementation` | Unless `type` is "function | Nothing | How this pseudo-element is implemented, either `"synthetic"` or `"element-reference"` - see below. | | `is-allowed-in-has` | No | `false` | Whether this is a [`:has`-allowed pseudo-element](https://drafts.csswg.org/selectors/#has-allowed-pseudo-element). | | `is-element-backed` | No | `false` | Whether this is an [element-backed pseudo-element](https://drafts.csswg.org/css-pseudo-4/#element-backed). | | `is-highlight` | No | `false` | Whether this is a [highlight pseudo-element](https://drafts.csswg.org/css-pseudo-4/#highlight-pseudos). | | `is-pseudo-root` | No | `false` | Whether this is a [pseudo-element root](https://drafts.csswg.org/css-view-transitions/#pseudo-element-root). | | `is-tree-abiding` | No | `false` | Whether this is a [tree-abiding pseudo-element](https://drafts.csswg.org/css-pseudo-4/#tree-abiding). | | `property-whitelist` | No | Nothing | Some pseudo-elements only permit certain properties. If so, name them in an array here. Some special values are allowed here for categories of properties - see below. | | `spec` | No | Nothing | Link to the spec definition, for reference. Not used in generated code. | | `type` | No | `"identifier"` | What type of pseudo-element is this. Either "identifier", "function", or "both". | The generated code provides: - A `PseudoElement` enum listing every pseudo-element name - `StringView pseudo_element_name(PseudoElement)` to convert a `PseudoElement` back into a string - `bool is_tree_abiding_pseudo_element(PseudoElement)` returns whether the pseudo-element is tree-abiding - `bool is_pseudo_element_root(PseudoElement)` returns whether the pseudo-element is a [pseudo-element root](https://drafts.csswg.org/css-view-transitions/#pseudo-element-root) - `bool is_highlight_pseudo_element(PseudoElement)` returns whether the pseudo-element is a [highlight pseudo-element](https://drafts.csswg.org/css-pseudo-4/#highlight-pseudos) ### `property-whitelist` This is an array of strings. Properties can be named directly ("color"), or categories of properties with a leading `#` ("#font-properties"), as the specs often says a group is allowed instead of listing the properties exactly. Any properties we don't support yet can be prefixed with "FIXME:" and will be ignored. The property groups and the properties that always apply are defined in `PseudoElementPropertyGroups.txt` and generated into the Rust cascade tables. The following categories are supported: - `#background-properties`: `background` and its longhands - `#border-properties`: `border`, `border-radius`, and their longhands - `#custom-properties`: Custom properties, AKA CSS variables - `#font-properties`: `font`, its longhands, and other `font-*` properties - `#inline-layout-properties`: Properties defined in [CSS Inline](https://drafts.csswg.org/css-inline-3/) - `#inline-typesetting-properties`: Properties defined in [CSS Text](https://drafts.csswg.org/css-text-4/) - `#margin-properties`: `margin` and its longhands - `#padding-properties`: `padding` and its longhands - `#text-decoration-properties`: Properties defined in [CSS Text Decoration](https://drafts.csswg.org/css-text-decor-4/) ### `implementation` Pseudo-elements are implemented in two ways, either: - "synthetic": The originating element is authoritative for the pseudo-element's data (e.g. animations, computed style, etc) and handles it's behavior (such as generating layout nodes) itself. This includes pseudo-elements such as "::first-line" and "::before" - "element-reference": The pseudo-element refers to a "real" element elsewhere in the DOM, usually in the originating element's shadow tree, and is thus not authoritative. This includes, among others, form pseudo-elements such as "::placeholder". NOTE: "element-reference" is an implementation detail and is distinct from the spec concept of "element-backed" pseudo-elements, at time of writing all "element-backed" pseudo-elements are "element-reference", but not vice versa. ## MediaFeatures.json This is a single JSON object, with media-feature names as keys and the values being objects with fields for the media-feature. This generates `MediaFeatureID.h`. A `` is a value that a media query can inspect. They are listed in the [`@media` descriptor table](https://www.w3.org/TR/mediaqueries-5/#media-descriptor-table) in the latest Media Queries spec. The definitions here are like a simplified version of the `Properties.json` definitions. | Field | Description | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | String. How the media-feature is evaluated, either `discrete` or `range`. | | `values` | Array of strings. These are directly taken from the spec, with keywords as they are, and `<>` around type names. Types may be ``, ``, ``, ``, or ``. | | `false-keywords` | Array of strings. These are any keywords that should be considered false when the media feature is evaluated as `@media (foo)`. Generally this will be a single value, such as `"none"`. | The generated code provides: - A `MediaFeatureID` enum, listing each media-feature ## MathFunctions.json This is a single JSON object, describing each [CSS math function](https://www.w3.org/TR/css-values/#math-function), with the keys being the function name and the values being objects describing that function's properties. This generates `MathFunctions.h` and `MathFunctions.cpp`. Each entry has two properties: | Field | Description | |------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `parameter-validation` | Optional string. Either "same" or "consistent", depending on whether the spec says the input calculations should be the same type or consistent types. Defaults to "same". Ignore this if there is only one parameter. | | `parameters` | An array of parameter definition objects, see below. | Parameter definitions have the following properties: | Field | Description | |------------|----------------------------------------------------------------------------------| | `name` | String. Name of the parameter, as given in the spec. | | `type` | String. Accepted types for the parameter, as a single string, separated by `\|`. | | `required` | Boolean. Whether this parameter is required. | The generated code provides: - A `MathFunction` enum listing the math functions - The implementation of the CSS Parser's `parse_math_function()` method ## TransformFunctions.json This is a single JSON object, describing each [CSS transform function](https://www.w3.org/TR/css-transforms/#transform-functions), with the keys being the function name and the values being objects describing that function's properties. This generates `TransformFunctions.h`, and the Rust parser and serializer read it directly. Each entry currently has a single property, `parameters`, which is an array of parameter definition objects. Parameter definitions have the following properties: | Field | Description | |------------|----------------------------------------------| | `type` | String. Accepted type for the parameter. | | `required` | Boolean. Whether this parameter is required. | The generated code provides: - A `TransformFunction` enum listing the transform functions ## EnvironmentVariables.json This is a single JSON object, describing each [CSS environment variable](https://drafts.csswg.org/css-env/#css-environment-variable), with the keys being the environment variable names, and the values being objects describing the variable's properties. This generates `EnvironmentVariable.h` and `EnvironmentVariable.cpp`. Each entry has 3 properties, all taken from the spec: | Field | Description | |--------------|---------------------------------------------------------------------| | `spec` | String. URL to the spec definition for this environment variable. | | `type` | String. CSS value type of the variable, eg ``. | | `dimensions` | Integer. Number of dimensions for the variable, or `0` for scalars. | The generated code provides: - An `EnvironmentVariable` enum listing the environment variables - `StringView to_string(EnvironmentVariable)` to convert the `EnvironmentVariable` back to a string - `ValueType environment_variable_type(EnvironmentVariable)` to get the variable's value type - `u32 environment_variable_dimension_count(EnvironmentVariable)` to get its dimension count ## Units.json This is a JSON object with the keys being dimension type names, and the values being objects. Those objects' keys are unit names, and their values are data about each unit. It generates `Units.h` and `Units.cpp`. Each unit has the following properties: | Field | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------------------| | `is-canonical-unit` | Boolean, default `false`. Each dimension has one canonical unit. | | `number-of-canonical-unit` | Number. How many of the canonical units 1 of this is equivalent to. Ignore this for relative units, and the canonical unit itself. | | `is-relative-to` | String. Some length units are relative to the font or viewport. Set this to `"font"` or `"viewport"` for those. | The generated code provides: - A `DimensionType` enum, listing each type of dimension that has units defined. - `Optional dimension_for_unit(StringView)` for querying which dimension a unit applies to, if any. - A `FooUnit` enum for each dimension "foo", which lists all the units of that dimension. - For each of those... - `constexpr FooUnit canonical_foo_unit()` which is the canonical unit for that type. - `Optional string_to_foo_unit(StringView)` for parsing a unit from a string. - `StringView to_string(FooUnit)` for serializing those units. - `bool units_are_compatible(FooUnit, FooUnit)` which returns whether these are compatible - basically whether you can convert from one to the other. - `double ratio_between_units(FooUnit, FooUnit)` to get a multiplier for converting the first unit into the second. - `bool is_absolute(LengthUnit)`, `bool is_font_relative(LengthUnit)`, `bool is_viewport_relative(LengthUnit)`, and `bool is_relative(LengthUnit)` for checking the category of length units. --- ### Documentation CSSProperties (`Documentation/CSSProperties.md`) # Adding or Modifying a CSS Property There are several different places you need to make changes in order to add or modify a CSS property. These are listed below in the order that Ladybird deals with them, starting at parsing and ending with them being used. ## Data The first place you will need to go to is `CSS/Properties.json`. This file contains the definition for each property, and is used to generate the `PropertyID` enum and a selection of functions. You may also need to modify `CSS/Keywords.json`, `CSS/Enums.json`, and `CSS/LogicalPropertyGroups.json`. See [CSSGeneratedFiles.md](CSSGeneratedFiles.md) for details. ## Parsing For many properties, there is no need to add custom parsing code. Properties that take a single value, or shorthands that are a list of their longhand properties, will be parsed automatically using the data in `Properties.json`. However, there are many CSS properties with more complicated grammar and so they require custom parsing. Property-parsing code goes in `CSS/Parser/PropertyParsing.cpp`, and `CSS/Parser/Parser.h`. First, `Parser::parse_css_value()` is called, which has a switch for specific properties. Call your method from there. It should return a `RefPtr` to a `StyleValue` or one of its subclasses. For shorthands, you should normally use `ShorthandStyleValue`, which automatically expands its longhand values. You might need to modify `ShorthandStyleValue::to_string` if your shorthand has special serialization rules. For example, `border-radius` serializes with a `/` separating the horizontal and vertical components. If your property's value can't be represented with an existing type, you might need to add a new style value class. If you need to do this, pester @AtkinsSJ until he gets around to documenting it. ;^) ## Computed style After parsing and style computation, longhand properties are stored as `StyleValue` pointers in `ComputedProperties`. Any shorthands have been expanded out, and so we do not need to store them directly. These longhands then need to be converted to a more usable form. To do this, add a getter to `ComputedProperties` with the same name as the property. It should return a type that holds the value in a compact form. Then, `CSS/ComputedValues.h` contains three classes that are relevant: - `ComputedValues` holds the computed value of each property, in a flat format. Depending on whether the property is inherited or not, it needs adding to the `m_inherited` or `m_noninherited` structs, with a corresponding getter. - `MutableComputedValues` also needs a setter for the value. - `InitialValues` has a getter for the default value of the property. This isn't always needed, for example if the default computed value is an empty `Optional` or `Vector`. Style is copied from `ComputedProperties` to `ComputedValues` in `NodeWithStyle::apply_style()`. Each property is copied individually. Then, read the value of your property with that `ComputedValues` getter we added. For example, this code reads the computed values of `visibility` and `opacity`: ```c++ bool Paintable::is_visible() const { auto const& computed_values = this->computed_values(); return computed_values.visibility() == CSS::Visibility::Visible && computed_values.opacity() != 0; } ``` ## JavaScript Some properties have special rules for getting the computed value from JS. For these, you will need to add to `CSSStyleProperties::style_value_for_computed_property()`. Shorthands that are serialized in an unusual way also need handling inside `CSSShorthandStyleValue::to_string()`. --- ### Documentation CodePolicy (`Documentation/CodePolicy.md`) # Code Policy This document describes expectations for code maintained in upstream Ladybird. It is primarily intended for project maintainers and people studying local Ladybird development. ## Testing policy When possible, code changes should include tests when fixing bugs or adding new features. If changes have relevant [Web Platform Tests (WPT)](https://wpt.fyi/) tests - especially if the changes cause Ladybird to pass any WPT tests it had not yet been passing - consider [importing those tests into the Ladybird tree](Testing.md#importing-web-platform-tests), and then committing the imported tests along with the code changes. ## Human language policy In Ladybird, we treat human language as seriously as we do programming language. The following applies to all user-facing strings, code, comments, and commit messages: * The official project language is American English with ISO 8601 dates and metric units. * Use proper spelling, grammar, and punctuation. * Write in an authoritative and technical tone. * Avoid contractions, slang, and idioms. * Avoid humor, sarcasm, and other forms of non-literal language. * Use gender-neutral pronouns, except when referring to a specific person. Note that this also applies to debug logging and other internal strings, as they may be exposed to users in the future. ## Code policy Nobody is perfect, and sometimes we mess things up. That said, here are some good do's & don'ts to try and stick to: **Do:** * Write in idiomatic project-style C++23, using the `AK` containers in all code. * Conform to the project coding style found in [CodingStyle.md](CodingStyle.md). Use `clang-format` to automatically format C++ files. * Choose expressive variable, function and class names. Make it as obvious as possible what the code is doing. * Split your changes into separate, atomic commits (i.e. A commit per feature or fix, where the build, tests and the system are all functioning). * Make sure your commits are rebased on the master branch. * Wrap your commit messages at 72 characters. * The first line of the commit message is the subject line, and must have the format "Category: Brief description of what's being changed". The category should be the name of a library, application, service, utility, etc. * Examples: `LibMedia`, `WebContent`, `CI`, `AK`, `RequestServer`, `js` * Don't use a category like "`Libraries`" or "`Utilities`", except for generic changes that affect a large portion of code within these directories. * Don't use specific component names, e.g. C++ class names, as the category either - mention them in the summary instead. E.g. `LibGUI: Brief description of what's being changed in FooWidget` rather than `FooWidget: Brief description of what's being changed` * Several categories may be combined with `+`, e.g. `LibJS+LibWeb+Browser: ...` * Write the commit message subject line in the imperative mood ("Foo: Change the way dates work", not "Foo: Changed the way dates work"). * Write your commit messages in proper English, with care and punctuation. * Amend existing commits when adding changes after a review, where relevant. * Mark each review comment as "resolved" after pushing a fix with the requested changes, where relevant. * Add your personal copyright line to files when making substantive changes. (Optional but encouraged!) * Check the spelling of your code, comments and commit messages. * If you have images that go along with your code, run `optipng -strip all` on them to optimize and strip away useless metadata - this can reduce file size from multiple kilobytes to a couple hundred bytes. **Don't:** * Introduce changes that are incompatible with the project licence (2-clause BSD.) * Touch anything outside the stated scope of the change. * Iterate excessively on your design across multiple commits. * Use weasel-words like "refactor" or "fix" to avoid explaining what's being changed. * End commit message subject lines with a period. * Include commented-out code. * Write in C. (Instead, take advantage of C++'s amenities, and don't limit yourself to the standard C library.) * Attempt large architectural changes until you are familiar with the system and have worked on it for a while. * Engage in excessive "feng shui programming" by moving code around without quantifiable benefit. * Add jokes or other "funny" things to user-facing parts of the system. ## On usage of AI and LLMs Usage of AI assistance is usually fine, but you are responsible for making sure the quality of the output is up to the standards of the project. Currently, AI-generated output is often too verbose and its quality is subpar compared to carefully written human work. Do not use an AI or LLM to generate changes, respond to issues, or participate in project discussion without holding the output to the same standards as human-written content. Do not use AI-generated descriptions or summaries as a substitute for understanding the relevant code, issue, or discussion. ## Commit hooks The repository contains a file called `.pre-commit-config.yaml` that defines several commit hooks that can be run automatically just before and after creating a new commit. These hooks lint your commit message, and the changes it contains to ensure they will pass the automated CI checks. The Python and workflow lint scripts use the versions pinned in `Meta/Linters/requirements.txt`, including when called by commit hooks or CI. They prepare a virtual environment under `Build/linters` on first use and reuse it afterward. Python with `venv` and `pip` support is required; the first setup downloads the pinned tools. Changing the requirements or Python interpreter selects a fresh environment. Concurrent invocations share a setup lock. To prepare the environment in advance or run a pinned tool directly: ```console python3 Meta/Linters/run.py python3 Meta/Linters/run.py ruff --version python3 Meta/Linters/run.py ruff check Meta/ladybird.py ``` Once prepared, the environment can be reused without downloading the packages again. Delete `Build/linters` to clear the cache when no linters are running. To enable these hooks, first follow the installation instructions available at https://pre-commit.com/#install and then enable one or both of the following hooks: * pre-commit hook - Runs `Meta/lint-ci.sh` and `Meta/lint-ports.py` to ensure changes to the code will pass linting: ```console pre-commit install ``` * post-commit hook - Lints the commit message to ensure it will pass the commit linting: ```console pre-commit install --hook-type commit-msg ``` ## Git notes The GitHub project contains [git notes](https://git-scm.com/docs/git-notes) for each commit that includes e.g. a link to the pull request from which the commit originated and reviewer information. These are updated automatically, but require an additional step locally to be able to see the notes in `git log`: ```bash git config --add remote.upstream.fetch '+refs/notes/*:refs/notes/*' ``` > [!NOTE] > The `upstream` remote in this command should be replaced with whatever you've named the LadybirdBrowser/ladybird.git > remote in your local clone. Use `git remote -v` to find that name. Now, any time you `git fetch`, the latest notes will be fetched as well. You will see information like the following when you run `git log`: ``` commit c1b0e180ba64d2ea7e815e2c2e93087ae9a26500 Author: Timothy Flynn Date: Mon Jul 29 10:18:25 2024 -0400 LibWebView: Insert line numbers before each line in about:srcdoc The behavior chosen here (fixed-width counters, alignment, etc.) matches Firefox. Notes: Author: https://github.com/trflynn89 Commit: https://github.com/LadybirdBrowser/ladybird/commit/c1b0e180ba6 Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/892 Reviewed-by: https://github.com/AtkinsSJ ✅ ``` --- ### Documentation CodingStyle (`Documentation/CodingStyle.md`) # Ladybird C++ coding style For low-level styling (spaces, parentheses, brace placement, etc), all code should follow the format specified in `.clang-format` in the project root. **Important: Make sure you use the correct version of `clang-format`!** See [lint_clang_format.py](../Meta/Linters/lint_clang_format.py) for the version enforced in CI. See [AdvancedBuildInstructions.md](AdvancedBuildInstructions.md#clang-format-updates) for instructions on how to get an up-to-date version if your OS distribution does not ship the correct version. This document describes the coding style used for C++ code in the Ladybird Browser project. All new code should conform to this style. We'll definitely be tweaking and amending this over time, so let's consider it a living document. :) ### Names A combination of CamelCase, snake\_case, and SCREAMING\_CASE: - Use CamelCase (Capitalize the first letter, including all letters in an acronym) in a class, struct, or namespace name - Use snake\_case (all lowercase, with underscores separating words) for variable and function names - Use SCREAMING\_CASE for constants (both global and static member variables) ###### Right: ```cpp struct Entry; size_t buffer_size; class FileDescriptor; String absolute_path(); ``` ###### Wrong: ```cpp struct data; size_t bufferSize; class Filedescriptor; String MIME_Type(); ``` When implementing spec algorithms and other constructs that a spec explicitly names, prefer closely matching the same names the spec uses, whenever possible. Given the construct at https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#suffering-from-being-missing which has the literal name _“Suffering from being missing”_ in the spec, for example: ###### Right: ```c++ bool HTMLInputElement::suffering_from_being_missing(); // exactly matches the spec naming ``` ###### Wrong: ```c++ bool HTMLInputElement::has_missing_constraint(); // arbitrarily differs from spec naming ``` Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand. ###### Right: ```cpp size_t character_size; size_t length; short tab_index; // More canonical. ``` ###### Wrong: ```cpp size_t char_size; size_t len; short tabulation_index; // Goofy. ``` Data members in C++ classes should be private. Static data members should be prefixed by "s\_". Other data members should be prefixed by "m\_". Global variables should be prefixed by "g\_". ###### Right: ```cpp class String { public: ... private: int m_length { 0 }; }; ``` ###### Wrong: ```cpp class String { public: ... int length { 0 }; }; ``` Precede setters with the word "set". Use bare words for getters. Setter and getter names should match the names of the variables being set/gotten. ###### Right: ```cpp void set_count(int); // Sets m_count. int count() const; // Returns m_count. ``` ###### Wrong: ```cpp void set_count(int); // Sets m_the_count. int get_count() const; // Returns m_the_count. ``` Precede getters that return values through out arguments with the word "get". ###### Right: ```cpp void get_filename_and_inode_id(String&, InodeIdentifier&) const; ``` ###### Wrong: ```cpp void filename_and_inode_id(String&, InodeIdentifier&) const; ``` Use descriptive verbs in function names. ###### Right: ```cpp bool convert_to_ascii(short*, size_t); ``` ###### Wrong: ```cpp bool to_ascii(short*, size_t); ``` When there are two getters for a variable, and one of them automatically makes sure the requested object is instantiated, prefix that getter function with `ensure_`. As it ensures that an object is created, it should consequently also return a reference, not a pointer. ###### Right: ```cpp Inode* inode(); Inode& ensure_inode(); ``` ###### Wrong: ```cpp Inode& inode(); Inode* ensure_inode(); ``` Leave meaningless variable names out of function declarations. A good rule of thumb is if the parameter type name contains the parameter name (without trailing numbers or pluralization), then the parameter name isn't needed. Usually, there should be a parameter name for bools, strings, and numerical types. ###### Right: ```cpp void set_count(int); void do_something(Context*); ``` ###### Wrong: ```cpp void set_count(int count); void do_something(Context* context); ``` Prefer enums to bools on function parameters if callers are likely to be passing constants, since named constants are easier to read at the call site. An exception to this rule is a setter function, where the name of the function already makes clear what the boolean is. ###### Right: ```cpp do_something(something, AllowFooBar::Yes); paint_text_with_shadows(context, ..., text_stroke_width > 0, is_horizontal()); set_resizable(false); ``` ###### Wrong: ```cpp do_something(something, false); set_resizable(NotResizable); ``` Enum members should use InterCaps with an initial capital letter. Prefer `const` to `#define`. Prefer inline functions to macros. `#defined` constants should use all uppercase names with words separated by underscores. Use `#pragma once` instead of `#define` and `#ifdef` for header guards. ###### Right: ```cpp // MyClass.h #pragma once ``` ###### Wrong: ```cpp // MyClass.h #ifndef MyClass_h #define MyClass_h ``` ### Other Punctuation Constructors for C++ classes should initialize their members using C++ initializer syntax. Each member (and superclass) should be indented on a separate line, with the colon or comma preceding the member on that line. Prefer initialization at member definition whenever possible. ###### Right: ```cpp class MyClass { ... Document* m_document { nullptr }; int m_my_member { 0 }; }; MyClass::MyClass(Document* document) : MySuperClass() , m_document(document) { } MyOtherClass::MyOtherClass() : MySuperClass() { } ``` ###### Wrong: ```cpp MyClass::MyClass(Document* document) : MySuperClass() { m_myMember = 0; m_document = document; } MyClass::MyClass(Document* document) : MySuperClass() : m_my_member(0) // This should be in the header. { m_document = document; } MyOtherClass::MyOtherClass() : MySuperClass() {} ``` Prefer index or range-for over iterators in Vector iterations for terse, easier-to-read code. ###### Right: ```cpp for (auto& child : children) child->do_child_thing(); ``` #### OK: ```cpp for (int i = 0; i < children.size(); ++i) children[i]->do_child_thing(); ``` ###### Wrong: ```cpp for (auto it = children.begin(); it != children.end(); ++it) (*it)->do_child_thing(); ``` ### Pointers and References Both pointer types and reference types should be written with no space between the type name and the `*` or `&`. An out argument of a function should be passed by reference except rare cases where it is optional in which case it should be passed by pointer. ###### Right: ```cpp void MyClass::get_some_value(OutArgumentType& out_argument) const { out_argument = m_value; } void MyClass::do_something(OutArgumentType* out_argument) const { do_the_thing(); if (out_argument) *out_argument = m_value; } ``` ###### Wrong: ```cpp void MyClass::get_some_value(OutArgumentType* outArgument) const { *out_argument = m_value; } ``` ### "using" Statements In header files in the AK sub-library, however, it is acceptable to use "using" declarations at the end of the file to import one or more names in the AK namespace into the global scope. ###### Right: ```cpp // AK/Vector.h namespace AK { } // namespace AK using AK::Vector; ``` ###### Wrong: ```cpp // AK/Vector.h namespace AK { } // namespace AK using namespace AK; ``` ###### Wrong: ```cpp // runtime/Object.h namespace AK { } // namespace AK using AK::SomethingOrOther; ``` In C++ implementation files, do not use "using" declarations of any kind to import names in the standard template library. Directly qualify the names at the point they're used instead. ###### Right: ```cpp // File.cpp std::swap(a, b); c = std::numeric_limits::max() ``` ###### Wrong: ```cpp // File.cpp using std::swap; swap(a, b); ``` ###### Wrong: ```cpp // File.cpp using namespace std; swap(a, b); ``` ### Types Omit "int" when using "unsigned" modifier. Do not use "signed" modifier. Use "int" by itself instead. ###### Right: ```cpp unsigned a; int b; ``` ###### Wrong: ```cpp unsigned int a; // Doesn't omit "int". signed b; // Uses "signed" instead of "int". signed int c; // Doesn't omit "signed". ``` ### Classes For types with methods, prefer `class` over `struct`. * For classes, make public getters and setters, keep members private with `m_` prefix. * For structs, let everything be public and skip the `m_` prefix. ###### Right: ```cpp struct Thingy { String name; int frob_count { 0 }; }; class Doohickey { public: String const& name() const { return m_name; } int frob_count() const { return m_frob_count; } void jam(); private: String m_name; int m_frob_count { 0 }; } ``` ###### Wrong: ```cpp struct Thingy { public: String m_name; int frob_count() const { return m_frob_count; } private: int m_frob_count { 0 }; } class Doohickey { public: String const& name() const { return this->name; } void jam(); String name; int frob_count { 0 }; }; ``` Use a constructor to do an implicit conversion when the argument is reasonably thought of as a type conversion and the type conversion is fast. Otherwise, use the explicit keyword or a function returning the type. This only applies to single argument constructors. ###### Right: ```cpp class LargeInt { public: LargeInt(int); ... class Vector { public: explicit Vector(int size); // Not a type conversion. Vector create(Array); // Costly conversion. ... ``` ###### Wrong: ```cpp class Task { public: Task(ExecutionContext&); // Not a type conversion. explicit Task(); // No arguments. explicit Task(ExecutionContext&, Other); // More than one argument. ... ``` ### Singleton pattern Use a static member function named "the()" to access the instance of the singleton. ###### Right: ```cpp class UniqueObject { public: static UniqueObject& the(); ... ``` ###### Wrong: ```cpp class UniqueObject { public: static UniqueObject& shared(); ... ``` ###### Wrong: ```cpp class UniqueObject { ... }; UniqueObject& my_unique_object(); // Free function. ``` ### Comments Comments should be written using `//` and not `/* */`, except for the copyright notice. Write comments as proper sentences starting with a capital letter and ending with a period (or other punctuation). One exception may be end of line comments like this: `if (x == y) // false for NaN` Another exception is comments copied from specifications. These should be quoted verbatim, and not modified except for wrapping or to insert necessary punctuation such as adding `**` when a number is raised to a power, as this is often done using elements like `` which do not appear in the copied text. Please wrap long comments onto multiple lines so that they are easier to read. Generally, 120 characters is a good width to aim for. Use FIXME: (without attribution) to denote items that need to be addressed in the future. TODO: (without attribution) is also permitted. ###### Right: ```cpp draw_jpg(); // FIXME: Make this code handle jpg in addition to the png support. ``` ###### OK: ```cpp draw_jpg(); // TODO: Make this code handle jpg in addition to the png support. ``` ###### Wrong: ```cpp draw_jpg(); // FIXME(joe): Make this code handle jpg in addition to the png support. ``` Explain *why* the code does something. The code itself should already say what is happening. ###### Right: ```cpp i++; // Go to the next page. ``` ```cpp // Let users toggle the advice functionality by clicking on catdog. catdog_widget.on_click = [&] { if (advice_timer->is_active()) advice_timer->stop(); else advice_timer->start(); }; ``` ###### Even better: ```cpp page_index++; ``` ###### Wrong: ```cpp i++; // Increment i. ``` ```cpp // If the user clicks, toggle the timer state. catdog_widget.on_click = [&] { if (advice_timer->is_active()) advice_timer->stop(); else advice_timer->start(); }; ``` #### Spec notes & questions Many web specs include notes that are prefixed with `NOTE: ...`. To allow for verbatim copying of these notes into our code, we retain the `NOTE:` prefix and use [`NB:`](https://en.wikipedia.org/wiki/Nota_bene) for our own notes. This only applies to comments as part of code that is directly implementing a spec algorithm or behavior. Comments in other places do not need a prefix. Sometimes a draft spec text includes a spec question, which should be included with double square brackets: `[[ ... ]]`. ##### Right: ```cpp // 2. If property is in already serialized, continue with the steps labeled declaration loop. // NOTE: The prefabulated aluminite will not be suitable for use here. If the listed spec note is so long that we reach // column 120, we wrap around and indent the lines to match up with the first line. // NB: We _can_ actually use the aluminite since we unprefabulated it in step 1 for performance reasons. // 3. For each property in window [[ in what order? ]]: ``` ##### Wrong: ```cpp // LB-NOTE: The aluminite might come pre-prefabulated at this point. // Spec-note: Another example of a custom note prefix that we shouldn't use. // There is no prefix whatsoever here, making it unclear whether this is a spec step, note or a developer note. // 3. For each property in window (in what order?): ``` ### Overriding Virtual Methods The declaration of a virtual method inside a class must be declared with the `virtual` keyword. All subclasses of that class must also specify either the `override` keyword when overriding the virtual method, or the `final` keyword when overriding the virtual method and requiring that no further subclasses can override it. ###### Right: ```cpp class Person { public: virtual String description() { ... }; } class Student : public Person { public: virtual String description() override { ... }; // This is correct because it contains both the "virtual" and "override" keywords to indicate that the method is overridden. } ``` ```cpp class Person { public: virtual String description() { ... }; } class Student : public Person { public: virtual String description() final { ... }; // This is correct because it contains both the "virtual" and "final" keywords to indicate that the method is overridden and that no subclasses of "Student" can override "description". } ``` ###### Wrong: ```cpp class Person { public: virtual String description() { ... }; } class Student : public Person { public: String description() override { ... }; // This is incorrect because it uses only the "override" keyword to indicate that the method is virtual. Instead, it should use both the "virtual" and "override" keywords. } ``` ```cpp class Person { public: virtual String description() { ... }; } class Student : public Person { public: String description() final { ... }; // This is incorrect because it uses only the "final" keyword to indicate that the method is virtual and final. Instead, it should use both the "virtual" and "final" keywords. } ``` ```cpp class Person { public: virtual String description() { ... }; } class Student : public Person { public: virtual String description() { ... }; // This is incorrect because it uses only the "virtual" keyword to indicate that the method is overridden. } ``` ### Const placement Use "east const" style where `const` is written on the right side of the type being qualified. See [this article](https://mariusbancila.ro/blog/2018/11/23/join-the-east-const-revolution/) for more information about east const. ###### Right: ```cpp Salt const& m_salt; ``` ###### Wrong: ```cpp const Salt& m_salt; ``` ### Casts Before you consider a cast, please see if your problem can be solved another way that avoids the visual clutter. - Integer constants can be specified to have (some) specific sizes with postfixes like `u, l, ul` etc. The same goes for single-precision floating-point constants with `f`. - Working with smaller-size integers in arithmetic expressions is hard because of [implicit promotion](https://wiki.sei.cmu.edu/confluence/display/c/INT02-C.+Understand+integer+conversion+rules). Generally, it is fine to use `int` and other "large" types in local variables, and possibly cast at the end. - If you `const_cast`, _really_ consider whether your APIs need to be adjusted in terms of their constness. Does the member function you're writing actually make sense to be `const`? - If you do checked casts between base and derived types, also consider your APIs. For example: Does the function being called actually need to receive the more general type or is it fine with the more specialized type? If you _do_ need to cast: **Don't use C-style casts**. The C-style cast has [complex behavior](https://en.cppreference.com/w/c/language/cast) that is undesired in many instances. Be aware of what sort of type conversion the code is trying to achieve, and use the appropriate (!) C++ cast operator, like `static_cast`, `reinterpret_cast`, `bit_cast`, `dynamic_cast` etc. There is a single exception to this rule: marking a function parameter as used with `(void)parameter;`. ###### Right: ```cpp MyParentClass& object = get_object(); // Verify the type... MyChildClass& casted = static_cast(object); ``` ```cpp // AK::Atomic::exchange() alignas(T) u8 buffer[sizeof(T)]; T* ret = reinterpret_cast(buffer); ``` ```cpp // SeekableStream::tell() // Seek with 0 and SEEK_CUR does not modify anything despite the const_cast, // so it's safe to do this. return const_cast(this)->seek(0, SeekMode::FromCurrentPosition); ``` ###### Wrong: ```cpp // These should be static_cast. size_t mask_length = (size_t)((u8)-1) + 1; ``` ```cpp // This should be reinterpret_cast. return (u8 const*)string.characters_without_null_termination(); ``` ### Omission of curly braces from statement blocks Curly braces may only be omitted from `if`/`else`/`for`/`while`/etc. statement blocks if the body is a single line. Additionally, if any body of a connected if/else statement requires curly braces according to this rule, all of them do. ###### Right: ```cpp if (condition) foo(); ``` ```cpp if (condition) { foo(); bar(); } ``` ```cpp if (condition) { foo(); } else if (condition) { bar(); baz(); } else { qux(); } ``` ```cpp for (size_t i = i; condition; ++i) { if (other_condition) foo(); } ``` ##### OK: ```cpp if (condition) { foo(); } ``` ###### Wrong: ```cpp if (condition) // There is a comment here. foo(); ``` ```cpp if (condition) foo(); else { bar(); baz(); } else qux(); ``` ```cpp for (size_t i = i; condition; ++i) if (other_condition) foo(); ``` --- ### Documentation CrashReports (`Documentation/CrashReports.md`) # Crash reports On macOS and Linux, Ladybird saves local text reports when the browser or a helper process crashes: WebContent, WebWorker, RequestServer, ImageDecoder, Compositor and WasmCompiler. Reports are stored in `~/Library/Application Support/Ladybird/CrashReports/` on macOS and `~/.local/share/Ladybird/CrashReports/` on Linux, or under `$XDG_DATA_HOME/Ladybird/CrashReports/` if that variable is set. The directory is private to the current user, and report files are read-only, with mode `0400`. Reports awaiting review are always kept; of the reports that have already been offered, the newest 20 are kept. Filenames start with a UTC date and time, for example `2026-09-06T12-34-56Z-WebContent-a1B2c3.txt`, so they sort chronologically. Hyphens in the time keep filenames compatible with Windows; the random suffix avoids collisions. Retention includes reports saved with the older filenames. Nothing is uploaded automatically. Once the report of a WebContent crash is saved, the crash screen shows a review of it, with sending it as the main action and **Reload page** next to it. After the report is answered, reloading is what the screen offers. Any other crash, such as one of the Compositor or RequestServer, shows a popover below the menu button as soon as its report is saved. A newer crash takes the place of a popover still on screen, and the popover closes when its tab goes out of view. It offers to review the report on the same crash screen in a new blank tab, which **Close tab** closes. A report on its way keeps being sent after the screen that showed its review is closed or lost. A browser-process report is recovered on the next launch, which shows the same popover for the newest report still awaiting review. While no browser window is active, the popover waits until one is. Browsers driven by WebDriver never ask. Ladybird automatically offers each report at most once; leaving the crash screen or the popover without answering keeps the report on the device without offering it again on a later launch. A report of a crash from more than 14 days ago, or from before October 2, 2026 20:00 UTC, is never offered, but stays in the folder. Reports that have been offered move into a `Seen/` subdirectory, where the newest 20 are kept for reference. **Settings > Advanced > Crash reports > Open folder** remains available even when nothing has crashed. Reload restores the failed page without adding a crash-screen history entry; Back and Forward continue to use the original session history. The crash screen is native browser UI, so it does not depend on a web content process. The review asks what the user was doing and lets them choose whether to send the report. Report details lists its main fields, such as the failure, signal, version and commit, and opens the full report, exactly as it would be attached, in the system's text viewer. Submissions omit the website URL by default; when the crashed page had one, the user can explicitly include it and edit it first. Ladybird does not collect contact information. Network errors, timeouts, rate limits and server errors are retried a few times, honoring the server's `Retry-After`; a report the server rejects is not. A report that changed on disk after it was reviewed is not sent. A successful submission removes the local copy. A report that is declined or could not be sent stays on the device, but is not offered again. Reports and filenames identify the process type. Build information includes the full Git commit, tracked-source modification state, C++ compiler identity and version, macOS SDK version when applicable, CMake build options, and flags from the helper's compilation command. Include/output paths, string-valued defines and arbitrary compiler arguments are omitted. The metadata refreshes on incremental builds and does not require Git at runtime. Source archives without Git metadata report an unknown revision; local source modifications and `-march=native` builds still require the corresponding source changes and build-machine target to reproduce. Reports also contain the time of the crash, the browser version, platform, architecture, numeric kernel release, build configuration, process uptime when available, termination signal or exit code, signal code when available, and a bounded native stack. Stack frames identify their binaries by Mach-O UUID on macOS or ELF build ID on Linux and contain object addresses with the load relocation removed. When a binary is also loaded in the surviving browser, its nearest available native symbol and the offset from that symbol are included. Binary IDs identify builds, not users or devices. Saved crash diagnostics do not collect page URLs, titles, content, JavaScript stacks, cookies, network requests, console output, stderr, command lines, environment variables, usernames, hostnames, installation paths, absolute source paths, general register values, or memory dumps. Native symbol names containing paths or non-printable characters are omitted. This also applies to crashes in private windows. Fatal `VERIFY` and `ASSERT` failures include their compile-time expression and source location. Locations inside the checkout are repository-relative; external locations include only the filename and line. Assertion text is bounded and does not include evaluated operands or runtime page data. It is saved before terminal formatting and backtrace generation, and remains available if those fail. ## Architecture After a WebContent crash, the browser displays a native crash screen and retains the failed URL, title and committed history entry. The replacement WebContent process remains dormant until the user chooses a recovery action. The crash screen provides reload and report review actions directly in the browser process. LibWebView's `CrashReportReview` prepares a report for display and validates the user's choices, and `CrashReportSubmission` sends it to the report server; the Qt UI only presents them. The browser creates an unlinked temporary file before spawning each helper and passes a descriptor to the child. The child cannot access the report directory. It snapshots native executable ranges and binary IDs before sandboxing. The POSIX signal handler writes fixed-size records to the descriptor, starting with the termination reason. It walks a bounded frame-pointer chain using Mach reads on macOS and a preopened `/proc/self/mem` descriptor on Linux. Unreadable memory ends the walk. Linux also has a bounded stack-scan fallback for code without frame pointers. The handler does not allocate, format strings, acquire application locks, or symbolize the stack. Signal termination is preserved so the operating system can still handle the crash normally. After process exit, the browser reads a bounded number of records and formats the report. It never copies arbitrary child-process text into the report. Clean exits, SIGTERM and SIGKILL do not produce reports. Other abnormal exits still produce a minimal report when capture was unavailable. Helpers launched by a test-mode browser do not produce automatic reports. The browser process has no parent process to finish its report, so Ladybird recovers its signal-safe crash data on the next launch. Clean exits and exits without a captured fatal signal do not produce a browser report. The record also keeps a description of the browser's build, so a report recovered after an update describes the build that crashed. A record without one says so instead of describing the launch that recovers it. The capture implementation and bounded record format live in LibCore, so all helpers can install the handler before sandboxing without linking browser UI code. Browser-owned report formatting and storage remain in LibWebView. Windows capture is not implemented yet; it will need native binary IDs, stack capture, storage and exit-status handling. ## Limitations and symbolication Only the crashing thread is captured. Stacks can be partial due to corruption, missing frame pointers, JIT code, or modules loaded after handler initialization. An alternate signal stack protects main-thread stack overflow; stack overflow on other threads may only produce a minimal report. Early startup crashes and other exits that bypass the handler also produce minimal reports for helpers. Helper reports require the browser to survive long enough to format them. Browser crashes before the handler is installed, or exits that bypass its signal handler, may not produce a report. Disk errors can prevent saving; they are reported to stderr. Keep the binaries and debug symbols for distributed builds. A binary ID and object address remain useful even when symbols were stripped from the user's install. On macOS, use `dwarfdump --uuid ` to match the report's build ID (ignoring hyphens and case), then `atos -arch arm64 -o ` to resolve a frame with the matching binary and dSYM. Use `x86_64` for Intel reports. Report addresses are already unslid, so do not add the user's ASLR slide. The report itself contains no local binary paths. On Linux, use `readelf -n ` to match the ELF build ID, then `addr2line -f -C -e ` with matching debug symbols. --- ### Documentation DevTools (`Documentation/DevTools.md`) # Firefox DevTools Integration Ladybird contains a DevTools server. This document describes how to use the server and the protocol used to communicate with the DevTools client. ## Using DevTools The DevTools server may be enabled in the "Inspect" menu via the "Enable DevTools" menu item, or with the `--devtools` command line flag. A banner will be displayed in Ladybird with the port on which the DevTools server is listening. This port may be changed by providing a port to the command line flag, e.g. `--devtools=6001`. To disable DevTools, use the menu item (which will now be titled "Disable DevTools"), or close the banner. Once DevTools is enabled, you may use the "Open Client" button on the banner to open a Firefox DevTools client window to inspect the current tab. Only one such window may be open at a time. Alternatively, in Firefox, navigate to `about:debugging` and select the "Setup" tab. In the "Network Location" form, enter the DevTools server address. In the above example with `--devtools=6001`, this will be `localhost:6001`. You will only have to enter this information once: DevTools setup This will make the address appear on the left-side of the page. Click "Connect": DevTools connect Once connected, the listed address will now be clickable itself. Click it to be brought to a page which shows Ladybird's tab list: DevTools tab list Click the "Inspect" button next to the tab you wish to debug. This will open another tab in Firefox with an inspector panel, which you may use to view the DOM tree: DevTools DOM tree ## DevTools protocol Firefox's documentation of its [DevTools protocol](https://firefox-source-docs.mozilla.org/devtools/backend/protocol.html) is quite incomplete, and even incorrect in some places. To aid with development, this section describes the protocol that Ladybird has implemented. Note that this is only observed behavior - our implementation could certainly be incorrect or incomplete in places. The protocol itself is based on ["actors"](https://firefox-source-docs.mozilla.org/devtools/backend/protocol.html#actors). Each packet contains a JSON object. Messages sent from the DevTools client contain a `"to"` field indicating the actor for which the message is intended. Messages sent from the DevTools server contain a `"from"` field indicating the actor from which the message originated. A very important aspect of this protocol is that the client may send multiple requests to an actor at once without waiting for a reply, to which the actor must then reply in order. Any requests that must be performed asynchronously (such as fetching the serialized DOM tree from the WebContent process) must block the actor from sending replies for subsequent requests. To log communication between the DevTools server and client, enable the `DEVTOOLS_DEBUG` flag: ```bash cmake -B Build/release -D DEVTOOLS_DEBUG=ON ``` Logged messages beginning with "<<" were sent from the server to the client. Messages beginning with ">>" were sent from the client to the server. ### Session initialization Once the DevTools client has connected, communication begins with a [root actor](../Libraries/LibDevTools/Actors/RootActor.cpp). The root actor initiates the session by sending a message to the client describing itself: ```jsonc << {"from":"root","applicationType":"browser","traits":{"sources":false,"highlightable":true,"customHighlighters":true,"networkMonitor":false}} ``` The client then sends a connection request, to which the server replies with an empty message: ```jsonc >> {"type":"connect","frontendVersion":"135.0","to":"root"} << {"from":"root"} ``` The client then asks the root actor to describe other top-level actors. We are required to provide a device actor and a preference actor: ```jsonc >> {"type":"getRoot","to":"root"} << {"from":"root","selected":0,"deviceActor":"server0-device1","preferenceActor":"server0-preference2"} ``` The device actor provides information about the device for which the server is running, such as application version and host OS. We provide a [subset of fields](https://github.com/mozilla/gecko-dev/blob/master/devtools/shared/system.js) that Firefox itself provides, as the other fields seem optional, and may not even make sense for Ladybird. The client will immediately request this information after the `getRoot` reply: ```jsonc >> {"type":"getDescription","to":"server0-device1"} << {"from":"server0-device1","value":{"apptype":"ladybird","name":"Ladybird","brandName":"Ladybird","version":"1.0","appbuildid":"Version 1.0","platformbuildid":"Version 1.0","platformversion":"135.0","useragent":"Mozilla/5.0 (macOS; AArch64) Ladybird/1.0","os":"macOS","arch":"AArch64"}} ``` The preference actor is used to query and update configuration options that resemble those found in Firefox's `about:config` page. We don't implement anything concrete here. The client will request a few boolean configuration options after the device request, to which the server will just reply with `false`: ```jsonc >> {"type":"getBoolPref","value":"devtools.debugger.prompt-connection","to":"server0-preference2"} << {"from":"server0-preference2","value":false} >> {"type":"getBoolPref","value":"browser.privatebrowsing.autostart","to":"server0-preference2"} << {"from":"server0-preference2","value":false} >> {"type":"getBoolPref","value":"dom.serviceWorkers.enabled","to":"server0-preference2"} << {"from":"server0-preference2","value":false} ``` The client then asks for a list of add-ons, workers, and service workers, to which the server replies with an empty list: ```jsonc >> {"type":"listTabs","to":"root"} << {"from":"root","addons":[]} >> {"type":"listWorkers","to":"root"} << {"from":"root","workers":[]} >> {"type":"listServiceWorkerRegistrations","to":"root"} << {"from":"root","registrations":[]} ``` Then client then asks for a list of processes, followed immediately by a request for the zeroth process. This zeroth process is required, and seems to correspond to the browser's main process. We currently stub out this information: ```jsonc >> {"type":"listProcesses","to":"root"} >> {"type":"getProcess","id":0,"to":"root"} << {"from":"root","processes":[{"actor":"server0-process3","id":0,"isParent":true,"isWindowlessParent":false,"traits":{"watcher":true,"supportsReloadDescriptor":true}}]} << {"from":"root","processDescriptor":{"actor":"server0-process3","id":0,"isParent":true,"isWindowlessParent":false,"traits":{"watcher":true,"supportsReloadDescriptor":true}}} ``` The client then asks for a list of tabs. The server contains a [delegate interface](../Libraries/LibDevTools/DevToolsDelegate.h) to be implemented by the WebView application. This interface includes a method to form a list open tabs. The server will reply with this list: ```jsonc >> {"type":"listTabs","to":"root"} << {"from":"root","tabs":[{"actor":"server0-tab4","title":"Ladybird","url":"https://ladybird.org/","browserId":1,"browsingContextID":1,"outerWindowID":1,"traits":{"watcher":true,"supportsReloadDescriptor":true}}]} ``` The client then asks for information about the tabs, including their favicon. The favicon is expected to be a URL, but when provided, the DevTools client seems to hang. So we use a null value here, which Firefox itself also uses. The server will reply with the same information provided in the `listTabs` request: ```jsonc >> {"type":"getFavicon","to":"server0-tab4"} << {"from":"server0-tab4","favicon":null} >> {"type":"getTab","browserId":1,"to":"root"} << {"from":"root","tab":{"actor":"server0-tab4","title":"Ladybird","url":"https://ladybird.org/","browserId":1,"browsingContextID":1,"outerWindowID":1,"traits":{"watcher":true,"supportsReloadDescriptor":true}}} ``` At this point, the session is established and Ladybird is listed on `about:debugging`. ### Inspecting a DOM tree When the user inspects a tab, the client initiates the inspection with a request for a "watcher". Watchers are the actors responsible for monitoring a wide variety of components. We currently only implement a "frame" watcher. The server will create a watcher associated with the inspected tab, and reply with a set of watcher options indicating our support of frame inspection: ```jsonc >> {"type":"getWatcher","isServerTargetSwitchingEnabled":true,"isPopupDebuggingEnabled":false,"to":"server0-tab4"} << {"from":"server0-tab4","actor":"server0-watcher5","traits":{"shared_worker":false,"service_worker":false,"frame":true,"process":false,"worker":false,"resources":{"Cache":false,"console-message":false,"cookies":false,"css-change":false,"css-message":false,"css-registered-properties":false,"document-event":false,"error-message":false,"extension-storage":false,"indexed-db":false,"jstracer-state":false,"jstracer-trace":false,"last-private-context-exit":false,"local-storage":false,"network-event":false,"network-event-stacktrace":false,"platform-message":false,"reflow":false,"server-sent-event":false,"session-storage":false,"source":false,"stylesheet":false,"thread-state":false,"websocket":false}}} ``` The client then asks the server to watch the inspected tab's frame. The server must reply with multiple messages here. The first message contains information about the inspected tab, as well as a list of other actors associated with the watcher. We are required to have an inspector actor, a CSS properties actor, and a thread actor. We also have the optional console actor. These actors are described below when they are requested by the client. The second message contains a small set of information about the tab again. The third message is just an empty message, which seems to indicate and end-of-transmission status: ```jsonc >> {"type":"watchTargets","targetType":"frame","to":"server0-watcher5"} << {"from":"server0-watcher5","type":"target-available-form","target":{"actor":"server0-frame10","title":"xkcd: Scream Cipher","url":"https://xkcd.com/","browsingContextID":1,"outerWindowID":1,"isTopLevelTarget":true,"traits":{"frames":true,"isBrowsingContext":true,"logInPage":false,"navigation":true,"supportsTopLevelTargetFlag":true,"watchpoints":true},"cssPropertiesActor":"server0-css-properties6","consoleActor":"server0-console8","inspectorActor":"server0-inspector7","threadActor":"server0-thread9"}} << {"from":"server0-frame9","type":"frameUpdate","frames":[{"id":1,"title":"Ladybird","url":"https://ladybird.org/"}]} << {"from":"server0-watcher5"} ``` The client then asks for a couple of configuration actors, and sends some configuration options to those actors. These actors are a target configuration actor and a thread configuration actor. The target configuration actor informs the client about features supported by the target tab, such as an "offline mode". We currently stub these options to indicate all features are not supported. The thread configuration actor is currently entirely a stub. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` The client then asks for a list of frames, to which the server replies with an empty message: ```jsonc >> {"type":"listFrames","to":"server0-frame9"} << {"from":"server0-frame9"} ``` The client then asks for a CSS database. The server must reply with a list of every CSS property that the rendering engine supports. The delegate interface includes a method for the application to provide this information. LibWebView will reply with the list of properties generated by [Properties.json](../Libraries/LibWeb/CSS/Properties.json). (For brevity, only the `font` property is included here, as the list of all properties is very large.) ```jsonc >> {"type":"getCSSDatabase","to":"server0-css-properties6"} << {"from":"server0-css-properties6","properties":{"font":{"isInherited":true,"supports":[],"values":[],"subproperties":["font"]}}} ``` The client then asks the inspector actor for a few more actors in a row. The inspector actor is essentially just a container that serves to hold other actors that actually perform inspection. First, the client asks for a walker actor. This walker is what will actually own and traverse the DOM tree. It is at this point that the server fetches the DOM tree from the WebContent process. The delegate interface includes a method for the application to asynchronously provide this information. The inspector actor's message queue is blocked until we receive the DOM tree (or encounter an error). The server will reply with information about the document element. Next, the client asks for a page style actor and a highlighter actor. The page style actor is what will provide layout and style information about a particular node. The highlighter actor's responsibility varies depending on the type of highlighter that is requested. Here, the client asks for a viewport resize highlighter, which we currently do not support. ```jsonc >> {"type":"getWalker","options":{"showAllAnonymousContent":false},"to":"server0-inspector7"} >> {"type":"getPageStyle","to":"server0-inspector7"} >> {"type":"getHighlighterByType","typeName":"ViewportSizeOnResizeHighlighter","to":"server0-inspector7"} << {"from":"server0-inspector7","walker":{"actor":"server0-walker14","root":{"actor":"server0-node15","attrs":[],"baseURI":"https://ladybird.org/","causesOverflow":false,"containerType":null,"displayName":"#document","displayType":"block","host":null,"isAfterPseudoElement":false,"isAnonymous":false,"isBeforePseudoElement":false,"isDirectShadowHostChild":null,"isDisplayed":false,"isInHTMLDocument":true,"isMarkerPseudoElement":false,"isNativeAnonymous":false,"isScrollable":false,"isShadowHost":false,"isShadowRoot":false,"isTopLevelDocument":true,"nodeName":"#document","nodeType":9,"nodeValue":null,"numChildren":1,"shadowRootMode":null,"traits":{}}}} << {"from":"server0-inspector7","pageStyle":{"actor":"server0-page-style12","traits":{"fontStyleLevel4":true,"fontWeightLevel4":true,"fontStretchLevel4":true,"fontVariations":true}}} << {"from":"server0-inspector7","highlighter":{"actor":"server0-highlighter13"}} ``` The client then asks for the frame's parent browsing context, to which the server currently replies with the same context as the frame itself: ```jsonc >> {"type":"getParentBrowsingContextID","browsingContextID":1,"to":"server0-watcher5"} << {"from":"server0-watcher5","browsingContextID":1} ``` The client then instructs the viewport resize highlighter actor to "show" the inspector actor, to which the server currently replies with a nack: ```jsonc >> {"type":"show","node":"server0-inspector7","to":"server0-highlighter13"} << {"from":"server0-highlighter13","value":false} ``` Then client then starts to ask for DOM node information. It begins by issuing a query selector request for the `` element, followed by requests for the children of the `` element, the document element, and the `` element. The query selector indicates the actor name of the node from which to start searching, and the name of the requested node. We do not currently create concrete actor objects for each node; rather, we just assign actor names to each node in the DOM tree received from the WebContent process. The query selector reply includes a field to indicate that its parent is not the parent from which the search started. Each serialized DOM node contains information such as its type, display name, tag name, attributes, etc. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` The client then instructs the server to watch the root node. The server replies with information about the document element again, followed by an empty message. We do not currently do anything more with this request. ```jsonc >> {"type":"watchRootNode","to":"server0-walker14"} << {"from":"server0-walker14","type":"root-available","node":{"actor":"server0-node15","attrs":[],"baseURI":"https://ladybird.org/","causesOverflow":false,"containerType":null,"displayName":"#document","displayType":"block","host":null,"isAfterPseudoElement":false,"isAnonymous":false,"isBeforePseudoElement":false,"isDirectShadowHostChild":null,"isDisplayed":false,"isInHTMLDocument":true,"isMarkerPseudoElement":false,"isNativeAnonymous":false,"isScrollable":false,"isShadowHost":false,"isShadowRoot":false,"isTopLevelDocument":true,"nodeName":"#document","nodeType":9,"nodeValue":null,"numChildren":1,"shadowRootMode":null,"traits":{}}} << {"from":"server0-walker14"} ``` At this point, the DOM tree in the DevTools client is interactable. As the user interacts with the client, the client will send similar requests as the above to retrieve more DOM node information. The server will log an error for features we do not yet support. ### Inspecting a DOM node After the DOM tree becomes interactable, the client will inspect a default node on the page (typically the `` element). The client will immediately ask for the layout of the inspected node and for a layout inspector. The layout consists of the box model metrics for the node. The layout inspector is an actor that provides e.g. grid and flexbox information, but we currently just sub this out. ```jsonc >> {"type":"getLayout","node":"server0-node31","autoMargins":true,"to":"server0-page-style12"} >> {"type":"getLayoutInspector","to":"server0-walker14"} << {"from":"server0-page-style12","autoMargins":{},"width":1514,"height":10236.8125,"border-top-width":"0px","border-right-width":"0px","border-bottom-width":"0px","border-left-width":"0px","margin-top":"0px","margin-right":"0px","margin-bottom":"0px","margin-left":"0px","padding-top":"0px","padding-right":"0px","padding-bottom":"0px","padding-left":"0px","box-sizing":"border-box","display":"block","float":"none","line-height":"1.5","position":"static","z-index":"auto"} << {"from":"server0-walker14","actor":{"actor":"server0-layout-inspector568"}} ``` The client then asks for a selector for the inspected node. The server replies with the display name of the node: ```jsonc >> {"type":"getUniqueSelector","to":"server0-node32"} << {"from":"server0-node32","value":"body"} ``` The client then asks for the applied style for the inspected node. This would be for the pane in the inspector tab which allows the user to toggle and edit styles on a live DOM node. We do not yet have support for this in LibWeb, so the server replies with an empty list: ```jsonc >> {"type":"getApplied","node":"server0-node32","inherited":true,"matchedSelectors":true,"to":"server0-page-style12"} << {"from":"server0-page-style12","entries":[]} ``` The client then asks the layout inspector for the inspect node's flexbox and grid information. As noted above, we have just stubbed this for now. The server replies with empty values: ```jsonc >> {"type":"getCurrentFlexbox","node":"server0-node32","onlyLookAtParents":false,"to":"server0-layout-inspector568"} >> {"type":"getGrids","rootNode":"server0-node15","to":"server0-layout-inspector568"} << {"from":"server0-layout-inspector568","flexbox":null} << {"from":"server0-layout-inspector568","grids":[]} ``` The client then asks if the inspected node's box model metrics are editable, and for the node's "offset parent". We currently don't support such edits, and have stubbed the offset parent. The server again replies with empty values: ```jsonc >> {"type":"isPositionEditable","node":"server0-node32","to":"server0-page-style12"} << {"from":"server0-page-style12","value":false} >> {"type":"getOffsetParent","node":"server0-node32","to":"server0-walker14"} << {"from":"server0-walker14","node":null} ``` If the user switches the inspector to the "Computed" pane, then the client will ask for the inspected node's computed style. The server collects the computed style from the WebContent process, and replies with that style: (For brevity, only the `color` property is included here, as the list of all styles is very large.) ```jsonc >> {"type":"getComputed","node":"server0-node32","markMatched":true,"onlyMatched":true,"filter":"user","to":"server0-page-style12"} << {"from":"server0-page-style12","computed":{"color":{"matched":true,"value":"canvastext"}}} ``` The user may select any other DOM node to inspect. As the mouse hovers over other DOM nodes, the client will ask (once) if the server supports highlighting DOM nodes. We do support this, and the server will reply: ```jsonc >> {"type":"supportsHighlighters","to":"server0-inspector7"} << {"from":"server0-inspector7","value":true} ``` The client will then ask for box model highlighter. This highlighter indicates when the WebContent process should render an overlay over a particular node, with information about that node's box model. The server will create this highlighter type, and reply: ```jsonc >> {"type":"getHighlighterByType","typeName":"BoxModelHighlighter","to":"server0-inspector7"} << {"from":"server0-inspector7","highlighter":{"actor":"server0-highlighter569"}} ``` When the user's mouse enters a DOM node, the client will instruct the server to show the box model overlay for that node: ```jsonc >> {"type":"show","node":"server0-node16","to":"server0-highlighter569"} << {"from":"server0-highlighter569","value":true} ``` When the user's mouse leaves a DOM node, the client will instruct the server to stop showing the box model overlay for that node: ```jsonc >> {"type":"hide","to":"server0-highlighter569"} << {"from":"server0-highlighter569"} ``` The above highlighter requests are repeated as the user's mouse is moved between nodes. When the user clicks on a DOM node, that node then becomes the inspected node, and the client will ask for the box model / computed style for that node. ### JavaScript console During the initialization of the watcher actor, the server advertises to the client that it supports the console. The client will then ask the server to begin some console-related listeners, which we do not yet support: ```jsonc >> {"type":"startListeners","listeners":["DocumentEvents"],"to":"server0-console8"} << {"from":"server0-console8","error":"unrecognizedPacketType","message":"Unrecognized packet type: 'startListeners'"} >> {"type":"startListeners","listeners":["PageError"],"to":"server0-console8"} << {"from":"server0-console8","error":"unrecognizedPacketType","message":"Unrecognized packet type: 'startListeners'"} ``` When the user enters text into the console, the client will ask the server for autocompletions and eager evaluation of the input text. We do not yet support either of these features, so the server replies with some stubbed information: ```jsonc >> {"type":"autocomplete","text":"1+","frameActor":null,"authorizedEvaluations":[],"expressionVars":[],"to":"server0-console8"} >> {"type":"evaluateJSAsync","text":"1+","eager":true,"to":"server0-console8"} << {"from":"server0-console8","matches":[],"matchProp":""} << {"from":"server0-console8","resultID":"server0-console8-1"} ``` When the script is finally executed by the user, the client will ask for a non-eager evaluation of the script. At this point, the server will send the script to the WebContent process for evaluation. Its result is serialized to a JSON value, which is called a [grip](https://firefox-source-docs.mozilla.org/devtools/backend/protocol.html#grips). We currently only support serialization of plain types; objects are serialized to a string for now. Since the request is async, the server replies immediately with a pending result ID for the script. The actual result associated with that ID is then sent once the script is complete: ```jsonc >> {"type":"evaluateJSAsync","text":"1+1","disableBreaks":false,"to":"server0-console8"} << {"from":"server0-console8","resultID":"server0-console8-3"} << {"from":"server0-console8","type":"evaluationResult","timestamp":1740417141889,"resultID":"server0-console8-3","input":"1+1","result":2,"exception":null,"exceptionMessage":null,"helperResult":null} ``` Anytime console messages are evaluated by the page (`console.log`, `console.warn`, etc.), the server will independently notify the client without any prompt. The same grip serialization used for console results is used here. ```jsonc << {"from":"server0-frame10","type":"resources-available-array","array":[["console-message",[{"level":"log","filename":"","line_number":1,"column_number":1,"time_stamp":1741096175644,"arguments":["hello!"]}]]]} ``` ### Session termination When the user disconnects from the DevTools server, the client will send a few cleanup messages. We currently do not implement the first few that are sent: ```jsonc >> {"type":"unwatchTargets","targetType":"frame","options":{},"to":"server0-watcher10"} << {"from":"server0-watcher10","error":"unrecognizedPacketType","message":"Unrecognized packet type: 'unwatchTargets'"} >> {"type":"finalize","to":"server0-highlighter18"} >> {"type":"finalize","to":"server0-highlighter573"} << {"from":"server0-highlighter18","error":"unrecognizedPacketType","message":"Unrecognized packet type: 'finalize'"} << {"from":"server0-highlighter573","error":"unrecognizedPacketType","message":"Unrecognized packet type: 'finalize'"} ``` We do implement the request to detach the frame, at which point we clear any inspected DOM node information from the WebContent process: ```jsonc >> {"type":"detach","to":"server0-frame14"} << {"from":"server0-frame14"} ``` ## Inspecting the protocol with Firefox When developing a DevTools feature, it's invaluable to see how the DevTools protocol is used by Firefox itself. First, enable remote debugging in your Firefox profile's `about:config` page: ``` devtools.chrome.enabled = true devtools.debugger.remote-enabled = true ``` You may wish to create a new profile for this, rather than modifying your default profile. To create a new profile from the command line: ```bash firefox -CreateProfile YOUR_PROFILE_NAME ``` If you are using your default profile, then close all Firefox windows. Restart Firefox via the command line, specifying the DevTools server port: ```bash firefox --start-debugger-server 6000 ``` Or if you created a new profile, you do not need to close all Firefox windows. Instead, launch a new instance with the `--new-instance` flag, and specify your new profile's path with the `--profile` flag: ```bash firefox --start-debugger-server 6000 --new-instance --profile ~/snap/firefox/common/.mozilla/firefox/z20dtqwq.YOUR_PROFILE_NAME ``` After Firefox is running, we can now snoop the specified port. The Servo team has written a nice script using `tshark` to listen on this port and pretty-print the JSON packets. You will have to install `tshark` before using the script. https://github.com/servo/servo/blob/main/etc/devtools_parser.py You may run into cases where the script does not log all captured packets. Since this occurs fairly regularly, it is recommended to run this script in two phases. First, use the script to snoop on the DevTools port and write out a packet capture. You may need to run this script with `sudo`. ```bash ./etc/devtools_parser.py -s /tmp/devtools.pcap -p 6000 ``` (NOTE: It is important to only run this script *after* Firefox has started. Running the script sooner will not intercept any DevTools packets.) Now, use `about:debugging` to connect to the Firefox DevTools server and inspect a tab. Use the DevTools client to exercise the feature you wish to implement. Once complete, use `ctrl+c` on Servo's snooping script to complete the capture. The script will try to print all packets at this point, but due to the aforementioned incomplete logging, it is likely that this will not print everything. So we can use the script again to inspect the now-existing .pcap, and it should be able to print everything this way: ```bash ./etc/devtools_parser.py --use /tmp/devtools.pcap -p 6000 ``` ## Known issues 1. We occasionally fail to inspect a tab. There isn't any information logged by client or server, other than the client indicating the session was disconnected. The following is the entire communication log from an instance of this error: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Documentation EventLoop (`Documentation/EventLoop.md`) # LibCore's `EventLoop` system This is not about web event loops, which are a separate LibWeb concept. For handling application tasks concurrently on one thread, LibCore provides the `EventLoop` system. The event loop is found in many systems, and it can be briefly summarized as an in-process loop, running all the time, which processes incoming events from signals, notifiers, file watchers, timers etc. by running associated callbacks. The event loop relies on the fact that the callbacks will eventually return control to it, so that other events can be processed. In that way, it's like a cooperative multitasking scheduler in userspace. LibCore's event loop system is mainly used with graphical applications, and LibGUI and IPC are deeply integrated into it. If you are working on a command-line application, chances are you don't have to deal with the event loop, though that's not a universal rule. ## How it works When an event loop runs, it usually sits in `exec()` repeatedly `pump()`ing the loop. `exec()` waits for an event to happen and then runs all the callbacks associated with that event. After that, it goes back to sleep and waits for more events to happen. On a lower level, this is what happens: - On `exec()`, the event loop enters the event loop stack. Then, the event loop is pumped repeatedly. - Each `pump()` first puts the event loop to sleep with `wait_for_event()`, then handles all events. - `wait_for_event()` uses the `select(2)` function to wait until one of the prepared file descriptors becomes writeable or readable, or until a timeout expires. This means that while an event loop has nothing to do, the kernel keeps the thread at sleep. That's also the reason you'll see most GUI applications being listed with a "Selecting" state in SystemMonitor. After `select(2)` returns, it immediately dispatches signals to all signal handlers. Other new events (expired timers, file notifications) are put into the event queue. - The specific file descriptors are the file notifiers the event loop has registered (this is the original purpose of `select(2)`) as well as the wake pipe. This pipe is responsible for two things: Once a POSIX signal is received which the event loop has a handler for (this might happen at any time, on any thread), `handle_signal()` is entered, which writes the handler number to the pipe. But second, the `wake()` function just writes 0 (not a valid signal number) to the wake pipe, which is used to trigger an event loop wake from other threads. - The timeout of the `select(2)` call might be infinite if there's no time-based wake condition. If there are timers, however, the `select(2)` timeout is the minimum of all timer timeouts. If there are available events before `select(2)` is even called, the timeout is zero, leading to a `select(2)` which immediately returns. - Event handling from the event queue happens by invoking associated callbacks. Remember that the event queue has two primary sources of events: `deferred_invoke()` adds an event immediately and signals a wake, while after returning from `select(2)` new events are created based on timers and notifications. - If the event loop's exit was requested (checked while handling events), it returns the pending events to the queue so that the next-lower event loop can handle them. The assumption is that that event loop will resume running shortly. The return value of `exec()` has comparable purpose to a process return code, which is why the pattern `return app.exec()` is so common in GUI applications (`GUI::Application::exec()` just runs an event loop under the hood). In any case, even if the event loop's exit doesn't mean program exit, it is removed from the event loop stack. All of this applies per thread. The event loops share some global state (notifiers, timers, event loop stack etc.) which are thread-local variables. The convenience getter `EventLoop::current()` relies on this to give you the topmost event loop on the thread you're calling from. The **event loop stack** is mainly used for nesting GUI windows. Each window adds another event loop onto the stack, and remaining events are added to the lower event loop's queue when it exits. The purpose behind this system is that `GUI::Window`s and other systems which provide their own event loop can just create and run this class depending on global variables without interfering with other event loops. ## What it can do An event loop handles several kinds of events: - POSIX signals can be registered with `EventLoop::register_signal()`. This means that the event loop of the calling thread registers the specified POSIX signal and callback with the kernel, and you can be sure that the signal handler will run as a normal event without the weirdness that comes with POSIX signal handlers (such as unspecified thread). - EventLoop::post_event() allows calling code to fire an event targeting a specific Core::EventReceiver the next time the event loop is pumped. - Similarly, an arbitrary callback can be called on the next event loop iteration with `EventLoop::deferred_invoke()`. - Timer events, i.e. events that fire after a certain timeout, possibly repeatedly, can be created with `EventLoop::register_timer` and `Object::start_timer()`. A more user-friendly version is the `Core::Timer` utility class which does the same thing and allows you to attach any callback to the timer. - For when a "file" becomes readable or writeable, the utility class `Core::Notifier` interfaces with the event loop system to handle exactly that. Note that all events are registered, and therefore happen, on the event loop of the thread that created the event. ## Dos and Don'ts with event loops - DO NOT store an event loop in a global variable. Because the event loop itself relies on global variable initialization, UBSAN will catch an initialization order fiasco. DO create your main event loop in `main` and pass it to classes which need it. - DO NOT access the current event loop if you don't know on which thread you are running. If there is no event loop on your thread, the program will crash. DO receive the specific event loop you need to talk to as an initializer variable. - DO NOT `pump()` and/or `exec()` the event loop of another thread. While handling events is fine, going to sleep and waking up relies on thread-local variables. DO signal events to event loops on other threads. --- ### Documentation FAQ (`Documentation/FAQ.md`) # Frequently Asked Questions about Ladybird ## What does 'Independent' mean, if you're including third party dependencies? Independent means: - We implement the web platform standards ourselves: Ladybird is not a Blink/Chromium shell, not a WebKit port, not a Firefox fork. - We don't take money from anyone with strings attached ## Is [some particular site] usable in Ladybird? Ladybird is pre-alpha software you have to build from the sources yourself in order to even try. That said, it’s getting better day-by-day at handling some of the most widely-used sites on the web. So, you may find that a given site among the sites you visit daily is already usable in Ladybird. Or you may not. The only way you can really know at this point is to follow the [build instructions](BuildInstructionsLadybird.md) to build Ladybird and try it yourself. ## Windows support when? There are very few maintainers working on Windows support. As such, maintaining a native Windows port would be a lot of effort that distracts from building out the web platform standards in a reasonable amount of time. After we have a solid foundation, we may consider a Windows port, but it's not a priority. In the meantime, Windows developers can use other tools such as WSL2 to work on Ladybird. ## Will Ladybird support `$THING`? Eventually, probably, if there's a Web Spec for it! ## When will you implement `$THING`? There's no concrete roadmap of individual features yet. You can always raise an issue so we can keep track, if one does not already exist! ### Will you have a built in ad blocker? Ladybird supports user-configured content blocker lists, and we already have open issues about supporting uBlock via extensions. ## Is there a release roadmap? - 2026: alpha release (daily driver for developers and early adopters) for Linux and macOS. - 2027: beta release; downloadable app for Linux and macOS. - 2028: stable release for general use ## Well, how do I run this thing then? Simple, my friend! Just refer to the [build instructions](BuildInstructionsLadybird.md). ## I did a `git pull` and now the build is broken! What do I do? If it builds on CI, it should build for you too. You may need to rebuild the toolchain. If that doesn't help, try it with a clean repo. If you can't figure out what to do, ask in the `#build-problems` channel on Discord. ## Where did Ladybird come from? For full details, see the [Ladybird: A new cross-platform browser project](https://awesomekling.substack.com/p/ladybird-a-new-cross-platform-browser-project) announcement from 12 September 2022. Here’s a short timeline: - 2019 June: Work on what eventually became Ladybird started as _LibHTML_ — the beginnings of an HTML viewer for [SerenityOS](https://github.com/SerenityOS/serenity) — with a commit titled [“LibHTML: Start working on a simple HTML library”](https://github.com/SerenityOS/serenity/commit/a67e8238389), and with this commit description: > _I'd like to have rich text, and we might as well use HTML for that. :^)_ LibHTML eventually became [LibWeb](https://github.com/LadybirdBrowser/ladybird/tree/master/Libraries/LibWeb) — which in turn eventually grew into being the core part of the browser engine and browser to which, on 4 July 2022, [the name _Ladybird_ was given](https://www.youtube.com/watch?v=X38MTKHt3_I&t=29s). - 2022 July: Renamed _Ladybird_ by Andreas in [“Let's make a Linux GUI for the SerenityOS browser”](https://youtu.be/X38MTKHt3_I) live-coding video. - 2022 Sept: Spun off from SerenityOS to separate project: [“A new cross-platform browser project”](https://awesomekling.substack.com/p/ladybird-a-new-cross-platform-browser-project) announcement. - 2024 June: [“I'm forking Ladybird and stepping down as SerenityOS BDFL”](https://awesomekling.substack.com/p/forking-ladybird-and-stepping-down-serenityos) announcement from Andreas. - 2024 July: [Ladybird Browser Initiative](https://ladybird.org/posts/announcement/) launched by Andreas and GitHub co-founder [defunkt](https://twitter.com/defunkt) (Chris Wanstrath). ## What makes Ladybird/[Ladybird Browser Initiative](https://ladybird.org/) different? - Fully independent: Written from scratch, using no code from any other browser engine. - Singular focus: Doing only one single thing: building a new browser engine and browser. - No monetization: Will never take funding from default search deals or any other forms of user monetization, ever. ## Are there video/audio announcements and interviews about the start of the Ladybird Browser Initiative? - Ladybird Browser Initiative [announcement video](https://www.youtube.com/watch?v=k9edTqPMX_k) from defunkt explaining the project _raison dʼêtre_ + goals (July 2024). - [Why we need Ladybird](https://changelog.com/podcast/604#t=5:08): _Changelog_ podcast interview with Andreas and defunkt (August 2024); [transcript](https://changelog.com/podcast/604#transcript); [chapters](https://changelog.com/podcast/604#chapters). - [Eron Wolf announcement grant of $200K](https://youtu.be/p6k9qcRpW_k) from [FUTO](https://www.futo.org/about/what-is-futo/) to the project (August 2024). - [Eron Wolf interview with Andreas](https://youtu.be/4xhaAAcKLtI) (August 2024). ## Can you describe some of the project goals and its culture? - Eventually give everybody the choice of a whole new browser they can use for their daily browsing. - Prove it is in fact possible to build a completely new browser, by implementing from the WHATWG/W3C/etc. specs. - Have a lot of real fun together actually doing it. - Prove that developing an engine doesn’t take hundreds of engineers — and not anything close to even just a hundred. - Browser engineering: Further help de-mystify it and make it a standard thing to learn (hat tip: https://browser.engineering/). - Using project Discord server for communication [discord.gg/nvfjVJ4Svh](https://discord.gg/nvfjVJ4Svh). - Using [one GitHub repo](https://github.com/LadybirdBrowser/ladybird) for issues, CI, and test automation. ## What are some of the project coding conventions? And do you have any activity metrics? - Implement web-platform features exactly according to the actual steps in spec algorithms. - Abundant code comments with verbatim spec text copy/pasted in — showing exactly what’s being implemented. - Additional _`“AD-HOC:”`_ comment convention to mark code that doesn’t map to any spec requirements. - Class/file names tend to closely match actual current spec terms; e.g., `Navigable.h`, `Transferable.h`. - [“critically reading standards and reporting what is wrong”](https://matrixlogs.bakkot.com/WHATWG/2024-08-23#L10) - Project activity relative rankings: https://git-pulse.github.io/snapshots/?project=LadybirdBrowser_ladybird ## Do you have some general details about the code and basic architecture? - Some use of third-party libraries (e.g., Harfbuzz, Skia, [simdutf](https://github.com/simdutf/simdutf), libcurl). - Performance optimizing is not yet a super-high priority (but performance-boosting changes are regularly getting made). - Code size: - Roughly same size (number of lines of code) as Servo. - About 1/15th as many lines of C++ code as WebKit. - About 1/20th as many lines as C++ code Gecko. - About 1/50th as many lines as C++ code Chromium. - Level of standards support: [wpt.fyi/results?product=ladybird](https://wpt.fyi/results/?product=ladybird) has current test results for all WPT tests. - [LadybirdBrowser/ladybird#features](https://github.com/LadybirdBrowser/ladybird/#features): - UI process, ImageDecoder process, RequestServer process, WebContent processes. - LibWeb: core web-rendering engine (HTML, CSS, Events, DOM, APIs). - LibJS: JavaScript engine written from scratch (currently JIT-less). - LibWasm: WebAssembly implementation written from scratch. - [AK](https://github.com/LadybirdBrowser/ladybird/tree/master/AK): Ladybird standard library/abstractions: asserts, smart pointers, strings, numbers (e.g., [fast_float](https://github.com/fastfloat/fast_float) impl.), more… ## What about funding? - Funded _entirely_ through donations and sponsorships. - https://donorbox.org/ladybird – donations of any amount: $10, $50, $100, etc. - [Sponsorship opportunities](https://ladybird.org/#sponsors): Platinum $100,000 • Gold $50,000 • Silver $10,000 • Bronze $5,000 • Copper $1,000. - Ladybird Browser Initiative announced/seeded with [1 million dollar donation](https://twitter.com/defunkt/status/1807779408092234134) from defunkt and his family. ## Do you have some places where I can watch videos related to the project? - Ladybird [YouTube channel](https://www.youtube.com/@LadybirdBrowser): monthly Ladybird project updates from Andreas. - Andreas’ [YouTube channel](https://www.youtube.com/@awesomekling): 1000+ videos from 6+ years; incl. “car talk” + OS/browser “hacking” (live-coding) videos. ## Is there some related background to help me understand what a browser _engine_ is and why it’s important? - [Understanding the role of browser engines](https://assets.publishing.service.gov.uk/media/61b86737e90e07043c35f5be/Appendix_F_-_Understanding_the_role_of_browser_engines.pdf) (UK Competition and Markets Authority [Mobile ecosystems market study](https://www.gov.uk/cma-cases/mobile-ecosystems-market-study#interim-report)). --- ### Documentation GettingStartedContributing (`Documentation/GettingStartedContributing.md`) # Getting involved with Ladybird Welcome to the Ladybird web browser project! This document is a beginner-friendly guide to getting familiar with Ladybird and helping the project through testing, bug reports, reductions, standards discussion, design discussion, security reports, and technical feedback. ## Getting familiar with the project Ladybird is a large project making use of many homegrown and third-party libraries, written primarily in C++. It is recommended you read the README and FAQs in case they already answer any questions you have: * [README](/README.md) * [FAQ](FAQ.md) * [FAQ on the Ladybird website](https://ladybird.org/#faq) The [Discord server](https://discord.gg/nvfjVJ4Svh) is the preferred way to get in contact with the maintainers and community. ## Getting familiar with browser engineering in general If you’ve never worked on browser-engine code before, and you’re not sure where to begin — one great place to get started is by reading the book [Web Browser Engineering](https://browser.engineering/). It explains how browser engines in general work, and how they’re built — by walking you through real code for actually building all the parts of a basic but complete browser engine (networking code, HTML parsing, layout engine, JavaScript handling, and more), in a couple thousand lines of Python. ## Building the code Ladybird must be built from source during this pre-alpha stage of development, and currently natively supports Linux and macOS; running it on Windows requires WSL. Carefully follow the steps outlined in the [build instructions](BuildInstructionsLadybird.md). If you are facing issues, consult the [troubleshooting guide](Troubleshooting.md) and the #build-problems channel on Discord. ## Finding bugs and other issues Here are some of the ways you can find an issue in Ladybird: * By checking the [issue tracker](https://github.com/LadybirdBrowser/ladybird/issues). * Manually, by using the browser as you normally would. * By finding failing WPT tests on [WPT.fyi](https://wpt.fyi/results/?label=master&product=ladybird). You do not need to submit issue reports for individual tests. * By finding WPT tests on [WPT.fyi](https://wpt.fyi/results/?label=master&product=ladybird) that are [timing out in Ladybird](https://wpt.fyi/results/?product=ladybird&q=status%3Atimeout). For a real-world walk-through of doing that from start to finish with an actual timing-out-in-Ladybird test case, see the [“Fixing a WPT timeout in Window.postMessage()”](https://www.youtube.com/watch?v=X4S9afzRTXs) “browser hacking” video. * By using a profiling tool such as [Callgrind](https://valgrind.org/docs/manual/cl-manual.html) to find code that can be improved. * By looking for [`TODO`](https://github.com/search?q=repo%3ALadybirdBrowser%2Fladybird%20%22%2F%2F%20TODO%22&type=code) and [`FIXME`](https://github.com/search?q=repo%3ALadybirdBrowser%2Fladybird+%22%2F%2F+FIXME%22&type=code) comments in the codebase. If you’re not necessarily fluent in C++, beginning by troubleshooting WPT tests may be the very best way to get started helping the project — especially if you _do_ already have some proficiency with frontend JavaScript code. That’s because without even knowing any C++ at all, you can still — by working just with the JavaScript code in the WPT test source — get a long way toward isolating the cause of a particular WPT test failure or timeout. That alone can be a very big help to maintainers and other people investigating the related C++ code. ## Submitting an issue If you have found an issue that is not already in the [issue tracker](https://github.com/LadybirdBrowser/ladybird/issues), you may submit it. Do not submit general questions about the project, please use the Discord server instead. Read the [project participation guidelines](/CONTRIBUTING.md), in particular the Issue policy and Human language policy. It is recommended you reduce the website to the most minimal amount of HTML/CSS/JS which still results in the error (if applicable), and provide the result expected from other browsers vs Ladybird. Read the [detailed issue-reporting guidelines](/ISSUES.md) for the exact steps to do so. ## Learning the codebase ### Getting familiar with C++ Ladybird requires at least a basic knowledge of C++. Consult a tutorial website like [Learn C++](https://www.learncpp.com/) and online references if you need help. ### Getting familiar with the codebase Ladybird makes use of the included AK library instead of the C++ STL, and employs a specific coding style based around it. Unfortunately most AK and internal library facilities are not documented; you may need to look for the header files, and examples of usage in existing code. Developer documentation: * [Coding style](CodingStyle.md) * [Coding patterns](Patterns.md) * [Smart pointers](SmartPointers.md) * [String formatting](StringFormatting.md) --- ### Documentation LibWebFromLoadingToPainting (`Documentation/LibWebFromLoadingToPainting.md`) ## LibWeb: From loading to painting **NOTE: This document is a work in progress!** FIXME: Add more information about everything. FIXME: Add lots of links to relevant specs, etc. ### Resource loading We make an IPC call to RequestServer, asking it to start loading the URL we've been asked to load. ### HTML parsing The job of the HTML parser is to take an input stream, possibly determine its encoding, and then parse it into a DOM tree. For historical reasons, this is unusually complicated. LibWeb implements the HTML tokenization and parsing algorithms as laid out in the HTML specification. While the spec is detailed, it's also highly idiosyncratic. The tokenizer and parser reach into each other and update the other's state in certain situations. Due to the `document.write()` API, the parser also allows programmatic injection of new input into the parser from JavaScript. The document being parsed may run JavaScript, and this JavaScript may indirectly interact with the parser by feeding it override inputs. ### CSS parsing * CSS parser * Builds the CSSOM * Values with variables can't be resolved until cascade, kept as "unresolved" values ### JS parsing & execution * JS parser * Builds JavaScript AST * Interpreter runs AST * Garbage collector (basic stop-the-world mark&sweep) ### Style computation This step is concerned with finding the set of CSS values that apply to a given DOM element. #### Selector matching A CSS selector is represented by the CSS::Selector class. Given the following selector: ```css #foo .bar.baz > img ``` We get the following C++ object tree: ``` * CSS::Selector * CSS::CompoundSelector (combinator: ImmediateChild) * CSS::SimpleSelector (type: TagName, value: img) * CSS::CompoundSelector (combinator: Descendant) * CSS::SimpleSelector (type: Class, value: bar) * CSS::SimpleSelector (type: Class, value: baz) * CSS::CompoundSelector (combinator: None) * CSS::SimpleSelector (type: ID) ``` Selectors are evaluated right-to-left, and we're looking for the first opportunity to reject it. ##### Optimization notes We try to minimize the number of selectors that have to be evaluated for each DOM element. The main optimization is a cache in StyleComputer that divides style rules into buckets based on what their rightmost complex selector must match. For example, a selector that can only match an element with the class "foo" will only ever be evaluated against elements that currently have the class "foo". #### Cascading to the final values The C in CSS is for "cascading" and "the cascade" refers to the process where all the CSS declarations that should apply to a DOM element are evaluated in order. The order is determined by a number of factors, such as selector specificity, rule order within the style sheet. There's also per-property consideration of the `!important` annotation, which allows authors to override the normal cascade order. * To compute the "computed style" for an element... * Perform the CSS cascade to determine final property values * Interpolate variables * Absolutize, etc We separate CSS rules by their cascade origin. The two origins we're concerned with are "user-agent" and "author". If we supported custom user style sheets (we don't), they'd need a separate cascade origin as well. The cascade origin determines the processing order for rules. The "user-agent" style is the least important, so it gets processed first. Then author style is added on top of that. Note: the user-agent style is a built-in CSS style sheet that lives in the LibWeb source code [here](https://github.com/LadybirdBrowser/ladybird/blob/master/Libraries/LibWeb/CSS/Default.css). The end product of style computation is a fully populated StyleProperties object. It has a StyleValue for each CSS::PropertyID. In spec parlance, these are the *computed* values. (Note that these are not the same as you get from `getComputedStyle()`, that API returns the *resolved* values.) #### Resolving CSS custom properties ("variables") Custom properties are resolved during the cascade. This is the earliest possible time where this can be done, as the value of a given variable depends on the result of the cascade. ### Building the layout tree To prepare for layout, we combine the DOM with the results of style computation to create a new tree: the layout tree. This is essentially the "box tree" in the CSS specifications, with some important differences that allow us to make better use of the C++ type system. There isn't a 1:1 mapping between DOM nodes and layout nodes. Elements with `display:none` style don't generate a layout node at all. A number of tree fix-ups are also performed: - To maintain the invariant that block containers only have all block-level children or all inline-level children, inline-level boxes with block-level siblings are wrapped in anonymous wrapper boxes. - If an individual table component box is found outside the context of a full table, a set of anonymous table boxes are generated to compensate and ensure that there's always a fully-formed table. (FIXME: This is currently buggy..) - For list item boxes (`display: list-item`), a box representing the marker is inserted if needed. ### Layout Layout starts at the ICB (initial containing block), which is the layout node that corresponds to the DOM document node. CSS says that the ICB should be the size of the viewport, so the very first thing layout does is assign these dimensions. Layout works through a mechanism call formatting contexts. CSS defines a number of different formatting contexts: - Block Formatting Context (BFC) - Inline Formatting Context (IFC) - Table Formatting Context (TFC) - Flex Formatting Context (FFC) In LibWeb, to simplify the layout model, we also define our own SVGFormattingContext for embedded SVG content. This isn't part of the SVG specification, but simplifies the implementation. Layout is fundamentally recursive. We start at the ICB, which always creates a BFC. #### Block-level layout BFC works by laying out its children, one by one in tree order. If its children are block level, they are laid out along the block axis of the BFC's root box. Block-axis margins between adjacent boxes are collapsed. Floating boxes (CSS `float:left` or `float:right`) are interesting. First, we compute where they would have ended up if they weren't floating. Then we push them towards the left or right edge as requested. If they collide with the edge of another floating box before getting to the edge, they are stacked next to that box, forming a sort of "float line". BFC keeps track of floating boxes on both sides. #### Inline-level layout If its children are inline level, BFC creates an IFC to handle them. Unlike other formatting contexts, IFC can't work alone; it always works together with its parent BFC. The job of IFC is to generate line boxes. Line boxes are essentially a sequence of inline content fragments, laid out along the inline axis. Line boxes are stored in the IFC's containing block box. There are three main classes involved in inline-level layout: - InlineFormattingContext (IFC) - LineBuilder - InlineLevelIterator IFC drives the high-level loop by creating a LineBuilder and an InlineLevelIterator. It then traverses the inline-level content within the IFC containing block, one item at a time, by calling InlineLevelIterator::next(). The items produced by InlineLevelIterator are then passed along to LineBuilder, which adds them to the line box we're currently building. When a line box is filled up, we insert a break and begin a new box after it. We always keep track of how much space is available on the current line. When starting a new line, this is reset by computing the width of the IFC's containing block and then subtracting the size occupied by floating boxes on both sides. We get this information by querying the parent BFC about floating boxes intersecting the Y coordinate of the new line. The result of performing a layout is a LayoutState object. This object contains the CSS "used values" (final metrics, including line boxes) for all box that were in scope of the layout. The LayoutState can either be committed (via `commit()`) or simply discarded. This allows us to perform non-destructive (or "immutable") layouts if we're only interested in measuring something. ### Paintable and the paint tree When layout is finished, we take all the final metrics for each box and generate a new tree: the paint tree. The paint tree hangs off of the layout tree, and you can reach the corresponding paintable for a given layout node via `Layout::Node::paintable()`. There's also a convenience accessor in the DOM: `DOM::Node::paintable()`. Unlike Layout::Node (which is basically a box tree node with associated style), Paintable is an object with fully finalized metrics. It has two jobs, painting and hit testing. Note that not every layout node will have a paintable. If a layout node cannot possibly be visible, it may not require a paintable. Every paintable has a corresponding layout node, and painting code will reach into the layout node for some information, to avoid having it in multiple places. ### Stacking contexts There's one final thing we have to do before we can paint: we have to create stacking contexts. Stacking contexts are a 3-dimensional model of layers (stacking contexts) that places content along a Z axis. This is what the CSS `z-index` property is for. The set of rules for what becomes a stacking context are somewhat intricate, but the important thing is that we create a new tree: the stacking context tree. The stacking context tree is rooted at the ICB, and can have zero or more descendants. Each descendant stacking context has a corresponding layout that it's attached to. ### Painting Painting follows the order specified in the CSS2 appendix E. The rules are quite involved, but two main things to know about: - Painting is driven through stacking contexts, which are painted back-to-front (stacking context tree order) - Painting is performed in *phases*. For each stacking context, we paint in order: backgrounds & borders, floats, backgrounds & borders for inline and replaced content, foreground (text), focus outlines and overlays. --- ### Documentation LibWebPatterns (`Documentation/LibWebPatterns.md`) # LibWeb Code Style & Patterns This document aims to describe agreed upon code style and patterns used across LibWeb. ## Directory Structure Generally we use a subdirectory, and thus C++ namespace, for each individual spec. For example XHR (`xhr.spec.whatwg.org`): - Code lives in `LibWeb/XHR/` - Uses the C++ namespace `Web::XHR` If necessary, code can also be grouped into sub-subdirectories (for example `HTML/Scripting/`). Sometimes a spec document affects several areas of the web platform. An example of this is CSSOM, which of course contains features belonging in `LibWeb/CSS/` / `Web::CSS`, but at the same time implements additions to `Window` from the HTML spec. Use best judgement in those cases. ## Error Handling The following error types are commonly used in LibWeb, each having a different purpose: ### `AK::ErrorOr` This error type is generally only used to propagate OOM errors from AK and other general libraries. It should not be used to propagate any other kinds of errors, even though this is supported and used in other parts of the system. For LibWeb, use any of the error types below. This should be propagated as far as possible before being turned into a JS error object (via the `TRY_OR_THROW_OOM` macro). This avoids a situation where almost everything returns a generic `WebIDL::ExceptionOr`. ### `Web::WebIDL::ExceptionOr` This is the most common and at the same time most broad error type in LibWeb. Internally it stores a variant of supported errors: - `SimpleException` - `GC::Ref` - `JS::Completion` (from `JS::ThrowCompletionOr`, assumed to be of `Type::Throw`) Use this error type for anything that needs to interact with the JS bindings, which will generally know how to turn any of the internally supported errors into JS objects. ### `Web::WebIDL::SimpleException` This is a thin wrapper around various built-in errors from ECMAScript: - `EvalError` - `RangeError` - `ReferenceError` - `TypeError` - `URIError` Instead of constructing one of these directly, create a `SimpleException` with the appropriate type and message instead whenever required by a web spec. These will be converted into actual JS objects in the bindings layer. > **Note** Relevant WebIDL documentation: https://webidl.spec.whatwg.org/#dfn-simple-exception ### `Web::WebIDL::DOMException` This is an error type from the WebIDL spec specifically for web AOs where none of the JS built-in error types are sufficient. Like `SimpleException`, use when indicated by a web spec. > **Note** Relevant WebIDL documentation: https://webidl.spec.whatwg.org/#idl-DOMException ### `JS::ThrowCompletionOr` This is an error type from LibJS, which uses "completions" to propagate errors and other types of AO results. Don't use this in LibWeb unless absolutely necessary, e.g. when overriding a `JS::Object` virtual method that returns this type. At the call site, these should be wrapped in a `ExceptionOr` as soon as possible for further propagation. > **Note** Relevant ECMAScript documentation: > https://tc39.es/ecma262/#sec-completion-record-specification-type ## Comments As in LibJS, **all** functions that represent an operation or JS function from a web specification must have: - A spec link, above the function definition: ```cpp // https://fetch.spec.whatwg.org/#concept-fetch WebIDL::ExceptionOr> fetch(JS::Realm& realm, Infrastructure::Request& request, Infrastructure::FetchAlgorithms const& algorithms, UseParallelQueue use_parallel_queue) { // ... } ``` - Comments for each individual step of the operation: ```cpp // 1. Assert: request’s mode is "navigate" or processEarlyHintsResponse is null. VERIFY(request.mode() == Infrastructure::Request::Mode::Navigate || !algorithms.process_early_hints_response().has_value()); // 2. Let taskDestination be null. GC::Ptr task_destination; // ... ``` - If a step cannot be implemented at the time, prepend it with a `FIXME` - Add a blank line between code and the next comment - Optimizations (e.g. fast paths) should be marked as such with an `// OPTIMIZATION:` comment explaining the reasoning - When adding non-standard code for a feature that is otherwise well-specified, it should be marked as such. This does not universally apply as certain areas (layout and painting, for instance) are only broadly spec'd - If the spec has additional prose before or after its algorithm steps, that doesn't need to be copied into the code ## JS Interfaces ### IDL Try to copy IDL verbatim, only making changes where necessary (IDL parser shortcomings, non-standard extended attributes). This includes not reordering functions, changing parameter names, etc. The major difference to the spec is that we use four spaces for indentation, like for any other code (not two). ### C++ Naming Try to stick with the interface's exact name as much as possible for the class and file names (no `Object` suffixes like in LibJS, for example). When there's a name clash, try to introduce a nested namespace, e.g. `Fetch::Request` vs `Fetch::Infrastructure::Request`. ### File placement The `.cpp`, `.h`, and `.idl` files for a given interface should all be in the same directory, unless the implementation is hand-written when it cannot be generated from IDL. In those cases, no IDL file is present and code should be placed in `Bindings/`. --- ### Documentation MediaPipelineDesign (`Documentation/MediaPipelineDesign.md`) # Media Pipeline ## Overview LibMedia turns demuxed media data into decoded audio and video, then feeds it to sinks that are driven by playback time. The pipeline is pull-based: downstream nodes ask upstream nodes whether data is available, then pull data when the reported status allows it. The current pipeline is made of three categories of nodes: - Producers materialize raw audio/video data. - Sinks consume that raw audio/video data. - Processors are both producers and sinks, pulling data from an input producer to transform it before a downstream sink makes use of it. Audio and video use separate producer interfaces because the data they carry is different, but their control flow is intentionally similar. ## Producer Interface Producers expose three core operations: - `peek()` reports the current status and, when data is available, exposes the head of the producer's output without removing it. - `consume()` removes the head that a prior `peek()` exposed. - `set_wake_handler(...)` is used by the downstream node to wake itself when a previously-observed status would result in it going to sleep. Downstream nodes `peek()` when they need new data, then either read the head and `consume()` it or go to sleep. Peeking without consuming lets a node decide whether to take the head, rather than being forced to accept data it may have no room for. ## PipelineStatus `PipelineStatus` is the shared status language between nodes: - `Pending`: Data is not available yet, but may become available later. - `HaveData`: A peek exposes data. - `Blocked`: Data is not available yet, i.e. we have run out of buffered data from over the network. - `Suspended`: The upstream node has released its decoding resources and will not produce data until it receives a seek. - `EndOfStream`: We have reached the end of the input data. - `Error`: The upstream node encountered an error and cannot continue without a seek. `HaveData` carries data. All other statuses require handling by downstream code. `Pending`, `Blocked`, `Suspended`, `EndOfStream` and `Error` are waiting statuses. A downstream node that normally polls for upstream input seeing these should sleep until its wake handler fires. `EndOfStream` and `Error` are terminal statuses. They resolve seeks even though they are still "waiting" statuses for helper APIs, because no more data is required to decide the seek has completed. ## Wake Handlers Wake handlers do not carry state. A wake means the downstream node should `peek()` again. Nodes should dispatch a wake when the downstream node may be waiting, and the status has changed to one that resolves a seek: `HaveData`, `EndOfStream`, or `Error`. Some nodes (i.e. AudioMixer) may also wake when moving away from a previously dispatched `EndOfStream`, so stale EOS state can be recovered after a seek or after new input becomes available. ## Seeking Seeking is initiated downstream and forwarded upstream. For downstream nodes, a seek completes when the upstream node reports a status that resolves the new position. Usually that means `HaveData`, but `EndOfStream` or `Error` can also complete the wait. Sinks report pipeline status changes to their users. A user such as the playback manager can interpret a seek-resolving status as seek completion. If a node forwards a seek upstream, it can clear or invalidate its cached data, since the upstream node is required to emit data at or before the target timestamp. However, if a node uses its cached data to resolve seeks, it must also resolve seeks past the last frame in that cached data if its last known status is `EndOfStream`. This ensures that a seek past EOS will not invalidate in-flight frames by bumping a seek generation. ## Decoded Data Producers Decoded data producers run demux and decode video/audio data into queues in order to absorb variance in processing for each individual coded frame. When a downstream `consume()` removes an item from the queue, the producer wakes its decoder thread so it can refill the queue. When the queue is full and no downstream activity occurs for the idle timeout, the producer auto-suspends: it drops its decoder, its queue, and any frame pool buffers it can free, then wakes the consumer with a `Suspended` status. `peek()` and `consume()` defer the idle timeout, but they never resume a suspended producer. When a downstream node needs new data, it must explicitly `seek()` the suspended node to resume it, so that the pipeline may insert pre-roll data at any stage where it is needed (i.e. for audio stretching). ## Playback Manager `PlaybackManager` creates, modifies and drives the end-to-end playback pipeline. When media data is received, it will spawn a thread to determine what tracks are present, and connect the necessary nodes for playback to begin. Behavior is defined through state handlers derived from `PlaybackStateHandler`, with each overriding methods for various functions and signals to determine when to transition to another state. Upon entering or exiting, a state handler will drive changes to the pipeline, like pausing/resuming or seeking. The media time is derived from the audio sink when audio is used, otherwise `GenericTimeProvider` calculates time from the monotonic clock. ## Audio Pipeline The usual audio path is: ```text DecodedAudioProducer -> AudioMixer -> AudioTimeStretchProcessor -> AudioPlaybackSink -> PlaybackStream ``` `AudioPlaybackSink` owns a small queue of `AudioBlock`s pulled from upstream, which it fills on a separate thread to avoid blocking the `PlaybackStream` data callback. It starts pulling input when its `start()` method is called, so that all inputs can be connected first. When its input reaches `EndOfStream`, it continues producing silence to allow the time to advance in case there is video data still available. `AudioMixer` sequences/mixes audio from multiple inputs into a single output. It emits silence for gaps, and pauses output when any input indicates data is not ready yet. When all inputs are at `EndOfStream`, the output becomes `EndOfStream` as well. `AudioTimeStretchProcessor` stretches audio without affecting pitch. ## Video Pipeline The usual video path is: ```text DecodedVideoProducer -> DisplayingVideoSink ``` `DisplayingVideoSink` keeps the current frame and the next frame. It advances when playback time passes the current frame's display interval. Video seeks are comparatively expensive, so the sink can satisfy some seeks locally when the requested timestamp is already covered by the current or next frame interval. This avoids unnecessary upstream seeks during scrubbing. The same optimization is less important for audio because it decodes exponentially faster. ## Threading The media pipeline crosses several threads: - The main thread coordinates playback state and serializes cross-thread communication through its event loop - Decoded data producers manage decoding threads to amortize the cost to decode each frame - The audio sink runs a processing thread to amortize the cost of mixing/stretching each audio block - The playback stream data callback is invoked from an (often system-managed) thread Data should only be consumed via `peek()` and `consume()` from a single thread, to allow producers to use lock-free structures internally. Control methods like `seek()` should similarly only initiate from a single thread, or be otherwise serialized. Avoid synchronous callback dispatch while holding locks unless the callee is known not to reenter the same pipeline. Deferred dispatch is often used to keep lock ordering simple. Wake handlers must be removed before disconnecting or destroying a node. An upstream node must never invoke a handler after downstream has cleared it. --- ### Documentation Omnibox (`Documentation/Omnibox.md`) # Omnibox Ladybird's omnibox combines URL entry, search, history, bookmarks, adaptive learning, and remote search suggestions. The implementation is used by the UI frontend through `LibWebView`. The central rule is that ordering, automatic selection, and inline completion are separate decisions. A result may be useful enough to display near the top without being safe to select or complete automatically. ## Code structure The implementation is divided into a few focused components: - `Omnibox` owns an editing session. It tracks the user's query, displayed text, selected row, completion state, popup state, and active query generation. - `Autocomplete` coordinates local and remote suggestion delivery. - `AutocompleteService` runs local database work on a serial worker thread. - `AutocompleteRanker` retrieves and scores history, bookmark, and adaptive candidates. - `AutocompleteMuxer` merges duplicate destinations, applies diversity rules, and constructs the final result list. - `HistoryStore`, `BookmarkStore`, and the omnibox engagement tables provide local evidence. - `UI/Qt/Autocomplete` renders the shared suggestion model. `OmniboxSuggestionProvider` is the boundary between the editing state machine and suggestion generation. The production provider wraps `Autocomplete`; tests use a scripted provider so they can deliver results in any order without relying on timing. ## Query lifecycle Every edit starts a new query generation identified by an incrementing `AutocompleteQueryID`. Local retrieval begins immediately. Remote search suggestions are debounced for 100 milliseconds. The local worker owns a separate SQLite connection. There is at most one running local query and one pending query per client. A newer pending query replaces an older one. When possible, a newer query interrupts stale SQLite work rather than waiting for it to finish. Results are delivered incrementally: 1. Local results are ranked and published. 2. A remote response, if enabled and successful, is merged into the same query generation. 3. The combined list is published again. Remote suggestions from the preceding query may remain visible while a compatible continuation is in flight. Only suggestions that still have the new input as a prefix are retained. A successful response replaces these provisional rows. The UI thread discards results when their query ID is no longer active. Ending an editing session, dismissing the popup, or starting another session cancels provider work and invalidates the active generation. Stale results can therefore neither reopen the popup nor become an Enter action. ## Suggestion model `AutocompleteSuggestion` contains: - Its source: literal URL, history, bookmark, adaptive engagement, or search. - Destination text and optional title, subtitle, and favicon. - The input used for presentation highlighting. - A match class and separate relevance components. - Whether it is the verbatim action. - Whether it may be automatically selected. - Whether it may be used for inline completion. The score components are retained after ranking so duplicate destinations can combine independent history, bookmark, and adaptive evidence without losing their provenance. ### Destination identity URL destinations are compared semantically. Scheme differences remain meaningful, while equivalent serializations of the same URL are merged. `www.` and bare hosts share a diversity family but are not otherwise treated as the same destination. Search destinations are identified by Unicode case-folded text with whitespace normalized. This allows an exact remote suggestion to merge with the verbatim search action. When history, bookmark, and adaptive candidates identify the same URL, their score components and eligibility flags are combined. Bookmark presentation is preferred so its title and favicon remain visible. ## Matching URL matching accepts the forms users commonly type by ignoring an `http://` or `https://` prefix, and optionally `www.`, when comparing a query with a candidate. Matching is case-insensitive. Match classes, from strongest to weakest, include: - Exact URL. - URL prefix. - Exact history or bookmark title. - Title word prefix. - URL substring. - Title substring. - Exact or prefix adaptive association. Title matching uses Unicode case folding. URL completion uses ASCII case-insensitive comparison because serialized non-ASCII URL components are already encoded. History titles participate after three input code points. Exact history titles outrank title-prefix matches, allowing a page named `Wikimedia Commons` to rank ahead of pages whose titles merely end in `Wikimedia Commons`. They remain ineligible for automatic selection and inline completion. Bookmark titles and folders normally participate after three input code points. An exact bookmark title participates at any non-empty length, so a bookmark named `GH` is retrieved by `GH`, `gh`, or `Gh`. This exception does not turn partial two-character title prefixes into candidates. An exact title match remains ineligible for automatic selection and inline completion. It is a strong retrieval signal, not permission to replace the user's search action or editor text. ## Ranking Ranking is deterministic and uses bounded integer components. Match quality is the largest signal; history quality, bookmark evidence, and adaptive engagement then refine candidates within the same general match quality. ### History History ranking distinguishes direct navigation intent from passive visits. Visit and direct-visit scores decay over time and are bounded before being added to a candidate score. Reloading or repeatedly encountering a page cannot produce unbounded relevance. For host-like input, history also creates aggregate origin candidates. Evidence comes from a capped number of distinct pages, which prevents one frequently reloaded deep page from making its origin look intentional. The origin may borrow a favicon from a matching page. Deep history pages are suppressed for one- and two-character host queries unless the input contains a URL path. This keeps short result lists from filling with incidental pages. ### Bookmarks A bookmark contributes a fixed relevance bonus in addition to match quality. URL-prefix bookmark matches are strong navigation evidence. Bookmark title and folder matches are useful for retrieval but are not automatically selected or inline-completed. Deep bookmarks remain eligible for a two-character URL prefix. Exact short title matches also remain eligible, but do not become automatic actions. ### Adaptive engagements The omnibox records committed input-to-destination associations. Search and URL destinations are stored separately. Explicit row choices and automatic commitments have separate counts. Exact associations are stronger than prefix associations. Short adaptive prefixes require repeated explicit use before they can become automatic: - A one-character deep destination requires three explicit uses. - A two-character deep destination requires two explicit uses. An exact input-to-URL association of at least two characters becomes automatic after one explicit choice, including search-like input containing whitespace. This allows the omnibox to learn a deliberate navigation without allowing passive title matches to replace the search action. Adaptive scores decay with time. Prefix evidence is scaled by the square root of the typed-prefix length divided by the learned-input length, so very short prefixes receive less credit. Merely displaying, automatically highlighting, or hovering a suggestion does not record an engagement. A private session never records engagements. ## Result composition The muxer first merges candidates with the same destination and sorts them by relevance. It then constructs a bounded result list while preserving the verbatim action and limiting repetition. The current limits are soft: - At most four local navigation rows before deferred local rows. - At most three remote search rows before deferred remote rows. - At most two rows per origin for ordinary host queries. - At most one row per origin and five total rows for one- and two-character host queries. Deferred source rows may fill unused space after the first pass. This prevents a source cap from leaving the popup unnecessarily sparse. For short queries, candidates from the same origin are collapsed to one representative. Proven adaptive destinations are preferred, followed by matching deep bookmarks, followed by origin rows. An exact bookmark-title match is treated as a matching deep bookmark for this decision, preventing an origin row from hiding it. The highest-ranked candidate eligible for automatic selection is moved to the first row. A higher-scoring but ineligible title or substring match may remain visible below it. ## Automatic selection Automatic selection determines what Enter does when the user has not deliberately chosen another row. It does not imply inline completion. A candidate may be selected automatically when it is supported by strong navigational evidence, for example: - A sufficiently long URL prefix backed by direct visits. - A bookmark URL prefix of at least two characters. - An adaptive association whose evidence meets the short-prefix thresholds. Title-only, folder, substring, previous-search, and remote suggestion matches are not automatic URL actions. The verbatim URL-or-search action remains available in every non-empty result list. Automatic defaults use hysteresis during incremental refreshes. A challenger replaces the current default only when it exceeds the incumbent by both 10 percent and 100 relevance points. This avoids visible selection churn as local and remote results arrive. ## Inline completion Inline completion is intentionally stricter than automatic selection. A candidate must: - Be eligible for automatic selection. - Be a URL-prefix match. - Extend the user's input at the end of the editor. - Produce a non-empty suffix after optional scheme and `www.` handling. - Not contain a query string unless an exact adaptive association permits it. Title, folder, substring, search, and literal URL candidates never inline-complete. The typed prefix is preserved exactly; only the borrowed suffix is selected. An existing completion is retained across forward typing while it remains valid and is within 150 relevance points of the best inline candidate. A materially better non-inline default clears it. Backspace suppresses completion for the resulting input. Typing a different input lifts the suppression. Moving the cursor away from the end removes the completion and prevents late results from applying another one. Right Arrow and End accept a completion, adopt the displayed text as the new query, and requery it. ## Editing and activation `Omnibox` keeps the user's query separate from borrowed display text. Display text has one of three provenances: - User text. - Inline completion. - Keyboard row preview. Arrow keys explicitly select rows. A selected row may preview its destination in the editor while the original query remains available for restoration. Pointer hover only changes row appearance; it does not select, preview, or train the result. Escape closes the popup and restores the query. Clicking outside does the same. If the user edits or rejects a completion, Enter commits the text currently owned by the user rather than silently choosing an unrelated automatic row. An explicitly selected row remains selected across a refresh of the same generation when a result with the same destination still exists. If it disappears, its preview is removed. Automatic selection is recalculated separately. Enter never waits for suggestions. If the displayed rows belong to an older query generation, the current input is immediately committed through normal URL-or-search resolution. ## Persistence and deletion History stores visit counts, direct-visit counts, last-use timestamps, and decayed scores. Redirect chains distinguish direct navigation from visits produced by redirects so redirect targets do not inherit typed intent. Engagement rows store normalized input, destination kind, destination identity, explicit and automatic use counts, and the last-use time. Database migrations add these fields to existing profiles. The database layer supports floating-point values, statement interruption, and a busy timeout because autocomplete reads concurrently with history writes. Removing a history row also removes its engagement associations unless the destination remains bookmarked. Forgetting a site and clearing all history remove the corresponding associations. ## Private browsing Private autocomplete reads normal-profile history, bookmarks, and adaptive associations so local suggestions remain useful. It does not write history or engagement data. Remote suggestions use the private RequestServer connection. No history, bookmark, or engagement data is sent to the search provider; the request contains only the query required by the configured autocomplete engine. ## Presentation Both native frontends render the same ordered suggestion list without source headers. Search rows use a search icon. Local navigation rows use a favicon when available and otherwise a globe. Bookmarks receive a star badge. Matched portions of titles and URLs use shared match ranges from `LibWebView`, ensuring the UI highlights the same text. The match uses both weight and brightness so it remains visible in dark and light themes. The popup displays at most six rows before scrolling. Rows with a title use two lines; URL-only and search rows use one. Selection and pointer hover have separate visual treatments. ## Settings Remote search suggestions are controlled by the autocomplete-engine setting. Disabling suggestions clears the configured engine; the setting is persisted with the rest of the browser settings and is restored on the next launch. The search engine used for the verbatim action is independent of whether remote suggestions are enabled. ## Tests The implementation has three main deterministic test layers: - `TestAutocompleteRanker` verifies matching, relevance components, eligibility, decay, and short query behavior. - `TestAutocompleteMuxer` verifies destination merging, diversity, source limits, verbatim preservation, and representative selection. - `TestOmnibox` drives the editing state machine with a scripted provider, covering stale delivery, completion acceptance and rejection, selection preservation, activation, and engagement recording. `TestAutocomplete` exercises the asynchronous integration with the application, service worker, bookmark updates, private-profile reads, and remote failure handling. History-store tests cover persisted ranking state, migrations, and deletion behavior. Tests control result delivery or inject a clock rather than depending on wall-clock timing. --- ### Documentation Patterns (`Documentation/Patterns.md`) # Coding Patterns ## Introduction Over time numerous reoccurring patterns have emerged from or were adopted by the Ladybird code base. This document aims to track and describe them, so they can be propagated further and the code base can be kept consistent. ## `TRY(...)` Error Handling The `TRY(..)` macro is used for error propagation in the Ladybird code base. The goal being to reduce the amount of boiler plate error code required to properly handle and propagate errors throughout the code base. Any code surrounded by `TRY(..)` will attempt to be executed, and any error will immediately be returned from the function. If no error occurs then the result of the contents of the TRY will be the result of the macro's execution. ### Examples: Example from LibGfx: ```cpp #include ... snip ... ErrorOr> Bitmap::create_shareable(BitmapFormat format, IntSize size, int scale_factor) { if (size_would_overflow(format, size, scale_factor)) return Error::from_string_literal("Gfx::Bitmap::create_shareable size overflow"); auto const pitch = minimum_pitch(size.width() * scale_factor, format); auto const data_size = size_in_bytes(pitch, size.height() * scale_factor); auto buffer = TRY(Core::AnonymousBuffer::create_with_size(round_up_to_power_of_two(data_size, PAGE_SIZE))); auto bitmap = TRY(Bitmap::create_with_anonymous_buffer(format, buffer, size, scale_factor, {})); return bitmap; } ``` Note: Our `TRY(...)` macro functions similarly to the `?` [operator in rust](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator). ## `MUST(...)` Error Handling The `MUST(...)` macro is similar to `TRY(...)` except the macro enforces that the code run inside the macro must succeed, otherwise we assert. Note that `MUST(...)` should not be used as a replacement for `TRY(...)` in cases where error propagation is not (currently) possible. Instead, the `release_value_but_fixme_should_propagate_errors()` method of `ErrorOr<>` should be used to retrieve the value and to mark the location for future improvement. `MUST(...)` is reserved for cases where we determine through other circumstances that it should not be possible for the code inside the macro to fail or if a failure is serious enough that the program _needs_ to crash. ### Example: ```cpp #include ... snip ... ErrorOr insert_one_to_onehundred(Vector& vector) { TRY(vector.try_ensure_capacity(vector.size() + 100)); for (int i = 1; i <= 100; i++) { // We previously made sure that we allocated enough space, so the append operation shouldn't ever fail. MUST(vector.try_append(i)); } return {}; } ``` ## Fallible Constructors The usual C++ constructors are incompatible with Ladybird's method of handling errors, as potential errors are passed using the `ErrorOr` return type. As a replacement, classes that require fallible operations during their construction define a static function that is fallible instead. This fallible function (which should usually be named `create`) will handle any errors while preparing arguments for the internal constructor and run any required fallible operations after the object has been initialized. The resulting object is then returned as `ErrorOr` or `ErrorOr>`. ### Example: ```cpp class Decompressor { public: static ErrorOr> create(NonnullOwnPtr stream) { auto buffer = TRY(CircularBuffer::create_empty(32 * KiB)); auto decompressor = TRY(adopt_nonnull_own_or_enomem(new (nothrow) Decompressor(move(stream), move(buffer)))); TRY(decompressor->initialize_settings_from_header()); return decompressor; } ... snip ... private: Decompressor(NonnullOwnPtr stream, CircularBuffer buffer) : m_stream(move(stream)) , m_buffer(move(buffer)) { } CircularBuffer m_buffer; NonnullOwnPtr m_stream; } ``` ## The `ladybird_main(..)` program entry point Ladybird has moved to a pattern where executables do not expose a normal C main function. A `ladybird_main(..)` is exposed instead. The main reasoning is that the `Main::Arguments` struct can provide arguments in a more idiomatic way that fits with the Ladybird's internal API surface area. The ErrorOr likewise allows the program to propagate errors seamlessly with the `TRY(...)` macro, avoiding a significant amount of clunky C style error handling. These executables are then linked with the `LibMain` library, which will link in the normal C `int main(int, char**)` function which will call into the programs `ladybird_main(..)` on program startup. The creation of the pattern was documented in the following video: [OS hacking: A better main() for SerenityOS C++ programs](https://www.youtube.com/watch?v=5PciKJW1rUc) ### Examples: A function `main(..)` would normally look something like: ```cpp int main(int argc, char** argv) { return 0; } ``` Instead, `ladybird_main(..)` is defined like this: ```cpp #include ErrorOr ladybird_main(Main::Arguments arguments) { return 0; } ``` ## Intrusive Lists [Intrusive lists](https://www.data-structures-in-practice.com/intrusive-linked-lists/) are used in some specific cases in Ladybird. A data structure is said to be "intrusive" when each element holds the metadata that tracks the element's membership in the data structure. In the case of a list, this means that every element in an intrusive linked list has a node embedded inside it. The main advantage of intrusive data structures is you don't need to worry about handling out of memory (OOM) on insertion into the data structure. This means error handling code is much simpler than say, using a `Vector` in environments that need to be durable to OOM. The common pattern for declaring an intrusive list is to add the storage for the intrusive list node as a private member. A public type alias is then used to expose the list type to anyone who might need to create it. ## Static Assertions of the size of a type It's a universal pattern to use `static_assert` to validate the size of a type matches the author's expectations. Unfortunately when these assertions fail they don't give you the values that actually caused the failure. This forces one to go investigate by printing out the size, or checking it in a debugger, etc. For this reason `AK::AssertSize` was added. It exploits the fact that the compiler will emit template argument values for compiler errors to provide debugging information. Instead of getting no information you'll get the actual type sizes in your compiler error output. Example Usage: ```cpp #include struct Empty { }; static_assert(AssertSize()); ``` ## String View Literals `AK::StringView` support for `operator""sv` which is a special string literal operator that was added as of [C++17 to enable `std::string_view` literals](https://en.cppreference.com/w/cpp/string/basic_string_view/operator%22%22sv). ```cpp [[nodiscard]] ALWAYS_INLINE constexpr AK::StringView operator""sv(const char* cstring, size_t length) { return AK::StringView(cstring, length); } ``` This allows `AK::StringView` to be constructed from string literals with no runtime cost to find the string length, and the data the `AK::StringView` points to will reside in the data section of the binary. Example Usage: ```cpp #include #include #include TEST_CASE(string_view_literal_operator) { StringView literal_view = "foo"sv; String test_string = "foo"; EXPECT_EQ(literal_view.length(), test_string.length()); EXPECT_EQ(literal_view, test_string); } ``` ## Source Location C++20 added std::source_location, which lets you capture the callers __FILE__ / __LINE__ / __FUNCTION__ etc as a default argument to functions. See: https://en.cppreference.com/w/cpp/utility/source_location `AK::SourceLocation` is the implementation of this feature in Ladybird's AK. It's become the idiomatic way to capture the location when adding extra debugging instrumentation, without resorting to littering the code with preprocessor macros. To use it, you can add the `AK::SourceLocation` as a default argument to any function, using `AK::SourceLocation::current()` to initialize the default argument. Example Usage: ```cpp #include #include static StringView example_fn(const SourceLocation& loc = SourceLocation::current()) { return loc.function_name(); } int main(int, char**) { return example_fn().length(); } ``` If you only want to only capture `AK::SourceLocation` data with a certain debug macro enabled, avoid adding `#ifdef`'s to all functions which have the `AK::SourceLocation` argument. Since SourceLocation is just a simple struct, you can just declare an empty class which can be optimized away by the compiler, and alias both to the same name. Example Usage: ```cpp #if LOCK_DEBUG # include #endif #if LOCK_DEBUG using LockLocation = SourceLocation; #else struct LockLocation { static constexpr LockLocation current() { return {}; } private: constexpr LockLocation() = default; }; #endif ``` ## `type[]` vs. `Array` vs. `Vector` vs. `FixedArray` There are four "contiguous list" / array-like types, including C-style arrays themselves. They share a lot of their API, but their use cases are all slightly different, mostly relating to how they allocate their data. Note that `Span` differs from all of these types in that it provides a *view* on data owned by somebody else. The four types mentioned above all own their data, but they can provide `Span`'s which view all or part of their data. For APIs that aren't specific to the kind of list and don't need to handle resizing in any way, `Span` is a good choice. * C-style arrays are generally discouraged (and this also holds for pointer+size-style arrays when passing them around). They are only used for the implementation of other collections or in specific circumstances. * `Array` is a thin wrapper around C-style arrays similar to `std::array`, where the template arguments include the size of the array. It allocates its data inline, just as arrays do, and never does any dynamic allocations. * `Vector` is similar to `std::vector` and represents a dynamic resizable array. For most basic use cases of lists, this is the go-to collection. It has an optional inline capacity (the second template argument) which will allocate inline as the name suggests, but this is not always used. If the contents outgrow the inline capacity, Vector will automatically switch to the standard out-of-line storage. This is allocated on the heap, and the space is automatically resized and moved when more (or less) space is needed. * `FixedArray` is essentially a runtime-sized `Array`. It can't resize like `Vector`, but it's ideal for circumstances where the size is not known at compile time but doesn't need to change once the collection is initialized. `FixedArray` guarantees to not allocate or deallocate except for its constructor and destructor. --- ### Documentation Porting (`Documentation/Porting.md`) # Porting to new Operating System Environments This document outlines the steps required to port Ladybird to a new OS environment, and expectations for such ports to be accepted into the mainline repository. ## Types of Ports There are two types of ports that can be made to Ladybird: - UI port: We define the "browser frontend" as the UI layer. This includes the browser window, tabs, address bar, etc. - Platform port: This includes the underlying platform-specific code that interacts with the OS. This includes things like file I/O, networking, and process management. ### UI Ports There are currently two supported UI ports: * [Android UI](https://developer.android.com/develop/ui) - The native UI on Android. * [Qt](https://doc.qt.io/qt-6/) - The UI used on all other platforms. ### Platform Ports There are currently two supported platform ports: - GNU/Linux: The Linux platform port that may work on other POSIX platforms - macOS: The macOS platform port Many other POSIX desktop platforms are known to work, or have worked in the past, but are not officially supported. Among others, these include Alpine Linux, FreeBSD, OpenBSD, and Haiku. Support for these systems is community-driven, meaning there is no regular CI to ensure that each master branch commit maintains their functionality. Contributions to restore or improve compatibility are welcome! There is currently one in progress platform port: - Android: The Android platform port, using the Android SDK/NDK directly. ## Porting Steps ### UI ports UI ports mostly concern themselves with the UI layer. This means the main Ladybird process, using LibWebView. To create a new Ladybird UI, you will need to implement a new `WebView::ViewImplementation` subclass. ViewImplementation is the main interface between the UI process and WebContent processes. It is expected that each tab of the browser will have its own WebContent process. This is all managed by the WebView layer. Each UI port must also subclass `WebView::Application` to add any UI-specific command-line flags. TODO: Explain any more details that are necessary ### Platform ports Platform ports concern themselves with the underlying OS-specific code. In Ladybird, this code is largely contained in the AK and LibCore libraries. AK is the standard template library for Ladybird. The first step of a new platform port is a new platform define in `AK/Platform.h`. This define will be used to conditionally compile platform-specific code. In AK, the most likely class to need platform-specific code is `AK::StackInfo`. LibCore is an abstraction over POSIX. It contains classes to wrap lower level OS functionality into APIs that are comfortable for Ladybird developers to use. The most likely place to need adjustment is `Core::System`, followed by `Core::Process` and `Core::Socket`. Ladybird makes heavy use of IPC, and the IPC layer is in `LibIPC`. This layer is mostly platform-agnostic, but there are some platform-specific details in LibCore that may need to be adjusted. The IPC system is based on Unix domain sockets, so any platform that supports Unix domain sockets should be able to use the IPC system out of the box. ## Special Consideration ### Windows Over the years excitement about a native Windows port has waxed and waned. The main issue is that Ladybird is built on top of LibCore, which is a POSIX abstraction. Windows is not POSIX, and so a Windows port requires a significant amount of effort to implement. To limit the scope of the work, we have decided that a Windows port will need the following properties: - Target x86_64-windows-msvc and arm64-windows-msvc only. We are not interested in accepting patches to make MinGW or MSYS2 work. - The port must use `clang-cl.exe` as the compiler. We are not interested in accepting patches to make MSVC work. - Platform `#ifdef`s must stay within AK and LibCore, with a few exceptions in LibWebView. - Prefer separate cpp files with the same interface to `#ifdef`s within a single file. - Avoid `#ifdef`s in headers, as much as possible. --- ### Documentation ProcessArchitecture (`Documentation/ProcessArchitecture.md`) # Ladybird Browser process architecture *NOTE: This document is partly aspirational, in that the state of the code does not yet fully reflect what's described here. Implementation is underway.* The Ladybird web browser uses a multi-process architecture to improve stability and security in the face of arbitrary (and possibly hostile) web content. ## Process overview Every instance of the **Browser** application can have one or more tabs open. Each tab has a unique **WebContent** service process spawned on its behalf. Two important aspects of web browsing are further separated from the **WebContent** process: *network requests* and *image decoding*, segregated to the **RequestServer** and **ImageDecoder** processes respectively. All processes are aggressively sandboxed using the `pledge()` and `unveil()` mechanisms. Furthermore, all processes except **Browser** run as an unprivileged user, separate from the primary logged-in desktop user. ### Process: WebContent This process hosts the main HTML/CSS engine (**LibWeb**.) It also runs JavaScript (**LibJS**.) It gets input events from **Browser** and paints the web content into shared bitmaps. It can only communicate with the outside world via **RequestServer**. ### Process: RequestServer This process can use networking protocols (like HTTP or HTTPS) to request files from the outside world. Each **WebContent** process gets its own **RequestServer** to do uploading or downloading on its behalf. For DNS lookups, **RequestServer** asks for help from the system's global **LookupServer** service, which handles all outgoing DNS requests. ### Process: ImageDecoder This process can decode images (PNG, JPEG, BMP, ICO, PBM, etc.) into bitmaps. Each image is decoded in a fresh **ImageDecoder** process. These are strongly sandboxed and can't do much except receive encoded bitmap data and return a bitmap to **WebContent** if decoding is successful. ### How processes are spawned To get a fresh **WebContent** process, anyone with the suitable file system permissions can spawn one by connecting to the socket at `/tmp/session/%sid/portal/webcontent`, with `%sid` being the current login session id. This socket is managed by **SystemServer** and will spawn a new instance of **WebContent** for every connection. The same basic concept applies to **RequestServer** and **ImageDecoder** as well, except that those services are spawned by **WebContent** as needed, not by **Browser**. ## Class overview In the GUI application process, a `OutOfProcessWebView` widget is placed somewhere in a window, and it takes care of spawning all of the helper processes, etc. Internally, the `OutOfProcessWebView` has a `WebContentClient` object that implements the client side of the **WebContent** IPC protocol. The `WebContentClient` speaks to a `WebContent::ConnectionFromClient` in the **WebContent** process. Internally, the `WebContent::ConnectionFromClient` has a `WebContent::PageHost` which hosts the **LibWeb** engine's main `Web::Page` object. Inside **LibWeb**, a `Web::Page` has a main `Web::Frame`, which may have subframes corresponding to `` or `