Chromium Contributing Tips

Personal tricks and tips for contributing to the Chromium C++ codebase.

Note: This guide targets Ubuntu 22.04 and is the most actively maintained. For other platforms, see macOS or Windows.

---

Table of Contents

• Getting the Code
• Building
• Stacked CLs
• Generating compile_commands.json
• Debugging
• Unit Tests
• Web Tests

---

Getting the Code

Prerequisites

1. Git
2. Python v3.8+

Upgrading Git on Ubuntu

sudo apt update && sudo apt install software-properties-common
sudo add-apt-repository ppa:git-core/ppa
sudo apt install git

Installing depot_tools (ref)

mkdir -p ~/code/google/
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git ~/code/google/depot_tools
export PATH="${HOME}/code/google/depot_tools:$PATH"

Fetching the Source (ref)

mkdir -p ~/code/google/chromium && cd ~/code/google/chromium
fetch --nohooks chromium
cd src
./build/install-build-deps.sh
gclient runhooks

Setting Up clangd

Add the following to your clangd config:

"-j=16"
"--malloc-trim"
"--background-index"
"--pch-storage=memory"

Configuring Build Arguments (ref)

gn gen out/Default
gn args out/Default

Set the following args:

is_debug = true
symbol_level = 1
blink_symbol_level = 1
v8_symbol_level = 0
enable_nacl = false
use_rtti = true  # useful runtime type info

Updating Your Checkout (ref)

git rebase-update
gclient sync -Df

---

Building

Faster Builds with RBE (ref)

1. Edit your .gclient file to add the RBE instance (ref):

solutions = [
  {
    ...,
    "custom_vars": {
      # Add this if we need clangd
      # After this, gclient will keep the binary at third_party/llvm-build/Release+Asserts/bin/clangd
      # in sync with the version of Clang used by Chromium.
      "checkout_clangd": True,
      # Chromium's RBE service instance. You can only use this if you have
      # been granted access. For a custom REAPI-compatible backend, change
      # this accordingly.
      "rbe_instance": "projects/rbe-chromium-untrusted/instances/default_instance",
    },
  },
]

2. Update your GN args:

gn args out/Default

is_debug = true
symbol_level = 1
blink_symbol_level = 1
v8_symbol_level = 0
enable_nacl = false
use_rtti = true
use_remoteexec = true
use_reclient = false
use_siso = true

Starting a Build (ref)

autoninja -C out/Default chrome

Listing All Targets

gn ls out/Default

Running Chrome

out/Default/chrome

---

Stacked CLs (ref, commands)

Stacked CLs let you split a large change into smaller, dependent changelists that are reviewed and landed in order.

Creating a Chain of Branches

# Start the first CL from main
git new-branch first-cl

# ... make changes, commit ...

# Create a second CL on top of the first
git new-branch --upstream-current second-cl

# ... make changes, commit ...

# Create a third CL on top of the second
git new-branch --upstream-current third-cl

Uploading the Stack

Upload from the root branch of the stack to upload all dependent CLs:

# Check out the root branch of the stack (use git map-branches -v to find it)

# Upload the current CL and all CLs that depend on it
git cl upload --dependencies

Navigating the Stack

# Move to the parent branch
git nav-upstream

# Move to a child branch
git nav-downstream

Rebasing the Stack

# Rebase only the current stack (not all local branches)
git rebase-update --tree
gclient sync -Df

git rebase-update --tree re-parents each branch in the current stack onto the latest upstream and drops branches whose commits have already landed.

Viewing the Branch Tree

git map-branches -v

Shows all local branches, their upstream relationships, and behind/ahead counts.

Re-parenting a Branch

If you need to change a branch's upstream after creation:

# Re-parent onto a specific branch
git reparent-branch <new-parent>

# Re-parent directly onto the root (main/master)
git reparent-branch --root

---

Generating compile_commands.json (ref)

# Linux / macOS
tools/clang/scripts/generate_compdb.py -p out/Default > compile_commands.json

# PowerShell (requires Python 3)
python tools/clang/scripts/generate_compdb.py -p out/Default | Out-File -Encoding utf8 compile_commands.json

---

Debugging

Logging (ref)

Enable stderr logging at runtime:

out/Default/chrome --enable-logging=stderr --v=-1

Add log statements in code:

#include "base/logging.h"
// ...
LOG(ERROR) << "YOUR LOG" << YOUR_VARIABLE;

Stack Traces (ref)

#include "base/debug/stack_trace.h"
// ...
LOG(ERROR) << "StackTrace: " << base::debug::StackTrace{};

Note: Use --disable-gpu-sandbox when debugging the GPU process, or --no-sandbox when debugging a renderer process.

---

Unit Tests

Running Unit Tests Locally (ref)

1. Find the test target for a given source file:

gn refs out/Default --testonly=true --type=executable --all chrome/browser/ui/browser_list_unittest.cc
# Output: //chrome/test:unit_tests

2. Build the test target (omit the leading //):

autoninja -C out/Default chrome/test:unit_tests

3. Run with a filter:

out/Default/unit_tests --gtest_filter="BrowserListUnitTest.*"

---

Web Tests

Initial Setup (ref)

autoninja -C out/Default blink_tests

Running Web Tests (ref)

third_party/blink/tools/run_web_tests.py -t Default

Unskipping Tests (ref)

The file third_party/blink/web_tests/TestExpectations lists all skipped tests. Remove lines ending with [Failure] to re-enable them.

Running a Subset of Tests

Caution: Do not prefix paths with ./ (e.g., use third_party/blink/..., not ./third_party/blink/...).

# Run all fast/forms tests
third_party/blink/tools/run_web_tests.py fast/forms

# Wildcard shorthand
third_party/blink/tools/run_web_tests.py fast/fo*

Running WPT Tests (ref)

third_party/blink/tools/run_wpt_tests.py --target=Default --product=headless_shell external/wpt/html/dom

Local Rebaselining (ref)

third_party/blink/tools/run_web_tests.py --reset-results foo/bar/test.html