add arbitray settings support for local toolchains

Author: rickeylev

docs/toolchains.md

@@ -377,15 +377,14 @@ local_runtime_repo(
 local_runtime_toolchains_repo(
     name = "local_toolchains",
     runtimes = ["local_python3"],
+    # TIP: The `target_settings` arg can be used to activate them based on
+    # command line flags; see docs below.
 )
 
 # Step 3: Register the toolchains
 register_toolchains("@local_toolchains//:all", dev_dependency = True)
 ```
 
-Note that `register_toolchains` will insert the local toolchain earlier in the
-toolchain ordering, so it will take precedence over other registered toolchains.
-
 :::{important}
 Be sure to set `dev_dependency = True`. Using a local toolchain only makes sense
 for the root module.
@@ -397,6 +396,49 @@ downstream modules.
 
 Multiple runtimes and/or toolchains can be defined, which allows for multiple
 Python versions and/or platforms to be configured in a single `MODULE.bazel`.
+Note that `register_toolchains` will insert the local toolchain earlier in the
+toolchain ordering, so it will take precedence over other registered toolchains.
+
+This behavior can be mitigated by specifying the
+{obj}`local_runtime_toolchains_repo.target_settings` arg. This allows attaching
+arbitrary {obj}`config_setting()` conditions for activating the toolchain.
+
+```
+# File: MODULE.bazel
+bazel_dep(name = "bazel_skylib", version = "1.7.1")
+
+local_runtime_toolchains_repo(
+    name = "local_toolchains",
+    runtimes = ["local_python3"],
+    target_settings = {
+        "local_python3": ["@//:is_py_local_set"]
+    }
+)
+
+# Step 2: Create toolchains for the runtimes
+local_runtime_toolchains_repo(
+    name = "local_toolchains",
+    runtimes = ["local_python3"],
+    # TIP: The `target_settings` arg can be used to activate them based on
+    # command line flags; see docs below.
+)
+
+# File: BUILD.bazel
+load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
+
+config_setting(
+    name = "is_py_local_set",
+    flag_values = {":py": "local"},
+)
+
+string_flag(
+    name = "py",
+    build_setting_default = "",
+)
+
+```
+
+
 
 ## Runtime environment toolchain
 

python/private/local_runtime_toolchains_repo.bzl

@@ -26,6 +26,7 @@ define_local_toolchain_suites(
     name = "toolchains",
     version_aware_repo_names = {version_aware_names},
     version_unaware_repo_names = {version_unaware_names},
+    repo_target_settings = {target_settings},
 )
 """
 
@@ -39,6 +40,10 @@ def _local_runtime_toolchains_repo(rctx):
 
     rctx.file("BUILD.bazel", _TOOLCHAIN_TEMPLATE.format(
         version_aware_names = render.list(rctx.attr.runtimes),
+        target_settings = render.dict(
+            rctx.attr.target_settings,
+            value_repr = render.list,
+        ),
         version_unaware_names = render.list(rctx.attr.default_runtimes or rctx.attr.runtimes),
     ))
 
@@ -78,7 +83,29 @@ Note that order matters: it determines the toolchain priority within the
 package.
 """,
         ),
-        "runtime_target_settings": attr.string_list_dict(
+        "target_settings": attr.string_list_dict(
+            doc = """
+Constraints that must be satisfied for a toolchain to be used.
+
+This is a dict where:
+ * **key**: A repo name; one of the names from the `runtimes` or
+   `default_runtimes` args.
+ * **value**: list of labels. The labels are typically {obj}`config_setting()`
+   targets.
+   :::{note}
+   Specify `@//foo:bar`, not simply `//foo:bar` or `:bar`. The additional `@` is
+   needed because the strings are evaluated in a different context than where
+   they originate.
+   :::
+
+The list of settings are added to the {obj}`toolchain.target_settings` value
+for each respective repo.
+
+This allows a local toolchain to only be used if certain flags or
+config setting conditions are met. Such conditions can include user-defined
+flags, platform constraints, etc.
+
+""",
         ),
         "_rule_name": attr.string(default = "local_toolchains_repo"),
     },

python/private/py_toolchain_suite.bzl

@@ -142,7 +142,11 @@ def _internal_toolchain_suite(prefix, runtime_repo_name, target_compatible_with,
     # call in python/repositories.bzl. Bzlmod doesn't need anything; it will
     # register `:all`.
 
-def define_local_toolchain_suites(name, version_aware_repo_names, version_unaware_repo_names):
+def define_local_toolchain_suites(
+        name,
+        version_aware_repo_names,
+        repo_target_settings,
+        version_unaware_repo_names):
     """Define toolchains for `local_runtime_repo` backed toolchains.
 
     This generates `toolchain` targets that can be registered using `:all`. The
@@ -160,11 +164,13 @@ def define_local_toolchain_suites(name, version_aware_repo_names, version_unawar
     i = 0
     for i, repo in enumerate(version_aware_repo_names, start = i):
         prefix = render.left_pad_zero(i, 4)
+        target_settings = ["@{}//:is_matching_python_version".format(repo)]
+        target_settings.extend(repo_target_settings.get(repo, []))
         _internal_toolchain_suite(
             prefix = prefix,
             runtime_repo_name = repo,
+            target_settings = target_settings,
             target_compatible_with = ["@{}//:os".format(repo)],
-            target_settings = ["@{}//:is_matching_python_version".format(repo)],
         )
 
     # The version unaware entries must go last because they will match any Python
@@ -174,6 +180,6 @@ def define_local_toolchain_suites(name, version_aware_repo_names, version_unawar
         _internal_toolchain_suite(
             prefix = prefix,
             runtime_repo_name = repo,
-            target_settings = [],
+            target_settings = repo_target_settings.get(repo, []),
             target_compatible_with = ["@{}//:os".format(repo)],
         )

tests/integration/local_toolchains/BUILD.bazel

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+load("@bazel_skylib//rules:common_settings.bzl", "string_flag")
 load("@rules_python//python:py_test.bzl", "py_test")
 
 py_test(
@@ -20,3 +21,16 @@ py_test(
     # Make this test better respect pyenv
     env_inherit = ["PYENV_VERSION"],
 )
+
+config_setting(
+    name = "is_py_local_set",
+    flag_values = {
+        ":py": "local",
+    },
+)
+
+# set to "local" to use the local toolchain
+string_flag(
+    name = "py",
+    build_setting_default = "",
+)

tests/integration/local_toolchains/MODULE.bazel

@@ -14,6 +14,8 @@
 module(name = "module_under_test")
 
 bazel_dep(name = "rules_python", version = "0.0.0")
+bazel_dep(name = "bazel_skylib", version = "1.7.1")
+
 local_path_override(
     module_name = "rules_python",
     path = "../../..",
@@ -32,6 +34,11 @@ local_runtime_repo(
 local_runtime_toolchains_repo(
     name = "local_toolchains",
     runtimes = ["local_python3"],
+    target_settings = {
+        "local_python3": [
+            "@//:is_py_local_set",
+        ],
+    },
 )
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")