Add basic implementation of rules_shtk for Bazel

This change brings a new implementation of shtk build rules for Bazel,
namely rules_shtk.

It does so by: adding a new bazel_rules subdirectory, which contains the
code of the rules_shtk; adding a new bazel_examples subdirectory, which
provides end-to-end examples for usage of rules_shtk; and adding a new
integration test (inttest) that leverages the bazel_examples to verify
that the rules work as expected.

.github/workflows/bazel.yml

@@ -0,0 +1,37 @@
+name: Bazel integration
+
+on: [push, pull_request]
+
+jobs:
+    build-rules:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v3
+              with:
+                  path: ~/.cache/bazelisk
+                  key: ${{ runner.os }}--${{ hashFiles('**/.bazelversion') }}
+            - uses: bazelbuild/setup-bazelisk@v2
+            - run: cd bazel_rules && bazel build //...
+
+    build-examples:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v3
+              with:
+                  path: ~/.cache/bazelisk
+                  key: ${{ runner.os }}--${{ hashFiles('**/.bazelversion') }}
+            - uses: bazelbuild/setup-bazelisk@v2
+            - run: cd bazel_examples && bazel build //...
+
+    test-examples:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/cache@v3
+              with:
+                  path: ~/.cache/bazelisk
+                  key: ${{ runner.os }}--${{ hashFiles('**/.bazelversion') }}
+            - uses: bazelbuild/setup-bazelisk@v2
+            - run: make -C bazel_examples

README.md

@@ -46,6 +46,18 @@ this repository, follow the instructions in the
 [INSTALL.md file](INSTALL.md).
 
 
+Bazel integration
+-----------------
+
+The `bazel_rules` directory provides the implementation of `rules_shtk`, a
+collection of build rules for the [Bazel build system](https://bazel.build/)
+to build and run `shtk` scripts.  See their [`README.md`](bazel_rules/README.md)
+for more details on usage.
+
+The `bazel_examples` directory provides sample usage of the rules.  See their
+[`README.md`](bazel_examples/README.md) for more details about them.
+
+
 Documentation
 -------------
 

bazel_examples/.bazelrc

@@ -0,0 +1 @@
+common --enable_bzlmod

bazel_examples/.bazelversion

@@ -0,0 +1 @@
+6.4.0

bazel_examples/.gitignore

@@ -0,0 +1,3 @@
+bazel-*
+inttest
+!Makefile

bazel_examples/BUILD.bazel

@@ -0,0 +1,27 @@
+# Copyright 2023 Julio Merino
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bazel_examples/MODULE.bazel

@@ -0,0 +1,36 @@
+# Copyright 2023 Julio Merino
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module(
+    name = "shtk_examples",
+    version = "0.0.0",
+)
+
+bazel_dep(name = "rules_shtk", version = "1.8.0")
+
+local_path_override(module_name = "rules_shtk", path = "../bazel_rules")

bazel_examples/Makefile

@@ -0,0 +1,46 @@
+# Copyright 2023 Julio Merino
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#
+# Rules to run the integration tests for the examples.
+#
+# We could use Bazel itself to run these tests, but doing so is difficult
+# because we need to run Bazel within Bazel and that's always tricky.
+# That said, while those issues are surmountable, the integration tests
+# themselves would rely on the shtk rules being functional and we cannot
+# trust that they are.
+#
+
+.PHONY: check
+check: inttest
+	@rm -rf tmp && mkdir tmp
+	cd tmp && REAL_HOME=$$HOME WORKSPACE=$$(pwd)/.. ../inttest
+	@rm -rf tmp
+
+inttest: inttest.sh
+	shtk build -m shtk_unittest_main -o $@ $<

bazel_examples/WORKSPACE.bazel

@@ -0,0 +1,32 @@
+# Copyright 2023 Julio Merino
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+load("@rules_shtk//:repositories.bzl", "shtk_configure", "shtk_dist")
+
+shtk_configure()  # Auto-discover installed shtk.
+shtk_dist()  # Download an shtk release.

bazel_examples/binary/BUILD.bazel

@@ -0,0 +1,34 @@
+# Copyright 2023 Julio Merino
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+load("@rules_shtk//:rules.bzl", "shtk_binary")
+
+shtk_binary(
+    name = "simple",
+    src = "hello.sh",
+)

bazel_examples/binary/hello.sh

@@ -0,0 +1,34 @@
+# Copyright 2023 Julio Merino
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+shtk_import cli
+
+
+main() {
+    shtk_cli_info "Hello, world!"
+}

bazel_examples/inttest.sh

@@ -0,0 +1,87 @@
+# Copyright 2023 Julio Merino
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+# * Neither the name of Google Inc. nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+shtk_import cli
+shtk_import unittest
+
+
+one_time_setup() {
+    # REAL_HOME provides access to the Bazel and Bazelisk caches from within this
+    # test program.  While not strictly necessary, this makes these tests much
+    # faster than they would otherwise and minimizes network traffic.
+    [ "${REAL_HOME-unset}" != unset ] \
+        || shtk_cli_error "REAL_HOME must point to the user's home directory"
+
+    # WORKSPACE points to the root of the bazel_examples directory so that we can
+    # run Bazel on it.
+    [ "${WORKSPACE-unset}" != unset ] \
+        || shtk_cli_error "WORKSPACE must point to the bazel_examples directory"
+
+    # Create a fake Bazel binary that is aware of our configuration variables
+    # above.  We do this so that we can invoke this wrapper via assert_command.
+    local real_bazel="$(which bazel)"
+    cat >run_bazel <<EOF
+#! /bin/sh
+cd "${WORKSPACE}"
+export HOME="${REAL_HOME}"
+exec "${real_bazel}" "\${@}"
+EOF
+    chmod +x run_bazel
+}
+
+
+shtk_unittest_add_test binary
+binary_test() {
+    assert_command -o ignore -e ignore ../run_bazel build //binary:simple
+    assert_command -e match:"Hello, world" "${WORKSPACE}/bazel-bin/binary/simple"
+}
+
+
+shtk_unittest_add_test minimum_shtk_version
+minimum_shtk_version_test() {
+    for kind in binary test; do
+        assert_command \
+            -o ignore \
+            -e ignore \
+            ../run_bazel build "//minimum_shtk_version:${kind}_request_older"
+
+        assert_command \
+            -s 1 \
+            -o ignore \
+            -e match:"Target requires shtk >= 1.50 but the toolchain provides 1." \
+            ../run_bazel build "//minimum_shtk_version:${kind}_request_future"
+    done
+
+    assert_command \
+        -e match:"Hello, world" \
+        "${WORKSPACE}/bazel-bin/minimum_shtk_version/binary_request_older"
+
+    assert_command \
+        -e match:"No tests" \
+        "${WORKSPACE}/bazel-bin/minimum_shtk_version/test_request_older"
+}