Allow passing env to cc_tool

cc/toolchains/cc_toolchain_info.bzl

@@ -198,6 +198,7 @@ ToolInfo = provider(
         "exe": "(File) The file corresponding to the tool",
         "runfiles": "(runfiles) The files required to run the tool",
         "execution_requirements": "(Sequence[str]) A set of execution requirements of the tool",
+        "env": "(dict[str, str]) Environment variables applied when using this tool",
         "allowlist_include_directories": "(depset[DirectoryInfo]) Built-in include directories implied by this tool that should be allowlisted in Bazel's include checker",
         "capabilities": "(Sequence[ToolCapabilityInfo]) Capabilities supported by the tool.",
     },

cc/toolchains/impl/collect.bzl

@@ -106,6 +106,7 @@ def collect_tools(ctx, targets, fail = fail):
                 exe = info.files_to_run.executable,
                 runfiles = collect_data(ctx, [target]),
                 execution_requirements = tuple(),
+                env = {},
                 allowlist_include_directories = depset(),
                 capabilities = tuple(),
             ))

cc/toolchains/impl/legacy_converter.bzl

@@ -102,6 +102,18 @@ def _convert_args_sequence(args_sequence, strip_actions = False):
 
     return struct(flag_sets = flag_sets, env_sets = env_sets)
 
+def _convert_tool_env(tool, action_name):
+    if not tool.env:
+        return None
+
+    return legacy_env_set(
+        actions = [action_name],
+        env_entries = [
+            legacy_env_entry(key = key, value = value)
+            for key, value in sorted(tool.env.items())
+        ],
+    )
+
 def convert_feature(feature, enabled = False):
     if feature.external:
         return None
@@ -188,6 +200,13 @@ def convert_toolchain(toolchain):
         args.flag_sets.extend(new_args.flag_sets)
         args.env_sets.extend(new_args.env_sets)
 
+    toolchain_args = _convert_args_sequence(toolchain.args.args)
+    tool_env_sets = []
+    for action_type in sorted(toolchain.tool_map.configs.keys(), key = lambda action: action.name):
+        env_set = _convert_tool_env(toolchain.tool_map.configs[action_type], action_type.name)
+        if env_set:
+            tool_env_sets.append(env_set)
+
     action_configs, cap_features = _convert_tool_map(toolchain.tool_map, args_by_action)
     features = [
         convert_feature(feature, enabled = feature in toolchain.enabled_features)
@@ -200,7 +219,7 @@ def convert_toolchain(toolchain):
         # conflict with the name of a feature the user creates.
         name = "implied_by_always_enabled_env_sets",
         enabled = True,
-        env_sets = _convert_args_sequence(toolchain.args.args).env_sets,
+        env_sets = tool_env_sets + toolchain_args.env_sets,
     ))
 
     cxx_builtin_include_directories = [

cc/toolchains/tool.bzl

@@ -15,6 +15,7 @@
 
 load("@bazel_skylib//rules/directory:providers.bzl", "DirectoryInfo")
 load("//cc/toolchains/impl:collect.bzl", "collect_data", "collect_provider")
+load("//cc/toolchains/impl:nested_args.bzl", "format_dict_values")
 load(
     ":cc_toolchain_info.bzl",
     "ToolCapabilityInfo",
@@ -30,12 +31,20 @@ def _cc_tool_impl(ctx):
     else:
         fail("Expected cc_tool's src attribute to be either an executable or a single file")
 
+    format_targets = {k: v for v, k in ctx.attr.format.items()}
+    env, _ = format_dict_values(
+        env = ctx.attr.env,
+        format = format_targets,
+        must_use = format_targets.keys(),
+    )
+
     runfiles = collect_data(ctx, ctx.attr.data + [ctx.attr.src])
     tool = ToolInfo(
         label = ctx.label,
         exe = exe,
         runfiles = runfiles,
         execution_requirements = tuple(ctx.attr.tags),
+        env = env,
         allowlist_include_directories = depset(
             direct = [d[DirectoryInfo] for d in ctx.attr.allowlist_include_directories],
         ),
@@ -59,7 +68,7 @@ def _cc_tool_impl(ctx):
         ),
     ]
 
-cc_tool = rule(
+_cc_tool = rule(
     implementation = _cc_tool_impl,
     # @unsorted-dict-items
     attrs = {
@@ -98,6 +107,20 @@ add them to 'data' as well.
 This can help work around errors like:
 `the source file 'main.c' includes the following non-builtin files with absolute paths
 (if these are builtin files, make sure these paths are in your toolchain)`.
+""",
+        ),
+        "env": attr.string_dict(
+            doc = """Environment variables to apply when running this tool.
+
+Format expansion is performed on values using the format attribute.
+""",
+        ),
+        "format": attr.label_keyed_string_dict(
+            allow_files = True,
+            doc = """Variables to be used in substitutions for env values.
+
+The keys are targets and the values are format strings. Use the cc_tool macro
+to provide the inverted mapping from format string to target.
 """,
         ),
         "capabilities": attr.label_list(
@@ -136,3 +159,86 @@ cc_tool(
 """,
     executable = True,
 )
+
+def cc_tool(
+        *,
+        name,
+        src = None,
+        data = None,
+        allowlist_include_directories = None,
+        env = None,
+        format = {},
+        capabilities = None,
+        **kwargs):
+    """Declares a tool for use by toolchain actions.
+
+    `cc_tool` rules are used in a `cc_tool_map` rule to ensure all files and
+    metadata required to run a tool are available when constructing a `cc_toolchain`.
+
+    In general, include all files that are always required to run a tool (e.g. libexec/** and
+    cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
+    required when certain flags are passed to the tool, consider using a `cc_args` rule to
+    bind the files to the flags that require them. This reduces the overhead required to properly
+    enumerate a sandbox with all the files required to run a tool, and ensures that there isn't
+    unintentional leakage across configurations and actions.
+
+    Example:
+    ```
+    load("//cc/toolchains:tool.bzl", "cc_tool")
+
+    cc_tool(
+        name = "clang",
+        src = "@llvm_toolchain//:bin/clang",
+        # Suppose clang needs libc to run.
+        data = ["@llvm_toolchain//:lib/x86_64-linux-gnu/libc.so.6"]
+        capabilities = ["//cc/toolchains/capabilities:supports_pic"],
+    )
+    ```
+
+    Args:
+        name: (str) The name of the target.
+        src: (Label) The underlying binary that this tool represents.
+            Usually just a single prebuilt (e.g. @toolchain//:bin/clang), but may be any
+            executable label.
+        data: (List[Label]) Additional files that are required for this tool to run.
+            Frequently, clang and gcc require additional files to execute as they often shell out to
+            other binaries (e.g. `cc1`).
+        allowlist_include_directories: (List[Label]) Include paths implied by using this tool.
+            Compilers may include a set of built-in headers that are implicitly available
+            unless flags like `-nostdinc` are provided. Bazel checks that all included
+            headers are properly provided by a dependency or allowlisted through this
+            mechanism.
+
+            As a rule of thumb, only use this if Bazel is complaining about absolute paths in your
+            toolchain and you've ensured that the toolchain is compiling with the
+            `-no-canonical-prefixes` and/or `-fno-canonical-system-headers` arguments.
+
+            These files are not automatically passed to each action. If they need to be,
+            add them to 'data' as well.
+
+            This can help work around errors like:
+            `the source file 'main.c' includes the following non-builtin files with absolute paths
+            (if these are builtin files, make sure these paths are in your toolchain)`.
+        env: (Dict[str, str]) Environment variables to apply when running this tool.
+            Format expansion is performed on values using `format`.
+        format: (Dict[str, Label]) A mapping of format strings to the label of a corresponding
+            target. This target can be a `directory`, `subdirectory`, or a single file that the
+            value should be pulled from. All instances of `{variable_name}` in the `env` dictionary
+            values will be replaced with the expanded value in this dictionary.
+        capabilities: (List[Label]) Declares that a tool is capable of doing something.
+            For example, `@rules_cc//cc/toolchains/capabilities:supports_pic`.
+        **kwargs: [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes)
+            that should be applied to this rule.
+    """
+    return _cc_tool(
+        name = name,
+        src = src,
+        data = data,
+        allowlist_include_directories = allowlist_include_directories,
+        env = env,
+        # We flip the key/value pairs in the dictionary here because Bazel doesn't have a
+        # string-keyed label dict attribute type.
+        format = {k: v for v, k in format.items()},
+        capabilities = capabilities,
+        **kwargs
+    )

docs/toolchain_api.md

@@ -474,53 +474,6 @@ cc_feature(
 | <a id="cc_mutually_exclusive_category-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 
 
-<a id="cc_tool"></a>
-
-## cc_tool
-
-<pre>
-load("@rules_cc//cc/toolchains/impl:documented_api.bzl", "cc_tool")
-
-cc_tool(<a href="#cc_tool-name">name</a>, <a href="#cc_tool-src">src</a>, <a href="#cc_tool-data">data</a>, <a href="#cc_tool-allowlist_include_directories">allowlist_include_directories</a>, <a href="#cc_tool-capabilities">capabilities</a>)
-</pre>
-
-Declares a tool for use by toolchain actions.
-
-[`cc_tool`](#cc_tool) rules are used in a [`cc_tool_map`](#cc_tool_map) rule to ensure all files and
-metadata required to run a tool are available when constructing a [`cc_toolchain`](#cc_toolchain).
-
-In general, include all files that are always required to run a tool (e.g. libexec/** and
-cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
-required when certain flags are passed to the tool, consider using a [`cc_args`](#cc_args) rule to
-bind the files to the flags that require them. This reduces the overhead required to properly
-enumerate a sandbox with all the files required to run a tool, and ensures that there isn't
-unintentional leakage across configurations and actions.
-
-Example:
-```
-load("@rules_cc//cc/toolchains:tool.bzl", "cc_tool")
-
-cc_tool(
-    name = "clang",
-    src = "@llvm_toolchain//:bin/clang",
-    # Suppose clang needs libc to run.
-    data = ["@llvm_toolchain//:lib/x86_64-linux-gnu/libc.so.6"]
-    capabilities = ["@rules_cc//cc/toolchains/capabilities:supports_pic"],
-)
-```
-
-**ATTRIBUTES**
-
-
-| Name  | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="cc_tool-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
-| <a id="cc_tool-src"></a>src |  The underlying binary that this tool represents.<br><br>Usually just a single prebuilt (eg. @toolchain//:bin/clang), but may be any executable label.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `None`  |
-| <a id="cc_tool-data"></a>data |  Additional files that are required for this tool to run.<br><br>Frequently, clang and gcc require additional files to execute as they often shell out to other binaries (e.g. `cc1`).   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
-| <a id="cc_tool-allowlist_include_directories"></a>allowlist_include_directories |  Include paths implied by using this tool.<br><br>Compilers may include a set of built-in headers that are implicitly available unless flags like `-nostdinc` are provided. Bazel checks that all included headers are properly provided by a dependency or allowlisted through this mechanism.<br><br>As a rule of thumb, only use this if Bazel is complaining about absolute paths in your toolchain and you've ensured that the toolchain is compiling with the `-no-canonical-prefixes` and/or `-fno-canonical-system-headers` arguments.<br><br>These files are not automatically passed to each action. If they need to be, add them to 'data' as well.<br><br>This can help work around errors like: `the source file 'main.c' includes the following non-builtin files with absolute paths (if these are builtin files, make sure these paths are in your toolchain)`.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
-| <a id="cc_tool-capabilities"></a>capabilities |  Declares that a tool is capable of doing something.<br><br>For example, `@rules_cc//cc/toolchains/capabilities:supports_pic`.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `[]`  |
-
-
 <a id="cc_tool_capability"></a>
 
 ## cc_tool_capability
@@ -725,6 +678,57 @@ use this rule.
 | <a id="cc_nested_args-kwargs"></a>kwargs |  [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.   |  none |
 
 
+<a id="cc_tool"></a>
+
+## cc_tool
+
+<pre>
+load("@rules_cc//cc/toolchains/impl:documented_api.bzl", "cc_tool")
+
+cc_tool(*, <a href="#cc_tool-name">name</a>, <a href="#cc_tool-src">src</a>, <a href="#cc_tool-data">data</a>, <a href="#cc_tool-allowlist_include_directories">allowlist_include_directories</a>, <a href="#cc_tool-env">env</a>, <a href="#cc_tool-format">format</a>, <a href="#cc_tool-capabilities">capabilities</a>, <a href="#cc_tool-kwargs">**kwargs</a>)
+</pre>
+
+Declares a tool for use by toolchain actions.
+
+[`cc_tool`](#cc_tool) rules are used in a [`cc_tool_map`](#cc_tool_map) rule to ensure all files and
+metadata required to run a tool are available when constructing a [`cc_toolchain`](#cc_toolchain).
+
+In general, include all files that are always required to run a tool (e.g. libexec/** and
+cross-referenced tools in bin/*) in the [data](#cc_tool-data) attribute. If some files are only
+required when certain flags are passed to the tool, consider using a [`cc_args`](#cc_args) rule to
+bind the files to the flags that require them. This reduces the overhead required to properly
+enumerate a sandbox with all the files required to run a tool, and ensures that there isn't
+unintentional leakage across configurations and actions.
+
+Example:
+```
+load("@rules_cc//cc/toolchains:tool.bzl", "cc_tool")
+
+cc_tool(
+    name = "clang",
+    src = "@llvm_toolchain//:bin/clang",
+    # Suppose clang needs libc to run.
+    data = ["@llvm_toolchain//:lib/x86_64-linux-gnu/libc.so.6"]
+    capabilities = ["@rules_cc//cc/toolchains/capabilities:supports_pic"],
+)
+```
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="cc_tool-name"></a>name |  (str) The name of the target.   |  none |
+| <a id="cc_tool-src"></a>src |  (Label) The underlying binary that this tool represents. Usually just a single prebuilt (e.g. @toolchain//:bin/clang), but may be any executable label.   |  `None` |
+| <a id="cc_tool-data"></a>data |  (List[Label]) Additional files that are required for this tool to run. Frequently, clang and gcc require additional files to execute as they often shell out to other binaries (e.g. `cc1`).   |  `None` |
+| <a id="cc_tool-allowlist_include_directories"></a>allowlist_include_directories |  (List[Label]) Include paths implied by using this tool. Compilers may include a set of built-in headers that are implicitly available unless flags like `-nostdinc` are provided. Bazel checks that all included headers are properly provided by a dependency or allowlisted through this mechanism.<br><br>As a rule of thumb, only use this if Bazel is complaining about absolute paths in your toolchain and you've ensured that the toolchain is compiling with the `-no-canonical-prefixes` and/or `-fno-canonical-system-headers` arguments.<br><br>These files are not automatically passed to each action. If they need to be, add them to 'data' as well.<br><br>This can help work around errors like: `the source file 'main.c' includes the following non-builtin files with absolute paths (if these are builtin files, make sure these paths are in your toolchain)`.   |  `None` |
+| <a id="cc_tool-env"></a>env |  (Dict[str, str]) Environment variables to apply when running this tool. Format expansion is performed on values using `format`.   |  `None` |
+| <a id="cc_tool-format"></a>format |  (Dict[str, Label]) A mapping of format strings to the label of a corresponding target. This target can be a `directory`, `subdirectory`, or a single file that the value should be pulled from. All instances of `{variable_name}` in the `env` dictionary values will be replaced with the expanded value in this dictionary.   |  `{}` |
+| <a id="cc_tool-capabilities"></a>capabilities |  (List[Label]) Declares that a tool is capable of doing something. For example, `@rules_cc//cc/toolchains/capabilities:supports_pic`.   |  `None` |
+| <a id="cc_tool-kwargs"></a>kwargs |  [common attributes](https://bazel.build/reference/be/common-definitions#common-attributes) that should be applied to this rule.   |  none |
+
+
 <a id="cc_tool_map"></a>
 
 ## cc_tool_map

tests/rule_based_toolchain/subjects.bzl

@@ -210,6 +210,7 @@ _ToolFactory = generate_factory(
         exe = _subjects.file,
         runfiles = runfiles_subject,
         execution_requirements = _subjects.collection,
+        env = _subjects.dict,
         allowlist_include_directories = _FakeDirectoryDepset,
         capabilities = ProviderSequence(_ToolCapabilityFactory),
     ),

tests/rule_based_toolchain/tool/BUILD

@@ -25,6 +25,23 @@ cc_tool(
     visibility = ["//tests/rule_based_toolchain:__subpackages__"],
 )
 
+cc_tool(
+    name = "tool_with_env",
+    src = "//tests/rule_based_toolchain/testdata:bin_wrapper.sh",
+    data = [
+        "//tests/rule_based_toolchain/testdata:bin",
+        "//tests/rule_based_toolchain/testdata:file1",
+    ],
+    env = {
+        "STATIC": "value",
+        "TOOL_ENV": "{tool_env}",
+    },
+    format = {
+        "tool_env": "//tests/rule_based_toolchain/testdata:file1",
+    },
+    visibility = ["//tests/rule_based_toolchain:__subpackages__"],
+)
+
 cc_directory_tool(
     name = "directory_tool",
     data = ["bin"],

tests/rule_based_toolchain/tool/tool_test.bzl

@@ -65,6 +65,13 @@ def _tool_with_allowlist_include_directories_test(env, targets):
         _FILE1,
     ])
 
+def _tool_env_expansion_test(env, targets):
+    tool = env.expect.that_target(targets.tool_with_env).provider(ToolInfo)
+    tool.env().contains_exactly({
+        "STATIC": "value",
+        "TOOL_ENV": "tests/rule_based_toolchain/testdata/file1",
+    })
+
 def _collect_tools_collects_tools_test(env, targets):
     env.expect.that_value(
         value = collect_tools(env.ctx, [targets.tool, targets.wrapped_tool]),
@@ -108,6 +115,7 @@ TARGETS = [
     "//tests/rule_based_toolchain/tool:wrapped_tool",
     "//tests/rule_based_toolchain/tool:directory_tool",
     "//tests/rule_based_toolchain/tool:tool_with_allowlist_include_directories",
+    "//tests/rule_based_toolchain/tool:tool_with_env",
     "//tests/rule_based_toolchain/testdata:bin_wrapper",
     "//tests/rule_based_toolchain/testdata:multiple",
     "//tests/rule_based_toolchain/testdata:bin_filegroup",
@@ -124,4 +132,5 @@ TESTS = {
     "collect_tools_collects_single_files_test": _collect_tools_collects_single_files_test,
     "collect_tools_fails_on_non_binary_test": _collect_tools_fails_on_non_binary_test,
     "tool_with_allowlist_include_directories_test": _tool_with_allowlist_include_directories_test,
+    "tool_env_expansion_test": _tool_env_expansion_test,
 }