diff_test: add rule and tests

This new test rule compares two files and passes
if the files match.

On Linux/macOS/non-Windows, the test compares
files using 'diff'.

On Windows, the test compares files using
'fc.exe'. This utility is available on all Windows
versions I tried (Windows 2008 Server, Windows
2016 Datacenter Core).

See bazelbuild/bazel#5508
See bazelbuild/bazel#4319

docs/BUILD

@@ -105,3 +105,10 @@ stardoc(
     input = "//rules:write_file.bzl",
     deps = ["//rules:write_file"],
 )
+
+stardoc(
+    name = "diff_test_docs",
+    out = "diff_test_doc_gen.md",
+    input = "//rules:diff_test.bzl",
+    deps = ["//rules:diff_test"],
+)

rules/BUILD

@@ -22,6 +22,11 @@ bzl_library(
     deps = ["//rules/private:write_file_private"],
 )
 
+bzl_library(
+    name = "diff_test",
+    srcs = ["diff_test.bzl"],
+)
+
 # 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/diff_test.bzl

@@ -0,0 +1,137 @@
+# 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.
+
+"""A test rule that compares two binary files.
+
+The rule uses a Bash command (diff) on Linux/macOS/non-Windows, and a cmd.exe
+command (fc.exe) on Windows (no Bash is required).
+"""
+
+def _runfiles_path(f):
+    if f.root.path:
+        return f.path[len(f.root.path) + 1:]  # generated file
+    else:
+        return f.path  # source file
+
+def _diff_test_impl(ctx):
+    if ctx.attr.is_windows:
+        test_bin = ctx.actions.declare_file(ctx.label.name + "-test.bat")
+        ctx.actions.write(
+            output = test_bin,
+            content = r"""@echo off
+setlocal enableextensions
+set MF=%RUNFILES_MANIFEST_FILE:/=\%
+set PATH=%SYSTEMROOT%\system32
+for /F "tokens=2* usebackq" %%i in (`findstr.exe /l /c:"%TEST_WORKSPACE%/{file1} " "%MF%"`) do (
+  set RF1=%%i
+  set RF1=%RF1:/=\%
+)
+if "%RF1%" equ "" (
+  echo>&2 ERROR: {file1} not found
+  exit /b 1
+)
+for /F "tokens=2* usebackq" %%i in (`findstr.exe /l /c:"%TEST_WORKSPACE%/{file2} " "%MF%"`) do (
+  set RF2=%%i
+  set RF2=%RF2:/=\%
+)
+if "%RF2%" equ "" (
+  echo>&2 ERROR: {file2} not found
+  exit /b 1
+)
+fc.exe 2>NUL 1>NUL /B "%RF1%" "%RF2%"
+if %ERRORLEVEL% equ 2 (
+  echo>&2 FAIL: "{file1}" and/or "{file2}" not found
+  exit /b 1
+) else (
+  if %ERRORLEVEL% equ 1 (
+    echo>&2 FAIL: files "{file1}" and "{file2}" differ
+    exit /b 1
+  )
+)
+""".format(
+                file1 = _runfiles_path(ctx.file.file1),
+                file2 = _runfiles_path(ctx.file.file2),
+            ),
+            is_executable = True,
+        )
+    else:
+        test_bin = ctx.actions.declare_file(ctx.label.name + "-test.sh")
+        ctx.actions.write(
+            output = test_bin,
+            content = r"""#!/bin/bash
+set -euo pipefail
+if [[ -d "${{RUNFILES_DIR:-/dev/null}}" ]]; then
+  RF1="$RUNFILES_DIR/$TEST_WORKSPACE/{file1}"
+  RF2="$RUNFILES_DIR/$TEST_WORKSPACE/{file2}"
+elif [[ -f "${{RUNFILES_MANIFEST_FILE:-/dev/null}}" ]]; then
+  RF1="$(grep -F -m1 '{file1} ' "$RUNFILES_MANIFEST_FILE" | sed 's/^[^ ]* //')"
+  RF2="$(grep -F -m1 '{file2} ' "$RUNFILES_MANIFEST_FILE" | sed 's/^[^ ]* //'))"
+else
+  echo >&2 "ERROR: could not find \"{file1}\" and \"{file2}\""
+fi
+if ! diff "$RF1" "$RF2"; then
+  echo >&2 "FAIL: files \"{file1}\" and \"{file2}\" differ"
+  exit 1
+fi
+""".format(
+                file1 = _runfiles_path(ctx.file.file1),
+                file2 = _runfiles_path(ctx.file.file2),
+            ),
+            is_executable = True,
+        )
+    return DefaultInfo(
+        executable = test_bin,
+        files = depset(direct = [test_bin]),
+        runfiles = ctx.runfiles(files = [test_bin, ctx.file.file1, ctx.file.file2]),
+    )
+
+_diff_test = rule(
+    attrs = {
+        "file1": attr.label(
+            allow_files = True,
+            mandatory = True,
+            single_file = True,
+        ),
+        "file2": attr.label(
+            allow_files = True,
+            mandatory = True,
+            single_file = True,
+        ),
+        "is_windows": attr.bool(mandatory = True),
+    },
+    test = True,
+    implementation = _diff_test_impl,
+)
+
+def diff_test(name, file1, file2, **kwargs):
+    """A test that compares two files.
+
+    The test succeeds if the files' contents match.
+
+    Args:
+      name: The name of the test rule.
+      file1: Label of the file to compare to <code>file2</code>.
+      file2: Label of the file to compare to <code>file1</code>.
+      **kwargs: The <a href="https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes-tests">common attributes for tests</a>.
+    """
+    _diff_test(
+        name = name,
+        file1 = file1,
+        file2 = file2,
+        is_windows = select({
+            "@bazel_tools//src/conditions:host_windows": True,
+            "//conditions:default": False,
+        }),
+        **kwargs
+    )

tests/diff_test/BUILD

@@ -0,0 +1,42 @@
+# This package aids testing the 'diff_test' rule.
+
+load("//rules:diff_test.bzl", "diff_test")
+
+package(default_testonly = 1)
+
+sh_test(
+    name = "diff_test_tests",
+    srcs = ["diff_test_tests.sh"],
+    data = [
+        "//rules:diff_test",
+        "//tests:unittest.bash",
+    ],
+    deps = ["@bazel_tools//tools/bash/runfiles"],
+)
+
+diff_test(
+    name = "same_src_src",
+    file1 = "a.txt",
+    file2 = "aa.txt",
+)
+
+diff_test(
+    name = "same_src_gen",
+    file1 = "a.txt",
+    file2 = "a-gen.txt",
+)
+
+diff_test(
+    name = "same_gen_gen",
+    file1 = "a-gen.txt",
+    file2 = "aa-gen.txt",
+)
+
+genrule(
+    name = "gen",
+    outs = [
+        "a-gen.txt",
+        "aa-gen.txt",
+    ],
+    cmd = "echo -n 'potato' > $(location a-gen.txt) && echo -n 'potato' > $(location aa-gen.txt)",
+)

tests/diff_test/a.txt

@@ -0,0 +1 @@
+potato

tests/diff_test/aa.txt

@@ -0,0 +1 @@
+potato

tests/diff_test/b.txt

@@ -0,0 +1 @@
+foo

tests/diff_test/diff_test_tests.sh

@@ -0,0 +1,139 @@
+# 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.
+
+# --- begin runfiles.bash initialization ---
+# Copy-pasted from Bazel's Bash runfiles library (tools/bash/runfiles/runfiles.bash).
+set -euo pipefail
+if [[ ! -d "${RUNFILES_DIR:-/dev/null}" && ! -f "${RUNFILES_MANIFEST_FILE:-/dev/null}" ]]; then
+  if [[ -f "$0.runfiles_manifest" ]]; then
+    export RUNFILES_MANIFEST_FILE="$0.runfiles_manifest"
+  elif [[ -f "$0.runfiles/MANIFEST" ]]; then
+    export RUNFILES_MANIFEST_FILE="$0.runfiles/MANIFEST"
+  elif [[ -f "$0.runfiles/bazel_tools/tools/bash/runfiles/runfiles.bash" ]]; then
+    export RUNFILES_DIR="$0.runfiles"
+  fi
+fi
+if [[ -f "${RUNFILES_DIR:-/dev/null}/bazel_tools/tools/bash/runfiles/runfiles.bash" ]]; then
+  source "${RUNFILES_DIR}/bazel_tools/tools/bash/runfiles/runfiles.bash"
+elif [[ -f "${RUNFILES_MANIFEST_FILE:-/dev/null}" ]]; then
+  source "$(grep -m1 "^bazel_tools/tools/bash/runfiles/runfiles.bash " \
+            "$RUNFILES_MANIFEST_FILE" | cut -d ' ' -f 2-)"
+else
+  echo >&2 "ERROR: cannot find @bazel_tools//tools/bash/runfiles:runfiles.bash"
+  exit 1
+fi
+# --- end runfiles.bash initialization ---
+
+source "$(rlocation bazel_skylib/tests/unittest.bash)" \
+  || { echo "Could not source bazel_skylib/tests/unittest.bash" >&2; exit 1; }
+
+function test_diff_test() {
+  local -r ws="${TEST_TMPDIR}/${FUNCNAME[0]}"
+
+  mkdir -p "$ws/rules"
+  ln -sf "$(rlocation bazel_skylib/rules/diff_test.bzl)" "$ws/rules/diff_test.bzl"
+  echo "exports_files(['diff_test.bzl'])" > "$ws/rules/BUILD"
+  touch "$ws/WORKSPACE"
+  cat >"$ws/BUILD" <<'eof'
+load("//rules:diff_test.bzl", "diff_test")
+
+diff_test(
+    name = "same",
+    file1 = "a.txt",
+    file2 = "a.txt",
+)
+
+diff_test(
+    name = "different",
+    file1 = "a.txt",
+    file2 = "b.txt",
+)
+eof
+  echo foo > "$ws/a.txt"
+  echo bar > "$ws/b.txt"
+
+  (cd "$ws" && \
+   bazel test //:same --test_output=errors 1>"$TEST_log" 2>&1 \
+     || fail "expected success")
+
+  (cd "$ws" && \
+   bazel test //:different --test_output=errors 1>"$TEST_log" 2>&1 \
+     && fail "expected failure" || true)
+  expect_log 'FAIL: files "a.txt" and "b.txt" differ'
+}
+
+function test_from_ext_repo() {
+  local -r ws="${TEST_TMPDIR}/${FUNCNAME[0]}"
+
+  mkdir -p "$ws/rules" "$ws/ext1/foo" "$ws/ext2/foo" 
+  ln -sf "$(rlocation bazel_skylib/rules/diff_test.bzl)" "$ws/rules/diff_test.bzl"
+  echo "exports_files(['diff_test.bzl'])" > "$ws/rules/BUILD"
+  cat >"$ws/WORKSPACE" <<'eof'
+local_repository(
+    name = "ext1",
+    path = "ext1",
+)
+
+local_repository(
+    name = "ext2",
+    path = "ext2",
+)
+eof
+
+  # ext1 has source files
+  touch "$ws/ext1/WORKSPACE"
+  echo 'exports_files(["foo.txt"])' >"$ws/ext1/foo/BUILD"
+  echo 'foo' > "$ws/ext1/foo/foo.txt"
+
+  # ext2 has generated files
+  touch "$ws/ext2/WORKSPACE"
+  cat >"$ws/ext2/foo/BUILD" <<'eof'
+genrule(
+    name = "gen",
+    outs = [
+        "foo.txt",
+        "bar.txt",
+    ],
+    cmd = "echo 'foo' > $(location foo.txt) && echo 'bar' > $(location bar.txt)",
+    visibility = ["//visibility:public"],
+)
+eof
+
+  cat >"$ws/BUILD" <<'eof'
+load("//rules:diff_test.bzl", "diff_test")
+
+diff_test(
+    name = "same",
+    file1 = "@ext1//foo:foo.txt",
+    file2 = "@ext2//foo:foo.txt",
+)
+
+diff_test(
+    name = "different",
+    file1 = "@ext1//foo:foo.txt",
+    file2 = "@ext2//foo:bar.txt",
+)
+eof
+
+  (cd "$ws" && \
+   bazel test //:same --test_output=errors 1>"$TEST_log" 2>&1 \
+     || fail "expected success")
+
+  (cd "$ws" && \
+   bazel test //:different --test_output=errors 1>"$TEST_log" 2>&1 \
+     && fail "expected failure" || true)
+  expect_log 'FAIL: files "external/ext1/foo/foo.txt" and "external/ext2/foo/bar.txt" differ'
+}
+
+run_suite "diff_test_tests test suite"