This directory contains experimental support files for using Bazel with the Fuchsia platform build. Nothing here is final and may break at any time for now.

REQUIREMENTS

Have a full Fuchsia platform checkout from Jiri, and run the following on a Linux build machine (MacOS is not supported at the moment!)

OVERVIEW

Now that you‘ve been warned, here’s how this is supposed to work:

• The BAZEL_TOPDIR directory under the Ninja output directory is used to store all files related to the Bazel part of the build. Its default value is out/default/gen/build/bazel.

• The ${BAZEL_TOPDIR}/workspace directory is used as the Bazel workspace for all bazel commands invoked from Ninja.

• The ${BAZEL_TOPDIR}/output_base directory is used to place all Bazel outputs (including external repositories).

• The ${BAZEL_TOPDIR}/bazel wrapper script is used to launch a known prebuilt Bazel binary with the right options to support this setup, and other requirements of the platform build.

• All four are generated by running fx build bazel_workspace (which ends up calling targets in //build/bazel/BUILD.gn). The workspace content has a specific layout that mirrors the Fuchsia source tree with a few exceptions:

  • A top-level BUILD.bazel symlink to //build/bazel/toplevel.BUILD.bazel in the source tree. This is the file you should modify to add new top-level targets in the Bazel build graph.

  • A top-level WORKSPACE.bazel generated from //build/bazel/templates/template.WORKSPACE.bazel in the source tree. This is the file you should modify to add new external repositories to the Bazel project.

  • A top-level auto-generated .bazelrc file to configure Bazel. Note that this does not support --config=fuchsia_x64 and --config=fuchsia_arm64 are per the Fuchsia Bazel SDK. Also note that the user's own bazel configuration file (e.g. $HOME/.bazelrc) will always be ignored. See Configurations for more details.

  • Symlinks to all top-level entries in the Fuchsia source tree, except for out. This way, any source or configuration file will appear at the same exact location during the Bazel and Ninja builds.

    In other words, if you add a file at $FUCHSIA_DIR/src/foo/BUILD.bazel, it will be visible and will define a Bazel package at //src/foo:.

  • The out directory is not symlinked intentionally to ensure that Ninja outputs are not visible by default. Instead, these are exposed to Bazel on a case-by-case basis using special bazel_input_xxx() template calls in BUILD.gn files. For more details, see the corresponding section below.

• Other Bazel external repositories are generated through repository rules, for example the @prebuilt_clang repository will provide C++ toolchain definitions that use the prebuilt Clang toolchain available from the Fuchsia checkout.

  This is intentionally different from the @fuchsia_clang repository generated by third_party/sdk-integration, since this allows experimenting with C++ toolchain definitions, build variants and PIE-optimized machine code generation without conflicts with sdk-integration development.

• The GN bazel_build_action() template can be used to invoke a bazel build ... command from GN, and copy its outputs to a GN-compatible location. See //build/bazel/bazel_build_action.gni for details.

  The //build/bazel/tests/build_action/ directory contains a working example, which invokes a Bazel build action from GN, then verifies the output.

• For debugging only, the fx bazel wrapper tool is provided to launch a Bazel command inside the Fuchsia workspace file. This will always update the Bazel workspace if needed.

  For example, use fx bazel version to print information about the version number, of fx bazel info workspace to print the absolute path to the workspace.

  And fx bazel build ... or fx bazel query ... commands will work as expected.

IMPLEMENTATION NOTES

The reasons why there are not top-level WORKSPACE.bazel or BUILD.bazel files provided in $FUCHSIA_DIR are that:

• The content of WORKSPACE.bazel contain multiple values that depend on the host machine type, and soon on the actual Jiri manifest or git supermodule hierarchy, and thus must always be auto-generated.

• Developers cannot call Bazel directly from the Fuchsia source tree (which otherwise would likely fail with very confusing error messages).

• Bazel's traditional command line interface to configure Bazel is not compatible with the requirements of the Fuchsia platform build. In particular, the Fuchsia Bazel SDK samples use --config=fuchsia_arm64 to specify the target device architecture, but this will not work here.

• Finally, Bazel support in the Fuchsia platform build is still very experimental, and is best considered an implementation detail, hidden from developer workflows.

Similarly, the reason why Bazel build artifacts are placed under ${BAZEL_TOPDIR}/output_base, instead of using the standard location under the user's home directory (e.g. $HOME/.cache/bazel/) are:

• This allows fx clean to properly remove previous build artifacts.

• This increases the chance of using hard-links when copying Bazel build outputs to the Ninja output directory, since in many setups, $HOME lives in a different partition / mount point than the Fuchsia checkout.

• This prevents filling up the user-specific directory with hundreds of GiBs of build artifacts that can be hard to clean up properly (e.g. when deleting a Fuchsia checkout directory manually with rm -rf).

  In particular, a Bazel module extension is used to generate a repository named @prebuilt_clang that provides C++ toolchain instances and configurations for the build.

• The Fuchsia platform build also relies on the new Platforms feature, which impacts how toolchain selection happens inside a given build configuration. See //build/bazel/platforms/BUILD.bazel for more details.

NINJA OUTPUTS AS BAZEL INPUTS

GN target outputs (i.e. Ninja build artifacts) can be exposed to the Bazel graph as inputs through two distinct mechanisms.

• The best scheme (simpler and more scalable) relies on bazel_input_file() and bazel_input_directory() GN target definitions to expose the outputs of other GN targets as filegroups in the special @gn_targets external repository.

• The older, and deprecated scheme, relies on bazel_input_resource() and bazel_input_resource_directory() to do the same in the special @legacy_ninja_build_outputs external repository.

In both cases, a GN bazel_action() target must be defined to invoke Bazel, through a script, and must list the bazel_input_xxx() in its dependencies to ensure that the right Ninja outputs are exposed to the Bazel graph before the Bazel command runs.

Ninja outputs in the @gn_targets repository

Example

Here's a simple example that uses the first scheme. It allows a Bazel target to process the output of a GN action, and copy the result back to the Ninja build directory through the //src/lib:process_foo GN target.

On the GN side:

# From //src/lib/BUILD.gn, evaluated in the default toolchain context:

# An action that generates one or more output files.
action("foo") {
  outputs = [ ... ]
}

# A target that exposes the outputs of :foo as
# as the @gn_targets//src/lib:foo filegroup()
bazel_input_file("foo.bazel_input") {
  generator = ":foo"
}

# A target that invokes a Bazel target to process the
# foo outputs. The result is copied to $BUILD_DIR/obj/src/lib/foo.final
bazel_action("process_foo") {
  command = "build"
  deps = [ ":foo.bazel_input" ]
  bazel_targets = [ ":foo_processor" ]
  copy_outputs = {
    bazel = "{{BAZEL_TARGET_OUT_DIR}}/foo.processed_by_bazel"
    ninja = "foo.final"
  }
}

And on the Bazel side.

# From //src/lib/BUILD.bazel
genrule(
  name = "foo_processor",
  srcs = [ "@gn_targets//src/lib:foo" ],
  outs = [ "foo.processed_by_bazel" ],
  command = "process.sh $< $@",
)

Notice the //src/lib:foo.bazel_input GN target definition. This does not build anything, but records information about the outputs of the generator target //src/lib:foo.

The //src/lib:process_foo GN target depends on it, which will force the content of the special @gn_targets repository to be automatically updated before invoking Bazel to reflect the target's dependencies.

In this case, because //src/lib:process_foo depends on //src/lib:foo.bazel_input in the GN graph, the Bazel @gn_targets//src/lib:foo filegroup will be defined, grouping the outputs of the GN //src/lib:foo target, built or updated by Ninja before Bazel is invoked.

Note that all Ninja outputs are accessed in Bazel through filegroups named from the GN target label that exposes it. I.e. one cannot access files using a Ninja artifact path such as @gn_targets//obj/src/lib/foo.out.

bazel_input_file() filegroup naming

The bazel_input_file() template requires a generator argument that must point to a GN target that generates Ninja output files.

The corresponding Bazel filegroup will be defined as @gn_targets//{package_name}:{bazel_name} where:

• {bazel_name} matches the name of the generator target itself, but this value can be overridden using the optional gn_targets_name argument.

• {bazel_package} matches the directory of the generator target itself, if it is defined in the default GN toolchain context. Otherwise, it will include a toolchain_{toolchain_name}/ prefix as well.

Note that the directory and names of the bazel_input_file() target itself does not impact the content of @gn_targets at all.

Hence the following examples:

# From //src/lib/BUILD.gn
action("foo") {
  ...
}

# This creates `@gn_targets//src/lib:foo`
bazel_input_file("foo_outputs") {
  generator = ":foo"
}

# This creates `@gn_targets//src/lib:foo_alt`, by overriding the
# name explicitly.
bazel_input_file("foo_outputs_alt") {
  generator = ":foo"
  gn_targets_name = "foo_alt"
}

if (current_toolchain == default_toolchain) {
  # This creates @gn_targets//toolchain_host_x64/src/lib:foo
  bazel_input_file("foo_host_outputs") {
    generator = ":foo($host_toolchain)"

    # Because the generator is in a different toolchain context,
    # its `outputs` argument must be provided (see next section).
    outputs = [ get_label_info(generator, "target_out_dir") + "/foo.out" ]
  }
}

If one defines several bazel_input_file() with the same filegroup package and name, Bazel will complain about multiply defined targets in the corresponding BUILD.bazel file (which can be inspected, as comments indicate which exact GN target defined them).

bazel_input_file() outputs selection

By default, bazel_input_file() exposes all outputs of the generator target, but this can only work if the following conditions apply:

• The generator target is a GN action() (i.e. not a group() or an executable()).
• The target and the generator are defined in the same BUILD.gn file.
• The target and the generator are evaluated in the same toolchain context.

Otherwise, specifying the list of outputs using the outputs argument is required. GN will try to print a user-friendly error message explaining the situation. An example of explicit outputs:

# From //src/lib/BUILD.gn
action("foo") {
  ...
}

# From //src/lib/bar/BUILD.gn

# Only expose the (first) output of //src/lib:foo as @gn_targets//src/lib:foo
# The fact that this target is defined under //src/lib/bar/ does not matter.
bazel_input_file("foo.bazel_input") {
  generator = "//src/lib:foo"
  _foo_output_dir = get_label_info(generator, "target_out_dir")
  outputs = [
      "${_foo_output_dir}/output",
  ]
}

Note that this generates the filegroup as @gn_targets//src/lib:foo, and not as @gn_targets//src/lib/bar:foo.

This is why defining bazel_input_file() targets in the same BUILD.gn file as the generator target is recommended, though not required.

bazel_input_directory()

It is an error to list a directory as an output in a bazel_input_file(), as this will may result in incremental build errors. There is no easy way to detect this from GN / Ninja, but one can use the bazel_input_directory() GN template to expose directory Ninja outputs to Bazel.

This creates a Bazel filegroup that uses a glob() statement, under the hood, to ensure that all files from the directory are visible from the Bazel sandbox / command execution environment, and carry dependency information properly across the GN / Bazel graph boundaries.

DEPRECATED: Ninja outputs in the @legacy_ninja_build_outputs repository

For historical reasons, it is also possible to use bazel_input_resource() instead or bazel_input_file(), but this use is now strongly discouraged. They differ in the following way (see next section for migration instructions):

• bazel_input_resource() populates both the @gn_targets and the @legacy_ninja_build_outputs repositories.

• bazel_input_resource() can specify an arbitrary filegroup() package and name inside @legacy_ninja_build_outputs, which can lead to conflicts if several different GN targets use the same one.

  By contrast, bazel_input_file() mandates the filegroup package and name from the GN target path to prevent them.

  NOTE: The sources argument of bazel_input_resource() corresponds to the outputs argument of bazel_input_file(). The outputs argument of bazel_input_resource() has no equivalent in bazel_input_file() since the filegroup locations are mandated from the GN target label itself.

• bazel_input_resource() dependencies must be listed with the bazel_inputs argument of the bazel_action() GN template, while bazel_input_file() can just be part of its deps.

• Bazel targets access Ninja outputs using their file path in @legacy_ninja_build_outputs repository (e.g. @legacy_ninja_build_outputs//:build_version_info.txt), and it is often difficult to determine how these paths are defined on the GN side.

  By contrast, @gn_targets filegroup labels always reflect the GN target path that defined them, making debugging easier (e.g. @gn_targets//build/info:version, which clearly shows that the files were exposed by a GN target in //build/info/BUILD.gn).

• To facilitate migration, bazel_input_resource() also defines a target in the @gn_targets repository, with a label like @gn_targets//{dir}:{name} where {gn_dir} matches the current BUILD.gn directory path, and {name} is, by default the current target name, with any optional _bazel_inputs suffix removed.

  NOTE: This _bazel_inputs suffix is different from the .bazel_input one supported by bazel_input_file().

  Using the gn_targets_name argument can be used to override the value of {name}.

• bazel_input_resource_directory() is used to expose a directory as a filegroup, and serves a similar purpose as bazel_input_directory() with a different (and slightly more complicated) interface.

  It also populates both @legacy_ninja_build_outputs and @gn_targets, and supports the gn_targets_name argument to override the filegroup name in @gn_targets only.

• Much more annoyingly, all bazel_input_resource() and bazel_input_resource_directory() used by any bazel_action() target much be reachable from the global target lists defined in //build/bazel/legacy_ninja_build_outputs.gni.

In practice, the last point is a major pain, prevents parallel development, and is the main reason why this scheme is now deprecated.

Critical differences, and a note on fx bazel:

One benefit of the deprecated scheme is that the content of @legacy_ninja_build_outputs is only setup once and for all when the platform build's Bazel workspace is setup. By contrast, the content of @gn_targets will change every time a bazel_action() command is run from Ninja.

Keep this in mind when invoking fx bazel directly. This command is only useful to debug Bazel invocations in the platform build, but it does not update Ninja outputs that your Bazel targets depend on. In other words:

• If you invoke fx bazel build //some:target, a target which references files from the @legacy_ninja_build_outputs repository, you must first ensure that all outputs in the Ninja build directory it may access are up-to-date, otherwise you may build the wrong thing.

• If you invoke fx bazel build //other:target, a target which references filegroups from the @gn_targets repository, you must ensure that the Ninja build artifacts are up-to-date as well, but also ensure that the content of @gn_targets is updated. Otherwise, its state will reflect a previous bazel_action() invocation that built something completely different. This will likely result in errors about

Hence the best way to rebuild things is to invoke the Ninja target that matches the GN bazel_action() target that invokes Bazel, e.g. with fx build //some:target.

Migrating from @legacy_ninja_build_outputs to @gn_targets:

Migrating Bazel targets from the deprecated to the new scheme can be done in the following steps:

• First, replace @legacy_ninja_build_outputs//:<file_path> labels in your BUILD.bazel files with the equivalent @gn_targets//<dir>:<name> label.

  Here <dir> should match the directory path of the BUILD.gn file that defines the bazel_input_resource() or bazel_input_resource_directory() target for <file_path>.

  If you don't know where this is, peek into the following file which defines the legacy filegroups, and contains comments providing the new target to use:

  out/default/gen/build/bazel/output_base/external/legacy_ninja_build_outputs/BUILD.bazel
  

  For example:

  # From GN target: //src/devices/bus/drivers/platform:platform-bus-package-bazel(//build/toolchain/fuchsia:arm64)
  # Migration target: @gn_targets//src/devices/bus/drivers/platform:platform-bus
  filegroup(
      name = "platform-bus-package-bazel",
      srcs = [
          "platform-bus.far",
      ],
  )
  

  Tells you to use @gn_targets//src/devices/bus/drivers/platform:platform-bus instead of @legacy_ninja_build_outputs//:platform-bus.far or @legacy_ninja_build_outputs//:platform-bus-package-bazel.

  NOTE: Remove all references from all repositories, i.e. including the ones that may exist under //vendor/.... This may require multiple CLs to do properly (In this case, add a build fence as suggested in the last step below).

• As a special case, replace @legacy_ninja_build_outputs//:license labels with @gn_targets//:all_licenses.spdx.json. These are the SPDX files that carry licensing information for all Ninja outputs exposed by each repository.

• Second, remove the GN target reference from //build/bazel/legacy_ninja_build_outputs.gnior its dependencies. If the target label does not appear in this file, use the following GN query to print a dependency path to determine where it is added:

  fx gn path out/default //build/bazel:legacy_ninja_build_outputs <your_bazel_input_resource_target_label>
  

  For example:

  $ fx gn path out/default //build/bazel:legacy_ninja_build_outputs //src/devices/bus/drivers/platform:platform-bus-package-bazel
  //build/bazel:legacy_ninja_build_outputs --[private]-->
  //sdk/lib/driver/devicetree/testing:devicetree-test-bazel-inputs --[private]-->
  //src/devices/bus/drivers/platform:platform-bus-package-bazel
  

  Tells you that the dependency was added by //sdk/lib/driver/devicetree/testing:devicetree-test-bazel-inputs, and that you should probably migrate this definition and the corresponding Bazel references as well.

• Verify that everything builds correctly.

• Replace the bazel_input_resource() target definition with a bazel_input_file() one.

  Similarly, use bazel_input_directory() instead of bazel_input_resource_directory().

• Verify that everything builds correctly.

• Add a build fence to your CL to work-around Ninja getting confused by the changes in the dependency graph. Due to the way Ninja works, it will inject stale depfile dependencies from a previous build into the next incremental build graph, which can result in flaky build failures.

  To do this, add a new print() statement to //build/force_clean/get_fences.py if you modify fuchsia.git, or to //vendor/<name>/build/force_clean/get_fences.pyif you are modifying the content of the //vendor/<name>/ git repository (if the file does not exist, create a new one with a single print() statement in it, it will be picked up automatically).

  NOTE: This forces the next build that includes your change to be a clean build, either locally or on CQ/CI.

• Upload your CL to Gerrit, and verify that all CQ builds pass.

BAZEL BUILD ACTION

The bazel_build_action() template, defined in //build/bazel/bazel_build_action.gni is used to create a GN action that will run a bazel build <targets> command in the Bazel workspace.

If such a Bazel target depends on a Ninja-generated output file, this must be expressed by a dependency on a bazel_input_xxx() target, as explained in the previous section,

After the Bazel build command completes, its outputs are copied from the non-deterministic location in the Bazel output base into a stable location under target_out_dir or target_gen_dir (as required by GN for all actions).

For a concrete example, see //build/bazel/tests/build_action/ that contains a working target that invokes a Bazel build command (that simply copies an input file into a Bazel output), then verify that it worked properly.

CLANG TOOLCHAIN REPOSITORY

The Bazel build generates an external repository named @prebuilt_clang that mirrors the content of the host Clang toolchain, and augments it with Bazel-specific files. These are needed to define C++ toolchain instances and configurations.

C++ Toolchain selection is performed using the new Bazel Platforms toolchain, which is very different to the traditional use of --crosstool_top, which is why using this option will not work.

Note that this is distinct from sdk-integration's own @fuchsia_clang external repository, which defines a C++ toolchain that generates Fuchsia binaries (while @prebuilt_clang is used to generate host binaries and experiment with build variants and PIE-optimized executables, without conflicts).

CONFIGURATIONS

Bazel command-line configurations are defined in //build/bazel/templates/template.bazelrc, which produces ${BAZEL_TOPDIR}/.bazelrc. Configurations are invoked as --config=NAME.

Publish Build and Test Results

Sharing build results can be helpful for triaging and reproducing issues. Use one of:

• --config=sponge streams build event data to the Sponge service.
• --config=resultstore streams build event data to the ResultStore service.

Remote Building

Remote building can speed up builds by 1) offloading work remotely and 2) caching.

• --config=remote enables remote build for many actions using RBE.

Authentication

• --config=gcertauth uses your LOAS credentials to authenticate for using the aforementioned build services.

TESTING

You can invoke build/bazel/scripts/test-all.py to verify that everything works properly. This is used to verify regressions during development of Bazel support in the platform build, what is does is:

1. Invoke build/bazel/scripts/prepare-fuchsia-checkout.py, unless the --skip-prepare option is used.

2. Invoke fx clean unless --skip-clean is used.

3. Setup the Bazel workspace, then run a series of tests to verify that things work properly.

Always try to add new tests when introducing new features under //build/bazel/, and run this script when changing its implementation (for now this is all manual, but will likely be automated in CQ in the future).

DEBUGGING HERMETICITY ISSUES IN REPOSITORY RULES

To help debug hermeticity issues that happen within repository rules, the Bazel workspace is configured to save a log of repository-related events to a file located under $BAZEL_TOPDIR/logs/workspace-events.log, this is a binary proto file (see https://bazel.build/remote/workspace) that can be converted to text automatically with //build/bazel/scripts/parse-workspace-event-log.py which can be invoked directly from your Fuchsia directory.

The script will automatically find the log for the latest command and dump its content to text on stdout, or to a file if the --output=FILE option is used.

The log files are rotated, up to 3 older revisions are stored in the $BAZEL_TOPDIR/logs directory so you can compare them if possible.