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 :bug:`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---------------------------- 97Set the required Bazel flags 98---------------------------- 99Pigweed projects need to set certain flags in their ``.bazelrc``. These 100generally pre-adopt Bazel features that will become default in the future and 101improve cache performance, disambiguate Python imports, etc. These flags are 102listed below. Unfortunately there's no way to automatically import them, see 103:bug:`353750350`. 104 105.. literalinclude:: ../../pw_build/pigweed.bazelrc 106 107-------------------------------------------- 108Configure backends for facades you depend on 109-------------------------------------------- 110Pigweed makes extensive use of :ref:`docs-facades`, and any module you choose 111to use will likely have a transitive dependency on some facade (typically 112:ref:`module-pw_assert` or :ref:`module-pw_log`). Continuing with our example, 113``pw::Vector`` depends on :ref:`module-pw_assert`. 114 115In Bazel, facades already have a default backend (implementation) that works 116for host builds (builds targeting your local development machine). But to build 117a binary for your embedded target, you'll need to select a suitable backend 118yourself. 119 120Fortunately, the default backend for :ref:`module-pw_assert` is 121:ref:`module-pw_assert_basic`, which is a suitable place to start for most 122embedded targets, too. But it depends on :ref:`module-pw_sys_io`, another 123facade for which you *will* have to choose a backend yourself. 124 125The simplest way to do so is to set the corresponding `label flag 126<https://bazel.build/extending/config#label-typed-build-settings>`__ when 127invoking Bazel. For example, to use the 128:ref:`module-pw_sys_io_baremetal_stm32f429` backend for :ref:`module-pw_sys_io` 129provided in upstream Pigweed: 130 131.. code-block:: console 132 133 $ bazel build \ 134 --@pigweed//targets/pw_sys_io_backend=@pigweed//pw_sys_io_baremetal_stm32f429 \ 135 //path/to/your:target 136 137You can also define backends within your own project. (If Pigweed doesn't 138include a :ref:`module-pw_sys_io` backend suitable for your embedded platform, 139that's what you should do now.) See 140:ref:`docs-build_system-bazel_configuration` for a tutorial that dives deeper 141into facade configuration with Bazel. 142