Bazel Codebase Guide for Gemini

Welcome to the Bazel repository. This document provides essential context and workflows for working with the Bazel codebase.

🏗️ Building & Running Bazel

To build Bazel from source, use a pre-installed bazel or bazelisk binary.

  • Fast Iteration Build (Recommended): bazel build //src:bazel-dev
  • Standard Build: bazel build //src:bazel

⚡ Performance Tips

  • Remote Execution: If you have access to a Remote Build Execution (RBE) cluster, use --config=remote to significantly speed up your builds:
    bazel build --config=remote //src:bazel-dev

🔄 Iterative Development Workflow

To test changes safely without interfering with your primary workspace, use a separate binary and output base:

  1. Build and Copy:
    bazel build //src:bazel-dev && cp bazel-bin/src/bazel-dev /tmp/bazel
  2. Run commands:
    /tmp/bazel --output_base=/tmp/ob-dev <command>

Note: Using a custom --output_base (e.g., /tmp/ob-dev) is crucial to avoid locking your main workspace server and ensures your development environment remains isolated.

🧪 Testing

Tests are located primarily in src/test.

Finding Relevant Tests

If you modify a file, find tests that transitively depend on it:

bazel query "rdeps(//src/test/..., path/to/file.java)"

Running Tests

  • Unit Tests: Typically java_test targets.
  • Integration Tests:
    • Java-based: Subclasses of BuildIntegrationTestCase.
    • Shell-based: Located in src/test/shell, using a bash test framework.

📜 Architecture & Codebase

Bazel uses a Client/Server architecture. The client (C++) is a lightweight wrapper that starts and communicates with a long-lived Java server.

  • Skyframe: The incremental evaluation framework. Most core logic is implemented as SkyFunctions evaluating SkyKeys into SkyValues.
  • Starlark: The configuration language used for BUILD and .bzl files.
  • Loading/Analysis/Execution: The three phases of a Bazel command.

For architectural details or introspection capabilities, see: docs/contribute/codebase.mdx

🧹 Linting & Formatting

  • Java: Follows Google Java Style.
  • Starlark: Use buildifier for BUILD and .bzl files.