chromium-ai-assisted/skills/linux-chromium-build/SKILL.md

name, description

name	description
linux-chromium-build	MANDATORY procedure for Linux x86 Chromium configure, build, test, and build-failure investigation. Activate before proposing or executing a build-neva wrapper, GN, Ninja, autoninja, Siso, or Chromium test command. Verify configured locations, target/output directory, diagnostics, and active build state; report and stop if a prerequisite fails.

Linux Chromium Build

Use this skill for Linux x86 Chromium builds and related tests. NEVA host builds use build-neva wrappers.

Pre-launch hard stops

Do not launch a build, configure, or test command until every applicable check below has passed. If any check fails, report the missing or invalid value and STOP.

1. Check existing environment variables first. They may also be supplied in an existing .env file:

   • CHROMIUM_SRC_DIR — Chromium src checkout.
   • CHROMIUM_WRAPPER_DIR — selected build-neva directory.
   • CHROMIUM_DEPOT_TOOLS_DIR — parent depot_tools checkout.
   • CHROMIUM_BUILD_LOG — log file for an unattended build.

   Use a set value exactly as supplied. In particular, if CHROMIUM_BUILD_LOG is set, use it exclusively; do not construct another log path. An unattended build requires CHROMIUM_BUILD_LOG to be set. Do not infer unverified absolute locations from the current directory or relative candidates.

2. Verify that CHROMIUM_SRC_DIR, CHROMIUM_WRAPPER_DIR, and CHROMIUM_DEPOT_TOOLS_DIR exist and that the selected wrapper directory contains the requested wrapper (chrome.bash or unit_tests.bash).

3. Establish the exact output directory and target before a build. State the target explicitly even when the wrapper selects its default browser target.

4. If C/C++ source or header files changed, run the diagnostic procedure in lsp-cli/SKILL.md for every modified file. Zero diagnostic errors is required before a build. Report warnings. If diagnostics cannot run or report any error, STOP.

5. Check for active autoninja, Siso, or Ninja build processes. If any is running, report it and STOP. Never kill, restart, or replace a running build without explicit user permission.

Start all builds from $CHROMIUM_WRAPPER_DIR.

Build Chromium

Build the browser with the wrapper's required depot_tools ordering:

cd "$CHROMIUM_WRAPPER_DIR"
PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \
TERM=xterm \
./chrome.bash

Build a focused unit-test target

For unattended runs, disable ccache as well: its setup can fail on tput under set -e.

cd "$CHROMIUM_WRAPPER_DIR"
PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \
CCACHE_DISABLE=1 \
TERM=xterm \
./unit_tests.bash <target>

unit_tests.bash defaults to out/unit_tests.

If you pass no target at all, get_all_targets_list() runs and builds every *_unittests target in the tree (filtering out //third_party, //chrome, //tools, //testing, plus blink).

The wrapper (unit_tests.bash) expects a GN label, and it strips the leading // before passing to ninja (build_gn_target ${target#//}). So the format is:

//extensions:extensions_unittests
//base:base_unittests
//content/test:content_unittests

And example call:

# With // prefix (what the wrapper strips internally)
./unit_tests.bash "//content/test:content_unittests"

# ninja-style, no prefix (also works since #// strips nothing)
./unit_tests.bash "content/test:content_unittests"

Unattended builds and logs

For a user-authorized new unattended build, start a new log session after the pre-launch checks have passed. Truncate CHROMIUM_BUILD_LOG with > and write a unique launch marker before starting the wrapper. Use >> only when continuing that same already-running build session.

When polling, read only output after the current launch marker (or its recorded byte offset). Do not cite earlier log entries as evidence about the current build. Expect gclient sync, GN generation, and Siso to take substantial time before the compiler starts.

cd "$CHROMIUM_WRAPPER_DIR"
build_session="codex-build-$(date -u +%Y%m%dT%H%M%SZ)"
: > "${CHROMIUM_BUILD_LOG:?set CHROMIUM_BUILD_LOG}"
printf '\n=== %s ===\n' "$build_session" >> "$CHROMIUM_BUILD_LOG"
nohup env \
  PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \
  CCACHE_DISABLE=1 \
  TERM=xterm \
  ./unit_tests.bash <target> \
  >> "$CHROMIUM_BUILD_LOG" 2>&1 &

When Siso is enabled, dots and S/F markers indicate activity, not a failure or successful completion. Confirm activity using the current session's new output and the active Siso process. Treat only explicit terminal output such as Build Succeeded, Build Failure, FAILED:, or compiler diagnostics as a result.

Test Chromium

Unless the user supplied the desired test command and environment, ask how tests should run before executing them. Run the relevant test after a successful build and use its output directory, for example:

cd "$CHROMIUM_SRC_DIR/out/unit_tests"
./content_unittests --gtest_filter='<suite>.<test>'

Another example with environment variables:

cd "$CHROMIUM_SRC_DIR/out/unit_tests"
XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/1000}" \
WAYLAND_DISPLAY="${WAYLAND_DISPLAY:-wayland-0}" \
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus \
DISPLAY=:0 \
./browser_tests --gtest_filter='<suite>.<test>' \
  --no-sandbox \
  --headless=new \
  --enable-logging=stderr

Debug Chromium failures

Read the failing source, target BUILD.gn, and at least one call site before changing code. Consult Chromium's relevant docs/ and source rather than relying on general knowledge. Use targeted rg queries; do not use recursive grep, git grep, or find in this tree.

• For a missing header, verify the target's deps and include path. Inspect the existing, wrapper-configured graph with gn desc and gn check from $CHROMIUM_SRC_DIR. Do not use direct gn gen as the normal regeneration path: it bypasses the wrapper's gclient configuration, generated args.gn, and ccache/icecc setup. Regenerate through build-neva instead:

  cd "$CHROMIUM_WRAPPER_DIR"
  PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \
  TERM=xterm \
  ./chrome.bash --configure
  

For a unit test

cd "$CHROMIUM_WRAPPER_DIR"
PATH="$CHROMIUM_DEPOT_TOOLS_DIR:$CHROMIUM_WRAPPER_DIR/depot_tools:$PATH" \
CCACHE_DISABLE=1 \
TERM=xterm \
./unit_tests.bash --configure <target>

• For an undefined symbol, confirm the providing target appears in deps and that is_component_build in args.gn matches the intended build.
• For a visibility error, inspect the dependency target's visibility before changing it.
• For runtime problems, consult docs/debugging.md in the Chromium checkout.
• Changing USE_SISO from true to false will trigger full rebuild.
• If gclient is missing, verify that both the parent and wrapper depot_tools directories are first on PATH in that order.