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