Abstract:

This video provides a beginner-friendly, step-by-step tutorial on using the Bazel build tool. Aimed at developers new to build systems, the guide explains core concepts by creating a simple project from the ground up. The tutorial begins with setting up a minimal project structure using WORKSPACE and BUILD files. It then focuses on the creation of a custom build rule in a .bzl file, demonstrating how to define inputs, outputs, and actions. A key highlight is the explanation of Bazel's powerful caching mechanism, showing how explicitly declaring dependencies allows Bazel to intelligently rebuild only what has changed. The video advances to creating a "hermetic" (self-contained and reproducible) build by replacing a system-dependent command with a custom Python script, which is managed as an executable target using Bazel's rules_python. This ensures the build can run reliably across different operating systems. The tutorial concludes by introducing the bazel aquery command for debugging build actions.

A Beginner's Guide to Bazel: From Zero to a Hermetic Build

• 0:02:06 - Minimal Project Setup: A Bazel project is defined by a root WORKSPACE file. Build actions for a package (a directory) are defined in a BUILD file. These two files are all that's needed for a basic project.
• 0:04:57 - Creating a Custom Rule: The core logic of a build step is defined in a custom rule within a .bzl file. This rule can then be imported into a BUILD file using the load command and used to create a specific build action with a unique name.
• 0:11:46 - Defining Inputs and Outputs: A rule is made configurable by adding attributes (e.g., input files, output names). The implementation uses ctx.actions.declare_file to specify an output and ctx.actions.run to execute a command that generates it.
• 0:22:22 - Returning Build Artifacts: For a rule to be valid, its implementation must return a DefaultInfo provider, which tells Bazel which files were generated. This is typically done by wrapping the output files in a depset.
• 0:26:25 - Enabling Intelligent Caching: A crucial feature of Bazel is its ability to cache build results. To enable this, you must explicitly list all file dependencies in the inputs argument of the ctx.actions.run function. This allows Bazel to detect changes and only rebuild when necessary.
• 0:31:57 - Achieving a Hermetic Build with External Tools: To make builds reproducible and cross-platform, you should avoid relying on system-installed tools. The video shows how to add an external dependency (rules_python) to the WORKSPACE file.
• 0:35:30 - Using a Custom Build Tool: A Python script is created to perform the build logic (copying and modifying a file). This script is then defined as an executable target in the BUILD file using the py_binary rule.
• 0:43:34 - Integrating the Custom Tool: The custom rule is updated to accept the py_binary target as an executable attribute. This replaces the hardcoded system command (e.g., cmd.exe) with the self-contained Python tool, ensuring the build works consistently in any environment where Bazel is installed.
• 0:47:50 - Debugging with Aquery: The bazel aquery command is introduced as a powerful debugging tool that allows you to inspect the details of a build action, including the exact command line, inputs, and outputs being used.