Gn Deps Debugging
Testing & Qualitygn-deps-debuggingGn Deps Debugging is an Agent Skill for testing & quality published in the chromium/chromium repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Diagnose Chromium GN dependency and include-visibility failures, including BUILD.gn deps/public_deps, DEPS include rules, private headers, and circular dependencies. Use for build or gn check dependency errors, not C++/link/runtime/test failures.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/chromium/chromium/blob/HEAD/agents/skills/gn-deps-debugging/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/gn-deps-debugging, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
GN Dependency Debugging
Fix Chromium GN dependency metadata, include visibility, and DEPS rule failures by correcting the dependency graph accurately, not by adding broad dependencies that only make errors disappear.
Core principles
- Read the exact error first. Identify the including source file, the included header, the failing target, and the diagnostic category before editing.
- Find both owning targets. Determine which GN target owns the including file and which GN target owns the included header.
- Prefer the narrowest dependency. Add the dependency to the smallest target that needs it, not a parent or aggregate target.
- Preserve platform conditions. If the failing include is in a
platform-specific file such as
*_win.cc, add the dependency inside the matching platform block such asif (is_win). - Use
depsfor implementation-only dependencies. If a symbol is used only in.ccfiles, keep the dependency private. - Use
public_depsonly for public API exposure. If a public header exposes a type from another target in its declarations or inline code, downstream consumers may need that dependency transitively. - Prefer forward declarations in headers. If a header only needs a pointer,
reference, or return type declaration, forward declare and move the include
to the
.ccfile when possible. - Do not paper over architecture issues. Circular dependencies usually indicate the need to split an interface target, move shared abstractions, or invert dependencies.
- Avoid
// nogncheck. Use it only for known GN limitations with conditional includes, and include the required bug reference if the local codebase already documents one.
Workflow
-
Capture the failing command and output.
- If the user provided a truncated error, ask for or rerun the relevant
gn checkor build command when an output directory and target are known. - Do not start a broad build just to reproduce unless the output directory and target are established.
- If the user provided a truncated error, ask for or rerun the relevant
-
Classify the failure.
- Read common-errors.md and map the diagnostic to one of the supported categories.
- Extract the including file, included header, and target names from the diagnostic.
-
Find the target that owns the including file.
- Inspect nearby
BUILD.gnfiles first. - Use GN queries when an output directory is known:
gn refs out/Default //path/to/file.cc --all - Prefer the most specific non-aggregate target that directly lists the file or owns the source set containing it.
- Check whether the file is platform-specific, such as
*_win.cc,*_mac.mm,*_linux.cc,*_android.cc, or*_ios.mm. Platform-specific files usually require platform-specific dependencies.
- Inspect nearby
-
Find the target that owns the included header.
- Search for the header in
BUILD.gnsources lists. - If several targets list it, prefer the public/interface target intended for consumers.
- Check whether the header belongs to a generated target, a
publicvariable, or a private implementation target.
- Search for the header in
-
Choose the correct fix.
- Read dependency-patterns.md for
depsvspublic_deps, forward declaration, DEPS, and cycle handling rules. - If the include appears only in
.cc, add a privatedepsentry. - If the include appears only in a platform-specific source file, add the
private
depsentry inside the matching platform condition, for exampleif (is_win). - If the include appears in a public header, first try to remove the include
using a forward declaration. If the header must expose the dependency, add
or promote the dependency to
public_deps. - If a
DEPSfile blocks the include, verify whether the dependency direction is allowed by the architecture before adding include rules. - If adding the dependency creates a cycle, stop and redesign the dependency
boundary instead of adding broader deps. When an output directory is known,
use
gn path <out_dir> //target_a //target_bto inspect the dependency chain that connects the targets.
- Read dependency-patterns.md for
-
Validate the narrow change.
- Run
git cl formatifBUILD.gnorDEPSfiles were edited. - Re-run the smallest relevant
gn checkor build command that reproduced the issue. - If the first fix reveals additional dependency errors, repeat the workflow one error at a time.
- Run
Common anti-patterns
- Adding dependencies to
//chrome/browser:browseror another aggregate target when a smaller target owns the failing file. - Adding a Windows-only, macOS-only, Android-only, or iOS-only dependency unconditionally when the include is only used by a platform-specific source file.
- Adding a dependency to
public_depsbecause it makes the build pass, without proving the type is part of a public header API. - Adding
// nogncheckinstead of fixing the dependency graph. - Adding broad DEPS allow rules without checking the intended layering.
- Fixing only the first error while leaving the target's public/private boundary inconsistent.
Reporting
When presenting a fix, state:
- The failing include and source file.
- The target that owns the source file.
- The target that owns the included header.
- Why the selected fix is
deps,public_deps, forward declaration, DEPS, or target split. - The validation command that passed, or why validation could not be run.