pw_build: Make run_action_on_executable public

Make the bazel rule public and document function arguments. This
function is used by Zephyr's bazel build.

BUG: b/380001331
Change-Id: I616dcff9a3b42c0e116c9d5bf6d38863b3d2d116

Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/263833
Docs-Not-Needed: Ted Pudlik <[email protected]>
Lint: Lint 🤖 <[email protected]>
Pigweed-Auto-Submit: Yuval Peress <[email protected]>
Commit-Queue: Auto-Submit <[email protected]>
Reviewed-by: Ted Pudlik <[email protected]>

pw_build/binary_tools.bzl

@@ -17,17 +17,29 @@ load("@bazel_tools//tools/build_defs/cc:action_names.bzl", "ACTION_NAMES")
 load("@bazel_tools//tools/cpp:toolchain_utils.bzl", "find_cpp_toolchain", "use_cpp_toolchain")
 load("//pw_toolchain/action:action_names.bzl", "PW_ACTION_NAMES")
 
-def _run_action_on_executable(
+def run_action_on_executable(
         ctx,
         action_name,
         action_args,
-        input,
+        inputs,
         output,
         additional_outputs,
         output_executable = False):
     """Macro to be used in rule implementation to run an action on input executable.
 
-    Looks up the current toolchain to find the path to the specified action."""
+    Looks up the current toolchain to find the path to the specified action.
+
+    Args:
+      ctx: Rule context
+      action_name: The name of the action
+      action_args: Arguments to pass to the action
+      inputs: Input files to use in the action
+      output: The output generated by the action
+      additional_outputs: Extra output objects that should be bundled into the result
+      output_executable: True if the output is an executable
+    Returns:
+      DefaultInfo with the output and additional_outputs.
+    """
     cc_toolchain = find_cpp_toolchain(ctx)
 
     feature_configuration = cc_common.configure_features(
@@ -43,7 +55,7 @@ def _run_action_on_executable(
 
     ctx.actions.run_shell(
         inputs = depset(
-            direct = [input],
+            direct = inputs,
             transitive = [
                 cc_toolchain.all_files,
             ],
@@ -61,7 +73,7 @@ def _run_action_on_executable(
     )
 
 def _pw_elf_to_bin_impl(ctx):
-    return _run_action_on_executable(
+    return run_action_on_executable(
         ctx = ctx,
         # TODO: https://github.com/bazelbuild/rules_cc/issues/292 - Add a helper
         # to rules cc to make it possible to get this from ctx.attr._objcopy.
@@ -71,7 +83,7 @@ def _pw_elf_to_bin_impl(ctx):
             input = ctx.executable.elf_input.path,
             output = ctx.outputs.bin_out.path,
         ),
-        input = ctx.executable.elf_input,
+        inputs = [ctx.executable.elf_input],
         output = ctx.outputs.bin_out,
         additional_outputs = ctx.files.elf_input,
         output_executable = True,
@@ -96,7 +108,7 @@ pw_elf_to_bin = rule(
 )
 
 def _pw_elf_to_dump_impl(ctx):
-    return _run_action_on_executable(
+    return run_action_on_executable(
         ctx = ctx,
         # TODO: https://github.com/bazelbuild/rules_cc/issues/292 - Add a helper
         # to rules cc to make it possible to get this from ctx.attr._objdump.
@@ -106,7 +118,7 @@ def _pw_elf_to_dump_impl(ctx):
             input = ctx.executable.elf_input.path,
             output = ctx.outputs.dump_out.path,
         ),
-        input = ctx.executable.elf_input,
+        inputs = [ctx.executable.elf_input],
         output = ctx.outputs.dump_out,
         additional_outputs = ctx.files.elf_input,
     )