Documentation

Edit

Getting Started with Bazel

Setup

Use the installation instructions to install a copy of Bazel on your machine.

Using a Workspace

All Bazel builds take place in a workspace, a directory on your filesystem that contains source code for the software you want to build, as well symbolic links to directories that contain the build outputs (for example, bazel-bin and bazel-out). The location of the workspace directory is not significant, but it must contain a file called WORKSPACE in the top-level directory; an empty file is a valid workspace. The WORKSPACE file can be used to reference external dependencies required to build the outputs. One workspace can be shared among multiple projects if desired.

touch WORKSPACE

Creating a Build File

To know which targets can be built in your project, Bazel inspects BUILD files. They are written in Bazel's build language which is syntactically similar to Python. Usually they are just a sequence of declarations of rules. Each rule specifies its inputs, outputs, and a way to compute the outputs from the inputs.

The rule probably most familiar to people who have used Makefiles before (as it is the only rule available there) is the genrule, which specifies how the output can be generated by invoking a shell command.

genrule(
  name = "hello",
  outs = ["hello_world.txt"],
  cmd = "echo Hello World > $@",
)

The shell command may contain Make variables.

Using the above BUILD file, you can ask Bazel to generate the target.

$ bazel build :hello
.
INFO: Found 1 target...
Target //:hello up-to-date:
  bazel-genfiles/hello_world.txt
INFO: Elapsed time: 2.255s, Critical Path: 0.07s

We note two things. First, targets are normally referred to by their label, which is specified by the name attribute of the rule. (Referencing them by the output file name is also possible, but this is not the preferred way.) Second, Bazel puts the generated files into a separate directory (the bazel-genfiles directory is actually a symbolic link) so as not to pollute your source tree.

Rules may use the output of other rules as input, as in the following example. Again, the generated sources are referred to by their label.

genrule(
  name = "hello",
  outs = ["hello_world.txt"],
  cmd = "echo Hello World > $@",
)

genrule(
  name = "double",
  srcs = [":hello"],
  outs = ["double_hello.txt"],
  cmd = "cat $< $< > $@",
)

Finally, note that, while the genrule might seem familiar, it usually is not the best rule to use. It is preferrable to use one of the specialized rules for various languages.

Next Steps

Next, check out the tutorial on building Java or C++ programs.