From df561687f6f31fd53a239864a36e9586cdd80106 Mon Sep 17 00:00:00 2001 From: Stefan Bucur <281483+stefanbucur@users.noreply.github.com> Date: Wed, 31 Mar 2021 20:46:08 -0400 Subject: 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 --- docs/getting-started/new-project-guide/bazel.md | 62 +++++++++---------------- 1 file changed, 21 insertions(+), 41 deletions(-) (limited to 'docs/getting-started') 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. -- cgit v1.2.3