---
name: linux-chromium-build
description: >-
  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:

```sh
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`.

```sh
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:

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

And example call:

```sh
# 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.

```sh
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:

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

Another example with environment variables:

```sh
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:

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

### For a unit test

  ```sh
  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.