### Building WebKit Documentation Site

Source: https://context7.com/webkit/documentation/llms.txt

Commands for installing dependencies, starting a local live-reloading server, and building a static version of the documentation site using MkDocs.

```bash
# Install the Material for MkDocs dependency
pip3 install mkdocs-material
```

```bash
# Start a live-reloading local server (http://127.0.0.1:8000)
mkdocs serve
```

```bash
# Build a static site for deployment
mkdocs build
```

```bash
# Optionally serve the generated static site locally
python3 -m http.server --directory site/
```

--------------------------------

### Get git-webkit Setup Info

Source: https://github.com/webkit/documentation/blob/main/docs/Other/Contributor Meetings/ContributorMeeting2022.md

Use the -v flag with git-webkit to retrieve detailed information about your current setup and configuration.

```bash
git-webkit -v
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/webkit/documentation/blob/main/README.md

Starts a local web server to preview the documentation. Updates are reflected automatically.

```bash
mkdocs serve
```

--------------------------------

### Enable Log Channels String Example

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/Logging.md

An example string format for enabling/disabling log channels at startup. Channels are separated by spaces, and '-' can be used to disable specific channels.

```text
WebGL -Loading
```

--------------------------------

### Get Help for Run WebKit Tests

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/Tests.md

Enumerate all supported options for the `run-webkit-tests` script by using the --help flag.

```sh
run-webkit-tests --help
```

--------------------------------

### Install MkDocs Dependencies

Source: https://github.com/webkit/documentation/blob/main/README.md

Installs the necessary Python package for building the documentation.

```python
pip3 install mkdocs-material
```

--------------------------------

### Example COMPATIBILITY Comment for Multiple Platforms

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/Web Inspector/Compatibility.md

An example of a COMPATIBILITY comment specifying compatibility boundaries for multiple operating systems.

```text
// COMPATIBILITY (macOS 13.0, iOS 16.0): CSS.CSSRule.ruleId did not exist yet.
```

--------------------------------

### Install Development Tools with WinGet

Source: https://github.com/webkit/documentation/blob/main/docs/Ports/WindowsPort.md

Installs core development tools using WinGet. Use `--scope=machine` for system-wide installation. Note that WinGet may not automatically update the system's PATH.

```powershell
winget install --scope=machine --id Git.Git Kitware.CMake Ninja-build.Ninja Python.Python.3.11 RubyInstallerTeam.Ruby.3.2 ApacheFriends.Xampp.8.2 LLVM.LLVM
winget install --id GnuWin32.Gperf
```

--------------------------------

### Fetch URL with XMLHttpRequest

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/Architecture/JSWrappers.md

This example demonstrates creating an XMLHttpRequest object, attaching an event listener for the 'load' event, and sending a GET request. It illustrates a scenario where a JS wrapper might need to be kept alive.

```js
function fetchURL(url, callback)
{
    const request = new XMLHttpRequest();
    request.addEventListener("load", callback);
    request.open("GET", url);
    request.send();
}
```

--------------------------------

### GDB Setup and Usage for WebKit

Source: https://context7.com/webkit/documentation/llms.txt

Integrate WebKit debugging helpers with GDB by adding the Python path and import to ~/.gdbinit. Manually debug DumpRenderTree by setting DYLD_FRAMEWORK_PATH.

```bash
# Add to ~/.gdbinit for automatic loading of WebKit GDB helpers
python
import sys
sys.path.insert(0, "{Path to WebKit}/Tools/gdb/")
import webkit
```

```bash
# Manually debug DumpRenderTree with GDB
export DYLD_FRAMEWORK_PATH=WebKitBuild/Debug
gdb --args WebKitBuild/Debug/DumpRenderTree test_file.html
```

--------------------------------

### Setup WebKit Environment for Contributions

Source: https://github.com/webkit/documentation/blob/main/docs/Getting Started/ContributingCode.md

Run this command to configure your local WebKit checkout for contributing code. It sets up your name, email, Git configuration, and GitHub API token.

```bash
git webkit setup
```

--------------------------------

### Example Unified Source File

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/Build/UnifiedBuilds.md

This C++ code demonstrates the structure of a generated unified source file, which includes multiple .cpp files as headers.

```cpp
#include "dom/Document.cpp"
#include "dom/DocumentEventQueue.cpp"
#include "dom/DocumentFragment.cpp"
#include "dom/DocumentMarkerController.cpp"
#include "dom/DocumentParser.cpp"
#include "dom/DocumentSharedObjectPool.cpp"
#include "dom/DocumentStorageAccess.cpp"
#include "dom/DocumentType.cpp"
```

--------------------------------

### Example HTML Test File with Matching Reference

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/Tests.md

This HTML file is an example of a layout test that uses a linked file as its matching expected result. It includes styles and image elements to test rendering, with the reference file specified via a rel=match link.

```html
<!doctype html>
<meta charset=utf-8>
<title>img hspace/vspace</title>
<link rel=match href=space-ref.html>
<style>
span { background: blue; }
</style>
<div style=width:400px;>
<p><span><img src=/images/green.png></span>
<p><span><img src=/images/green.png hspace=10></span>
<p><span><img src=/images/green.png vspace=10></span>
<p><span><img src=/images/green.png hspace=10%></span>
<p><span><img src=/images/green.png vspace=10%></span>
</div>
```

--------------------------------

### Install Python and Ruby Modules

Source: https://github.com/webkit/documentation/blob/main/docs/Ports/WindowsPort.md

Install required Python and Ruby modules for running WebKit tests. Ensure Apache service is stopped before proceeding.

```bash
python -m pip install pywin32
```

```bash
gem install webrick
```

--------------------------------

### Initialize git-webkit for Contributing

Source: https://context7.com/webkit/documentation/llms.txt

Sets up the Git environment for contributing to WebKit. This includes configuring user name/email, setting up a personal fork, installing commit-message hooks, and storing a GitHub API token.

```bash
# Run once per checkout
git webkit setup

# What it configures in .git/config (after running setup):
# [remote "origin"]
#     url = https://github.com/WebKit/WebKit.git
#     fetch = +refs/heads/*:refs/remotes/origin/*
# [remote "<username>"]
#     url = https://github.com/<username>/WebKit.git
#     fetch = +refs/heads/*:refs/remotes/<username>/*
# [remote "fork"]
#     url = https://github.com/<username>/WebKit.git
```

--------------------------------

### Example WebKit Commit Message

Source: https://github.com/webkit/documentation/blob/main/docs/Getting Started/ContributingCode.md

This is an example of a well-formatted commit message for the WebKit project, demonstrating the required structure and content.

```text
Allow downsampling when invoking Remove Background or Copy Subject
https://bugs.webkit.org/show_bug.cgi?id=242048

Reviewed by NOBODY (OOPS!).

Soft-link `vk_cgImageRemoveBackgroundWithDownsizing` from VisionKitCore, and call into it to perform
background removal when performing Remove Background or Copy Subject, if available. On recent builds
of Ventura and iOS 16, VisionKit will automatically reject hi-res (> 12MP) images from running
through subject analysis; for clients such as WebKit, this new SPI allows us to opt into
downsampling these large images, instead of failing outright.

* Source/WebCore/PAL/pal/cocoa/VisionKitCoreSoftLink.h:
* Source/WebCore/PAL/pal/cocoa/VisionKitCoreSoftLink.mm:
* Source/WebCore/PAL/pal/spi/cocoa/VisionKitCoreSPI.h:
* Source/WebKit/Platform/cocoa/ImageAnalysisUtilities.h:
* Source/WebKit/Platform/cocoa/ImageAnalysisUtilities.mm:
(WebKit::requestBackgroundRemoval):

Refactor the code so that we call `vk_cgImageRemoveBackgroundWithDownsizing` if it's available, and
otherwise fall back to `vk_cgImageRemoveBackground`.

* Source/WebKit/UIProcess/ios/WKContentViewInteraction.mm:
(-[WKContentView doAfterComputingImageAnalysisResultsForBackgroundRemoval:]):
(-[WKContentView _completeImageAnalysisRequestForContextMenu:requestIdentifier:hasTextResults:]):
(-[WKContentView imageAnalysisGestureDidTimeOut:]):
* Source/WebKit/UIProcess/mac/WebContextMenuProxyMac.mm:
(WebKit::WebContextMenuProxyMac::appendMarkupItemToControlledImageMenuIfNeeded):
(WebKit::WebContextMenuProxyMac::getContextMenuFromItems):

Additionally, remove the `cropRect` completion handler argument, since the new SPI function no
longer provides this information. The `cropRect` argument was also unused after removing support for
revealing the subject, in `249582@main`.
```

--------------------------------

### RefPtr and Ref Declaration Examples

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/MemoryManagement.md

Demonstrates the declaration of `Ref` and `RefPtr` types. `Ref` cannot be null, while `RefPtr` can be initialized to `nullptr`.

```cpp
Ref<A> a1; // This will result in compilation error.
RefPtr<A> a2; // This is okay.
Ref<A> a3 = A::create(); // This is okay.
a3->f(); // Calls f() on an instance of A.
A* a4 = a3.ptr();
a4 = a2.get();
```

--------------------------------

### Basic Regular Expression Examples

Source: https://github.com/webkit/documentation/blob/main/docs/Other/Contributor Meetings/ContributorMeeting2025.md

Illustrates fundamental regular expression patterns for string matching, digit matching, and alternation.

```regex
/abc/
```

```regex
/\d{3,5}/
```

```regex
/Yes|No/
```

--------------------------------

### LLDB Setup and Usage for WebKit

Source: https://context7.com/webkit/documentation/llms.txt

Configure LLDB to automatically load WebKit debugging helpers by adding the script import to ~/.lldbinit. Manually debug DumpRenderTree by setting DYLD_FRAMEWORK_PATH.

```bash
# Add to ~/.lldbinit for automatic loading of WebKit LLDB helpers
command script import {Path to WebKit}/Tools/lldb/lldb_webkit.py
```

```bash
# Manually debug DumpRenderTree with LLDB
export DYLD_FRAMEWORK_PATH=WebKitBuild/Debug
lldb -f WebKitBuild/Debug/DumpRenderTree -- LayoutTests/fast/dom/Element/element-traversal.html
```

--------------------------------

### TestExpectations Syntax Example

Source: https://context7.com/webkit/documentation/llms.txt

Illustrates the syntax for the `TestExpectations` file, showing how to mark tests with bug numbers, platform modifiers, and specific expectations like `Crash`, `Failure`, `Skip`, or `WontFix`.

```text
# Format: [ bugs ] [ "[" modifiers "]" ] test_name [ "[" expectations "]" ]

# Mark a test as expected to crash on Windows Debug
webkit.org/b/12345 [ Win Debug ] fast/html/keygen.html [ Crash ]

# Mark a test as flaky (pass or fail) on macOS
webkit.org/b/12345 [ Mac ] fast/html/section-element.html [ Failure Crash ]

# Skip a test on all platforms
webkit.org/b/12345 fast/html/some-test.html [ Skip ]

# Mark as WontFix (implies Skip, no plans to fix)
webkit.org/b/12345 fast/html/some-test.html [ WontFix ]
```

--------------------------------

### TestExpectations File Syntax Example

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/Tests.md

Illustrates the syntax for the TestExpectations file, specifying a test, its platform and configuration, and the expected outcome (crash) along with the associated bug ID.

```text
webkit.org/b/12345 [ Win Debug ] fast/html/keygen.html [ Crash ]
```

--------------------------------

### Build WebKit on macOS (Debug)

Source: https://context7.com/webkit/documentation/llms.txt

Installs Xcode command-line tools and performs a debug build of WebKit on macOS. Includes commands for cloning the repository, building, and running applications with the local build.

```bash
# 1. Install Xcode command line tools
xcode-select --install
xcodebuild -downloadComponent MetalToolchain

# 2. Clone the repository
git clone https://github.com/WebKit/WebKit.git WebKit
cd WebKit

# 3. Build a debug build (macOS)
Tools/Scripts/build-webkit --debug

# 4. Build a release build (for performance testing)
Tools/Scripts/build-webkit --release

# 5. Run Safari with your local WebKit build
Tools/Scripts/run-safari --debug

# 6. Run any app with your local build
Tools/Scripts/run-webkit-app /Applications/Mail.app

# 7. Run MiniBrowser
Tools/Scripts/run-minibrowser
```

--------------------------------

### Example js-test.js Layout Test

Source: https://context7.com/webkit/documentation/llms.txt

A basic example of a JavaScript layout test using `js-test-pre.js` and `js-test-post.js` for setup and teardown. It tests the DOM `remove` method on a comment node.

```html
<!DOCTYPE html>
<script src="../../../resources/js-test-pre.js"></script>
<div id="test"></div>
<script>
description('This tests the DOM 4 remove method on a Comment.');

var testDiv = document.getElementById('test');
var comment = document.createComment('Comment');
testDiv.appendChild(comment);
shouldBe('testDiv.childNodes.length', '1');
comment.remove();
shouldBe('testDiv.childNodes.length', '0');
comment.remove();
shouldBe('testDiv.childNodes.length', '0');
</script>
<script src="../../../resources/js-test-post.js"></script>
```

--------------------------------

### HTML Test Case with js-test-pre.js

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/Tests.md

Example of a test case using js-test-pre.js, demonstrating the inclusion of the script, test setup, assertions, and cleanup.

```html
<!DOCTYPE html>
<script src="../../../resources/js-test-pre.js"></script>
<div id="test"></div>
<script>

description('This tests the DOM 4 remove method on a Comment.');

var testDiv = document.getElementById('test');
var comment = document.createComment('Comment');
testDiv.appendChild(comment);
shouldBe('testDiv.childNodes.length', '1');
comment.remove();
shouldBe('testDiv.childNodes.length', '0');
comment.remove();
shouldBe('testDiv.childNodes.length', '0');

</script>
<script src="../../../resources/js-test-post.js"></script>
```

--------------------------------

### Build and Serve Documentation

Source: https://github.com/webkit/documentation/blob/main/README.md

Builds the documentation for a static site and optionally serves it locally for viewing.

```bash
mkdocs build
python3 -m http.server --directory site/ # (Optional) View generated documentation
```

--------------------------------

### Install pywin32 Python Module

Source: https://github.com/webkit/documentation/blob/main/docs/Ports/WindowsPort.md

Installs the pywin32 Python module, which is required for running WebKit tests and git-webkit scripts.

```python
python -m pip install pywin32
```

--------------------------------

### Run WebKit App

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/BuildOptions.md

Launch a specified application using your local WebKit build. Replace `<application-path>` with the actual path to the application.

```bash
Tools/Scripts/run-webkit-app <application-path>
```

--------------------------------

### Run iOS Simulator with Local Build

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/BuildOptions.md

Launch the iOS simulator with your locally built WebKit. Use `--release` for release builds.

```bash
run-safari --debug --ios-simulator
```

--------------------------------

### Install Development Tools with Chocolatey

Source: https://github.com/webkit/documentation/blob/main/docs/Ports/WindowsPort.md

Installs essential development tools for WebKit on Windows using the Chocolatey package manager. Ensure Python 3.11 is used due to known issues with 3.12.

```bash
choco install -y xampp-81 python311 ruby git cmake gperf llvm ninja
```

--------------------------------

### Run Safari with Local Build

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/BuildOptions.md

Launch Safari using your locally built WebKit. This script sets the DYLD_FRAMEWORK_PATH to prioritize your build.

```bash
Tools/Scripts/run-safari --debug
```

--------------------------------

### Run WebKit Minibrowser

Source: https://github.com/webkit/documentation/blob/main/docs/index.md

Launch the minibrowser application to test WebKit builds.

```sh
Tools/Scripts/run-minibrowser
```

--------------------------------

### Render Tree Dump Example

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/Tests.md

This is an example of a render tree dump, which is a text serialization of WebKit's render tree. This style of test is discouraged due to platform-specific outputs but can be useful for testing rendering features.

```text
layer at (0,0) size 800x600
  RenderView at (0,0) size 800x600
layer at (0,0) size 800x600
  RenderBlock {HTML} at (0,0) size 800x600
    RenderBody {BODY} at (8,8) size 784x584
      RenderInline {A} at (0,0) size 238x18 [color=#0000EE]
        RenderInline {B} at (0,0) size 238x18
          RenderText {#text} at (0,0) size 238x18
            text run at (0,0) width 238: "the second copy should not be bold"
      RenderText {#text} at (237,0) size 5x18
        text run at (237,0) width 5: " "
      RenderText {#text} at (241,0) size 227x18
        text run at (241,0) width 227: "the second copy should not be bold"
```

--------------------------------

### Run All Build and Test Scripts

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/Libpas/LibpasBuildAndTest.md

Execute the main script to build and test libpas. Use the -a option to specify the architecture, such as 'arm64e' on M1 machines, to avoid building fat binaries.

```bash
./build_and_test.sh
```

```bash
./build_and_test.sh -a arm64e
```

--------------------------------

### Build WebKit for iOS/tvOS/watchOS Simulators and Devices

Source: https://context7.com/webkit/documentation/llms.txt

Builds WebKit for various Apple platforms and their simulators/devices by passing platform arguments to the build script. Also shows how to launch Safari on the iOS Simulator with a local build.

```bash
# iOS simulator (debug)
Tools/Scripts/build-webkit --debug --ios-simulator

# iOS device (debug)
Tools/Scripts/build-webkit --debug --ios-device

# tvOS simulator
Tools/Scripts/build-webkit --debug --tvos-simulator

# watchOS device
Tools/Scripts/build-webkit --debug --watchos-device

# Launch Safari on the iOS Simulator with the local build
run-safari --debug --ios-simulator
```

--------------------------------

### Inline Allocation Fast Path Example

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/Libpas/Internals.md

This function demonstrates the inline-only fast path for allocation. It attempts to use an inline implementation and falls back to a casual case if the inline path fails. This pattern avoids stack frames for the fast path.

```c
static PAS_ALWAYS_INLINE void* bmalloc_try_allocate_inline(size_t size)
{
    pas_allocation_result result;
    result = bmalloc_try_allocate_impl_inline_only(size, 1);
    if (PAS_LIKELY(result.did_succeed))
        return (void*)result.begin;
    return bmalloc_try_allocate_casual(size);
}
```

--------------------------------

### Commit Identifier Timeline Example

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/GitHub/SourceControl.md

Visual representation of commit identifiers across multiple branches, illustrating how they evolve and relate.

```text
                      ———— o ————————————— o
                    /      |               |
                   /  101.2@branch-b  101.3@branch-b
                  ——————— o ———————————— o
                /         |              |
           /   101.1@branch-a  101.2@branch-a
——— o ———————— o ———————— o ——————— o ——————— o
    |          |          |         |         |
 100@main   101@main   102@main  103@main  104@main
```

--------------------------------

### Enabling Log Channels at Runtime (Linux/Android/macOS/Windows)

Source: https://context7.com/webkit/documentation/llms.txt

Configure logging levels and channels for different WebKit processes using environment variables, system properties, or defaults.

```bash
# Linux: set WEBKIT_DEBUG environment variable
WEBKIT_DEBUG=Scrolling Tools/Scripts/run-minibrowser --gtk --debug
```

```bash
# Multiple channels with per-channel log levels
WEBKIT_DEBUG='all=error,GLContext=debug,-Network' Tools/Scripts/run-minibrowser --wpe --release
```

```bash
# Android: set system property via adb

```

```bash
adb shell setprop debug.WPEWebKit.log 'WebGL,Media=error'
adb shell setprop log.tag.WPEWebKit VERBOSE
adb logcat -s WPEWebKit
```

```bash
# macOS: write to defaults database for each process
for identifier in com.apple.WebKit.WebContent.Development com.apple.WebKit.WebContent org.webkit.MiniBrowser; do
    for key in WTFLogging WebCoreLogging WebKitLogging WebKit2Logging; do
        defaults write ${identifier} "${key}" "Language"
    done
done
```

```bash
# macOS: pass directly as argument
Tools/Scripts/run-minibrowser --debug -WebCoreLogging Scrolling
```

```bash
# Windows: set environment variables
# WTFLogging=Scrolling
# WebCoreLogging=MediaQueries
# WebKit2Logging=Network
```

```bash
# JSC dataLog logging
JSC_logGC=2 jsc script.js
run-jsc --logGC=2 --debug
run-jsc --options   # list all JSC options
```

--------------------------------

### Build WPE Port Development

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/BuildOptions.md

Build the WPE port for development. This command assumes dependencies are already installed or managed by the SDK.

```bash
Tools/wpe/install-dependencies
Tools/Scripts/build-webkit --wpe --debug
```

--------------------------------

### Build GTK Port Development

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/BuildOptions.md

Build the GTK port for development. This command assumes dependencies are already installed or managed by the SDK.

```bash
Tools/gtk/install-dependencies
Tools/Scripts/build-webkit --gtk --debug
```

--------------------------------

### Load LLDB WebKit Helpers

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/DebuggingOnTheCommandLine.md

Add this line to `~/.lldbinit` to automatically load WebKit debug helpers into LLDB on launch.

```shell
command script import {Path to WebKit}/Tools/lldb/lldb_webkit.py
```

--------------------------------

### Find Git Ref by Commit Identifier

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/GitHub/SourceControl.md

Uses the git-webkit find command to retrieve commit details when starting from a WebKit identifier.

```bash
git-webkit find 232923.400@safari-611-branch
```

--------------------------------

### Git Merge Commit History Example

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/GitHub/SourceControl.md

Illustrates the structure of a Git merge commit, which can have multiple parents, making history harder to follow.

```text
                  ——— o ———————————— o ————
                /                           \
           /                             \
——— o ———————— o ———————— o ——————— o ——————— o ——————— o
```

--------------------------------

### Commit Data JSON Structure

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/GitHub/SourceControl.md

Example JSON response from commits.webkit.org, detailing commit attributes like author, branch, hash, and identifier.

```json
{
    "author": {
        "emails": [
            "repstein@apple.com"
        ],
        "name": "Russell Epstein"
    },
    "branch": "safari-612-branch",
    "hash": "76f038bbe2889a3714c6176b3c9e35b404c57e35",
    "identifier": "240672.6@safari-612-branch",
    "message": "Versioning.\n\nWebKit-7612.2.1\n\nCanonical link: https://commits.webkit.org/240672.6@safari-612-branch
git-svn-id: https://svn.webkit.org/repository/webkit/branches/safari-612-branch@281269 268f45cc-cd09-0410-ab3c-d52691b4dbfc",
    "order": 0,
    "repository_id": "webkit",
    "revision": 281269,
    "timestamp": 1629406217
}
```

--------------------------------

### Enable All Logging

Source: https://github.com/webkit/documentation/blob/main/docs/Build & Debug/Logging.md

Use the string 'all' to enable all logging channels.

```text
all
```

--------------------------------

### Change Build Configuration

Source: https://github.com/webkit/documentation/blob/main/docs/Deep Dive/Libpas/LibpasBuildAndTest.md

Modify the build configuration using the -c option, for example, to build a 'Debug' variant instead of the default 'Release'.

```bash
./build.sh -c Debug
```