A modular toolkit for declaring C/C++ toolchains in Bazel

Unstable Starlark

  • Modular: Construct your own toolchain using shared building blocks, and share common flags between multiple platforms. You can even share toolchain components and definitions across the boundaries of different projects!

  • Declarative: Toolchain configurations are centralized to a single source-of-truth.

Assembling a complete, hermetic C/C++ toolchain using Bazel’s native primitives can be quite challenging. Additionally, the native API for declaring C/C++ toolchains doesn’t inherently encourage modularity or reusability, and lacks consistent documentation.

pw_toolchain_bazel provides a suite of building blocks that make the process of assembling a complete, hermetic toolchain significantly easier. The Bazel rules introduced by this module push the vast majority of a toolchain’s declaration into build files, and encourages reusability through sharing of flag groups, tools, and toolchain feature implementations.

Why create hermetic toolchains?

  • Eliminate “it compiles on my machine.” The same toolchain across every workstation means the same flags, the same warnings, and the same errors.

  • Produce the same binary every time. By keeping the toolchain and associated flags consistent and isolated across different environments, you can expect your final firmware images to be the same no matter where they’re compiled.

  • Correctly support incremental builds. When the system environment affects how tools behave, incremental builds can produce misconfigured or fundamentally broken binaries.

While this module does not provide a hermetic toolchain, Pigweed provides fully instantiated and supported toolchains that are a useful reference for building your own toolchain.


b/309533028: This module is under construction, and is missing a few significant features.

Get started

Set up a custom C/C++ toolchain project.

API reference

Detailed reference information about the pw_toolchain_bazel API.

Original SEED

SEED-0113: Add modular Bazel C/C++ toolchain API


This module is not permitted to have dependencies on other modules. When this module stabilizes, it will be broken out into a separate repository.