Add test and docs.

pkgs/development/tools/build-managers/bazel/bash-tools-test.nix

@@ -0,0 +1,42 @@
+{ stdenv, writeText, runCommandCC, bazel }:
+
+# Tests that certain executables are available in bazel-executed bash shells.
+
+let
+  WORKSPACE = writeText "WORKSPACE" ''
+    workspace(name = "our_workspace")
+  '';
+
+  fileIn = writeText "input.txt" ''
+  one
+  two
+  three
+  '';
+
+  fileBUILD = writeText "BUILD" ''
+    genrule(
+      name = "tool_usage",
+      srcs = [ ":input.txt" ],
+      outs = [ "output.txt" ],
+      cmd = "cat $(location :input.txt) | gzip - | gunzip - | awk '/t/' > $@",
+    )
+  '';
+
+  runLocal = name: script: runCommandCC name { preferLocalBuild = true; } script;
+
+  workspaceDir = runLocal "our_workspace" ''
+    mkdir $out
+    cp ${WORKSPACE} $out/WORKSPACE
+    cp ${fileIn} $out/input.txt
+    cp ${fileBUILD} $out/BUILD
+  '';
+
+  testBazel = runLocal "bazel-test-bash-tools" ''
+    export HOME=$(mktemp -d)
+    cp -r ${workspaceDir} wd && chmod +w wd && cd wd
+    ${bazel}/bin/bazel build :tool_usage
+    cp bazel-genfiles/output.txt $out
+    echo "Testing content" && [ "$(cat $out | wc -l)" == "2" ] && echo "OK"
+  '';
+
+in testBazel

pkgs/development/tools/build-managers/bazel/default.nix

@@ -24,6 +24,33 @@ let
   '';
 
   defaultShellPath = lib.makeBinPath
+    # Keep this list conservative. For more exotic tools, prefer to use
+    # @rules_nixpkgs to pull in tools from the nix repository. Example:
+    #
+    # WORKSPACE:
+    #
+    #     nixpkgs_git_repository(
+    #         name = "nixpkgs",
+    #         revision = "def5124ec8367efdba95a99523dd06d918cb0ae8",
+    #     )
+    #
+    #     # This defines an external Bazel workspace.
+    #     nixpkgs_package(
+    #         name = "bison",
+    #         repositories = { "nixpkgs": "@nixpkgs//:default.nix" },
+    #     )
+    #
+    # some/BUILD.bazel:
+    #
+    #     genrule(
+    #        ...
+    #        cmd = "$(location @bison//:bin/bison) -other -args",
+    #        tools = [
+    #            ...
+    #            "@bison//:bin/bison",
+    #        ],
+    #     )
+    #
     [ bash coreutils findutils gawk gnugrep gnutar gnused gzip which unzip ];
 
 in
@@ -39,9 +66,14 @@ stdenv.mkDerivation rec {
     platforms = platforms.linux ++ platforms.darwin;
   };
 
-  # additional tests that check bazel’s functionality
+  # Additional tests that check bazel’s functionality. Execute
+  #
+  #     nix-build . -A bazel.tests
+  #
+  # in the nixpkgs checkout root to exercise them locally.
   passthru.tests = {
     pythonBinPath = callPackage ./python-bin-path-test.nix {};
+    bashTools = callPackage ./bash-tools-test.nix {};
   };
 
   name = "bazel-${version}";

pkgs/development/tools/build-managers/bazel/python-bin-path-test.nix

@@ -42,8 +42,10 @@ let
 
   testBazel = runLocal "bazel-test-builtin-rules" ''
     export HOME=$(mktemp -d)
-    cp -r ${workspaceDir}/* .
+    # Note https://github.com/bazelbuild/bazel/issues/5763#issuecomment-456374609
-    ${bazel}/bin/bazel --output_base=/tmp/bazel-tests/wd\
+    # about why to create a subdir for the workspace.
+    cp -r ${workspaceDir} wd && chmod u+w wd && cd wd
+    ${bazel}/bin/bazel \
       test \
         --test_output=errors \
         --host_javabase='@local_jdk//:jdk' \