---
layout: default
title: FAQ
nav: faq
---

What is Bazel?
-------------

Bazel is a build tool, i.e. a tool that will run compilers and
tests to assemble your software, similar to Make, Ant, Gradle, Buck, Pants,
and Maven.


What is special about Bazel?
-----------------------

Bazel was designed to fit the way software is developed at Google. It
has the following features:

* Multi-language support: Bazel supports Java, Objective-C and C++ out
  of the box, and can be extended to support arbitrary programming
  languages.

* High-level build language: Projects are described in the BUILD
  language, a concise text format that describes a project as sets of
  small interconnected libraries, binaries and tests. By contrast, with
  tools like Make you have to describe individual files and compiler
  invocations.

* Multi-platform support: The same tool and the same BUILD files can
  be used to build software for different architectures, and even
  different platforms.  At Google, we use Bazel to build both server
  applications running on systems in our data centers and client apps
  running on mobile phones.

* Reproducibility: In BUILD files, each library, test, and binary must
  specify its direct dependencies completely.  Bazel uses this
  dependency information to know what must be rebuilt when you make
  changes to a source file, and which tasks can run in parallel.  This
  means that all builds are incremental and will always produce the
  same result.

* Scalable: Bazel can handle large builds; at Google, it is common for
  a server binary to have 100k source files, and builds where no files
  were changed take about ~200ms.


Why doesn't Google use ...?
-----------------------

* Make, Ninja: These tools give very exact control over what commands
  get invoked to build files, but it's up to the user to write rules
  that are correct.

  Users interact with Bazel on a higher level. For example, it has
  built-in rules for "Java test", "C++ binary", and notions such as
  "target platform" and "host platform". The rules have been battle
  tested to be foolproof.

* Ant and Maven: Ant and Maven are primarily geared toward Java, while
  Bazel handles multiple languages.  Bazel encourages subdividing
  codebases in smaller reusable units, and can rebuild only ones that
  need rebuilding. This speeds up development when working with larger
  codebases.

* Gradle: Bazel configuration files are much more structured than
  Gradle's, letting Bazel understand exactly what each action does.
  This allows for more parallelism and better reproducibility.

* Pants, Buck: Both tools were created and developed by ex-Googlers at
  Twitter and Foursquare, and Facebook respectively. They have been modeled
  after Bazel, but their feature sets are different, so they aren't viable
  alternatives for us.


What is Bazel's origin?
-----------------------

Bazel is a flavor of the tool that Google uses to build its server
software internally. It has expanded to also build the client apps
(iOS, Android) that connect to our servers.


Did you rewrite your internal tool as open-source? Is it a fork?
----------------------------------------------------------------

Bazel shares most of its code with the internal tool, and its rules
are used for millions of builds every day.


Why did Google build Bazel?
---------------------------

A long time ago, Google built its software using large, generated
Makefiles. These led to slow and unreliable builds, which began to
interfere with our developers' productivity and the company's
agility. Hence, we built Bazel.


Does Bazel require a build cluster?
-----------------------------------

Google's in-house flavor of Bazel does use [build
clusters](http://google-engtools.blogspot.com/2011/09/build-in-cloud-distributing-build-steps.html),
so Bazel does have hooks in the code base to plug in a remote build
cache or a remote execution system.

The code base we are opening up runs tasks locally. We are confident
that this is fast enough for most of our users.


How does the Google development process work?
----------------------------------------------

For our server code base, we use the following development workflow:

* All of our server code base is in a single, gigantic version control
  system.

* Everybody builds their software with Bazel.

* Different teams own different parts of the source tree, and make
  their components available as BUILD targets.

* Branching is primarily used for managing releases, so everybody
  develops their software at head.

Bazel is a cornerstone of this philosophy: since Bazel requires all
dependencies to be fully specified, we can predict which programs and
tests are affected by a change, and vet them before submission.

More background on the development process at Google can be found on
the [eng tools blog](http://google-engtools.blogspot.com/).


Why are you opening up Bazel?
-----------------------------

Building software should be fun and easy, and slow and unpredictable
builds take the fun out of programming.


Why would I want to use Bazel?
------------------------------

* Bazel may give you faster build times because it can recompile only
  the files that need to be recompiled. Similarly, it can skip
  re-running tests it knows haven't changed.

* Bazel produces deterministic results. This eliminates skew
  between incremental and clean builds, laptop and CI system, etc.

* Bazel can build different client and server apps with the same tool
  from the same workspace. For example, you can change a client/server
  protocol in a single commit, and test that the updated mobile app
  works with the updated server, building both with the same tool,
  reaping all the aforementioned benefits of Bazel.


Can I see examples?
-------------------

Yes, for a simple example, see

  <https://github.com/google/bazel/blob/master/examples/cpp/BUILD>

The bazel source code itself provides more complex examples, eg.

  <https://github.com/google/bazel/blob/master/src/main/java/BUILD>\\
  <https://github.com/google/bazel/blob/master/src/test/java/BUILD>


What is Bazel best at?
----------------------

Bazel shines at building and testing projects with the following properties:

* Projects with a large codebase
* Projects written in (multiple) compiled languages
* Projects that deploy on multiple platforms
* Projects that have extensive tests


On what platforms does Bazel run?
---------------------------------

Currently, Linux and MacOS. Porting to other Unix platforms should be
straightforward, provided a JDK is available for the platform.


What about Windows?
-------------------

We have experimented with a Windows port
[using MinGW/MSYS](docs/windows.html), but have no plans to invest in this
port right now. Due to its Unix heritage, porting Bazel is significant
work. For example, Bazel uses symlinks extensively, which has varying
levels of support across Windows versions.


What should I not use Bazel for?
--------------------------------

* Bazel tries to be smart about caching. This means it is a bad match
  for build steps that should not be cached. For example, the following
  steps should not be controlled from Bazel:

  * A compilation step that fetches data from the internet.
  * A test step that connects to the QA instance of your site.
  * A deployment step that changes your site's cloud configuration.

* Bazel tries to minimize expensive compilation steps. If you are only
  using interpreted languages directly, such as JavaScript or Python,
  Bazel will likely not interest you.


How stable is Bazel's feature set?
--------------------

The core features (C++, Java, and shell rules) have extensive use
inside Google, so they are thoroughly tested and have very little
churn.  Similarly, we test new versions of Bazel across hundreds of
thousands of targets every day to find regressions, and we release new
versions multiple times every month.

In short, except for features marked as experimental, at any point in
time, Bazel should Just Work. Changes to non-experimental rules will
be backward compatible. A more detailed list of feature support
statuses can be found in our [support document](support.html).


How stable is Bazel as a binary?
--------------------

Inside Google, we make sure that Bazel crashes are very rare. This
should also hold for our open-source codebase.


How can I start using Bazel?
----------------------------

See our [getting started document](docs/getting-started.html).


Why do I need to have a tools/ directory in my package path?
------------------------------------------------------------

Your project never works in isolation. Typically, it builds with a
certain version of the JDK/C++ compiler, with a certain test driver
framework, on a certain version of your operating system.

To guarantee builds are reproducible even when we upgrade our
workstations, we at Google check most of these tools into version
control, including the toolchains and Bazel itself. By convention, we
do this in a directory called "tools".

Bazel allows tools such as the JDK to live outside your workspace, but
the configuration data for this (where is the JDK, where is the C++
compiler?) still needs to be somewhere, and that place is also the
`tools/` directory.

Bazel's `compile.sh` script builds a minimal set of configuration files,
suitable for running toolchains from standard system directories, e.g.,
`/usr/bin/`.


Doesn't Docker solve the reproducibility problems?
--------------------------------------------------

With Docker you can easily create sandboxes with fixed OS releases,
eg. Ubuntu 12.04, Fedora 21. This solves the problem of
reproducibility for the system environment (i.e. "which version of
/usr/bin/c++ do I need?").

It does not address reproducibility with regard to changes in the
source code.  Running Make with an imperfectly written Makefile inside a
Docker container can still yield unpredictable results.

Inside Google, we check tools into source control for reproducibility.
In this way, we can vet changes to tools ("upgrade GCC to 4.6.1") with
the same mechanism as changes to base libraries ("fix bounds check in
OpenSSL").


Can I build binaries for deployment on Docker?
----------------------------------------------

With Bazel, you can build standalone, statically linked binaries in
C(++), and self-contained jar files for Java. These run with few
dependencies on normal Unix systems, and as such should be simple to
install inside a Docker container.

Bazel has conventions for structuring more complex programs, e.g., a
Java program that consumes a set of data files, or runs another
program as subprocess. It is possible to package up such environments
as standalone archives, so they can be deployed on different systems,
including Docker images. We currently don't have code to do this,
though.


Can I build Docker images with Bazel?
-------------------------------------

Bazel builds programs such that they are reproducible with respect to
the source tree used to build them.  By design, Bazel does not know
about the environment outside the source tree. Therefore, it does not
know what Docker image would be consistent with its own
environment. So, if you use Bazel with Docker, we recommend to run
Bazel in an environment that resembles the deployment environment to
ensure repeatability.

It is possible to write rules that generate Docker images as files.
However, since Docker images reflect live filesystems, they are full
of timestamps, which makes reproducibility challenging.


Will Bazel make my builds reproducible automatically?
-----------------------------------------------------

For Java and C++ binaries, yes, assuming you do not change the
toolchain. If you have build steps that involve custom recipes
(eg. executing binaries through a shell script inside a rule), you
will need to take some extra care:

  * Do not use dependencies that were not declared. Sandboxed
    execution (--spawn_strategy=sandboxed, only on Linux) can
    help find undeclared dependencies.

  * Avoid storing timestamps in generated files. ZIP files and other
    archives are especially prone to this.

  * Avoid connecting to the network. Sandboxed execution can help here
    too.

  * Avoid processes that use random numbers, in particular, dictionary
    traversal is randomized in many programming languages.


Do you have binary releases?
----------------------------

No, but we should. Stay tuned.


I use Eclipse/IntelliJ. How does Bazel interoperate with IDEs?
--------------------------------------------------------------

We currently have no IDE integration API as such but the iOS rules generate Xcode
projects based on the bazel BUILD targets (see below).

How does Bazel interact with Xcode?
-----------------------------------

Bazel generates Xcode projects that you can use to work with any inputs and
dependencies for the target, build apps from Xcode directly and deploy to the
simulator and devices. To use this, open the project file whose path is printed
by Bazel after building any iOS target. There is no support to invoke Bazel from
Xcode (for example to re-generate generated sources such as Objc files based on
protos), nor to open Xcode from Bazel directly.


I use Jenkins/CircleCI/TravisCI. How does Bazel interoperate with CI systems?
-----------------------------------------------------------------------------

Bazel returns a non-zero exit code if the build or test invocation
fails, and this should be enough for basic CI integration.  Since
Bazel does not need clean builds for correctness, the CI system can
be configured to not clean before starting a build/test run.

Further details on exit codes are in the [User Manual](docs/bazel-user-manual.html).

What future features can we expect in Bazel?
--------------------------------------------

Our initial goal is to work on Google's internal use-cases. This
includes Google's principal languages (C++, Java, Go) and major
platforms (Linux, Android, iOS).  For practical reasons, not all of
these are currently open-sourced. For more details see our
[roadmap](roadmap.html).


What about Python?
------------------

It is possible to write Python rules as extensions (see below). See
the following files for an example of generating self-contained zip
files for python:

  <https://github.com/google/bazel/blob/master/tools/build_rules/py_rules.bzl>\\
  <https://github.com/google/bazel/tree/master/examples/py>

We are working on opening up a subset of our internal Python rules, so
they can be used as helper scripts as part of a build.

We currently have no plans to provide packaging up of self-contained
Python binaries.


What about Go?
--------------

If your codebase is 100% Go, the `go` tool has excellent support for
building and testing, and Bazel will not bring you much benefit.

The server code written in Go at Google is built with Bazel. However,
the rules that accomplish this are rather complex due to their
interactions with our C++ libraries, and are incompatible with the
conventions of the `go` tool.  For this reason, we'd rather not open
them up in their current form.


Can I use Bazel for my LISP/Python/Haskell/Scala/Rust project?
-----------------------------------------------

We have an extension mechanism that allows you to add new rules
without recompiling Bazel.

For documentation: see [here](docs/skylark/index.html).

At present, the extension mechanism is experimental though.


I need more functionality; can I add rules that are compiled into Bazel?
---------------------------------------------

If our extension mechanism is insufficient for your use case, email
the mailing list for advice: <bazel-discuss@googlegroups.com>.


Can I contribute to the Bazel code base?
----------------------------------------

See our [contribution guidelines](contributing.html).


Why isn't all development done in the open?
-------------------------------------------

We still have to refactor the interfaces between the public code in
Bazel and our internal extensions frequently. This makes it hard to do
much development in the open. See our [governance plan](governance.html)
for more details.


How do I contact the team?
--------------------------

We are reachable at <bazel-discuss@googlegroups.com>.


Where do I report bugs?
-----------------------

Send e-mail to <bazel-discuss@googlegroups.com> or file a bug
[on GitHub](https://github.com/google/bazel/issues).


What's up with the word "Blaze" in the codebase?
------------------------------------------------

This is an internal name for the tool. Please refer to Bazel as
Bazel.


Why do other Google projects (Android, Chrome) use other build tools?
---------------------------------------------------------------------

Until now, Bazel was not available externally, so open source projects
such as Chromium, Android, etc. could not use it. In addition, lack of
Windows support is a problem for building Windows applications, such
as Chrome.


How do you pronounce "Bazel"?
-----------------------------

The same way as "basil" (the herb) in US English: "BAY-zel". It rhymes with
"hazel". IPA: /ˈbeɪzˌəl/