Introduction to Bazel: Building a Java Project

In this tutorial, you’ll learn the basics of building Java applications with
Bazel. You will set up your workspace and build a simple Java project that
illustrates key Bazel concepts, such as targets and BUILD files.

Build with Bazel

Set up the workspace

Before you can build a project, you need to set up its workspace. A workspace is
a directory that holds your project’s source files and Bazel’s build outputs. It
also contains files that Bazel recognizes as special:

The WORKSPACE file, which identifies the directory and its contents as a
Bazel workspace and lives at the root of the project’s directory structure,

One or more BUILD files, which tell Bazel how to build different parts of
the project. (A directory within the workspace that contains a BUILD file
is a package. You will learn about packages later in this tutorial.)

To designate a directory as a Bazel workspace, create an empty file named
WORKSPACE in that directory.

When Bazel builds the project, all inputs and dependencies must be in the same
workspace. Files residing in different workspaces are independent of one
another unless linked, which is beyond the scope of this tutorial.

Understand the BUILD file

A BUILD file contains several different types of instructions for Bazel.
The most important type is the build rule, which tells Bazel how to build the
desired outputs, such as executable binaries or libraries. Each instance
of a build rule in the BUILD file is called a target and points to a
specific set of source files and dependencies. A target can also point to other
targets.

In our example, the ProjectRunner target instantiates Bazel’s built-in
java_binary rule. The rule tells Bazel to
build a .jar file and a wrapper shell script (both named after the target).

The attributes in the target explicitly state its dependencies and options.
While the name attribute is mandatory, many are optional. For example, in the
ProjectRunner rule target, name is the name of the target, srcs specifies
the source files that Bazel uses to build the target, and main_class specifies
the class that contains the main method. (You may have noticed that our example
uses glob to pass a set of source files to Bazel
instead of listing them one by one.)

Build the project

Let’s build your sample project. Change into the java-tutorial directory
and run the following command:

bazel build //:ProjectRunner

Notice the target label - the // part is the location of our BUILD file
relative to the root of the workspace (in this case, the root itself), and
ProjectRunner is what we named that target in the BUILD file. (You will
learn about target labels in more detail at the end of this tutorial.)

Congratulations, you just built your first Bazel target! Bazel places build
outputs in the bazel-bin directory at the root of the workspace. Browse
through its contents to get an idea for Bazel’s output structure.

As you can see, the project has a single target that build two source files with
no additional dependencies:

Now that you have set up your workspace, built your project, and examined its
dependencies, let’s add some complexity.

Refine your Bazel build

While a single target is sufficient for small projects, you may want to split
larger projects into multiple targets and packages to allow for fast incremental
builds (that is, only rebuild what’s changed) and to speed up your builds by
building multiple parts of a project at once.

Specify multiple build targets

Let’s split our sample project build into two targets. Replace the contents of
the java-tutorial/BUILD file with the following:

With this configuration, Bazel first builds the greeter library, then the
ProjectRunner binary. The deps attribute in java_binary tells Bazel that
the greeter library is required to build the ProjectRunner binary.

Let’s build this new version of our project. Run the following command:

If you now modify ProjectRunner.java and rebuild the project, Bazel only
recompiles that file.

Looking at the dependency graph, you can see that ProjectRunner depends on the
same inputs as it did before, but the structure of the build is different:

You’ve now built the project with two targets. The ProjectRunner target builds
two source files and depends on one other target (:greeter), which builds
one additional source file.

Use multiple packages

Let’s now split the project into multiple packages. If you take a look at the
src/main/java/com/example/cmdline directory, you can see that it also contains
a BUILD file, plus some source files. Therefore, to Bazel, the workspace now
contains two packages, //src/main/java/com/example/cmdline and // (since
there is a BUILD file at the root of the workspace).

The runner target depends on the greeter target in the // package (hence
the target label //:greeter) - Bazel knows this through the deps attribute.
Take a look at the dependency graph:

However, for the build to succeed, you must explicitly give the runner target in
//src/main/java/com/example/cmdline/BUILD visibility to targets in
//BUILD using the visibility attribute. This is because by default targets
are only visible to other targets in the same BUILD file. (Bazel uses target
visibility to prevent issues such as libraries containing implementation details
leaking into public APIs.)

To do this, add the visibility attribute to the greeter target in
java-tutorial/BUILD as shown below:

You’ve now modified the project to build as two packages, each containing one
target, and understand the dependencies between them.

Use labels to reference targets

In BUILD files and at the command line, Bazel uses target labels to reference
targets - for example, //:ProjectRunner or
//src/main/java/com/example/cmdline:runner. Their syntax is as follows:

//path/to/package:target-name

If the target is a rule target, then path/to/package is the path to the
directory containing the BUILD file, and target-name is what you named the
target in the BUILD file (the name attribute). If the target is a file
target, then path/to/package is the path to the root of the package, and
target-name is the name of the target file, including its full path.

When referencing targets within the same package, you can skip the package path
and just use //:target-name. When referencing targets within the same BUILD
file, you can even skip the // workspace root identifier and just use
:target-name.

For example, for targets in the java-tutorial/BUILD file, you did not have to
specify a package path, since the workspace root is itself a package (//), and
your two target labels were simply //:ProjectRunner and //:greeter.

However, for targets in the //src/main/java/com/example/cmdline/BUILD file you
had to specify the full package path of //src/main/java/com/example/cmdline
and your target label was //src/main/java/com/example/cmdline:runner.

Package a Java target for deployment

Let’s now package a Java target for deployment by building the binary with all
of its runtime dependencies. This lets you run the binary outside of your
development environment.

As you remember, the java_binary build rule
produces a .jar and a wrapper shell script. Take a look at the contents of
runner.jar using this command:

As you can see, runner.jar contains Runner.class, but not its dependency,
Greeting.class. The runner script that Bazel generates adds greeter.jar
to the classpath, so if you leave it like this, it will run locally, but it
won’t run standalone on another machine. Fortunately, the java_binary rule
allows you to build a self-contained, deployable binary. To build it, add the
_deploy.jar suffix to the file name when building runner.jar
(_deploy.jar):