feat: expose toolchains used for copy actions (#661)

docs/copy_file.md

@@ -62,6 +62,27 @@ the TreeArtifact to the file to copy.
 This helper is used by copy_file. It is exposed as a public API so it can be used within
 other rule implementations.
 
+To use `copy_file_action` in your own rules, you need to include the toolchains it uses
+in your rule definition. For example:
+
+```starlark
+load("@aspect_bazel_lib//lib:copy_file.bzl", "COPY_FILE_TOOLCHAINS")
+
+my_rule = rule(
+    ...,
+    toolchains = COPY_FILE_TOOLCHAINS,
+)
+```
+
+Additionally, you must ensure that the coreutils toolchain is has been registered in your
+WORKSPACE if you are not using bzlmod:
+
+```starlark
+load("@aspect_bazel_lib//lib:repositories.bzl", "register_coreutils_toolchains")
+
+register_coreutils_toolchains()
+```
+
 
 **PARAMETERS**
 

docs/copy_to_bin.md

@@ -25,6 +25,27 @@ returned.
 If the file passed in is already in the output tree is then it is returned
 without a copy action.
 
+To use `copy_file_to_bin_action` in your own rules, you need to include the toolchains it uses
+in your rule definition. For example:
+
+```starlark
+load("@aspect_bazel_lib//lib:copy_file.bzl", "COPY_FILE_TO_BIN_TOOLCHAINS")
+
+my_rule = rule(
+    ...,
+    toolchains = COPY_FILE_TO_BIN_TOOLCHAINS,
+)
+```
+
+Additionally, you must ensure that the coreutils toolchain is has been registered in your
+WORKSPACE if you are not using bzlmod:
+
+```starlark
+load("@aspect_bazel_lib//lib:repositories.bzl", "register_coreutils_toolchains")
+
+register_coreutils_toolchains()
+```
+
 
 **PARAMETERS**
 

lib/copy_file.bzl

@@ -31,9 +31,11 @@ copy_file in the same package.
 
 load(
     "//lib/private:copy_file.bzl",
+    _COPY_FILE_TOOLCHAINS = "COPY_FILE_TOOLCHAINS",
     _copy_file = "copy_file",
     _copy_file_action = "copy_file_action",
 )
 
 copy_file = _copy_file
 copy_file_action = _copy_file_action
+COPY_FILE_TOOLCHAINS = _COPY_FILE_TOOLCHAINS

lib/copy_to_bin.bzl

@@ -9,6 +9,7 @@ https://github.com/bazelbuild/rules_nodejs/blob/8b5d27400db51e7027fe95ae413eeabe
 
 load(
     "//lib/private:copy_to_bin.bzl",
+    _COPY_FILE_TO_BIN_TOOLCHAINS = "COPY_FILE_TO_BIN_TOOLCHAINS",
     _copy_file_to_bin_action = "copy_file_to_bin_action",
     _copy_files_to_bin_actions = "copy_files_to_bin_actions",
     _copy_to_bin = "copy_to_bin",
@@ -17,3 +18,4 @@ load(
 copy_file_to_bin_action = _copy_file_to_bin_action
 copy_files_to_bin_actions = _copy_files_to_bin_actions
 copy_to_bin = _copy_to_bin
+COPY_FILE_TO_BIN_TOOLCHAINS = _COPY_FILE_TO_BIN_TOOLCHAINS

lib/private/copy_file.bzl

@@ -27,6 +27,14 @@ cmd.exe (on Windows). `_copy_xfile` marks the resulting file executable,
 load(":copy_common.bzl", _COPY_EXECUTION_REQUIREMENTS = "COPY_EXECUTION_REQUIREMENTS", _progress_path = "progress_path")
 load(":directory_path.bzl", "DirectoryPathInfo")
 
+_COREUTILS_TOOLCHAIN = "@aspect_bazel_lib//lib:coreutils_toolchain_type"
+
+# Declare toolchains used by copy file actions so that downstream rulesets can pass it into
+# the `toolchains` attribute of their rule.
+COPY_FILE_TOOLCHAINS = [
+    _COREUTILS_TOOLCHAIN,
+]
+
 def copy_file_action(ctx, src, dst, dir_path = None):
     """Factory function that creates an action to copy a file from src to dst.
 
@@ -36,6 +44,27 @@ def copy_file_action(ctx, src, dst, dir_path = None):
     This helper is used by copy_file. It is exposed as a public API so it can be used within
     other rule implementations.
 
+    To use `copy_file_action` in your own rules, you need to include the toolchains it uses
+    in your rule definition. For example:
+
+    ```starlark
+    load("@aspect_bazel_lib//lib:copy_file.bzl", "COPY_FILE_TOOLCHAINS")
+
+    my_rule = rule(
+        ...,
+        toolchains = COPY_FILE_TOOLCHAINS,
+    )
+    ```
+
+    Additionally, you must ensure that the coreutils toolchain is has been registered in your
+    WORKSPACE if you are not using bzlmod:
+
+    ```starlark
+    load("@aspect_bazel_lib//lib:repositories.bzl", "register_coreutils_toolchains")
+
+    register_coreutils_toolchains()
+    ```
+
     Args:
         ctx: The rule context.
         src: The source file to copy or TreeArtifact to copy a single file out of.
@@ -52,7 +81,7 @@ def copy_file_action(ctx, src, dst, dir_path = None):
     else:
         src_path = src.path
 
-    coreutils = ctx.toolchains["@aspect_bazel_lib//lib:coreutils_toolchain_type"].coreutils_info
+    coreutils = ctx.toolchains[_COREUTILS_TOOLCHAIN].coreutils_info
 
     ctx.actions.run(
         executable = coreutils.bin,
@@ -107,7 +136,7 @@ _copy_file = rule(
     implementation = _copy_file_impl,
     provides = [DefaultInfo],
     attrs = _ATTRS,
-    toolchains = ["@aspect_bazel_lib//lib:coreutils_toolchain_type"],
+    toolchains = COPY_FILE_TOOLCHAINS,
 )
 
 _copy_xfile = rule(
@@ -115,7 +144,7 @@ _copy_xfile = rule(
     executable = True,
     provides = [DefaultInfo],
     attrs = _ATTRS,
-    toolchains = ["@aspect_bazel_lib//lib:coreutils_toolchain_type"],
+    toolchains = COPY_FILE_TOOLCHAINS,
 )
 
 def copy_file(name, src, out, is_executable = False, allow_symlink = False, **kwargs):

lib/private/copy_to_bin.bzl

@@ -15,7 +15,9 @@
 """Implementation of copy_to_bin macro and underlying rules."""
 
 load("@bazel_skylib//lib:paths.bzl", "paths")
-load(":copy_file.bzl", "copy_file_action")
+load(":copy_file.bzl", "COPY_FILE_TOOLCHAINS", "copy_file_action")
+
+COPY_FILE_TO_BIN_TOOLCHAINS = COPY_FILE_TOOLCHAINS
 
 def copy_file_to_bin_action(ctx, file):
     """Factory function that creates an action to copy a file to the output tree.
@@ -26,6 +28,27 @@ def copy_file_to_bin_action(ctx, file):
     If the file passed in is already in the output tree is then it is returned
     without a copy action.
 
+    To use `copy_file_to_bin_action` in your own rules, you need to include the toolchains it uses
+    in your rule definition. For example:
+
+    ```starlark
+    load("@aspect_bazel_lib//lib:copy_file.bzl", "COPY_FILE_TO_BIN_TOOLCHAINS")
+
+    my_rule = rule(
+        ...,
+        toolchains = COPY_FILE_TO_BIN_TOOLCHAINS,
+    )
+    ```
+
+    Additionally, you must ensure that the coreutils toolchain is has been registered in your
+    WORKSPACE if you are not using bzlmod:
+
+    ```starlark
+    load("@aspect_bazel_lib//lib:repositories.bzl", "register_coreutils_toolchains")
+
+    register_coreutils_toolchains()
+    ```
+
     Args:
         ctx: The rule context.
         file: The file to copy.
@@ -121,7 +144,7 @@ _copy_to_bin = rule(
     attrs = {
         "srcs": attr.label_list(mandatory = True, allow_files = True),
     },
-    toolchains = ["@aspect_bazel_lib//lib:coreutils_toolchain_type"],
+    toolchains = COPY_FILE_TO_BIN_TOOLCHAINS,
 )
 
 def copy_to_bin(name, srcs, **kwargs):

lib/repositories.bzl

@@ -14,6 +14,7 @@ load("//tools:version.bzl", "VERSION")
 # buildifier: disable=unnamed-macro
 def aspect_bazel_lib_dependencies():
     "Load dependencies required by aspect rules"
+
     http_archive(
         name = "bazel_skylib",
         sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa",