192 lines
6.9 KiB
Markdown
192 lines
6.9 KiB
Markdown
---
|
|
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.
|