Rooba
/
oss-fuzz
mirror of https://github.com/google/oss-fuzz.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Stefan Bucur 2021-03-31 20:46:08 -04:00 committed by GitHub
parent 8c1a588bef
commit df561687f6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 19 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
docs/getting-started/new-project-guide/bazel.md
View File

@ -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.
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.
The complete query command would look as follows ([example][example-query]):
If necessary, the behavior of the tool can be customized though a set of
environment variables. The most common are:
```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
* `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.