Introducing the Codelabs repository

Here is the codelabs repository: https://github.com/aspect-build/codelabs. We're going to add Bazel to it.

By the end of this section, you should have an idea of what code is in this repository, and be able to run the bazel info command in the repo.

Clone the repo

Clone the repo to your machine:

git clone https://github.com/aspect-build/codelabs.git
cd codelabs

The default git branch, called start has an existing monorepo layout but no Bazel yet.

Tour of the logger application

Let's take a quick look around.

This repo contains a logging service, with code in lots of languages, communicating with gRPC. It's meant as a simulation of the kind of monorepo you might start out with in a Bazel migration.

Here are the components of the application:

• schema/ generates code for all languages to agree on the protocol, using protobuf and gRPC.
• backend/ has a server written in Go which stores messages.
• client/ is a sample of a program that wants to store log messages, written in Java.
• frontend/ is a web site written in TypeScript.
• cli/ is a terminal-based frontend for viewing the messages, written in Python.

All of these components have some third-party dependencies, so we'll have to fetch those too!

Our end goal is to make a hypothetical large team of developers productive in this repository, by writing a single integration test in tests/integrationtest.sh which will detect if a developer breaks something in any of the components.

note

Without Bazel, it would be impossible to write an integration test across all these languages in a single build tool.

You won't have time to setup all four languages during this course. Hopefully you feel comfortable in at least one of these languages, and we suggest that you use that one throughout the course. If you have extra time, feel free to try expanding your Bazel setup to more of them!

Demo

Here is what the application looks like once you've got everything working.

First, we startup the Go backend server:

Then we launch the Java client which produces log messages and sends them to the backend:

Now we can run our Python CLI to see the messages so far:

Finally, we can run a TypeScript web frontend and see the messages there too:

Here's what the app looks like in the browser after loading some messages:

Structure of a Bazel project

Definition

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

<workspace-root>/  # This is a workspace
├─ .bazelversion
├─ .bazelrc
├─ BUILD.bazel
├─ WORKSPACE.bazel
├─ bazel-out/
├─ sub-package/
│  └─ BUILD.bazel
└─ 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.

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.

For this codelab, we just need one flag, to enable bzlmod which is opt-in in Bazel 6 and planned to be turned on by default for Bazel 7. We want it to apply to all commands, so we use "common" as the command:

echo common --enable_bzlmod > .bazelrc

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.

% touch WORKSPACE.bazel
% echo "6.0.0" > .bazelversion # As of Dec 2022
% bazel version                # Make sure it's 6.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 only

The bazel docs command opens documentation in your browser. For example, run bazel docs glossary to learn all of Bazel's terminology