Support custom 'mnemonic' and 'progress_message'

Adds support for custom 'mnemonic' and 'progress_message' attributes for
'copy_file', 'copy_directory' and 'run_binary' rules.

Author: joshua-k-harris

docs/copy_directory_doc.md

@@ -11,7 +11,7 @@ on Windows (no Bash is required).
 ## copy_directory
 
 <pre>
-copy_directory(<a href="#copy_directory-name">name</a>, <a href="#copy_directory-src">src</a>, <a href="#copy_directory-out">out</a>, <a href="#copy_directory-kwargs">kwargs</a>)
+copy_directory(<a href="#copy_directory-name">name</a>, <a href="#copy_directory-src">src</a>, <a href="#copy_directory-out">out</a>, <a href="#copy_directory-progress_message">progress_message</a>, <a href="#copy_directory-mnemonic">mnemonic</a>, <a href="#copy_directory-kwargs">kwargs</a>)
 </pre>
 
 Copies a directory to another location.
@@ -33,6 +33,8 @@ for more context.
 | <a id="copy_directory-name"></a>name |  Name of the rule.   |  none |
 | <a id="copy_directory-src"></a>src |  The directory to make a copy of. Can be a source directory or TreeArtifact.   |  none |
 | <a id="copy_directory-out"></a>out |  Path of the output directory, relative to this package.   |  none |
+| <a id="copy_directory-progress_message"></a>progress_message |  A custom action progress message.   |  <code>"Copying directory %{input}"</code> |
+| <a id="copy_directory-mnemonic"></a>mnemonic |  A custom action mnemonic.   |  <code>"CopyDirectory"</code> |
 | <a id="copy_directory-kwargs"></a>kwargs |  further keyword arguments, e.g. <code>visibility</code>   |  none |
 
 

docs/copy_file_doc.md

@@ -14,7 +14,7 @@ on Windows (no Bash is required).
 ## copy_file
 
 <pre>
-copy_file(<a href="#copy_file-name">name</a>, <a href="#copy_file-src">src</a>, <a href="#copy_file-out">out</a>, <a href="#copy_file-is_executable">is_executable</a>, <a href="#copy_file-allow_symlink">allow_symlink</a>, <a href="#copy_file-kwargs">kwargs</a>)
+copy_file(<a href="#copy_file-name">name</a>, <a href="#copy_file-src">src</a>, <a href="#copy_file-out">out</a>, <a href="#copy_file-is_executable">is_executable</a>, <a href="#copy_file-allow_symlink">allow_symlink</a>, <a href="#copy_file-progress_message">progress_message</a>, <a href="#copy_file-mnemonic">mnemonic</a>, <a href="#copy_file-kwargs">kwargs</a>)
 </pre>
 
 Copies a file to another location.
@@ -34,6 +34,8 @@ This rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command
 | <a id="copy_file-out"></a>out |  Path of the output file, relative to this package.   |  none |
 | <a id="copy_file-is_executable"></a>is_executable |  A boolean. Whether to make the output file executable. When True, the rule's output can be executed using <code>bazel run</code> and can be in the srcs of binary and test rules that require executable sources. WARNING: If <code>allow_symlink</code> is True, <code>src</code> must also be executable.   |  <code>False</code> |
 | <a id="copy_file-allow_symlink"></a>allow_symlink |  A boolean. Whether to allow symlinking instead of copying. When False, the output is always a hard copy. When True, the output *can* be a symlink, but there is no guarantee that a symlink is created (i.e., at the time of writing, we don't create symlinks on Windows). Set this to True if you need fast copying and your tools can handle symlinks (which most UNIX tools can).   |  <code>False</code> |
+| <a id="copy_file-progress_message"></a>progress_message |  A custom action progress message.   |  <code>"Copying files"</code> |
+| <a id="copy_file-mnemonic"></a>mnemonic |  A custom action mnemonic.   |  <code>"CopyFile"</code> |
 | <a id="copy_file-kwargs"></a>kwargs |  further keyword arguments, e.g. <code>visibility</code>   |  none |
 
 

docs/run_binary_doc.md

@@ -11,7 +11,7 @@ Runs a binary as a build action. This rule does not require Bash (unlike native.
 ## run_binary
 
 <pre>
-run_binary(<a href="#run_binary-name">name</a>, <a href="#run_binary-args">args</a>, <a href="#run_binary-env">env</a>, <a href="#run_binary-outs">outs</a>, <a href="#run_binary-srcs">srcs</a>, <a href="#run_binary-tool">tool</a>)
+run_binary(<a href="#run_binary-name">name</a>, <a href="#run_binary-args">args</a>, <a href="#run_binary-env">env</a>, <a href="#run_binary-mnemonic">mnemonic</a>, <a href="#run_binary-outs">outs</a>, <a href="#run_binary-progress_message">progress_message</a>, <a href="#run_binary-srcs">srcs</a>, <a href="#run_binary-tool">tool</a>)
 </pre>
 
 Runs a binary as a build action.
@@ -26,7 +26,9 @@ This rule does not require Bash (unlike `native.genrule`).
 | <a id="run_binary-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
 | <a id="run_binary-args"></a>args |  Command line arguments of the binary.<br><br>Subject to [<code>$(location)</code>](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion.   | List of strings | optional | <code>[]</code> |
 | <a id="run_binary-env"></a>env |  Environment variables of the action.<br><br>Subject to  [<code>$(location)</code>](https://bazel.build/reference/be/make-variables#predefined_label_variables) expansion.   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> |
+| <a id="run_binary-mnemonic"></a>mnemonic |  Custom action mnemonic.   | String | optional | <code>"RunBinary"</code> |
 | <a id="run_binary-outs"></a>outs |  Output files generated by the action.<br><br>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>.   | List of labels | required |  |
+| <a id="run_binary-progress_message"></a>progress_message |  Custom action progress message.   | String | optional | <code>"Running binary"</code> |
 | <a id="run_binary-srcs"></a>srcs |  Additional inputs of the action.<br><br>These labels are available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>.   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> |
 | <a id="run_binary-tool"></a>tool |  The tool to run in the action.<br><br>Must be the label of a *_binary rule, of a rule that generates an executable file, or of a file that can be executed as a subprocess (e.g. an .exe or .bat file on Windows or a binary with executable permission on Linux). This label is available for <code>$(location)</code> expansion in <code>args</code> and <code>env</code>.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
 

rules/private/copy_directory_private.bzl

@@ -40,9 +40,6 @@ if not exist \"{src}\\\" (
 )
 @robocopy \"{src}\" \"{dst}\" /E /MIR >NUL & @exit 0
 """
-    mnemonic = "CopyDirectory"
-    progress_message = "Copying directory %{input}"
-
     ctx.actions.write(
         output = bat,
         # Do not use lib/shell.bzl's shell.quote() method, because that uses
@@ -58,8 +55,8 @@ if not exist \"{src}\\\" (
         outputs = [dst],
         executable = "cmd.exe",
         arguments = ["/C", bat.path.replace("/", "\\")],
-        mnemonic = mnemonic,
-        progress_message = progress_message,
+        mnemonic = ctx.attr.mnemonic,
+        progress_message = ctx.attr.progress_message,
         use_default_shell_env = True,
         execution_requirements = COPY_EXECUTION_REQUIREMENTS,
     )
@@ -73,16 +70,13 @@ fi
 
 rm -rf \"$2\" && cp -fR \"$1/\" \"$2\"
 """
-    mnemonic = "CopyDirectory"
-    progress_message = "Copying directory %s" % src.path
-
     ctx.actions.run_shell(
         inputs = [src],
         outputs = [dst],
         command = cmd,
         arguments = [src.path, dst.path],
-        mnemonic = mnemonic,
-        progress_message = progress_message,
+        mnemonic = ctx.attr.mnemonic,
+        progress_message = ctx.attr.progress_message,
         use_default_shell_env = True,
         execution_requirements = COPY_EXECUTION_REQUIREMENTS,
     )
@@ -124,10 +118,12 @@ _copy_directory = rule(
         # Cannot declare out as an output here, because there's no API for declaring
         # TreeArtifact outputs.
         "out": attr.string(mandatory = True),
+        "mnemonic": attr.string(),
+        "progress_message": attr.string(),
     },
 )
 
-def copy_directory(name, src, out, **kwargs):
+def copy_directory(name, src, out, progress_message = "Copying directory %{input}", mnemonic = "CopyDirectory", **kwargs):
     """Copies a directory to another location.
 
     This rule uses a Bash command on Linux/macOS/non-Windows, and a cmd.exe command on Windows (no Bash is required).
@@ -142,6 +138,8 @@ def copy_directory(name, src, out, **kwargs):
       name: Name of the rule.
       src: The directory to make a copy of. Can be a source directory or TreeArtifact.
       out: Path of the output directory, relative to this package.
+      progress_message: A custom action progress message.
+      mnemonic: A custom action mnemonic.
       **kwargs: further keyword arguments, e.g. `visibility`
     """
     _copy_directory(
@@ -152,5 +150,7 @@ def copy_directory(name, src, out, **kwargs):
             "//conditions:default": False,
         }),
         out = out,
+        mnemonic = mnemonic,
+        progress_message = progress_message,
         **kwargs
     )

rules/private/copy_file_private.bzl

@@ -43,8 +43,8 @@ def copy_cmd(ctx, src, dst):
         outputs = [dst],
         executable = "cmd.exe",
         arguments = ["/C", bat.path.replace("/", "\\")],
-        mnemonic = "CopyFile",
-        progress_message = "Copying files",
+        mnemonic = ctx.attr.mnemonic,
+        progress_message = ctx.attr.progress_message,
         use_default_shell_env = True,
         execution_requirements = COPY_EXECUTION_REQUIREMENTS,
     )
@@ -55,8 +55,8 @@ def copy_bash(ctx, src, dst):
         outputs = [dst],
         command = "cp -f \"$1\" \"$2\"",
         arguments = [src.path, dst.path],
-        mnemonic = "CopyFile",
-        progress_message = "Copying files",
+        mnemonic = ctx.attr.mnemonic,
+        progress_message = ctx.attr.progress_message,
         use_default_shell_env = True,
         execution_requirements = COPY_EXECUTION_REQUIREMENTS,
     )
@@ -89,6 +89,8 @@ _ATTRS = {
     "is_windows": attr.bool(mandatory = True),
     "is_executable": attr.bool(mandatory = True),
     "allow_symlink": attr.bool(mandatory = True),
+    "mnemonic": attr.string(),
+    "progress_message": attr.string(),
 }
 
 _copy_file = rule(
@@ -104,7 +106,7 @@ _copy_xfile = rule(
     attrs = _ATTRS,
 )
 
-def copy_file(name, src, out, is_executable = False, allow_symlink = False, **kwargs):
+def copy_file(name, src, out, is_executable = False, allow_symlink = False, progress_message = "Copying files", mnemonic = "CopyFile", **kwargs):
     """Copies a file to another location.
 
     `native.genrule()` is sometimes used to copy files (often wishing to rename them). The 'copy_file' rule does this with a simpler interface than genrule.
@@ -126,6 +128,8 @@ def copy_file(name, src, out, is_executable = False, allow_symlink = False, **kw
           created (i.e., at the time of writing, we don't create symlinks on
           Windows). Set this to True if you need fast copying and your tools can
           handle symlinks (which most UNIX tools can).
+      progress_message: A custom action progress message.
+      mnemonic: A custom action mnemonic.
       **kwargs: further keyword arguments, e.g. `visibility`
     """
 
@@ -143,5 +147,7 @@ def copy_file(name, src, out, is_executable = False, allow_symlink = False, **kw
         }),
         is_executable = is_executable,
         allow_symlink = allow_symlink,
+        mnemonic = mnemonic,
+        progress_message = progress_message,
         **kwargs
     )

rules/run_binary.bzl

@@ -47,7 +47,8 @@ def _impl(ctx):
         tools = [ctx.executable.tool],
         executable = ctx.executable.tool,
         arguments = args,
-        mnemonic = "RunBinary",
+        mnemonic = ctx.attr.mnemonic,
+        progress_message = ctx.attr.progress_message,
         use_default_shell_env = False,
         env = dicts.add(ctx.configuration.default_shell_env, envs),
     )
@@ -92,5 +93,13 @@ run_binary = rule(
                   " [`$(location)`](https://bazel.build/reference/be/make-variables#predefined_label_variables)" +
                   " expansion.",
         ),
+        "mnemonic": attr.string(
+            default = "RunBinary",
+            doc = "Custom action mnemonic.",
+        ),
+        "progress_message": attr.string(
+            default = "Running binary",
+            doc = "Custom action progress message.",
+        ),
     },
 )