Initial rules_toolchain implementation (#9)

Author: matts1

.bazelrc

@@ -20,4 +20,9 @@ common --check_direct_dependencies=off
 try-import %workspace%/.bazelrc.user
 
 # Stardoc fails without this flag set.
-common --noincompatible_disallow_empty_glob
+common --noincompatible_disallow_empty_glob
+
+common --experimental_platforms_api
+
+build --host_platform=@rules_toolchains//tests/platforms:host_platform
+build --platforms=@rules_toolchains//tests/platforms:target_platform1

.bcr/presubmit.yml

@@ -1,5 +1,5 @@
 bcr_test_module:
-  module_path: "examples/rules_lang"
+  module_path: "."
   matrix:
     platform: ["debian10", "macos", "ubuntu2004", "windows"]
     bazel: ["8.x", "7.x"]

.github/workflows/ci.yaml

@@ -28,6 +28,7 @@ jobs:
       exclude: |
         [
           {"folder": ".", "bzlmodEnabled": false}
+          {"folder": "examples/rules_lang", "bzlmodEnabled": false}
         ]
   pre-commit:
     runs-on: ubuntu-latest

BUILD.bazel

@@ -1,5 +1,7 @@
 load("@bazel_gazelle//:def.bzl", "gazelle", "gazelle_binary")
 
+package(default_visibility = ["//visibility:public"])
+
 gazelle_binary(
     name = "gazelle_bin",
     languages = ["@bazel_skylib_gazelle_plugin//bzl"],
@@ -9,3 +11,7 @@ gazelle(
     name = "gazelle",
     gazelle = "gazelle_bin",
 )
+
+licenses(["notice"])
+
+exports_files(["LICENSE"])

MODULE.bazel

@@ -1,13 +1,19 @@
 module(
     name = "rules_toolchains",
-    version = "0.0.0",
     compatibility_level = 1,
 )
 
-bazel_dep(name = "bazel_skylib", version = "1.4.1")
-bazel_dep(name = "platforms", version = "0.0.5")
+bazel_dep(name = "bazel_skylib", version = "1.7.1")
+bazel_dep(name = "platforms", version = "0.0.10")
+bazel_dep(name = "rules_python", version = "1.3.0")
 
+bazel_dep(name = "rules_testing", version = "0.6.0", dev_dependency = True)
 bazel_dep(name = "gazelle", version = "0.35.0", dev_dependency = True, repo_name = "bazel_gazelle")
 bazel_dep(name = "bazel_skylib_gazelle_plugin", version = "1.4.1", dev_dependency = True)
-bazel_dep(name = "aspect_bazel_lib", version = "1.32.1", dev_dependency = True)
+bazel_dep(name = "aspect_bazel_lib", version = "2.10.0", dev_dependency = True)
 bazel_dep(name = "buildifier_prebuilt", version = "6.1.2", dev_dependency = True)
+
+register_toolchains(
+    "//tests/toolchain:all",
+    dev_dependency = True,
+)

MODULE.bazel.lock

@@ -1,33 +1,31 @@
-# Template for Bazel rules
+# Toolchain rules for bazel
 
-Copy this template to create a Bazel ruleset.
+This repository contains rules for configuring toolchains. It is designed to be integrated with rulesets to allow a ruleset to specify what they _want_ an action to do, and have the configuration decide how to achieve that. For example, a ruleset author would specify `run_action(action_type=compile, variables = struct(header_files = [foo.h], source_files = [foo.cc], output = [foo.o]), inputs=[foo.cc, foo.h], outputs = [foo.o])`, and the configuration would turn that into the command-line `clang++ foo.cc foo.h -o foo.o`.
 
-Features:
+# Getting Started
 
-- follows the official style guide at https://bazel.build/rules/deploying
-- allows for both WORKSPACE.bazel and bzlmod (MODULE.bazel) usage
-- includes Bazel formatting as a pre-commit hook (using [buildifier])
-- includes stardoc API documentation generator
-- includes typical toolchain setup
-- CI configured with GitHub Actions
-- release using GitHub Actions just by pushing a tag
-- the release artifact doesn't need to be built by Bazel, but can still exclude files and stamp the version
+Add the following to your `MODULE.bazel` file:
 
-# Bazel rules for toolchains
+```starlark
+bazel_dep(name = "rules_testing", version = "<version>")
+```
 
-## Installation
+## For ruleset authors
 
-From the release you wish to use:
-<https://github.com/matts1/rules_toolchains/releases>
-copy the WORKSPACE snippet into your `WORKSPACE` file.
+Look at `examples/rules_lang`. You will first need to configure your toolchain to take in a `ToolchainConfig` parameter.
 
-To use a commit rather than a release, you can point at any SHA of the repo.
+Once you've done that, you'll need to configure your rule to, instead of calling `ctx.actions.run`, call `run_action` (see [`examples/rules_lang/lang/defs.bzl`](examples/rules_lang/lang/defs.bzl)).
 
-For example to use commit `abc123`:
+## For toolchain authors
 
-1. Replace `url = "https://github.com/matts1/rules_toolchains/releases/download/v0.1.0/rules_toolchains-v0.1.0.tar.gz"` with a GitHub-provided source archive like `url = "https://github.com/matts1/rules_toolchains/archive/abc123.tar.gz"`
-1. Replace `strip_prefix = "rules_toolchains-0.1.0"` with `strip_prefix = "rules_toolchains-abc123"`
-1. Update the `sha256`. The easiest way to do this is to comment out the line, then Bazel will
-   print a message with the correct value. Note that GitHub source archives don't have a strong
-   guarantee on the sha256 stability, see
-   <https://github.blog/2023-02-21-update-on-the-future-stability-of-source-code-archives-and-hashes/>
+Either use the default toolchain configured by your ruleset author, or create a custom `toolchain_config` rule.
+
+# Testing
+
+`rules_toolchains` supports generating "input files". These files contain a full specification of generated actions, and can be used to validate that your toolchain configuration works as intended with golden tests. For an example of how this works, see `@rules_toolchain//tests`.
+
+# Contributing
+
+We appreciate your help!
+
+To contribute, please read the contribution guidelines: [CONTRIBUTING.md](https://github.com/matts1/rules_toolchains/blob/main/CONTRIBUTING.md).

README.md

@@ -0,0 +1,21 @@
+# Copyright 2025 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+load("@rules_python//python:defs.bzl", "py_binary")
+
+py_binary(
+    name = "generate_inputs_file",
+    srcs = ["generate_inputs_file.py"],
+    visibility = ["//visibility:public"],
+)

debug/BUILD.bazel

@@ -0,0 +1,70 @@
+"""Generates a file containing a specification of an action that was run.
+
+The file will contain information such as:
+* The features in use
+* The args in use
+* Which command-line entries are generated by which args
+* Environment variables
+* Input files
+"""
+
+import itertools
+import json
+import os
+import re
+import sys
+
+def format_dict(d):
+    return "\n".join(f"  {k}={repr(v)}" for k, v in sorted(d.items()))
+
+output_file = sys.argv[1]
+args = sys.argv[2:]
+arg_groups = []
+for arg in sys.argv[2:]:
+    if arg == "ARG_SPLITTER":
+        arg_groups.append([])
+    else:
+        arg_groups[-1].append(arg)
+
+arg_labels = [label for label in os.environ["ARGS"].split("\n") if label]
+
+assert len(arg_groups) >= len(arg_labels), (sys.argv, arg_groups, arg_labels)
+args_by_label = itertools.zip_longest(arg_labels, arg_groups, fillvalue="Extra action args:")
+
+
+action = os.environ["ACTION"]
+env = json.loads(os.environ["ENV"])
+features = os.environ["FEATURES"]
+outputs = os.environ["OUTPUTS"]
+progress_message = os.environ["PROGRESS_MESSAGE"]
+tool = os.environ["TOOL"]
+tool_exe = os.environ["TOOL_EXE"]
+execution_requirements = json.loads(os.environ["EXECUTION_REQUIREMENTS"])
+
+inputs = []
+for dirpath, _, filenames in os.walk("."):
+    for filename in filenames:
+        inputs.append(f"{dirpath[2:]}/{filename}")
+
+inputs = sorted([
+    path for path in inputs if "generate_inputs_file" not in path
+])
+
+content = [
+    f"Action: {action}",
+    f"Tool: {tool} ({tool_exe})",
+    f"Progress message: {repr(progress_message)}",
+    "\nInputs:\n{}".format("\n".join(inputs)),
+    f"\nOutputs:\n{outputs}\n",
+    f"Features:\n{features}\n",
+    f"Execution requirements:\n{format_dict(execution_requirements)}\n",
+    f"Env:\n{format_dict(env)}\n",
+    "Command-line:",
+]
+for arg, group in args_by_label:
+    content.append(arg)
+    for entry in group:
+        content.append(f"  {entry}")
+
+with open(output_file, 'w') as f:
+    f.write(re.sub("bazel-out/[^/]*", "bazel-out/<config>", "\n".join(content)))

debug/generate_inputs_file.py

@@ -3,8 +3,68 @@
 load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
 
 stardoc_with_diff_test(
-    name = "rules",
-    bzl_library_target = "//toolchains:defs",
+    name = "args",
+    bzl_library_target = "//toolchains:args",
+)
+
+stardoc_with_diff_test(
+    name = "args_list",
+    bzl_library_target = "//toolchains:args_list",
+)
+
+stardoc_with_diff_test(
+    name = "feature",
+    bzl_library_target = "//toolchains:feature",
+)
+
+stardoc_with_diff_test(
+    name = "feature_constraint",
+    bzl_library_target = "//toolchains:feature_set",
+)
+
+stardoc_with_diff_test(
+    name = "feature_set",
+    bzl_library_target = "//toolchains:feature_set",
+)
+
+stardoc_with_diff_test(
+    name = "generic_rule",
+    bzl_library_target = "//toolchains:generic_rule",
+)
+
+stardoc_with_diff_test(
+    name = "mutually_exclusive_category",
+    bzl_library_target = "//toolchains:mutually_exclusive_category",
+)
+
+stardoc_with_diff_test(
+    name = "tool",
+    bzl_library_target = "//toolchains:tool",
+)
+
+stardoc_with_diff_test(
+    name = "tool_capability",
+    bzl_library_target = "//toolchains:tool_capability",
+)
+
+stardoc_with_diff_test(
+    name = "tool_map",
+    bzl_library_target = "//toolchains:tool_map",
+)
+
+stardoc_with_diff_test(
+    name = "toolchain",
+    bzl_library_target = "//toolchains:toolchain",
+)
+
+stardoc_with_diff_test(
+    name = "toolchain_info",
+    bzl_library_target = "//toolchains:toolchain_info",
+)
+
+stardoc_with_diff_test(
+    name = "variables",
+    bzl_library_target = "//toolchains:variables",
 )
 
 update_docs(name = "update")