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 include JavaScript in your repository, 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 repository".

Try it: bazel info

It shows you where Bazel installs onto your disk.

% bazel version    # Make sure it's 7.x
% 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
...