Create a repository

Bazel defines a “repository” as a directory tree with a boundary marker file at its root, such as REPO.bazel and MODULE.bazel. This directory contains source files that can be used in a Bazel build. See https://bazel.build/reference/glossary#repository.

You’ll create an empty Bazel repository using Aspect’s template repo. Your work repository will have many similar files, but if it uses an older Bazel version, there will be some differences. For example, older Bazel versions relied on a WORKSPACE file to install plugins.

Bazel repositories are commonly 1:1 with git repositories, so the training uses the term interchangeably. However, it’s possible to have multiple Bazel repositories in the same git repository or even have them nested.

Run init

Aspect CLI only Run bazel init to create a new Bazel repository, and select “Shell (Bash)” along with the other language(s) you want to work in.

If you don't want to install Aspect CLI, you can still continue using the scaffold utility:

% brew tap hay-kot/scaffold-tap % brew install scaffold % scaffold new https://github.com/aspect-build/aspect-workflows-template.git

The command prompts you for which languages and features you want to try out. This 101 course uses Shell (Bash) as the example language because it’s common to most engineers and also because it’s a great scripting language to combine with Bazel’s orchestration powers.

You may also pick languages you already code in regularly, which is useful if you continue in the 100-series courses. Our goal is to learn Bazel, not a new programming language, so don’t overwhelm yourself by adding more languages right now.

When complete, the init command prints useful tips about the newly created repository. In particular, note that a README.bazel.md file was created. This gives developers a quick reference for interacting with the build system. It’s highly recommended that you keep this updated as you evolve the Bazel installation in your repo. Otherwise, your co-workers will quickly get lost!

Before continuing, move into the folder the init command created for the repository.

Temporary files & folders

Due to historical usage with the Perforce version control system at Google, Bazel always puts the files it creates outside the source tree in temporary folders. The info command shows you where Bazel places these on your filesystem.

# print all key-values
% bazel info
...
output_base: /tmp/_bazel_user/[hash]

# See the available keys
% bazel help info-keys

# Print the value of a single key, useful in scripting
% bazel info execution_root

For convenience, Bazel creates symbolic links from the repository root to certain common temporary folders.

• bazel-out → $(bazel info execution_root)/bazel-out
• bazel-bin → bazel-out/[most recent target platform]/bin
• bazel-testlogs → $(bazel info bazel-testlogs)

Standard Bazel files

• MODULE.bazel allows this repository to participate in Bazel’s plugin dependency system (called “bzlmod”), either by publishing a module, or declaring dependencies on existing ones. We’ll cover the details in a later section.
• REPO.bazel is used to specify some common attributes for all build targets inside the repository. This is used with JavaScript to ignore the node_modules folders. See https://bazel.build/rules/lib/globals/repo.
• .bazelversion file indicates what version of Bazel should be used. It typically contains the exact version, to ensure identical results between developers and the CI system. However it’s also possible to use “floating” versions like latest.See the bazelisk documentation.
• .bazelrc stores persistent settings. We’ll cover this in detail in a later section.
• .bazeliskrc is a less commonly-used configuration for Bazelisk, the version-aware wrapper we installed. This is where the Aspect CLI is selected.

In the next sections, you’ll be given an orientation to the remaining files which were created.

Next Lesson