From 3dc8600e30a3031e189d0d7ca0a9abb78a85eddf Mon Sep 17 00:00:00 2001 From: Greg Estren Date: Thu, 20 Nov 2025 21:59:35 +0000 Subject: [PATCH] Update test exec platform documentation. Default behavior changed at https://github.com/bazelbuild/bazel/commit/0dd0da99799b17116a2b33fc9bd62635d596d81c. Also space out some paragraphs more to de-densify content. --- site/en/reference/test-encyclopedia.md | 40 +++++++++++++++----------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/site/en/reference/test-encyclopedia.md b/site/en/reference/test-encyclopedia.md index ea8ca87754db9c..71e4443ea856f4 100644 --- a/site/en/reference/test-encyclopedia.md +++ b/site/en/reference/test-encyclopedia.md @@ -706,26 +706,34 @@ via [toolchain resolution](/extending/toolchains#toolchain-resolution), just like for any other action. Each test rule has an implicitly defined [ `test` exec group](/extending/exec-groups#exec-groups-for-native-rules) that, unless overridden, has a mandatory toolchain requirement on -`@bazel_tools//tools/test:default_test_toolchain_type`. Toolchains of this type -do not carry any data in the form of providers, but can be used to influence the -execution platform of the test action. By default, Bazel registers two such -toolchains: +`@bazel_tools//tools/test:default_test_toolchain_type`. + +Toolchains of this type do not carry any data in the form of providers, but can +be used to influence the execution platform of the test action. + +Bazel registers two such toolchains, which take effect if users don't explicitly +define their own:: * If `--@bazel_tools//tools/test:incompatible_use_default_test_toolchain` is - disabled (the current default), the active test toolchain is - `@bazel_tools//tools/test:legacy_test_toolchain`. This toolchain does not - impose any constraints and thus test actions without manually specified exec - constraints are configured for the first registered execution platform. This - is often not the intended behavior in multi-platform builds as it can result - in e.g. a test binary built for Linux on a Windows machine to be executed on - Windows. -* If `--@bazel_tools//tools/test:incompatible_use_default_test_toolchain` is - enabled, the active test toolchain is + enabled (**default**), the active test toolchain is `@bazel_tools//tools/test:default_test_toolchain`. This toolchain requires an - execution platform to match all the constraints of the test rule's target - platform. In particular, the target platform is compatible with this toolchain + execution platform to match all of the test rule's target platform constraints. + + In particular, the target platform is compatible with this toolchain if it is also registered as an execution platform. If no such platform is - found, the test rule fails with a toolchain resolution error. + found, the test rule fails with a toolchain resolution error +* If `--@bazel_tools//tools/test:incompatible_use_default_test_toolchain` is + disabled, the active test toolchain is + `@bazel_tools//tools/test:legacy_test_toolchain`. This toolchain does not + impose any constraints and thus test actions without manually specified exec + constraints are configured for the first registered execution platform. + + This is often not the intended behavior in multi-platform builds as it can + result in e.g. a test binary built for Linux on a Windows machine to be + executed on Windows. + + As a legacy setting, expect this option to be unavailable in a future Bazel + release. Users can register additional toolchains for this type to influence this behavior and their toolchains will take precedence over the default ones.