1.. _seed-0111: 2 3=============================================== 40111: Make Bazel Pigweed's Primary Build System 5=============================================== 6.. seed:: 7 :number: 111 8 :name: Make Bazel Pigweed's Primary Build System 9 :status: Accepted 10 :proposal_date: 2023-09-26 11 :cl: 171695 12 :authors: Ted Pudlik 13 :facilitator: Armando Montanez 14 15------- 16Summary 17------- 18This SEED proposes that Pigweed transition to using `Bazel 19<https://bazel.build/>`_ as its primary build system, replacing `GN 20<https://gn.googlesource.com/gn/>`_ in that role. 21 22Pigweed is and will continue to be a multi-build-system project. As modular 23middleware, Pigweed aspires to be easy to integrate with existing embedded 24projects whatever their build system. To facilitate this, we provide BUILD 25files for multiple systems (Bazel, CMake, GN, Soong), as well as other 26distributables where applicable (npm packages, Python wheels, etc). 27 28But Pigweed is more than just a collection of modules. Pigweed offers a quick, 29ergonomic way to start a new embedded project, as well as developer tooling 30that lets it scale from a prototype to production deployment. And if you're 31starting a new project using Pigweed from day one, you will ask: which build 32system *should* I use? This is what we mean by Pigweed's *primary* build 33system. 34 35Pigweed's primary build system has been GN, but soon will be Bazel. 36 37---------- 38Motivation 39---------- 40GN has been Pigweed's primary build system since inception, and we've developed 41an extensive GN build that was used to successfully ship products at scale. GN 42is fast and extensible, and its flexible toolchain abstraction is well-suited 43to the multi-target builds that arise in most embedded projects. 44 45But GN has limitations: 46 47#. **Small community.** GN is a niche build system: the only major open-source 48 projects that use it are Chromium and Fuchsia. It is not championed by any 49 major nonprofit or corporation. Few users or open-source contributors come 50 to Pigweed with any past experience with GN. 51#. **No reusable rulesets.** Pigweed has written and maintains all its GN 52 rules: for C/C++, for Python, for Go (though those are deprecated). With 53 Rust entering Pigweed, we are now developing GN rules for Rust. There are 54 no built-in or community-provided rules we could adopt instead. Developing 55 all rules in-house gives us flexibility, but requires large up-front and 56 ongoing investments. 57#. **No hermetic builds.** GN offers no sandboxing and relies on timestamps to 58 decide if outputs need to be rebuilt. This has undesirable consequences: 59 60 * The boundary between the environment produced by 61 :ref:`module-pw_env_setup` and GN is blurred, making GN-built Pigweed as 62 a whole hostile to systems like Docker or remote execution services. 63 * Incremental builds can become corrupted. Deleting the output directory 64 and environment is an undesirable but necessary piece of every Pigweed 65 developer's toolkit. 66 * Reliably running only affected tests in CQ is not possible. 67 68We would like Pigweed to recommend a build system that does not suffer from these 69limitations. 70 71These limitations are not new. What's changed is the build system landscape. 72When Pigweed was started years ago, GN was the best choice for a project 73emphasizing multi-target builds. But the alternatives have now matured. 74 75-------- 76Proposal 77-------- 78The proposal is to make Bazel the recommended build system to use with Pigweed, 79and the best overall build system for embedded developers. This will involve a 80combination of contributions to Pigweed itself, to existing open-source Bazel 81rules we wish to reuse, and when necessary to core Bazel. 82 83The vision is not merely to achieve feature parity with Pigweed's GN offering 84while addressing the limitations identified above, but to fully utilize the 85capabilities provided by Bazel to produce the best possible developer 86experience. For example, Bazel offers native support for external dependency 87management and remote build execution. We will make it easy for Pigweed 88projects to leverage features like these. 89 90* **What about GN?** Pigweed's GN support will continue, focusing on 91 maintenance rather than new build features. No earlier than 2026, if no 92 Pigweed projects are using GN, we may remove GN support. *The approval of 93 this SEED does not imply approval of removing GN support.* This decision is 94 explicitly deferred until a future date. 95 96* **What about CMake?** Because of its wide adoption in the C++ community, 97 CMake will be supported indefinitely at the current level. 98 99------- 100Roadmap 101------- 102This section lists the high-level milestones for Pigweed's Bazel support, and 103then dives into the specific work needed to reach them. 104 105This roadmap is our plan of record as of the time of writing, but like all SEED 106content it represents a snapshot in time. We are not as committed to the 107specific dates as we are to the general direction. 108 109There's no specific action that users must take by any date. But our 110recommendations about build system choice (embodied in docs and in what we tell 111people when they ask us) will change at some point. 112 113Milestones 114========== 115* **M0: Good for Most.** We can recommend Bazel as the build system for most 116 new projects. We may not have full parity with GN yet, but we're close enough 117 that the benefits of adopting Bazel exceed the costs, even in the short run. 118 The target date for this milestone is the end of 2023. 119 120 * Out of scope for M0: Windows support. We have to start somewhere, and we're 121 starting with Linux and MacOS. 122 123* **M1: Good for All.** We can recommend Bazel for all new Pigweed projects, 124 including ones that need Windows support. The target date is end of Q1 125 2024. After this date, we don't expect any new projects to use GN. 126 127* **M2: Best.** We develop compelling features for embedded within the 128 Bazel ecosystem. This will happen throughout 2024. 129 130Technical tracks 131================ 132There are three main technical tracks: 133 134* **Configurable toolchains** exist for host and embedded, for C++ and Rust. 135 A separate upcoming SEED will cover this area in detail, but the high-level 136 goal is to make it straightforward to create families of related toolchains 137 for embedded targets. This is required for milestone M0, except for Windows 138 support, which is part of M1. The overall tracking issue is `b/300458513 139 <https://issues.pigweed.dev/issues/300458513>`_. 140 141* **Core build patterns** (facades, multi-platform build, third-party crate 142 deps for Rust) are established, documented, and usable. 143 144 * M0: 145 146 * Module configuration is supported in Bazel, `b/234872811 147 <https://issues.pigweed.dev/issues/234872811>`_. 148 * Bazel proto codegen is feature-complete, `b/301328390 149 <https://issues.pigweed.dev/issues/301328390>`_. 150 * Multiplatform build is ergonomic thanks to the adoption of 151 `platform_data 152 <https://github.com/bazelbuild/proposals/blob/main/designs/2023-06-08-standard-platform-transitions.md#depend-on-a-target-built-for-a-different-platform>`_ 153 and `platform-based flags 154 <https://github.com/bazelbuild/proposals/blob/main/designs/2023-06-08-platform-based-flags.md>`_, `b/301334234 155 <https://issues.pigweed.dev/issues/301334234>`_. 156 * Clang sanitizers (asan, msan, tsan) are easy to enable in the Bazel build, `b/301487567 157 <https://issues.pigweed.dev/issues/301487567>`_. 158 159 * M1: 160 161 * On-device testing pattern for Bazel projects developed and documented, `b/301332139 162 <https://issues.pigweed.dev/issues/301332139>`_. 163 * Sphinx documentation can be built with Bazel. 164 * OSS Fuzz integration through Bazel. 165 166* **Bootstrap** for Bazel projects is excellent. This includes offering 167 interfaces to Pigweed developer tooling like :ref:`module-pw_console`, 168 :ref:`module-pw_cli`, etc. 169 170 * M0: GN-free bootstrap for Bazel-based projects is designed and prototyped, `b/274658181 171 <https://issues.pigweed.dev/issues/274658181>`_. 172 173 * M1: Pigweed is straightforward to manage as a Bazel dependency, `b/301336229 174 <https://issues.pigweed.dev/issues/301336229>`_. 175 176* **Onboarding** for users new to Pigweed-on-Bazel is easy thanks to 177 excellent documentation, including examples. 178 179 * M0: 180 181 * There is a Bazel example project for Pigweed, `b/299994234 182 <https://issues.pigweed.dev/issues/299994234>`_. 183 * We have a "build system support matrix" that compares the features 184 available in the three main build systems (Bazel, CMake, GN), 185 `b/301481759 <https://issues.pigweed.dev/issues/301481759>`_. 186 187 * M1: 188 189 * The sample project has Bazel support, `b/302150820 190 <https://issues.pigweed.dev/issues/302150820>`_. 191 192------------ 193Alternatives 194------------ 195The main alternatives to investing in Bazel are championing GN or switching to 196a different build system. 197 198Champion GN 199=========== 200Pigweed does not have the resources to bring GN to parity with modern build 201systems like Bazel, Buck2, or Meson. This is an area where we should partner 202with another large project rather than build capabilities ourselves. 203 204CMake 205===== 206CMake is `the most popular build system for C++ projects 207<https://www.jetbrains.com/lp/devecosystem-2021/cpp/#Which-project-models-or-build-systems-do-you-regularly-use>`_, 208by a significant margin. We already offer some CMake support in Pigweed. But 209it's not a viable candidate for Pigweed's primary build system: 210 211* **No multi-toolchain builds** Unlike Bazel and GN, CMake does not support 212 multi-toolchain builds. 213* **No Python or Rust support** Again unlike Bazel and GN, CMake is primarily 214 focused on building C++ code. But Pigweed is a multilingual project, and 215 Python and Rust need first-class treatment. 216* **No hermetic builds** Unlike Bazel, CMake does not support sandboxing. 217 218Many developers are attracted to CMake by its IDE support. Fortunately, `IDE 219support for Bazel is also well-developed <https://bazel.build/install/ide>`_. 220 221Other build systems 222=================== 223There are other multi-lingual, correctness-emphasizing build systems out there, 224most prominently `Meson <https://mesonbuild.com/>`_ and `Buck2 225<https://buck2.build/>`_. We did not consider them realistic targets for 226migration at this time. They offer similar features to Bazel, and we have an 227existing Bazel build that's in use by some projects, as well as a closer 228relationship with the Bazel community. 229 230-------------- 231Open questions 232-------------- 233Additional SEEDs related to Bazel support are anticipated but have not yet been 234written. They will be linked from here once they exist. 235 236* `SEED-0113 237 <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/173453>`_: 238 Modular Bazel C/C++ toolchain API 239* SEED-????: Pigweed CI/CQ for Bazel 240 241---------------------------- 242Appendix: Why Bazel is great 243---------------------------- 244This SEED has not focused on why Bazel is a great build system. This is because 245we are not choosing Bazel over other major build systems, like Meson or Buck2, 246for its specific features. We are motivated to recommend a new build system 247because of GN's limitations, and we choose Bazel because we have a pre-existing 248community of Bazel users, developers with Bazel experience, and a close 249relationship with the Bazel core team. 250 251But actually, Bazel *is* great! Here are some things we like best about it: 252 253* **Correct incremental builds.** It's great to be able to trust the build 254 system to just do the right thing, including on a rebuild. 255* **External dependency management.** Bazel can manage external dependencies 256 for you, including lazily downloading them only when needed. By leveraging 257 this, we expect to speed up Pigweed bootstrap from several minutes to 258 several seconds. 259* **Remote build execution** Bazel has excellent native support for `executing 260 build actions in a distributed manner on workers in the cloud 261 <https://bazel.build/remote/rbe>`_. Although embedded builds are typically 262 small, build latency and infra test latency is a recurring concern among 263 Pigweed users, and leveraging remote builds should allow us to dramatically 264 improve performance in this area. 265* **Python environment management.** The Python rules for Bazel take care of 266 standing up a Python interpreter with a project-specific virtual 267 environment, a functionality we had to develop in-house for our GN build. 268* **Multilingual support.** Bazel comes with official or widely adopted 269 third-party rules for C++, Python, Java, Go, Rust, and other langauges. 270* **Active community.** The Bazel Slack is always helpful, and GitHub issues 271 tend to receive swift attention. 272