1---
2layout: default
3title: Integrating a Bazel project
4parent: Setting up a new project
5grand_parent: Getting started
6nav_order: 5
7permalink: /getting-started/new-project-guide/bazel/
8---
9
10# Integrating a Bazel project
11{: .no_toc}
12
13- TOC
14{:toc}
15---
16
17## Bazel projects
18
19The process of integrating a project using the [Bazel](https://bazel.build/)
20build system with OSS-Fuzz is very similar to the general
21[Setting up a new project]({{ site.baseurl }}/getting-started/new-project-guide/)
22process. The key specifics of integrating a Bazel project are outlined below.
23
24## Fuzzing support in Bazel
25
26For Bazel-based projects, we recommend using the
27[`rules_fuzzing`](https://github.com/bazelbuild/rules_fuzzing) extension library
28for defining fuzz tests. `rules_fuzzing` provides support for building and running
29fuzz tests under
30[multiple sanitizer and fuzzing engine configurations][rules-fuzzing-usage].
31It also supports specifying corpora and dictionaires as part of the fuzz test
32definition.
33
34The fuzzing rules provide out-of-the-box support for building and packaging fuzz
35test artifacts in the OSS-Fuzz format. Each `//path/to:fuzz_test` fuzz test
36target automatically has a `//path/to:fuzz_test_oss_fuzz` packaging target that
37(a) builds the fuzz test using the instrumentation and engine library specified
38in the OSS-Fuzz environment variables, and (b) generates an archive containing
39the binary and its associated artifacts (corpus, dictionary, etc.). Moreover,
40OSS-Fuzz provides a standard tool to automatically process these targets,
41substantially simplifying the `build.sh` script (see below).
42
43[rules-fuzzing-usage]: https://github.com/bazelbuild/rules_fuzzing#using-the-rules-in-your-project
44
45## Project files
46
47This section explains how to integrate the fuzz tests written using the
48`rules_fuzzing` library with OSS-Fuzz. You can also see a complete example in the
49[`bazel-rules-fuzzing-test`](https://github.com/google/oss-fuzz/tree/master/projects/bazel-rules-fuzzing-test)
50project.
51
52The structure of the project directory in the OSS-Fuzz repository does not
53differ for Bazel-based projects. The project files have the following specific
54aspects.
55
56### project.yaml
57
58Only C++ projects are currently supported.
59
60Since the OSS-Fuzz target builds the fuzz test using the instrumentation and
61engine specified in the OSS-Fuzz environment variables, all the engine and
62sanitizer configurations supported in the `project.yaml` file are automatically
63supported by the fuzzing rules.
64
65### Dockerfile
66
67There is no need to install Bazel in your Docker image. The OSS-Fuzz builder
68image provides the `bazel` executable through the
69[Bazelisk](https://github.com/bazelbuild/bazelisk) launcher, which will fetch
70and use the latest Bazel release. If your project requires a particular Bazel
71version, create a
72[`.bazelversion`](https://docs.bazel.build/versions/master/updating-bazel.html)
73file in your repository root with the desired version string.
74
75### build.sh
76
77Your `build.sh` script essentially needs to perform three steps: (1) selecting
78which fuzz tests to build, (2) building their OSS-Fuzz package targets in the
79right configuration, and (3) copying the build artifacts to the `${OUT}/`
80destination.
81
82OSS-Fuzz provides a
83[`bazel_build_fuzz_tests`](https://github.com/google/oss-fuzz/blob/master/infra/base-images/base-builder/bazel_build_fuzz_tests)
84tool that implements these steps in a standard way, so in most cases your
85build script only needs to invoke this command with no arguments.
86
87If necessary, the behavior of the tool can be customized though a set of
88environment variables. The most common are:
89
90* `BAZEL_EXTRA_BUILD_FLAGS` are extra build flags passed on the Bazel command
91   line.
92* `BAZEL_FUZZ_TEST_TAG` and `BAZEL_FUZZ_TEST_EXCLUDE_TAG` can be overriden to
93  specify which target tags to use when determining what fuzz tests to include.
94  By default, the tool selects all the fuzz tests except for those tagged as
95  `"no-oss-fuzz"`.
96* `BAZEL_FUZZ_TEST_QUERY` overrides the Bazel query the tool uses to identify
97  the fuzz tests to build, if the tag-based approach is not sufficient.
98