Meeting notes (https://github.com/orgs/eclipse-score/discussions/236#discussioncomment-14403465):

• this is C++ only
• keep in mind, that rust toolchain is using c++ linker
• platforms is probably not even needed
• usual reservations regarding "I want to use the system compiler, not the one dictated by bazel" --> please add that to description. Explaining that these toolchains are optional. And how exactly to use the system toolchain.
• currently modules, e.g. communication, hardcodes the toolchain. They effectively override integrator settings. This needs to be cleaned up.
• please add documentation how to use a specific toolchain without downloading the tools - as they are preinstalled in some setups

(Please correct whatever is wrong here)

I'm not sure if I need to publish this as document or not, so let's first have it as comment and then if needed I can move it to separate docs.

Understanding Bazel Toolchains

Introduction

Bazel’s toolchain mechanism is one of the areas where it differs most from other build systems such as Make, CMake, or Gradle.
Many developers initially find it unintuitive because it does not follow the “usual” way build systems pick up compilers or tools from the system environment.

This document explains:

• Why Bazel introduces toolchains
• How they differ from traditional build setups
• Their benefits and trade-offs
• When they are the optimal choice

1. Traditional Build Systems: How They Work

In most common build systems:

• Tools (compiler, linker, code generators, etc.) are assumed to exist in the developer’s environment.
• The build system simply invokes them via $PATH.
• Selecting a toolchain often means setting environment variables or configuration flags:
  • Example (CMake): -DCMAKE_CXX_COMPILER=/usr/bin/clang++
  • Example (Gradle): JAVA_HOME=/path/to/jdk

This approach is:

• Simple for small projects.
• Fast to set up when you only target one environment.
• But also fragile:
  • Builds may break across machines if tools differ.
  • CI/CD often requires carefully crafted Docker images or system setup scripts.
  • Cross-compilation can be painful and ad-hoc.

2. Bazel’s Approach with Toolchains

Instead of assuming tools from the environment, Bazel makes them first-class citizens in the build graph:

• Tools are modeled as toolchains.
• Each toolchain specifies:
  • Which platform(s) it can target.
  • Which constraints it satisfies (e.g., OS, CPU architecture).
• Bazel automatically resolves the correct toolchain during the build based on:
  • The requested target platform (& and other set constraints).
  • The available toolchain definitions.

This feels unusual compared to traditional systems, but it has clear advantages.

3. Benefits of Bazel Toolchains

Hermetic Builds

• The build does not depend on arbitrary tools in the system environment.
• Tool versions and configurations are explicitly defined.

Cross-Compilation Support

• Toolchains model which compilers can produce binaries for which platforms.
• Switching between local builds and cross-builds is handled declaratively.

Reproducibility

• A Bazel build behaves the same on a developer’s laptop, in CI, and with remote execution.
• Eliminates “works on my machine” problems.

Scalability Across Teams

• Large projects with multiple languages and platforms benefit from consistent tooling definitions.
• Toolchains can be reused and shared across repositories.

4. Trade-Offs

Using Bazel toolchains introduces some challenges:

• Steeper learning curve: Developers need to learn Bazel’s toolchain model.
• More upfront work: Every tool must be wrapped in a toolchain definition instead of being used directly from the system.
• Overhead for small projects: For simple, single-platform projects, toolchains may feel like unnecessary complexity.

5. When Are Toolchains Optimal?

• Best suited for:

  • Multi-platform builds (e.g., Linux, macOS, Windows, Android, iOS).
  • Projects using remote execution or hermetic CI/CD pipelines.
  • Large organizations where reproducibility and consistency are critical.

• May be overkill for:

  • Small, single-platform projects with a single build environment.
  • Experimental or short-lived projects where reproducibility is less important.

Conclusion

The statement “Bazel toolchains are not how build systems usually work” is true — but that is intentional.
Bazel prioritizes hermeticity, reproducibility, and scalability over simplicity.

For small projects, toolchains can feel heavy. But for large-scale, multi-platform, or long-lived codebases, Bazel’s toolchain mechanism provides a robust and future-proof foundation and that's the reason why we chose to use Bazel as main build system on S-CORE project.

And that comment as an introduction to your DR? But it currently lacks a section which explains how to use other solutions like devcontainers (build-containers).

And that comment as an introduction to your DR? But it currently lacks a section which explains how to use other solutions like devcontainers (build-containers).

This document is not about how to setup build without Bazel toolchains. We need to have separate document for that. I don't want to mix these 2 things because it will just bring more confusion. For system toolchains (TC installed on your host system which is also a target system) you don't care about this repository.

• How to proceed?
• Please change to an DR Needs item