This page describes how to identify and locate FIDL files, client libraries, and build artifacts on your host machine for Fuchsia projects using the Fuchsia SDK with the Bazel{:.external} build system.
When developing Fuchsia components in a Fuchsia-SDK-based development environment, developers use the following interfaces and libraries included in the Fuchsia SDK:
With these interfaces and libraries available in the development environment, the Bazel build system can build Fuchsia packages (containing Fuchsia components) and generate build artifacts on the host machine.
Run a bazel build
command first to create symlinks to FIDL files in your local project setup, for example:
bazel build @fuchsia_sdk//:ffx
All FIDL files (.fidl
) included in a Bazel-and-Fuchsia-SDK-based project can be found in the following directory of a local project checkout:
<YOUR_PROJECT_CHECKOUT_DIR>/bazel-<PROJECT_NAME>/external/fuchsia_sdk/fidl
To identify the absolute path to <YOUR_PROJECT_CHECKOUT_DIR>/bazel-<PROJECT_NAME>
on the host machine, you can run the bazel info output_base
command.
For more details on each FIDL interface, see the FIDL reference pages.
Note: To understand how FIDL files are selected and added to a project, see Flow of FIDL files and client libraries from the Fuchsia source tree to Fuchsia-SDK-based projects in Appendices.
You can also use Bazel commands to list FIDL targets in your Bazel-and-Fuchsia-SDK-based development environment.
To list FIDL targets available in the development environment, run a bazel query
command using the template below:
bazel query 'ATTR(<GENERATOR_FUNCTION>, <FUCHSIA_FIDL_LIBRARY>, <PATH>)'
See the following example commands:
List all targets from the top FIDL directory of your local project checkout:
$ bazel query '@fuchsia_sdk//fidl/...'
List all targets in a specific FIDL protocol directory:
$ bazel query '@fuchsia_sdk//fidl/fuchsia.auth/...'
List all generated C++ libraries from the top FIDL directory:
$ bazel query 'kind(cc_library, @fuchsia_sdk//fidl/...)'
Fuchsia generates multiple cc_library
targets for each FIDL target. Therefore, these commands tend to print a large list. Consider filtering the output using a grep
command.
Important: You must run a bazel build
command first to build client libraries in your local project setup.
C++ client libraries included in the Fuchsia SDK provide useful features and building blocks on top of the APIs available in Fuchsia. However, unlike FIDL files (which describe the services that must be provided by the system at runtime), the code from client libraries (either in source or prebuilt form) is never part of the Fuchsia platform, so it must be added directly to Fuchsia packages at build time.
All client libraries, header files (.h
) and prebuilt files (.so
), included in a Bazel-and-Fuchsia-SDK-based project can be found in the following directories of a local project checkout:
<YOUR_PROJECT_CHECKOUT_DIR>/bazel-<PROJECT_NAME>/external/fuchsia_sdk/arch <YOUR_PROJECT_CHECKOUT_DIR>/bazel-<PROJECT_NAME>/external/fuchsia_sdk/pkg
For more details on each client library, see comments in the header files.
Note: To understand how client libraries are selected and added to a project, see Flow of FIDL files and client libraries from the Fuchsia source tree to Fuchsia-SDK-based projects in Appendices.
When you run a bazel build
command in a Bazel-and-Fuchsia-SDK-based development environment, the Bazel build system compiles target Fuchsia software (specified in a BUILD.bazel
file) and generates the following build artifacts:
.far
) – Contain newly built Fuchsia components and binaries (for example, driver binaries).The exact locations of where these build artifacts are generated in your development environment depend on the configuration of your Fuchsia project. To identify these locations, examine the settings of the project's Bazel build system. For instance, by default the SDK driver samples repository (fuchsia-drivers
) stores Bazel build artifacts in the $HOME/.cache/bazel
directory on the host machine.
You can also use Bazel commands to list and locate all build artifacts for a specific Fuchsia package in your Bazel-and-Fuchsia-SDK-based development environment.
To list all build artifacts generated for a newly built Fuchsia package in your development environment, run a bazel cquery
command using the template below:
bazel cquery <PATH:TARGET> --output files
Replace the following:
PATH
– The directory path of the target Fuchsia package in your development environment.TARGET
– The label of the target Fuchsia package.The example command below prints a list of the build artifacts generated for the iwlwifi
driver package:
$ bazel cquery //third_party/iwlwifi/platform:iwlwifi_pkg --output files
The bazel query
command returns information about non-configurable targets; therefore, it cannot list generated build artifacts. On the other hand, the bazel cquery
command returns information about targets evaluated in a specific build configuration.
By default, the bazel cquery
command uses a build configuration that matches the architecture of your host system. For instance, on an x64
Linux host machine, the bazel cquery
command lists Fuchsia/x64
artifacts. However, Bazel allows command-line flags to be used to change the build configuration. For example, bazel cquery --cpu=aarch64
commands can be used to list Fuchsia/arm64
artifacts on an x64
host machine. By the way, this also applies to bazel build
commands. For example, bazel build --cpu=aarch64
commands can be used to generate Fuchsia/arm64
artifacts on an x64
host machine.
However, one difficulty is that there are too many different ways to change the build configuration in Bazel. For instance, the correct way to configure for a specific Fuchsia CPU architecture may be to use --config=fuchsia_arm64
instead of using the mentioned --cpu=aarch64
flag. This may depend on the settings of the project in the .bazelrc
file.
{: width=“600”}
Figure 1. Flow of files and libraries from the Fuchsia source to various Bazel-and-Fuchsia-SDK-based Fuchsia projects.
Note: The information in this section may be of less interest if you're not a project integrator or you do not contribute directly to the Fuchsia source tree (fuchsia.git
).
The sequence below describes how some FIDL files and client libraries are selected from the Fuchsia source tree (fuchsia.git
) and become available in Bazel-and-Fuchsia-SDK-based projects:
The directory structure and layout of these FIDL files and client libraries may vary among the Fuchsia projects, especially if the projects use different build systems other than Bazel.