layout | title |
---|---|
contribute |
Contributing to Bazel |
There are many ways to help the Bazel project and ecosystem.
-
Provide feedback as you use Bazel. As you use it, you may find things that can be improved. Please report them:
- Report bugs. In particular, it's important to report any crash or correctness bug.
- Report issues when the documentation is incomplete or unclear.
- Report issues when an error message could be improved.
-
As you get experienced with Bazel, engage with the community:
- Answer questions on Stack Overflow.
- Help other users on Slack.
- Improve the documentation or contribute examples.
- Share your experience or your tips, for example on a blog or social media.
-
Contribute to the Bazel ecosystem:
- Help rules maintainers by contributing pull requests.
- Create new rules and open-source them.
- Contribute to Bazel-related tools, for example migration tools.
- Improve Bazel integration with other IDEs and tools.
Bazel is a large project and making a significant change to Bazel source code can be difficult. Please check with us on the dev list or on a GitHub issue before investing a lot of time in a patch.
In general, we prefer contributions that fix bugs or add features (as opposed to stylistic, refactoring, or "cleanup" changes). When making a change, please include tests and documentation, and keep in mind backward-compatibility, portability, as well as the impact on memory usage and performance.
- Read the Bazel governance plan.
- Discuss your plan and design, and get agreement on a GitHub issue or our mailing list. Significant changes need a design document.
- Prepare a git commit that implements the feature. Don't forget to add tests.
- Ensure you've signed a Contributor License Agreement.
- Send us a pull request on GitHub. If you're new to GitHub, read about pull requests. Note that we restrict permissions to create branches on the main Bazel repository, so you will need to push your commit to your own fork of the repository.
- Wait for a Bazel team member to assign you a reviewer. It should be done in 2 business days (excluding holidays in the USA and Germany). If you do not get a reviewer within that time frame, you can ask for one by sending a mail to [email protected].
- Work with the reviewer to complete a code review. For each change, create a new commit and push it to make changes to your pull request. If the review takes too long (e.g. reviewer is unresponsive), please also send an email to [email protected].
- A Bazel maintainer at Google will apply the patch to our internal version control system. The patch is exported as a Git commit, at which point the GitHub pull request is closed.
If your change has user-visible effects, consider adding release notes. If it is an incompatible change, read the guide for rolling out breaking changes.
For now we have support for IntelliJ. We don't have IDE support for other languages in Bazel right now.
-
Install Bazel on your system. Note that for developing Bazel, you need the latest released version of Bazel.
-
Clone Bazel's Git repository from GitHub:
git clone https://github.com/bazelbuild/bazel.git
-
Try to build Bazel:
-
On Linux/macOS, in Bash/Terminal:
cd bazel bazel build //src:bazel
-
On Windows, in the Command Prompt:
cd bazel bazel --output_user_root=c:\tmp build //src:bazel.exe
For faster iteration times (but larger binaries), use
//src:bazel-dev.exe
instead.
-
-
This will produce a working Bazel binary in
bazel-bin/src/bazel
(orbazel-bin/src/bazel.exe
on Windows).
To work with IntelliJ:
- Install Bazel's IntelliJ plug-in.
- Set the path to the Bazel binary in the plugin preferences
(
Preferences
>Other Settings
>Bazel Settings
). - Import the Bazel workspace as a Bazel project
(
File
>Import Bazel Project...
) with the following settings:- Use existing Bazel workspace: choose your cloned Git repository.
- Select
Import from workspace
and choose thescripts/ij.bazelproject
file as theProject view
.
- Download Google's Java Code Style Scheme file for IntelliJ,
import it (go to
Preferences
>Editor
>Code Style
>Java
, clickManage
, thenImport
) and use it when working on Bazel's code.
To test out Bazel, you need to compile it. To compile a development version of Bazel, you need a the latest released version of Bazel, which can be compiled from source.
bazel build //src:bazel
builds the Bazel binary using bazel
from your PATH
and the resulting binary can be found at bazel-bin/src/bazel
. This is the
recommended way of rebuilding Bazel once you have bootstrapped it.
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 their directories contain README files describing their
respective utility.
When modifying Bazel, you want to make sure that the following still works:
- Build a distribution archive with
bazel build //:bazel-distfile
. After unzipping it in a new empty directory, runbash compile.sh all
there. It rebuilds Bazel with./compile.sh
, Bazel with thecompile.sh
Bazel and Bazel with the Bazel-built binary. It compares if the constructed Bazel builts are identical and then runs all Bazel tests withbazel test //src/... //third_party/ijar/...
. This is what we use at Google to ensure that we don't break Bazel when pushing new commits, too.
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 run it from gdb or lldb as you normally would. But if you want to debug the Java code, you must attach to the server using the following:
- Run Bazel with debugging option
--host_jvm_debug
before the command (e.g.,bazel --host_jvm_debug build //src:bazel
). - Attach a debugger to the port 5005. With
jdb
for instance, runjdb -attach localhost:5005
. - Our IntelliJ plugin has built-in debugging support
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
andsrc/test/java
.- Core code which is mostly composed of SkyFrame and some utilities.
- Builtin rules in
com.google.devtools.build.lib.rules
and incom.google.devtools.build.lib.bazel.rules
. You might want to read about the Challenges of Writing Rules first.
- Java native interfaces in
src/main/native
. - Various tooling for language support (see the list in the compiling Bazel section).
To quickly search through Bazel's source code, use Bazel Code Search. You can navigate Bazel's repositories, branches, and files. You can also view history, diffs, and blame information. To learn more, see the Bazel Code Search User Guide.
To get started with the Bazel CI system, see Bazel Continuous Integration. To monitor the tests and builds of your Bazel contributions, use the Bazel CI Dashboard.