1.. _docs-bazel-integration: 2 3=================================================== 4Using a Pigweed module in an existing Bazel project 5=================================================== 6This guide explains how to start using a Pigweed module in your existing 7Bazel-based C or C++ project. We'll assume you're familiar with the build 8system at the level of the `Bazel tutorial <https://bazel.build/start/cpp>`__. 9 10------------------------------------- 11Add Pigweed as a WORKSPACE dependency 12------------------------------------- 13Add Pigweed as a `git_repository 14<https://bazel.build/rules/lib/repo/git#git_repository>`__ in your 15``WORKSPACE``: 16 17.. code-block:: python 18 19 git_repository( 20 name = "pigweed", 21 commit = "c00e9e430addee0c8add16c32eb6d8ab94189b9e", 22 remote = "https://pigweed.googlesource.com/pigweed/pigweed.git", 23 ) 24 25(You can find the latest tip-of-tree commit in the History tab in `CodeSearch 26<https://cs.opensource.google/pigweed/pigweed>`__.) 27 28If you manage your dependencies as submodules, you can add Pigweed as a 29submodule, too, and then add it to the ``WORKSPACE`` as a `local_repository 30<https://bazel.build/reference/be/workspace#local_repository>`__: 31 32.. code-block:: python 33 34 local_repository( 35 name = "pigweed", 36 path = "third_party/pigweed", 37 ) 38 39We don't yet publish releases that could be pulled in using `http_archive 40<https://bazel.build/rules/lib/repo/http#http_archive>`__. 41 42We don't support `bzlmod <https://bazel.build/external/overview#bzlmod>`__ yet. 43See http://pwbug.dev/258836641. 44 45If either of these limitations is important to you, please reach out to us on 46`chat <https://discord.gg/M9NSeTA>`__. 47 48--------------------------- 49Use Pigweed in your project 50--------------------------- 51Let's say you want to use ``pw::Vector`` from :ref:`module-pw_containers`, our 52embedded-friendly replacement for ``std::vector``. 53 54#. Include the header you want in your code: 55 56 .. code-block:: cpp 57 58 #include "pw_containers/vector.h" 59 60#. Look at the module's `build file 61 <https://cs.opensource.google/pigweed/pigweed/+/main:pw_containers/BUILD.bazel>`__ 62 to figure out which build target you need to provide the header and 63 implementation. For ``pw_containers/vector.h``, it's 64 ``//pw_containers:vector``. 65 66#. Add this target to the ``deps`` of your 67 `cc_library <https://bazel.build/reference/be/c-cpp#cc_library>`__ or 68 `cc_binary <https://bazel.build/reference/be/c-cpp#cc_binary>`__: 69 70 .. code-block:: python 71 72 cc_library( 73 name = "my_library", 74 srcs = ["my_library.cc"], 75 hdrs = ["my_library.h"], 76 deps = [ 77 "@pigweed//pw_containers:vector", # <-- The new dependency 78 ], 79 ) 80 81#. Add a dependency on ``@pigweed//pw_build:default_link_extra_lib`` to your 82 final *binary* target. See :ref:`docs-build_system-bazel_link-extra-lib` 83 for a discussion of why this is necessary, and what the alternatives are. 84 85 .. code-block:: python 86 87 cc_binary( 88 name = "my_binary", 89 srcs = ["my_binary.cc"], 90 deps = [ 91 ":my_library", 92 "@pigweed//pw_build:default_link_extra_lib", # <-- The new dependency 93 ], 94 ) 95 96-------------------------------------------- 97Configure backends for facades you depend on 98-------------------------------------------- 99Pigweed makes extensive use of :ref:`docs-facades`, and any module you choose 100to use will likely have a transitive dependency on some facade (typically 101:ref:`module-pw_assert` or :ref:`module-pw_log`). Continuing with our example, 102``pw::Vector`` depends on :ref:`module-pw_assert`. 103 104In Bazel, facades already have a default backend (implementation) that works 105for host builds (builds targeting your local development machine). But to build 106a binary for your embedded target, you'll need to select a suitable backend 107yourself. 108 109Fortunately, the default backend for :ref:`module-pw_assert` is 110:ref:`module-pw_assert_basic`, which is a suitable place to start for most 111embedded targets, too. But it depends on :ref:`module-pw_sys_io`, another 112facade for which you *will* have to choose a backend yourself. 113 114The simplest way to do so is to set the corresponding `label flag 115<https://bazel.build/extending/config#label-typed-build-settings>`__ when 116invoking Bazel. For example, to use the 117:ref:`module-pw_sys_io_baremetal_stm32f429` backend for :ref:`module-pw_sys_io` 118provided in upstream Pigweed: 119 120.. code-block:: console 121 122 $ bazel build \ 123 --@pigweed//targets/pw_sys_io_backend=@pigweed//pw_sys_io_baremetal_stm32f429 \ 124 //path/to/your:target 125 126You can also define backends within your own project. (If Pigweed doesn't 127include a :ref:`module-pw_sys_io` backend suitable for your embedded platform, 128that's what you should do now.) See 129:ref:`docs-build_system-bazel_configuration` for a tutorial that dives deeper 130into facade configuration with Bazel. 131