Update the Bazel project integration guide to capture the new simpler tool. (#5550)

* Update the Bazel project integration guide to capture the new simpler tool.

* Update bazel.md

Co-authored-by: Abhishek Arya <inferno@chromium.org>

1 files changed, 21 insertions, 41 deletions

diff --git a/docs/getting-started/new-project-guide/bazel.md b/docs/getting-started/new-project-guide/bazel.md
index 5422f7b0d..45b942fee 100644
--- a/docs/getting-started/new-project-guide/bazel.md
+++ b/docs/getting-started/new-project-guide/bazel.md
@@ -36,10 +36,9 @@ test artifacts in the OSS-Fuzz format. Each `//path/to:fuzz_test` fuzz test
 target automatically has a `//path/to:fuzz_test_oss_fuzz` packaging target that
 (a) builds the fuzz test using the instrumentation and engine library specified
 in the OSS-Fuzz environment variables, and (b) generates an archive containing
-the binary and its associated artifacts (corpus, dictionary, etc.). Using the
-`_oss_fuzz` target substantially simplifies the `build.sh` script, which only
-needs to copy the build artifacts from `bazel-bin/` to the `${OUT}/` directory.
-The next section explains this process in more detail.
+the binary and its associated artifacts (corpus, dictionary, etc.). Moreover,
+OSS-Fuzz provides a standard tool to automatically process these targets,
+substantially simplifying the `build.sh` script (see below).
 
 [rules-fuzzing-usage]: https://github.com/bazelbuild/rules_fuzzing#using-the-rules-in-your-project
 
@@ -61,7 +60,7 @@ Only C++ projects are currently supported.
 Since the OSS-Fuzz target builds the fuzz test using the instrumentation and
 engine specified in the OSS-Fuzz environment variables, all the engine and
 sanitizer configurations supported in the `project.yaml` file are automatically
-supported by the `_oss_fuzz` packaging rule, too.
+supported by the fuzzing rules.
 
 ### Dockerfile
 
@@ -75,43 +74,24 @@ file in your repository root with the desired version string.
 
 ### build.sh
 
-Your `build.sh` script essentially needs to perform three tasks: (1) selecting
+Your `build.sh` script essentially needs to perform three steps: (1) selecting
 which fuzz tests to build, (2) building their OSS-Fuzz package targets in the
 right configuration, and (3) copying the build artifacts to the `${OUT}/`
 destination.
 
-For the first step, you can use the "bazel query" command for the most
-flexibility. Each fuzz test has the `"fuzz-test"` tag, which you can query. You
-may also perform additional filtering. We recommend using the `"no-oss-fuzz"`
-tag to opt-out particular fuzz tests if they are a work in progress or
-test-only.
-
-The complete query command would look as follows ([example][example-query]):
-
-```sh
-declare -r QUERY='
-    let all_fuzz_tests = attr(tags, "fuzz-test", "//...") in
-    $all_fuzz_tests - attr(tags, "no-oss-fuzz", $all_fuzz_tests)
-'
-declare -r OSS_FUZZ_TESTS="$(bazel query "${QUERY}" | sed "s/$/_oss_fuzz/")"
-```
-
-Building the `_oss_fuzz` targets requires setting the engine and instrumentation
-options. We recommend creating a `--config=oss-fuzz` configuration in your
-`.bazelrc` file ([example][example-bazelrc]), so you can directly invoke
-`bazel build --config=oss-fuzz` in your build script ([example][example-build]).
-
-If all goes well, `bazel-bin/` will contain an `_oss_fuzz.tar` archive for each
-fuzz test built. You need to traverse each archive and extract it in the
-`${OUT}/` directory ([example][example-copy]):
-
-```sh
-for oss_fuzz_archive in $(find bazel-bin/ -name '*_oss_fuzz.tar'); do
-    tar -xvf "${oss_fuzz_archive}" -C "${OUT}"
-done
-```
-
-[example-query]: https://github.com/google/oss-fuzz/blob/b19e7001928b08f9ae8fd3c017688cd5edf96cb2/projects/bazel-rules-fuzzing-test/build.sh#L27-L37
-[example-bazelrc]: https://github.com/bazelbuild/rules_fuzzing/blob/f6062a88d83463e2900e47bc218547ba046dad44/.bazelrc#L56-L58
-[example-build]: https://github.com/google/oss-fuzz/blob/b19e7001928b08f9ae8fd3c017688cd5edf96cb2/projects/bazel-rules-fuzzing-test/build.sh#L43-L45
-[example-copy]: https://github.com/google/oss-fuzz/blob/b19e7001928b08f9ae8fd3c017688cd5edf96cb2/projects/bazel-rules-fuzzing-test/build.sh#L50-L52
+OSS-Fuzz provides a
+[`bazel_build_fuzz_tests`](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/bazel_build_fuzz_tests)
+tool that implements these steps in a standard way, so in most cases your
+build script only needs to invoke this command with no arguments.
+
+If necessary, the behavior of the tool can be customized though a set of
+environment variables. The most common are:
+
+* `BAZEL_EXTRA_BUILD_FLAGS` are extra build flags passed on the Bazel command
+   line.
+* `BAZEL_FUZZ_TEST_TAG` and `BAZEL_FUZZ_TEST_EXCLUDE_TAG` can be overriden to
+  specify which target tags to use when determining what fuzz tests to include.
+  By default, the tool selects all the fuzz tests except for those tagged as
+  `"no-oss-fuzz"`.
+* `BAZEL_FUZZ_TEST_QUERY` overrides the Bazel query the tool uses to identify
+  the fuzz tests to build, if the tag-based approach is not sufficient.