scripts/gn_complete/README.md

# GN build target shell completion

`complete.py` is a python script that takes as input a GN label and emits
a list of suggested completions based on the GN build targets available in
the build. For interactive performance, the list of targets must be
generated ahead of time by the `fx set` command and pre-processed by
`prepare.py`.

`prepare.py` is a python script that takes as input a JSON project file
generated by `fx set` and creates a copy with nothing but the names of
the GN build targets. This is then read by `complete.py` during shell
completion.

## Setup

The completion scripts require some extra metadata to be generated by the
`fx set` command. When invoking your usual `fx set` command, include the
following arguments:

```
fx set ... --ide json --json-ide-script //scripts/gn_complete/prepare.py
```

This will generate two files: `out/default/project.json` and
`out/default/project_lite.json`. The latter file is a stripped down version
of the former and is the input to `complete.py`.

### BASH

Make sure that `scripts/fx-env.sh` is sourced in your shell. See
[fx_workflow](/docs/development/build/fx.md).

The default completion configuration for BASH treats `:` characters as word
breaks, which breaks completion for GN targets (`foo/bar:test`).

To remove the `:` character from the set of completion word break characters,
add the following to your `.bashrc`:

```
COMP_WORDBREAKS=${COMP_WORDBREAKS//:}
```

### ZSH

ZSH currently has its own implementation of GN build target shell completion,
which lives at `//scripts/zsh-completion/_fx_build`. Unfortunately, since
it queries ninja to assemble the target names, the latency is too high for
interactive use-cases.

## Tests

Tests can be run from the Fuchsia project root with:

```
python3 -m unittest discover -s scripts/gn_complete
```