Skip to content
This repository has been archived by the owner on Mar 20, 2024. It is now read-only.

Home

Jump to bottom
Alex Eagle edited this page Dec 15, 2017 · 10 revisions

Using Bazel

Welcome to Bazel! This is the build tool used at Google for nearly all projects, including all Frontend work. We like it a lot, so much so that ex-googlers have started clones like Pants and Buck, and probably a bunch of others, before Bazel was open-sourced. Now you don’t need to clone it, and can share the same build tooling as the Angular developers at Google.

We find a few key advantages from using Bazel, and all of them are benefits to engineering productivity.

  • Can parallelize a build across workers in the cloud, without touching the Build definitions

  • Builds are highly incremental - typically the work required to re-build is proportional to what you changed

  • Almost never need to “clean” the output tree, so you can stay incremental

  • A CI system can run all the tests affected by a change across a wide range of interdependent packages, and can also be incremental (only re-build what has changed)

  • Plugins, known as rules, are highly composable. You can generally take two different rules written without knowledge of each other, and just plug them together without surprising broken interactions between them

This guide assumes you are already familiar with JS/TypeScript and/or Angular development.

Check out the Getting Started page to set up your computer and your project before proceeding through the guide.

Common operations

Build and test code

The common commands in Bazel are:

  • bazel build [targets]: Compile the default output artifacts of the given targets
  • bazel test [targets]: For whichever *_test targets are found in the patterns, run the tests
  • bazel run [target]: Compile the program represented by target, then run it

To repeat the command any time the inputs change (watch mode), just replace bazel with ibazel in these commands.

The output locations will be printed in the output.

Full documentation for the Bazel CLI is at https://docs.bazel.build/versions/master/command-line-reference.html.

Query the build graph

Since Bazel constructs a graph out of your targets, you can find lots of useful information.

Using the graphviz optional dependency, you'll have a program dot which you can use with bazel query:

$ bazel query --output=graph ... | dot -Tpng > graph.png

See https://docs.bazel.build/versions/master/query-how-to.html for more details on bazel query.

Bazel Rules for Frontend development

"Rules" are like plugins for Bazel. Many rule sets are available. This guide documents the ones maintained by the Angular team at Google.

Rules are used in BUILD.bazel files, which are markers for the packages in your workspace. Each BUILD.bazel file declares a separate package to Bazel, though you could have more coarse-grained distributions so the packages you publish to eg. npm might be made up of many Bazel packages. Note that Bazel also allows these files to be called BUILD, though you should be careful not to have collisions with directories named build since case-insensitive filesystems will do The Wrong Thing.

In the BUILD.bazel file, each rule must first be imported, using the load statement. Then the rule is called with some attributes, and the result of calling the rule is that you've declared to Bazel how it can derive some outputs given some inputs and dependencies. Then later, when you run a bazel command line, Bazel will load all the rules you've declared to determine an absolute ordering of what needs to be run. Note that only the rules needed to produce the requested output will actually be executed.

Coming soon

If you build the code using the rules above, you'll have .d.ts and .js files, but don't know how to use them.

Soon we'll have

  • a karma rule that runs unit tests
  • a protractor rule that runs end-to-end tests against real running server(s)
  • a production bundling/optimizing rule that generates a distribution of the app (or library)

End-to-end example

The repository https://github.com/alexeagle/angular-bazel-example contains the canonical example maintained by the Angular team at Google.

The master branch reflects what parts we suggest trying today. Everything in that branch is supported for registered early adopters of ABC, and is roughly "Beta" quality software (still subject to design changes, and not well documented).

Other branches of this repository demonstrate work-in-progress, such as a devserver, karma testing, and production bundling. These bits are experimental and not supported for use by anyone. During 2017Q4 we expect that these will mature to "beta" status, at which time usage will be demonstrated on the master branch.

Clone this wiki locally