This repository is an educational, narrative guide to creating a new Bazel project from scratch. The wiki for this repository contains a step-by-step guide that iteratively builds up a Bazel project in bite-sized pieces. We'll cover the basics of Bazel, how to set up your workspace, how to define and build your own targets, and more.
The lessons can be found in the wiki of this repository. They progressively build this repository from an initial empty commit to the current state.
- Lesson 1: Installing Bazel
- Installs Bazel on your machine and sets up the repository as a Bazel project.
- Lesson 2: Creating Packages
- Creates a few basic packages, links them together, and explores the dependency graph.
- Lesson 3: Building Artifacts
- Installs Java and Python, and builds executable binaries with both languages.
- Lesson 4: Dependency Management
- Develops internally usable Java and Python libraries, and downloads external artifacts from Maven Central and PyPI.
- Lesson 5: Executing Tests
- Writes and runs unit tests for both Java and Python code.
- Lesson 6: General Rules
- Explores the built-in general rules provided by Bazel.
- Lesson 7: Authoring Rules
- Extends Bazel by writing custom rules in Starlark.
- Lesson 8: Build Tools
- Introduces
buildifierandbuildozerfor the programmatic manipulation of BUILD and .bzl files.
- Introduces
- Lesson 9: Symbolic Macros
- Extends Bazel by creating a symbolic macro which generates multiple targets at once.
- Lesson 10: Toolchains
- Extends Bazel with rules which have system-specific dependencies.
- Lesson 11: Advanced Toolchains
- Extends Bazel with rules that require their own, language-specific source code.
- Lesson 12: Stardoc
- Generating API documentation for custom Starlark rules.
- Lesson 13: Aspects
- Explores additional routes for dependency metadata to flow through the graph.
- Lesson 14: Modifying The Source Tree
- Develops executable targets that update the repository's source code.
This is intended as an educational resource, not a production-ready project. For the sake of narrative consistency, we'll be pinning versions of most dependencies and Bazel itself. Over time, these will naturally fall out of date- please refer to the official documentation for the most current information.
Furthermore, this guide is not exhaustive. Bazel is a powerful tool that can be used in many different ways and enables developers to build their own tooling, workflows, and more. This guide is intended to help understand the fundamentals of Bazel, not to prescribe a particular toolchain, workflow, or process.
Explicitly pinned tools will be documented below:
- Bazel: 8.3.1
- The build tool this repository describes
- rules_java: 8.12.0
- A Bazel toolchain for the Java Programming Language
- rules_python: 1.6.1
- A Bazel toolchain for the Python Programming Language
- OpenJDK: 21.0.8
- An open-source Java Development Kit
- Python: 3.11.9
- The Python Programming Language
- rules_jvm_external: 6.8
- A Bazel toolchain for managing external Maven dependencies
- Gson: 2.13.2
- A Java library for handling JSON
- json-lineage: 0.2.2
- A Python library for handling JSON
- jUnit: 4.13.2
- A Java testing library and framework
- buildifier: 8.2.1
- A command-line linter for Starlark
- buildozer: 8.2.1
- A command-line tool for manipulating Starlark
- babashka: 1.12.209
- A hosted port of the Clojure Programming language on GraalVM
- platforms: 1.0.0
- A Bazel repository which defines system constraints
- clojure: 1.12.3
- The Clojure Programming Language
- clojure.spec.alpha: 0.5.238
- A Clojure library for schema validation
- clojure.core.specs.alpha: 0.4.74
- A Clojure library containing clojure.spec.alpha definitions for functionality in the core language
- Cheshire: 6.1.0
- A Clojure library for handling JSON
- Stardoc: 0.8.0
- Rules to generate API documentation for Starlark
- Skylib: 1.8.1
- A collection of Starlark utility functions
- bazelisk
- Used to manage the running Bazel version
- Graphviz
- Used to visualize dependency graphs as images.
- jEnv
- Java version manager.
- pyenv
- Python version manager.
This repository, the documentation, and all included code is licensed under the MIT License. That said, it was primarily created for educational purposes, so please use accordingly. See the LICENSE file for more details.