Build with GN labels

fx build can now build GN targets directly. To do so, simply use one or more GN target labels, with a // prefix on the command-line as in:

# Build the `cstr` and `uuid` libraries for Fuchsia.
fx build //src/lib/cstr //src/lib/uuid

# Equivalent to the previous command.
fx build //src/lib/cstr:cstr //src/lib/uuid:uuid

An error is printed if the label is not part of the configured GN graph. Even if it is defined in the corresponding BUILD.gn file, it still needs to be a transitive dependency from //:default or the other dependency lists defined in your args.gn, such as universe_package_labels and others:

# Build the corresponding tests for Fuchsia too.
$ fx build //src/lib/cstr:tests
ERROR: Unknown GN label (not in the configured graph): //src/lib/cstr:tests

For more details about why this happens, see gn-root-targets.

GN Toolchain suffixes

GN toolchain suffixes are supported (but the parentheses require shell quoting) as in:

# Build the host tests for the `cstr` library.
fx build '//src/lib/cstr:tests(//build/toolchain:host_x64)'

Or even:

# Same as above
fx build //src/lib/cstr:tests\(//build/toolchain:host_x64\)

GN Toolchain aliases

As a convenience, specific options can be used to append a GN toolchain suffix for the next labels that appear on the command-line, as in:

# Build the `cstr` and `fidl` tests for the host, and the `trace` library for Fuchsia.
fx build --host //src/lib/cstr:tests //src/lib/fidl:tests --fuchsia //src/lib/trace

A small fixed number of options are supported to alias toolchain definitions:

  • --host matches the host toolchain label for your build machine (e.g. //build/toolchain:host_x64 or //build/toolchain:host_arm64).

  • --default matches the default toolchain for your current build configuration (e.g. //build/toolchain/fuchsia:riscv64).

  • --fuchsia is another name for --default since Fuchsia binaries are built in the default GN toolchain (for now).

  • --fidl matches //build/fidl:fidling, the GN toolchain used for processing FIDL files.

Other aliases may be added over time for convenience.

GN Toolchain option

The --toolchain=LABEL option can be used to specific a GN toolchain label:

# Build the `cstr` tests for Linux/arm64 through cross-compiling
fx build --toolchain=//build/toolchain:linux_arm64 //src/lib/cstr:tests

It also accepts toolchain aliases, as in:

# Same as using `--host` directly as well.
fx build --toolchain=host //src/lib/cstr:tests

GN labels to Ninja target paths

The fx build command will always print the list of Ninja targets it wants to build, as in:

$ fx build //src/lib/cstr
Building Ninja target(s): obj/src/lib/cstr/cstr.stamp
...

Note that this lists includes all outputs from the corresponding build commands, including ones generated implicitly by GN. Building any of them will trigger the command that generates all of the outputs at once anyway.

$ fx build //src/lib/json_parser
Building Ninja target(s): obj/src/lib/json_parser/json_parser.inputdeps.stamp obj/src/lib/json_parser/json_parser.json_parser.cc.o obj/src/lib/json_parser/json_parser.rapidjson_validation.cc.o obj/src/lib/json_parser/json_parser.stamp
...

Ninja targets to GN labels

Passing a Ninja target path is still supported, but will print a warning, giving you the best build arguments to use instead, for example:

$ fx build host_x64/zbi host_x64/ffx
WARNING: Use '--host //zircon/tools/zbi' instead of Ninja path 'host_x64/zbi'
WARNING: Use '--host //src/developer/ffx/frontends/ffx:ffx_bin' instead of Ninja path 'host_x64/ffx'
Building Ninja target(s): host_x64/exe.unstripped/zbi host_x64/ffx host_x64/obj/src/developer/ffx/frontends/ffx/ffx_bin.stamp host_x64/obj/zircon/tools/zbi/zbi.zbi.cc.o host_x64/zbi host_x64/zbi.build-id.stamp
...

If you do not want to see this label, pass the Ninja path after the -- option separator, as anything following it is passed directly to Ninja:

fx build -- host_x64/zbi host_x64/ffx

However, as our Bazel migration carries on, this will not work for any Bazel-generated outputs in the future.