layout: community

Contributing to Bazel

How can I contribute to Bazel?

In general, we prefer contributions that fix bugs or add features (as opposed to stylistic, refactoring, or “cleanup” changes). Please check with us on the dev list before investing a lot of time in a patch.

Patch Acceptance Process

We will make changes to this process as necessary, and we're hoping to move closer to a fully open development model in the future (also see Is Bazel developed fully in the open?).

Setting up your coding environment

Note that some of our tests target Java 8 so you must test using a JDK 8.

For now we have partial support for the Eclipse and IntelliJ IDEs for Java. We don't have IDE support for other languages in Bazel right now.

Creating an Eclipse project

To work with Eclipse, run sh scripts/setup-eclipse.sh from the root of the source tree and it will create the .project and the .classpath files (if a .project file is present, only the .classpath will get overwritten). You can then import the project in Eclipse.

You might see some errors in Eclipse concerning Truth assertions.

Creating an IntelliJ project

To work with IntelliJ, run sh scripts/setup-intellij.sh from the root of the source tree and it will create the necessary project files. You can then open the folder as a project in IntelliJ.

Compiling Bazel

To test out bazel, you need to compile it. There is currently two ways of compiling it:

  • sh compile.sh build a Bazel binary without Bazel, it should only be used to bootstrap Bazel itself. The resulting binary can be found at output/bazel.
  • bazel build //src:bazel builds the Bazel binary using Bazel and the resulting binary can be found at bazel-bin/src/bazel.

In addition to the Bazel binary, you might want to build the various tools Bazel uses. They are located in //src/java_tools, //src/objc_tools and //src/tools and contains README files describing their respective utility.

When modifying Bazel, you want to make sure that the following still works:

  • Bootstrap test with sh compile.sh all after having removed the output directory: it rebuilds Bazel with ./compile.sh, Bazel with the compile.sh Bazel and Bazel with the Bazel-built binary. It compares if the constructed Bazel builts are identical and then run all bazel tests with bazel test //src/... //third_party/ijar/....

Debugging Bazel

Start creating a debug configuration for both C++ and Java in your bazelrc with the following:

build:debug -c dbg
build:debug --javacopt="-g"
build:debug --copt="-g"
build:debug --strip="never"

Then you can rebuild Bazel with bazel build --config debug //src:bazel and use your favorite debugger to start debugging.

For debugging the C++ client you can just fire it from gdb or lldb as you normally would. But if you want to debug the Java code, you must attach to the server with the following:

  • Run Bazel with debugging option --host_jvm_debug before the command (e.g., bazel --batch --host_jvm_debug build //src:bazel).
  • Attach a debugger to the port 5005. With jdb for instance, run jdb -attach localhost:5005. From within Eclipse, use the remote Java application launch configuration.

Bazel's code description

Bazel is organized in several parts:

  • Client code in src/main/cpp provides the command-line interface.
  • Protocol buffers in src/main/protobuf.
  • Server code in src/main/java and src/test/java.
    • Core code which is mostly composed of SkyFrame and some utilities.
    • Skylark rules are defined in tools/build_rules. If you want to add rules, consider using Skylark first.
    • Builtin rules in com.google.devtools.build.lib.rules and in com.google.devtools.build.lib.bazel.rules.
  • Java native interfaces in src/main/native.
  • Various tooling for language support (see the list in the compiling Bazel section).