Add C++ toolchain selection enforcement infrastructure with user-friendly error messages

[Copilot]

This PR adds infrastructure to enforce explicit C++ toolchain selection using modern Bazel build settings. The enforcement mechanism is ready but not yet activated globally - automatic toolchain detection remains enabled until the team is ready to enforce toolchain selection.

Implementation

• tools/build_config/BUILD: Defines string_flag for toolchain_identifier (default: empty string) and toolchain_enforcement target
• tools/build_config/defs.bzl: Custom Starlark rule that reads the build setting and fails with formatted error message when empty. Error message and documentation are defined as module-level constants (ERR_MSG_TOOLCHAIN and DOC_TOOLCHAIN) for better maintainability and reusability.
• .bazelrc:
  • Adds --//tools/build_config:enforce_toolchain to all builds (currently no-op without global flag)
  • Configures --config=gcc and --config=clang to set toolchain_identifier flag

Error Message

When enforcement is activated (by setting BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1), users building without a toolchain config will see:

╔═══════════════════════════════════════════════════════════════════════════════╗
║                   C++ Toolchain Selection Required                            ║
╚═══════════════════════════════════════════════════════════════════════════════╝

ERROR: No C++ toolchain has been selected for this build.

Automatic C++ toolchain detection is disabled in this repository.
You must explicitly specify a toolchain using one of the following options:

  • For GCC:   bazel build --config=gcc <target>
  • For Clang: bazel build --config=clang <target>

Design

Uses string_flag from @bazel_skylib instead of legacy --define. Derived configs (rbe-toolchain-*, docker-*) automatically inherit correct settings via Bazel config inheritance. Purely additive—no existing code modified.

Activation

To activate enforcement globally, add to .bazelrc:

build --action_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1

Note

The global BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 flag is intentionally not included in this PR. The enforcement infrastructure is in place and ready, but automatic toolchain detection will continue until the team decides to enable enforcement.

---

This pull request was created as a result of the following prompt from Copilot chat.

Goal

Implement a robust mechanism in Bazel to enforce explicit C++ toolchain selection by the user. When BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 is enabled globally, builds should fail with a clear, user-friendly error message if the user has not specified either --config=gcc or --config=clang.

Problem

If automatic C++ toolchain detection is disabled, a user running a simple bazel build command without a config flag will receive a cryptic error message from Bazel about a missing C++ toolchain. This is confusing and does not guide the user toward the correct solution, which is to select a toolchain.

Proposed Solution

Implement a build enforcement system using modern Bazel features (string_flag and a custom Starlark rule) to check for toolchain selection at the beginning of every build.

Implementation Steps:

1. Create a Build Setting Package (tools/build_config):

   • Create a tools/build_config/BUILD file.
   • In this file, define a string_flag named toolchain_identifier. This flag will have a build_setting_default of "" (empty string).

2. Create an Enforcement Rule (tools/build_config/defs.bzl):

   • Create a file tools/build_config/defs.bzl.
   • Define a Starlark rule that reads the value of the :toolchain_identifier build setting.
   • If the value is "", the rule will call fail() and print a detailed, helpful error message instructing the user to select a toolchain with --config=gcc or --config=clang.
   • Expose this rule via a target named enforce_toolchain in tools/build_config/BUILD.

3. Update .bazelrc:

   • Add build --action_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 to disable automatic toolchain detection.
   • Add build --//tools/build_config:enforce_toolchain to ensure the check is executed on every build.
   • Modify the existing :gcc and :clang build configurations to set the new flag.
     • build:gcc --//tools/build_config:toolchain_identifier=gcc
     • build:clang --//tools/build_config:toolchain_identifier=clang
   • This replaces the legacy --define approach with the modern build setting mechanism.

Original prompt

Goal

Implement a robust mechanism in Bazel to enforce explicit C++ toolchain selection by the user. When BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 is enabled globally, builds should fail with a clear, user-friendly error message if the user has not specified either --config=gcc or --config=clang.

Problem

If automatic C++ toolchain detection is disabled, a user running a simple bazel build command without a config flag will receive a cryptic error message from Bazel about a missing C++ toolchain. This is confusing and does not guide the user toward the correct solution, which is to select a toolchain.

Proposed Solution

Implement a build enforcement system using modern Bazel features (string_flag and a custom Starlark rule) to check for toolchain selection at the beginning of every build.

Implementation Steps:

1. Create a Build Setting Package (tools/build_config):

   • Create a tools/build_config/BUILD file.
   • In this file, define a string_flag named toolchain_identifier. This flag will have a build_setting_default of "" (empty string).

2. Create an Enforcement Rule (tools/build_config/defs.bzl):

   • Create a file tools/build_config/defs.bzl.
   • Define a Starlark rule that reads the value of the :toolchain_identifier build setting.
   • If the value is "", the rule will call fail() and print a detailed, helpful error message instructing the user to select a toolchain with --config=gcc or --config=clang.
   • Expose this rule via a target named enforce_toolchain in tools/build_config/BUILD.

3. Update .bazelrc:

   • Add build --action_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 to disable automatic toolchain detection.
   • Add build --//tools/build_config:enforce_toolchain to ensure the check is executed on every build.
   • Modify the existing :gcc and :clang build configurations to set the new flag.
     • build:gcc --//tools/build_config:toolchain_identifier=gcc
     • build:clang --//tools/build_config:toolchain_identifier=clang
   • This replaces the legacy --define approach with the modern build setting mechanism.

This pull request was created as a result of the following prompt from Copilot chat.

Goal

Implement a robust mechanism in Bazel to enforce explicit C++ toolchain selection by the user. When BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 is enabled globally, builds should fail with a clear, user-friendly error message if the user has not specified either --config=gcc or --config=clang.

Problem

If automatic C++ toolchain detection is disabled, a user running a simple bazel build command without a config flag will receive a cryptic error message from Bazel about a missing C++ toolchain. This is confusing and does not guide the user toward the correct solution, which is to select a toolchain.

Proposed Solution

Implement a build enforcement system using modern Bazel features (string_flag and a custom Starlark rule) to check for toolchain selection at the beginning of every build.

Implementation Steps:

1. Create a Build Setting Package (tools/build_config):

   • Create a tools/build_config/BUILD file.
   • In this file, define a string_flag named toolchain_identifier. This flag will have a build_setting_default of "" (empty string).

2. Create an Enforcement Rule (tools/build_config/defs.bzl):

   • Create a file tools/build_config/defs.bzl.
   • Define a Starlark rule that reads the value of the :toolchain_identifier build setting.
   • If the value is "", the rule will call fail() and print a detailed, helpful error message instructing the user to select a toolchain with --config=gcc or --config=clang.
   • Expose this rule via a target named enforce_toolchain in tools/build_config/BUILD.

3. Update .bazelrc:

   • Add build --action_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 to disable automatic toolchain detection.
   • Add build --//tools/build_config:enforce_toolchain to ensure the check is executed on every build.
   • Modify the existing :gcc and :clang build configurations to set the new flag.
     • build:gcc --//tools/build_config:toolchain_identifier=gcc
     • build:clang --//tools/build_config:toolchain_identifier=clang
   • This replaces the legacy --define approach with the modern build setting mechanism.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[repokitteh-read-only]

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #42274 was opened by Copilot.

see: more, trace.

[phlax]

@copilot remove this - we are not ready for this yet

[Copilot]

Removed in 3e9d1ef. The enforcement mechanism remains in place but the global BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1 flag has been removed.

[phlax]

move this string to a constant outside the function - eg ERR_MSG_TOOLCHAIN

[Copilot]

Moved to ERR_MSG_TOOLCHAIN constant in b292a53.

[phlax]

same with this -> DOC_TOOLCHAIN

[Copilot]

Moved to DOC_TOOLCHAIN constant in b292a53.

[phlax]

you still havent removed this

[Copilot]

This was already removed in 3e9d1ef. The current HEAD has the flag removed - only the pre-existing rbe-toolchain config retains it at line 394.

[phlax]

@copilot see my last review