feat: add copy_file_action helper function to the public API (#68)

docs/copy_file.md

@@ -46,3 +46,32 @@ for more context.
 | <a id="copy_file-kwargs"></a>kwargs |  further keyword arguments, e.g. <code>visibility</code>   |  none |
 
 
+<a id="#copy_file_action"></a>
+
+## copy_file_action
+
+<pre>
+copy_file_action(<a href="#copy_file_action-ctx">ctx</a>, <a href="#copy_file_action-src">src</a>, <a href="#copy_file_action-dst">dst</a>, <a href="#copy_file_action-dir_path">dir_path</a>, <a href="#copy_file_action-is_windows">is_windows</a>)
+</pre>
+
+Helper function that creates an action to copy a file from src to dst.
+
+If src is a TreeArtifact, dir_path must be specified as the path within
+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.
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="copy_file_action-ctx"></a>ctx |  The rule context.   |  none |
+| <a id="copy_file_action-src"></a>src |  The source file to copy or TreeArtifact to copy a single file out of.   |  none |
+| <a id="copy_file_action-dst"></a>dst |  The destination file.   |  none |
+| <a id="copy_file_action-dir_path"></a>dir_path |  If src is a TreeArtifact, the path within the TreeArtifact to the file to copy.   |  <code>None</code> |
+| <a id="copy_file_action-is_windows"></a>is_windows |  If true, an cmd.exe action is created so there is no bash dependency.   |  <code>False</code> |
+
+

lib/copy_directory.bzl

@@ -7,8 +7,8 @@ on Windows (no Bash is required).
 load(
     "//lib/private:copy_directory.bzl",
     _copy_directory = "copy_directory",
-    _copy_helper = "copy_directory_action",
+    _copy_directory_action = "copy_directory_action",
 )
 
 copy_directory = _copy_directory
-copy_directory_action = _copy_helper
+copy_directory_action = _copy_directory_action

lib/copy_file.bzl

@@ -32,6 +32,8 @@ copy_file in the same package.
 load(
     "//lib/private:copy_file.bzl",
     _copy_file = "copy_file",
+    _copy_file_action = "copy_file_action",
 )
 
 copy_file = _copy_file
+copy_file_action = _copy_file_action

lib/private/copy_directory.bzl

@@ -13,7 +13,6 @@ _execution_requirements = {
     "no-remote-exec": "1",
 }
 
-# buildifier: disable=function-docstring
 def _copy_cmd(ctx, src, dst):
     # Most Windows binaries built with MSVC use a certain argument quoting
     # scheme. Bazel uses that scheme too to quote arguments. However,
@@ -53,7 +52,6 @@ def _copy_cmd(ctx, src, dst):
         execution_requirements = _execution_requirements,
     )
 
-# buildifier: disable=function-docstring
 def _copy_bash(ctx, src, dst):
     cmd = "rm -rf \"$2\" && cp -fR \"$1/\" \"$2\""
     mnemonic = "CopyDirectory"

lib/private/copy_file.bzl

@@ -35,8 +35,7 @@ _execution_requirements = {
     "no-remote-exec": "1",
 }
 
-# buildifier: disable=function-docstring
-def copy_cmd(ctx, src_file, src_path, dst):
+def _copy_cmd(ctx, src, src_path, dst):
     # Most Windows binaries built with MSVC use a certain argument quoting
     # scheme. Bazel uses that scheme too to quote arguments. However,
     # cmd.exe uses different semantics, so Bazel's quoting is wrong here.
@@ -63,7 +62,7 @@ def copy_cmd(ctx, src_file, src_path, dst):
         is_executable = True,
     )
     ctx.actions.run(
-        inputs = [src_file],
+        inputs = [src],
         tools = [bat],
         outputs = [dst],
         executable = "cmd.exe",
@@ -74,14 +73,13 @@ def copy_cmd(ctx, src_file, src_path, dst):
         execution_requirements = _execution_requirements,
     )
 
-# buildifier: disable=function-docstring
-def copy_bash(ctx, src_file, src_path, dst):
+def _copy_bash(ctx, src, src_path, dst):
     cmd_tmpl = "cp -f \"$1\" \"$2\""
     mnemonic = "CopyFile"
     progress_message = "Copying file %s" % src_path
 
     ctx.actions.run_shell(
-        tools = [src_file],
+        tools = [src],
         outputs = [dst],
         command = cmd_tmpl,
         arguments = [src_path, dst.path],
@@ -91,6 +89,35 @@ def copy_bash(ctx, src_file, src_path, dst):
         execution_requirements = _execution_requirements,
     )
 
+def copy_file_action(ctx, src, dst, dir_path = None, is_windows = False):
+    """Helper function that creates an action to copy a file from src to dst.
+
+    If src is a TreeArtifact, dir_path must be specified as the path within
+    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.
+
+    Args:
+        ctx: The rule context.
+        src: The source file to copy or TreeArtifact to copy a single file out of.
+        dst: The destination file.
+        dir_path: If src is a TreeArtifact, the path within the TreeArtifact to the file to copy.
+        is_windows: If true, an cmd.exe action is created so there is no bash dependency.
+    """
+    if dst.is_directory:
+        fail("dst must not be a TreeArtifact")
+    if src.is_directory:
+        if not dir_path:
+            fail("dir_path must be set if src is a TreeArtifact")
+        src_path = "/".join([src.path, dir_path])
+    else:
+        src_path = src.path
+    if is_windows:
+        _copy_cmd(ctx, src, src_path, dst)
+    else:
+        _copy_bash(ctx, src, src_path, dst)
+
 def _copy_file_impl(ctx):
     if ctx.attr.allow_symlink:
         if len(ctx.files.src) != 1:
@@ -102,21 +129,20 @@ def _copy_file_impl(ctx):
             target_file = ctx.files.src[0],
             is_executable = ctx.attr.is_executable,
         )
+    elif DirectoryPathInfo in ctx.attr.src:
+        copy_file_action(
+            ctx,
+            ctx.attr.src[DirectoryPathInfo].directory,
+            ctx.outputs.out,
+            dir_path = ctx.attr.src[DirectoryPathInfo].path,
+            is_windows = ctx.attr.is_windows,
+        )
     else:
-        if DirectoryPathInfo in ctx.attr.src:
-            src_file = ctx.attr.src[DirectoryPathInfo].directory
-            src_path = "/".join([src_file.path, ctx.attr.src[DirectoryPathInfo].path])
-        else:
-            if len(ctx.files.src) != 1:
-                fail("src must be a single file or a target that provides a DirectoryPathInfo")
-            if ctx.files.src[0].is_directory:
-                fail("cannot use copy_file on a directory; try copy_directory instead")
-            src_file = ctx.files.src[0]
-            src_path = src_file.path
-        if ctx.attr.is_windows:
-            copy_cmd(ctx, src_file, src_path, ctx.outputs.out)
-        else:
-            copy_bash(ctx, src_file, src_path, ctx.outputs.out)
+        if len(ctx.files.src) != 1:
+            fail("src must be a single file or a target that provides a DirectoryPathInfo")
+        if ctx.files.src[0].is_directory:
+            fail("cannot use copy_file on a directory; try copy_directory instead")
+        copy_file_action(ctx, ctx.files.src[0], ctx.outputs.out, is_windows = ctx.attr.is_windows)
 
     files = depset(direct = [ctx.outputs.out])
     runfiles = ctx.runfiles(files = [ctx.outputs.out])