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 121Note that copying the ``far`` file to fuchsia.git does not copy the debug symbols which 122means that crashes won't be symbolicated. If you need debug symbols you can run the 123following command in the Pigweed repository to register the symbols. 124 125.. tab-set:: 126 127 .. tab-item:: arm64 128 129 .. code-block:: console 130 131 $ bazelisk run --config=fuchsia //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.arm64.debug_symbols 132 133 .. tab-item:: x64 134 135 .. code-block:: console 136 137 $ bazelisk run --config=fuchsia //pw_bluetooth_sapphire/fuchsia/bt_host:pkg.x64.debug_symbols 138 139-------------------- 140Working with devices 141-------------------- 142 143Inspect 144======= 145To query the current state of the ``bt-host`` component Inspect hierarchy, run: 146 147#. ``pw ffx inspect list | grep bt-host`` to find the component's ``<moniker>`` 148 149#. ``pw ffx inspect show "<moniker>"`` 150 151 * Note that the full moniker from step 2 should be in quotations, e.g. 152 ``pw ffx inspect show "core/bluetooth-core/bt-host-collection\:bt-host_000"``. 153 154 * Wildcards can be passed into the selector as needed, e.g. 155 ``pw ffx inspect show "core/bluetooth-core/bt-host-collection*"``. 156 157-------------------- 158Editor configuration 159-------------------- 160 161Clangd 162====== 163Currently some manual steps are required to get clangd working with Fuchsia 164code (for example, for FIDL server files). 165 166#. Execute the following command to generate ``compile_commands.json``. This 167 needs to be done whenever the build graph changes. 168 169 .. code-block:: console 170 171 bazelisk run //:refresh_compile_commands_for_fuchsia_sdk 172 173#. Add this flag to your clangd configuration, fixing the full path to your 174 Pigweed checkout: 175 176 .. code-block:: console 177 178 --compile-commands-dir=/path/to/pigweed/.compile_commands/fuchsia 179 180-------------- 181Infrastructure 182-------------- 183 184Run Fuchsia presubmit tests 185=========================== 186Presubmits for ``bt-host`` are captured in a dedicated separate builder, 187``pigweed-linux-bazel-bthost``, rather than existing ones such as 188``pigweed-linux-bazel-noenv``. 189 190On the builder invocation console, there are a number of useful artifacts for 191examining the environment during test failures. Here are some notable examples: 192 193* ``bt_host_package`` ``stdout``: Combined ``stdout``/``stderr`` of the entire test orchestration and execution. 194* ``subrunner.log``: Combined test ``stdout``/``stderr`` of test execution only. 195* ``target.log``: The ``ffx`` target device's logs. 196* ``ffx_config.txt``: The ``ffx`` configuration used for provisioning and testing. 197* ``ffx.log``: The ``ffx`` host logs. 198* ``ffx_daemon.log``: The ``ffx`` daemon's logs. 199* ``env.dump.txt``: The environment variables when test execution started. 200* ``ssh.log``: The SSH logs when communicating with the target device. 201 202These presubmits can be also be replicated locally with the following command: 203 204.. code-block:: 205 206 bazelisk run --config=fuchsia //pw_bluetooth_sapphire/fuchsia:infra.test_all 207 208.. note:: 209 Existing package servers must be stopped before running this command. To 210 check for any existing package servers run ``lsof -i :8083`` and make sure 211 each of those processes are killed. 212 213.. note:: 214 You do not need to start an emulator beforehand to to run all tests this way. 215 This test target will automatically provision one before running all tests. 216 217Add a test to presubmit 218======================= 219Fuchsia test packages are those defined with a Fuchsia SDK rule like 220``fuchsia_unittest_package``. All Fuchsia test packages need to be added to the 221Fuchsia presubmit step or they will not be tested. 222 223To add new Fuchsia test packages to presubmit, add the test package targets to 224``//pw_bluetooth_sapphire/fuchsia/BUILD.bazel``. 225 226Example: 227 228.. code-block:: 229 230 # pw_bluetooth_sapphire/fuchsia/BUILD.bazel 231 232 qemu_tests = [ 233 "//pw_bluetooth_sapphire/fuchsia/bt_host:integration_test_pkg", 234 ... 235 ] 236 237Uploading to CIPD 238================= 239Pigweed infrastructure uploads ``bt-host`` artifacts to 240`fuchsia/prebuilt/bt-host`_ and `fuchsia/prebuilt/bt-hci-virtual`_ via the 241`pigweed-linux-bazel-bthost`_ builder by building the top level infra target: 242 243.. code-block:: 244 245 # Ensure all dependencies are built. 246 bazelisk build --config=fuchsia //pw_bluetooth_sapphire/fuchsia:infra 247 248 # Get builder manifest file. 249 bazelisk build --config=fuchsia --output_groups=builder_manifest //pw_bluetooth_sapphire/fuchsia:infra 250 251The resulting file contains a ``cipd_manifests`` JSON field which references a 252sequence of JSON files specifying the CIPD package path and package file 253contents. 254 255.. _fuchsia/prebuilt/bt-host: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-host 256.. _fuchsia/prebuilt/bt-hci-virtual: https://chrome-infra-packages.appspot.com/p/fuchsia/prebuilt/bt-hci-virtual 257.. _pigweed-linux-bazel-bthost: https://ci.chromium.org/ui/p/pigweed/builders/pigweed.ci/pigweed-linux-bazel-bthost 258 259.. _module-pw_bluetooth_sapphire-fuchsia-zxdb: 260 261Using Zxdb: the Fuchsia debugger 262================================ 263 264`Zxdb is a console-mode debugger`_ for native code running on Fuchsia. 265 266To run Zxdb in pw_bluetooth_sapphire: 267 268#. Start the emulator. 269 270#. Run: 271 272 .. code-block:: console 273 274 # Connect to the debugger 275 $ pw ffx debug connect 276 277 # Attach test package from test output url (e.g. fuchsia-pkg://bazel.test.pkg.publish.anonymous/bt_host_fidl_tests_bazel#meta/fidl_test.cm) 278 $ [zxdb] attach <test-package> (e.g. attach fidl_test.cm) 279 280 # Set a breakpoint 281 $ [zxdb] break <file.cc>:<line-number> (e.g. break fidl/profile_server.cc:384) 282 283#. Run your test in a new terminal: 284 285 .. code-block:: console 286 287 $ bazelisk run --config=fuchsia //pw_bluetooth_sapphire/fuchsia/host/fidl:test_pkg 288 289Once you have successfully connected to the debugger, see `further capabilities`_. 290 291.. _Zxdb is a console-mode debugger: https://fuchsia.dev/fuchsia-src/development/debugger 292.. _further capabilities: https://fuchsia.dev/fuchsia-src/development/debugger?hl=en#working_with_zxdb 293