tree: 8c1d58eb3126551603b05732a81ebfe209e623e0 [path history] [tgz]
  1. bin/
  2. gn_graph/
  3. gn_json/
  4. tests/
  5. BUILD.gn
  6. OWNERS
  7. README.md
tools/gn_desc/README.md

gn_desc: A tool for rapidly querying the GN build graph

The gn_desc cli tool uses a pre-built copy of the JSON output of GN‘s desc command to more rapidly query GN’s build graph.

Setup

The gn_desc tool is not built by default, to add it to your configuration:

fx set ... --with-host //tools/gn_desc

or add //tools/gn_desc to host_labels via fx args.

The tool can then be built with:

fx build host-tools/gn_desc

This also runs gn itself, again, to produce the $outdir/gn_desc.json file.

Example Usage

To list targets that match a pattern:

fx gn_desc -v --file out/default/gn_desc.json match <pattern> list

The <pattern> is a regex.

Usage

The cached gn_desc.json file can be rebuilt after changing GN files with:

fx build host-tools/gn_desc

If the GN files have been changed, a build hasn't been performed, the file is not updated before running the tool.

Note: this can be adventageous when GN is failing and you need to determine what the dependency edges are that are causing issues.

Operation

The tool does the following when run:

  1. parses the given file
  2. creates a graph of all targets and their dependencies
  3. selects some subset of the targets
  4. runs a command on each selected target

Target Selection

gn_desc has the following target selection mechanisms:

  • match <regex> - selects all targets that match the given regex
  • match-file [-a|-ois] <regex> - selects all targets that have files that match the given regex:
    • -a - any file (the default)
    • -i - inputs
    • -o - outputs
    • -s - sources
    • -x - scripts (executable things)
  • label <label> - Selects only given label (via an exact match, including the toolchain).

Commands

gn_desc has the following commands that can be run on the selected targets:

  • list - lists the labels of the selected targets, one per line
  • summarize - provides a summary description of the targets, which can be customized by various flags, see the tool's own help for more information: gn_desc --file <file> exact <label> summarize --help

Future Work

Planned future commands are:

  • dep-tree - prints an ascii-art or dot-file format dependency tree
  • file-tree - prints an ascii-art or dor-file format file input->output tree
  • metadata query - performs a metadata-query similar to what gn does

Planned future selectors are:

  • match-metadata - selects all targets that have a given metadata key