New rules: native_binary and native_test (#152)

native_binary() wraps a pre-built binary or script
in a *_binary rule interface. Rules like genrule
can tool-depend on it, and it can be executed with
"bazel run". This rule can also augment the binary
with runfiles.

native_test() is similar, but creates a testable
rule instead of a binary rule.

Fixes bazelbuild/bazel-skylib#148

RELNOTES[NEW]: The new `native_binary()` and `native_test()` rules let you wrap a pre-built binary in a binary and test rule respectively.

docs/BUILD

@@ -114,3 +114,10 @@ stardoc(
     input = "//rules:diff_test.bzl",
     deps = ["//rules:diff_test"],
 )
+
+stardoc(
+    name = "native_binary_docs",
+    out = "native_binary_doc_gen.md",
+    input = "//rules:native_binary.bzl",
+    deps = ["//rules:native_binary"],
+)

docs/native_binary_doc.md

@@ -0,0 +1,131 @@
+## native_binary
+
+<pre>
+native_binary(<a href="#native_binary-name">name</a>, <a href="#native_binary-src">src</a>, <a href="#native_binary-out">out</a>, <a href="#native_binary-data">data</a>, <a href="#native_binary-kwargs">kwargs</a>)
+</pre>
+
+Wraps a pre-built binary or script with a binary rule.
+
+You can "bazel run" this rule like any other binary rule, and use it as a tool in genrule.tools for example. You can also augment the binary with runfiles.
+
+
+### Parameters
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="native_binary-name">
+      <td><code>name</code></td>
+      <td>
+        required.
+      </td>
+    </tr>
+    <tr id="native_binary-src">
+      <td><code>src</code></td>
+      <td>
+        required.
+        <p>
+          label; path of the pre-built executable
+        </p>
+      </td>
+    </tr>
+    <tr id="native_binary-out">
+      <td><code>out</code></td>
+      <td>
+        required.
+        <p>
+          output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.)
+        </p>
+      </td>
+    </tr>
+    <tr id="native_binary-data">
+      <td><code>data</code></td>
+      <td>
+        optional. default is <code>None</code>
+        <p>
+          list of labels; data dependencies
+        </p>
+      </td>
+    </tr>
+    <tr id="native_binary-kwargs">
+      <td><code>kwargs</code></td>
+      <td>
+        optional.
+        <p>
+          The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-binaries">common attributes for binaries</a>.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+
+## native_test
+
+<pre>
+native_test(<a href="#native_test-name">name</a>, <a href="#native_test-src">src</a>, <a href="#native_test-out">out</a>, <a href="#native_test-data">data</a>, <a href="#native_test-kwargs">kwargs</a>)
+</pre>
+
+Wraps a pre-built binary or script with a test rule.
+
+You can "bazel test" this rule like any other test rule. You can also augment the binary with
+runfiles.
+
+
+### Parameters
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="native_test-name">
+      <td><code>name</code></td>
+      <td>
+        required.
+      </td>
+    </tr>
+    <tr id="native_test-src">
+      <td><code>src</code></td>
+      <td>
+        required.
+        <p>
+          label; path of the pre-built executable
+        </p>
+      </td>
+    </tr>
+    <tr id="native_test-out">
+      <td><code>out</code></td>
+      <td>
+        required.
+        <p>
+          output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.)
+        </p>
+      </td>
+    </tr>
+    <tr id="native_test-data">
+      <td><code>data</code></td>
+      <td>
+        optional. default is <code>None</code>
+        <p>
+          list of labels; data dependencies
+        </p>
+      </td>
+    </tr>
+    <tr id="native_test-kwargs">
+      <td><code>kwargs</code></td>
+      <td>
+        optional.
+        <p>
+          The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+

rules/BUILD

@@ -27,6 +27,12 @@ bzl_library(
     srcs = ["diff_test.bzl"],
 )
 
+bzl_library(
+    name = "native_binary",
+    srcs = ["native_binary.bzl"],
+    deps = ["//rules/private:copy_file_private"],
+)
+
 # Exported for build_test.bzl to make sure of, it is an implementation detail
 # of the rule and should not be directly used by anything else.
 exports_files(["empty_test.sh"])

rules/native_binary.bzl

@@ -0,0 +1,116 @@
+# Copyright 2019 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""native_binary() and native_test() rule implementations.
+
+These rules let you wrap a pre-built binary or script in a conventional binary
+and test rule respectively. They fulfill the same goal as sh_binary and sh_test
+do, but they run the wrapped binary directly, instead of through Bash, so they
+don't depend on Bash and work with --shell_exectuable="".
+"""
+
+load("//rules/private:copy_file_private.bzl", "copy_bash", "copy_cmd")
+
+def _impl_rule(ctx, is_windows):
+    out = ctx.actions.declare_file(ctx.attr.out)
+    if is_windows:
+        copy_cmd(ctx, ctx.file.src, out)
+    else:
+        copy_bash(ctx, ctx.file.src, out)
+    return DefaultInfo(
+        executable = out,
+        files = depset(items = [out]),
+        runfiles = ctx.runfiles(
+            files = [out],
+            collect_data = True,
+            collect_default = True,
+        ),
+    )
+
+def _impl(ctx):
+    return _impl_rule(ctx, ctx.attr.is_windows)
+
+_ATTRS = {
+    "src": attr.label(
+        executable = True,
+        allow_single_file = True,
+        mandatory = True,
+        cfg = "host",
+    ),
+    "data": attr.label_list(allow_files = True),
+    # "out" is attr.string instead of attr.output, so that it is select()'able.
+    "out": attr.string(mandatory = True),
+    "is_windows": attr.bool(mandatory = True),
+}
+
+_native_binary = rule(
+    implementation = _impl,
+    attrs = _ATTRS,
+    executable = True,
+)
+
+_native_test = rule(
+    implementation = _impl,
+    attrs = _ATTRS,
+    test = True,
+)
+
+def native_binary(name, src, out, data = None, **kwargs):
+    """Wraps a pre-built binary or script with a binary rule.
+
+    You can "bazel run" this rule like any other binary rule, and use it as a tool in genrule.tools for example. You can also augment the binary with runfiles.
+
+    Args:
+      name: The name of the test rule.
+      src: label; path of the pre-built executable
+      out: output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.)
+      data: list of labels; data dependencies
+      **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-binaries">common attributes for binaries</a>.
+    """
+    _native_binary(
+        name = name,
+        src = src,
+        out = out,
+        data = data,
+        is_windows = select({
+            "@bazel_tools//src/conditions:host_windows": True,
+            "//conditions:default": False,
+        }),
+        **kwargs
+    )
+
+def native_test(name, src, out, data = None, **kwargs):
+    """Wraps a pre-built binary or script with a test rule.
+
+    You can "bazel test" this rule like any other test rule. You can also augment the binary with
+    runfiles.
+
+    Args:
+      name: The name of the test rule.
+      src: label; path of the pre-built executable
+      out: output; an output name for the copy of the binary. (Bazel requires that this rule make a copy of 'src'.)
+      data: list of labels; data dependencies
+      **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>.
+    """
+    _native_test(
+        name = name,
+        src = src,
+        out = out,
+        data = data,
+        is_windows = select({
+            "@bazel_tools//src/conditions:host_windows": True,
+            "//conditions:default": False,
+        }),
+        **kwargs
+    )

tests/native_binary/BUILD

@@ -0,0 +1,102 @@
+load("//rules:copy_file.bzl", "copy_file")
+load("//rules:native_binary.bzl", "native_binary", "native_test")
+
+package(
+    default_testonly = 1,
+    default_visibility = ["//visibility:private"],
+)
+
+cc_binary(
+    name = "assertarg",
+    srcs = ["assertarg.cc"],
+)
+
+cc_binary(
+    name = "assertdata",
+    srcs = ["assertdata.cc"],
+    deps = ["@bazel_tools//tools/cpp/runfiles"],
+    # Depends on the runfiles library but doesn't have data-dependencies, on
+    # purpose. We supplement the runfiles in the native_binary / native_test
+    # rule.
+)
+
+# A rule that copies "assertarg"'s output as an opaque executable, simulating a
+# binary that's not built from source and needs to be wrapped in native_binary.
+copy_file(
+    name = "copy_assertarg_exe",
+    src = ":assertarg",
+    # On Windows we need the ".exe" extension.
+    # On other platforms the extension doesn't matter.
+    # Therefore we can use ".exe" on every platform.
+    out = "assertarg_copy.exe",
+    is_executable = True,
+)
+
+# A rule that copies "assertdata"'s output as an opaque executable, simulating a
+# binary that's not built from source and needs to be wrapped in native_binary.
+copy_file(
+    name = "copy_assertdata_exe",
+    src = ":assertdata",
+    # On Windows we need the ".exe" extension.
+    # On other platforms the extension doesn't matter.
+    # Therefore we can use ".exe" on every platform.
+    out = "assertdata_copy.exe",
+    is_executable = True,
+)
+
+_ARGS = [
+    "'a b'",
+    "c\\ d",
+    "$(location testdata.txt) $$(location testdata.txt) $(location testdata.txt)",
+    "'$(location testdata.txt) $$(location testdata.txt) $(location testdata.txt)'",
+    "$$TEST_SRCDIR",
+
+    # TODO(laszlocsomor): uncomment this (and its counterpart in assertarg.cc)
+    # after https://github.com/bazelbuild/bazel/issues/6622 is resolved and the
+    # Bash-less test wrapper is the default on Windows.
+    # "$${TEST_SRCDIR}",
+]
+
+native_binary(
+    name = "args_bin",
+    src = ":copy_assertarg_exe",
+    # On Windows we need the ".exe" extension.
+    # On other platforms the extension doesn't matter.
+    # Therefore we can use ".exe" on every platform.
+    out = "args_bin.exe",
+    args = _ARGS,
+    # We only need the data-dependency for $(location) expansion.
+    data = ["testdata.txt"],
+)
+
+native_test(
+    name = "args_test",
+    src = ":copy_assertarg_exe",
+    # On Windows we need the ".exe" extension.
+    # On other platforms the extension doesn't matter.
+    # Therefore we can use ".exe" on every platform.
+    out = "args_test.exe",
+    args = _ARGS,
+    # We only need the data-dependency for $(location) expansion.
+    data = ["testdata.txt"],
+)
+
+native_binary(
+    name = "data_bin",
+    src = ":copy_assertdata_exe",
+    # On Windows we need the ".exe" extension.
+    # On other platforms the extension doesn't matter.
+    # Therefore we can use ".exe" on every platform.
+    out = "data_bin.exe",
+    data = ["testdata.txt"],
+)
+
+native_test(
+    name = "data_test",
+    src = ":copy_assertdata_exe",
+    # On Windows we need the ".exe" extension.
+    # On other platforms the extension doesn't matter.
+    # Therefore we can use ".exe" on every platform.
+    out = "data_test.exe",
+    data = ["testdata.txt"],
+)