docs/development/sdk/navigating-a-bazel-and-fuchsia-sdk-based-development-environment.md - fuchsia - Git at Google

 # Navigating a Bazel-and-Fuchsia-SDK-based development environment

 This page describes how to identify and locate [FIDL][fidl] files, client
 libraries, and build artifacts on your host machine for Fuchsia projects
 using the Fuchsia SDK with the [Bazel][bazel]{:.external} build system.

 When developing [Fuchsia components][fuchsia-components] in a
 Fuchsia-SDK-based development environment, developers use the following
 interfaces and libraries included in the Fuchsia SDK:

 - [FIDL files](#fidl-files-in-a-fuchsia-sdk-based-project) – Interfaces
   for inter-process communication (IPC) protocols used by programs running
   on Fuchsia.
 - [Client libraries](#client-libraries-in-a-fuchsia-sdk-based-project) –
   Libraries that provide features and building blocks on top of
   the Fuchsia APIs.

 With these interfaces and libraries available in the development
 environment, the Bazel build system can build
 [Fuchsia packages][fuchsia-package] (containing Fuchsia components)
 and generate [build artifacts](#build-artifacts-from-the-bazel-build-system)
 on the host machine.

 ## FIDL files in a Fuchsia-SDK-based project {:#fidl-files-in-a-fuchsia-sdk-based-project}

 Run a `bazel build` command first to create symlinks to
 FIDL files in your local project setup, for example:

 ```posix-terminal
 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:

 ``` {:.devsite-disable-click-to-copy}
 <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][fidl-reference].

 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](#flow-of-fidl-files-and-client-libraries)
 in Appendices.

 ### List FIDL targets using Bazel commands {:#list-fidl-targets-using-bazel-commands}

 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:

 ```posix-terminal
 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:

   ``` {:.devsite-disable-click-to-copy}
   $ bazel query '@fuchsia_sdk//fidl/...'
   ```
 - List all targets in a specific FIDL protocol directory:

   ``` {:.devsite-disable-click-to-copy}
   $ bazel query '@fuchsia_sdk//fidl/fuchsia.auth/...'
   ```

 - List all generated C++ libraries from the top FIDL directory:

   ``` {:.devsite-disable-click-to-copy}
   $ 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.

 ## Client libraries in a Fuchsia-SDK-based project {:#client-libraries-in-a-fuchsia-sdk-based-project}

 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:

 ``` {:.devsite-disable-click-to-copy}
 <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](#flow-of-fidl-files-and-client-libraries)
 in Appendices.

 ## Build artifacts from the Bazel build system {:#build-artifacts-from-the-bazel-build-system}

 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:

 - [Fuchsia packages][create-a-package-repository] (`.far`) – Contain
   newly built Fuchsia components and binaries (for example, driver binaries).
 - [Debug symbols][debug-symbols] – Needed for symbolizing debug messages
   and logs.

 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`][fuchsia-drivers]) stores Bazel build artifacts
 in the `$HOME/.cache/bazel` directory on the host machine.

 ### List build artifacts using Bazel commands {:#list-build-artifacts-using-bazel-commands}

 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:

 ```posix-terminal
 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:

 ``` {:.devsite-disable-click-to-copy}
 $ bazel cquery //third_party/iwlwifi/platform:iwlwifi_pkg --output files
 ```

 ## Appendices

 ### Difference between bazel query and bazel cquery {:#difference-between-bazel-query-and-bazel-cquery}

 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.

 ### Flow of FIDL files and client libraries from the Fuchsia source tree to Fuchsia-SDK-based projects {:#flow-of-fidl-files-and-client-libraries}

 ![Diagram of the Fuchsia SDK flow](images/fuchsia-idk-to-sdk-01.png "Image showing the flow of file and libraries in the Fuchsia SDK"){: 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:

 1. The Fuchsia source tree builds a new version of
    [the Fuchsia IDK][fuchsia-idk] (Integrator Development Kit), which
    contains collections of FIDL files, libraries, headers, and more.
 1. The Fuchsia IDK is combined with Bazel build system integrations to
    create a new version of the Fuchsia SDK.
 1. The new Fuchsia SDK is published and becomes available to project
    integrators.
 1. Project integrators download [the latest Fuchsia SDK][download-sdk] and
    publish all or selected contents of the SDK to their Fuchsia project
    repositories (usually through automation).
 1. Developers get access to the new contents of the Fuchsia SDK when they
    update their development environment (which then downloads the latest
    changes in the project).

 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.

 <!-- Reference links -->

 [fidl]: /docs/development/languages/fidl/README.md
 [bazel]: https://bazel.build/docs
 [fuchsia-package]: /docs/concepts/packages/package.md
 [fuchsia-components]: /docs/concepts/components/v2/README.md
 [fidl-reference]: https://fuchsia.dev/reference/fidl
 [create-a-package-repository]: /docs/development/tools/ffx/workflows/create-a-package-repository.md
 [debug-symbols]: /docs/development/tools/ffx/workflows/register-debug-symbols.md
 [fuchsia-drivers]: https://fuchsia.googlesource.com/sdk-samples/drivers
 [fuchsia-idk]: /docs/development/idk/README.md
 [download-sdk]: https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core/linux-amd64/+/latest
	# Navigating a Bazel-and-Fuchsia-SDK-based development environment

	This page describes how to identify and locate [FIDL][fidl] files, client
	libraries, and build artifacts on your host machine for Fuchsia projects
	using the Fuchsia SDK with the [Bazel][bazel]{:.external} build system.

	When developing [Fuchsia components][fuchsia-components] in a
	Fuchsia-SDK-based development environment, developers use the following
	interfaces and libraries included in the Fuchsia SDK:

	- [FIDL files](#fidl-files-in-a-fuchsia-sdk-based-project) – Interfaces
	for inter-process communication (IPC) protocols used by programs running
	on Fuchsia.
	- [Client libraries](#client-libraries-in-a-fuchsia-sdk-based-project) –
	Libraries that provide features and building blocks on top of
	the Fuchsia APIs.

	With these interfaces and libraries available in the development
	environment, the Bazel build system can build
	[Fuchsia packages][fuchsia-package] (containing Fuchsia components)
	and generate [build artifacts](#build-artifacts-from-the-bazel-build-system)
	on the host machine.

	## FIDL files in a Fuchsia-SDK-based project {:#fidl-files-in-a-fuchsia-sdk-based-project}

	Run a `bazel build` command first to create symlinks to
	FIDL files in your local project setup, for example:

	```posix-terminal
	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:

	``` {:.devsite-disable-click-to-copy}
	<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][fidl-reference].

	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](#flow-of-fidl-files-and-client-libraries)
	in Appendices.

	### List FIDL targets using Bazel commands {:#list-fidl-targets-using-bazel-commands}

	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:

	```posix-terminal
	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:

	``` {:.devsite-disable-click-to-copy}
	$ bazel query '@fuchsia_sdk//fidl/...'
	```
	- List all targets in a specific FIDL protocol directory:

	``` {:.devsite-disable-click-to-copy}
	$ bazel query '@fuchsia_sdk//fidl/fuchsia.auth/...'
	```

	- List all generated C++ libraries from the top FIDL directory:

	``` {:.devsite-disable-click-to-copy}
	$ 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.

	## Client libraries in a Fuchsia-SDK-based project {:#client-libraries-in-a-fuchsia-sdk-based-project}

	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:

	``` {:.devsite-disable-click-to-copy}
	<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](#flow-of-fidl-files-and-client-libraries)
	in Appendices.

	## Build artifacts from the Bazel build system {:#build-artifacts-from-the-bazel-build-system}

	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:

	- [Fuchsia packages][create-a-package-repository] (`.far`) – Contain
	newly built Fuchsia components and binaries (for example, driver binaries).
	- [Debug symbols][debug-symbols] – Needed for symbolizing debug messages
	and logs.

	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`][fuchsia-drivers]) stores Bazel build artifacts
	in the `$HOME/.cache/bazel` directory on the host machine.

	### List build artifacts using Bazel commands {:#list-build-artifacts-using-bazel-commands}

	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:

	```posix-terminal
	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:

	``` {:.devsite-disable-click-to-copy}
	$ bazel cquery //third_party/iwlwifi/platform:iwlwifi_pkg --output files
	```

	## Appendices

	### Difference between bazel query and bazel cquery {:#difference-between-bazel-query-and-bazel-cquery}

	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.

	### Flow of FIDL files and client libraries from the Fuchsia source tree to Fuchsia-SDK-based projects {:#flow-of-fidl-files-and-client-libraries}

	![Diagram of the Fuchsia SDK flow](images/fuchsia-idk-to-sdk-01.png "Image showing the flow of file and libraries in the Fuchsia SDK"){: 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:

	1. The Fuchsia source tree builds a new version of
	[the Fuchsia IDK][fuchsia-idk] (Integrator Development Kit), which
	contains collections of FIDL files, libraries, headers, and more.
	1. The Fuchsia IDK is combined with Bazel build system integrations to
	create a new version of the Fuchsia SDK.
	1. The new Fuchsia SDK is published and becomes available to project
	integrators.
	1. Project integrators download [the latest Fuchsia SDK][download-sdk] and
	publish all or selected contents of the SDK to their Fuchsia project
	repositories (usually through automation).
	1. Developers get access to the new contents of the Fuchsia SDK when they
	update their development environment (which then downloads the latest
	changes in the project).

	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.

	<!-- Reference links -->

	[fidl]: /docs/development/languages/fidl/README.md
	[bazel]: https://bazel.build/docs
	[fuchsia-package]: /docs/concepts/packages/package.md
	[fuchsia-components]: /docs/concepts/components/v2/README.md
	[fidl-reference]: https://fuchsia.dev/reference/fidl
	[create-a-package-repository]: /docs/development/tools/ffx/workflows/create-a-package-repository.md
	[debug-symbols]: /docs/development/tools/ffx/workflows/register-debug-symbols.md
	[fuchsia-drivers]: https://fuchsia.googlesource.com/sdk-samples/drivers
	[fuchsia-idk]: /docs/development/idk/README.md
	[download-sdk]: https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core/linux-amd64/+/latest