1.. _module-pw_toolchain_bazel: 2 3================== 4pw_toolchain_bazel 5================== 6.. pigweed-module:: 7 :name: pw_toolchain_bazel 8 9 - **Modular**: Construct your own toolchain using shared building blocks, and 10 share common flags between multiple platforms. You can even share toolchain 11 components and definitions across the boundaries of different projects! 12 - **Declarative**: Toolchain configurations are centralized to a single 13 source-of-truth. 14 15Assembling a complete, hermetic C/C++ toolchain using Bazel's native primitives 16can be quite challenging. Additionally, the native API for declaring C/C++ 17toolchains doesn't inherently encourage modularity or reusability, and lacks 18consistent documentation. 19 20``pw_toolchain_bazel`` provides a suite of building blocks that make the process 21of assembling a complete, hermetic toolchain significantly easier. The Bazel 22rules introduced by this module push the vast majority of a toolchain's 23declaration into build files, and encourages reusability through sharing of 24flag groups, tools, and toolchain feature implementations. 25 26Why create `hermetic toolchains <https://bazel.build/basics/hermeticity>`_? 27 28- **Eliminate "it compiles on my machine."** The same toolchain across every 29 workstation means the same flags, the same warnings, and the same errors. 30- **Produce the same binary every time.** By keeping the toolchain and 31 associated flags consistent and isolated across different environments, you 32 can expect your final firmware images to be the same no matter where they're 33 compiled. 34- **Correctly support incremental builds.** When the system environment affects 35 how tools behave, incremental builds can produce misconfigured or 36 fundamentally broken binaries. 37 38While this module does **not** provide a hermetic toolchain, Pigweed provides 39`fully instantiated and supported toolchains <https://cs.opensource.google/pigweed/pigweed/+/main:pw_toolchain/host_clang/BUILD.bazel>`_ 40that are a useful reference for building your own toolchain. 41 42.. warning:: 43 `b/309533028 <https://issues.pigweed.dev/309533028>`_\: This module is under 44 construction, and is missing a few significant features. 45 46.. grid:: 1 47 48 .. grid-item-card:: :octicon:`rocket` Get started 49 :link: module-pw_toolchain_bazel-get-started 50 :link-type: ref 51 :class-item: sales-pitch-cta-primary 52 53 Set up a custom C/C++ toolchain project. 54 55.. grid:: 2 56 57 .. grid-item-card:: :octicon:`info` API reference 58 :link: module-pw_toolchain_bazel-api 59 :link-type: ref 60 :class-item: sales-pitch-cta-secondary 61 62 Detailed reference information about the pw_toolchain_bazel API. 63 64 .. grid-item-card:: :octicon:`file` Original SEED 65 :link: seed-0113 66 :link-type: ref 67 :class-item: sales-pitch-cta-secondary 68 69 SEED-0113: Add modular Bazel C/C++ toolchain API 70 71------------ 72Dependencies 73------------ 74This module is not permitted to have dependencies on other modules. When this 75module stabilizes, it will be broken out into a separate repository. 76 77.. toctree:: 78 :hidden: 79 :maxdepth: 1 80 81 API reference <api> 82 Get Started <get_started> 83