1.. _module-pw_bluetooth_sapphire-fuchsia: 2 3=================== 4Fuchsia development 5=================== 6.. pigweed-module-subpage:: 7 :name: pw_bluetooth_sapphire 8 9``//pw_bluetooth_sapphire/fuchsia`` currently contains the Fuchsia build 10targets for building, running, and testing the ``bt-host`` and 11``bt-hci-virtual`` packages. 12 13Fuchsia's Sapphire Bluetooth stack integration uses the ``bt-host`` core 14package which is built from Pigweed CI, uploaded to CIPD, and rolled 15automatically. The ``bt-host`` package is assembled into products in any 16Fuchsia build which uses Bluetooth. The ``bt-hci-virtual`` package is included 17in some builds for testing. See `bt-host README 18<https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/connectivity/bluetooth/core/bt-host/README.md>`__ 19for more details on product assembly. 20 21.. note:: 22 Every ``bazelisk`` invocation needs ``--config=fuchsia`` whenever the target 23 is a fuchsia-specific target. 24 These fuchsia-specific targets are disabled (marked incompatible with the 25 target platform) by default to avoid polluting/conflicting with non-fuchsia 26 pigweed builds. 27 Specifying ``--config=fuchsia`` also allows ``@fuchsia_sdk`` backends to be 28 specified for Pigweed dependencies. 29 30---------------------------------------- 31Accessing ffx from a Pigweed environment 32---------------------------------------- 33The ``ffx`` command is available as a subcommand of ``pw``: 34 35.. code-block:: console 36 37 pw ffx help 38 39------- 40Testing 41------- 42 43Running tests 44============= 45First, ensure the emulator is running or hardware running Fuchsia is 46connected. Then run a test package with: 47 48.. code-block:: console 49 50 bazelisk run --config=fuchsia //pw_bluetooth_sapphire/fuchsia/host/l2cap:test_pkg 51 52Flags can also be passed to the test binary: 53 54.. code-block:: console 55 56 bazelisk run --config=fuchsia //pw_bluetooth_sapphire/fuchsia/host/l2cap:test_pkg \ 57 -- --gtest-filter="*Example" --severity=DEBUG 58 59.. note:: 60 If the test is unable to connect to the emulator, run ``pw ffx target 61 remove --all`` first to clean your machine's target list. 62 63You can also run the presubmit step that will start an emulator and run 64all tests, but this is slow: 65 66.. code-block:: console 67 68 pw presubmit --step bthost_package 69 70Emulator 71======== 72To start the emulator, use one of the following commands: 73 74.. code-block:: 75 76 bazelisk run @fuchsia_products//:core.x64.emu -- --headless 77 # OR 78 bazelisk run @fuchsia_products//:minimal.arm64.emu -- --headless 79 80To stop the running emulator, use the following command: 81 82.. code-block:: 83 84 pw ffx emu stop --all 85 86-------- 87Building 88-------- 89.. note:: 90 See the main :ref:`Building <module-pw_bluetooth_sapphire-building>` section 91 for instructions on building for your host machine (producing Linux/macOS 92 test binaries). 93 94To build the ``bt-host`` package, use one of the following commands: 95 96.. tab-set:: 97 98 .. tab-item:: arm64 99 100 .. code-block:: 101 102 bazelisk build --config=fuchsia //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.arm64 103 104 .. tab-item:: x64 105 106 .. code-block:: 107 108 bazelisk build --config=fuchsia //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.x64 109 110The ``bt-host.far`` package will end up in a Bazel build directory that will be 111printed in the command output. For example: 112``bazel-out/aarch64-fastbuild-e2b/bin/pw_bluetooth_sapphire/fuchsia/bt_host/bt-host.far``. 113Note that ``bazel-out`` is symlinked from the root Pigweed directory. 114 115Use the prebuilt in fuchsia.git 116=============================== 117fuchsia.git developers can copy/link the ``bt-host.far`` file to 118``//prebuilt/connectivity/bluetooth/bt-host/<arch>/`` and rename it to 119``bt-host`` to replace the prebuilt that Fuchsia uses. 120 121-------------------- 122Working with devices 123-------------------- 124 125Inspect 126======= 127To query the current state of the ``bt-host`` component Inspect hierarchy, run: 128 129#. ``pw ffx inspect list | grep bt-host`` to find the component's ``<moniker>`` 130 131#. ``pw ffx inspect show "<moniker>"`` 132 133 * Note that the full moniker from step 2 should be in quotations, e.g. 134 ``pw ffx inspect show "core/bluetooth-core/bt-host-collection\:bt-host_000"``. 135 136 * Wildcards can be passed into the selector as needed, e.g. 137 ``pw ffx inspect show "core/bluetooth-core/bt-host-collection*"``. 138 139-------------------- 140Editor configuration 141-------------------- 142 143Clangd 144====== 145Currently some manual steps are required to get clangd working with Fuchsia 146code (for example, for FIDL server files). 147 148#. Execute the following command to generate ``compile_commands.json``. This 149 needs to be done whenever the build graph changes. 150 151 .. code-block:: console 152 153 bazelisk run //:refresh_compile_commands_for_fuchsia_sdk 154 155#. Add this flag to your clangd configuration, fixing the full path to your 156 Pigweed checkout: 157 158 .. code-block:: console 159 160 --compile-commands-dir=/path/to/pigweed/.compile_commands/fuchsia 161 162-------------- 163Infrastructure 164-------------- 165 166Run Fuchsia presubmit tests 167=========================== 168Presubmits for ``bt-host`` are captured in a dedicated separate builder, 169``pigweed-linux-bazel-bthost``, rather than existing ones such as 170``pigweed-linux-bazel-noenv``. 171 172On the builder invocation console, there are a number of useful artifacts for 173examining the environment during test failures. Here are some notable examples: 174 175* ``bt_host_package`` ``stdout``: Combined ``stdout``/``stderr`` of the entire test orchestration and execution. 176* ``subrunner.log``: Combined test ``stdout``/``stderr`` of test execution only. 177* ``target.log``: The ``ffx`` target device's logs. 178* ``ffx_config.txt``: The ``ffx`` configuration used for provisioning and testing. 179* ``ffx.log``: The ``ffx`` host logs. 180* ``ffx_daemon.log``: The ``ffx`` daemon's logs. 181* ``env.dump.txt``: The environment variables when test execution started. 182* ``ssh.log``: The SSH logs when communicating with the target device. 183 184These presubmits can be also be replicated locally with the following command: 185 186.. code-block:: 187 188 bazelisk run --config=fuchsia //pw_bluetooth_sapphire/fuchsia:infra.test_all 189 190.. note:: 191 Existing package servers must be stopped before running this command. To 192 check for any existing package servers run ``lsof -i :8083`` and make sure 193 each of those processes are killed. 194 195.. note:: 196 You do not need to start an emulator beforehand to to run all tests this way. 197 This test target will automatically provision one before running all tests. 198 199Add a test to presubmit 200======================= 201Fuchsia test packages are those defined with a Fuchsia SDK rule like 202``fuchsia_unittest_package``. All Fuchsia test packages need to be added to the 203Fuchsia presubmit step or they will not be tested. 204 205To add new Fuchsia test packages to presubmit, add the test package targets to 206``//pw_bluetooth_sapphire/fuchsia/BUILD.bazel``. 207 208Example: 209 210.. code-block:: 211 212 # pw_bluetooth_sapphire/fuchsia/BUILD.bazel 213 214 qemu_tests = [ 215 "//pw_bluetooth_sapphire/fuchsia/bt_host:integration_test_pkg", 216 ... 217 ] 218 219Uploading to CIPD 220================= 221Pigweed infrastructure uploads ``bt-host`` artifacts to 222`fuchsia/prebuilt/bt-host`_ and `fuchsia/prebuilt/bt-hci-virtual`_ via the 223`pigweed-linux-bazel-bthost`_ builder by building the top level infra target: 224 225.. code-block:: 226 227 # Ensure all dependencies are built. 228 bazelisk build --config=fuchsia //pw_bluetooth_sapphire/fuchsia:infra 229 230 # Get builder manifest file. 231 bazelisk build --config=fuchsia --output_groups=builder_manifest //pw_bluetooth_sapphire/fuchsia:infra 232 233The resulting file contains a ``cipd_manifests`` JSON field which references a 234sequence of JSON files specifying the CIPD package path and package file 235contents. 236 237.. _fuchsia/prebuilt/bt-host: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-host 238.. _fuchsia/prebuilt/bt-hci-virtual: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-hci-virtual 239.. _pigweed-linux-bazel-bthost: https://ci.chromium.org/ui/p/pigweed/builders/pigweed.ci/pigweed-linux-bazel-bthost 240