Workspace structure

Structure of a Bazel project

Definition

A Bazel "Workspace" is a file tree rooted at a WORKSPACE or WORKSPACE.bazel marker file.

At the root, a few other Bazel configuration files appear:

<workspace-root>/  # This is a workspace
├─ .bazelversion
├─ .bazelrc
├─ BUILD.bazel
├─ MODULE.bazel
├─ WORKSPACE.bazel
├─ bazel-out/
│  └─ <build results>
└─ sub-workspace/  # And so is this!
   └─ WORKSPACE.bazel

Nested Workspaces are possible, but atypical and discouraged. For the rest of the training, assume: one Workspace <-> one git repository

After a build, Bazel will create subdirectories like /bazel-out. These are symlinks to Bazel's output tree, which lives somewhere else on the disk.

Configuring Bazel's flags

Bazel has an insane number of command-line flags. Even experts are routinely surprised to learn of a new one they hadn't heard of. And many have the wrong default value.

Typically we set these flags in an "rc" file so that we don't have to remember them.

# applies to 'bazel build' as well as 'bazel test' and 'bazel run'
build --some_build_flag=1

# applies only to 'bazel test'
test --some_test_flag=on

# applies to any command (use Bazel 6.4 or greater)
common --other_flag=yes

# Create named configs
# applies only when --config=ci is set
common:ci --this_flag=only-on-CI

In a real project, the flags get hard to organize, so we recommend that the .bazelrc file in your project just import from several rc files.

Read more

bazelrc guide

Ignoring files

You're probably used to .gitignore. Bazel has a similarly named file, but it doesn't understand wildcards. If you decide to implement the JavaScript part of the codelab, you'll need to add node_modules folders to the .bazelignore file to avoid Bazel accidentally walking into this tree if you ask it to do a recursive operation like "build everything in the repo".

Try it: bazel info

It shows you where Bazel installs onto your disk.

% bazel version    # Make sure it's 7.0
% bazel help info  # Better w/ Aspect CLI
% bazel info
bazel-bin: /private/var/tmp/_bazel_alexeagle/d9ca1c4a6ff5b50680a67b9c3f6b217b/execroot/__main__/bazel-out/darwin_arm64-fastbuild/bin
# See the available keys
% bazel help info-keys
# You can print the value of a single key as well
% bazel info execution_root
...

Aspect CLI

This repository is configured to use the Aspect CLI rather than "vanilla Bazel". It's meant to improve your experience, while remaining fully backwards compatible. You could go back to "vanilla Bazel" at any time.

Any commands in the course that aren't present on "vanilla Bazel" will be noted like this:

Aspect CLI only

The bazel docs command opens documentation in your browser.

For example, run bazel docs glossary to learn all of Bazel's terminology.

Run bazel docs aspect_rules_js to see documentation for @aspect_rules_js loads.