English for Bazel Build System Developers

Bazel’s promise of fast, reproducible builds rests on a vocabulary of hermeticity, dependency graphs, and caching that a team needs shared language for — because “the build is slow” or “the build is flaky” almost always traces back to one of a handful of specific, nameable causes. This guide covers the English used when discussing Bazel configuration with a team.

Key Vocabulary

Target — a named, buildable or testable unit declared in a BUILD file (a library, binary, or test), the basic unit Bazel schedules and caches independently. “Split this into two targets instead of one monolithic library — right now changing an unrelated file forces every dependent target to rebuild.”

Hermeticity — the property of a build depending only on its declared inputs, with no reliance on ambient system state, network access, or unpinned tool versions, which is what makes builds reproducible and cacheable. “This test reads a file from /tmp outside its declared inputs — that breaks hermeticity, which is why it passes locally but fails in the remote cache.”

Build graph — the dependency graph Bazel constructs from declared targets and their dependencies, used to determine what needs rebuilding and what can run in parallel. “Adding this dependency creates a cycle in the build graph — we need to extract the shared piece into its own target that both sides can depend on.”

Remote cache — a shared cache of build and test outputs, keyed by input hashes, that lets one machine reuse another machine’s results instead of rebuilding from scratch. “That target isn’t hitting the remote cache because its action inputs include a timestamp — let’s make the input deterministic so cache hits actually work.”

Sandboxing — running each build action in an isolated environment with only its declared inputs visible, which is how Bazel catches hidden or undeclared dependencies. “Enable sandboxing locally before you debug this — without it, the build might be silently depending on a file that isn’t declared, and you won’t see the problem until CI.”

Visibility — a BUILD file attribute restricting which other targets are allowed to depend on a given target, used to enforce module boundaries in a large monorepo. “Set this target’s visibility to the owning team’s package only — right now anyone in the monorepo can depend on it, which defeats the point of having an internal API.”

Common Phrases

• “Is this a hermetic build, or does it depend on something outside its declared inputs?”
• “Why isn’t this hitting the remote cache — is an input non-deterministic?”
• “Does this dependency introduce a cycle in the build graph?”
• “Can we run this with sandboxing enabled to catch any undeclared dependencies?”
• “Should this target’s visibility be restricted, or does it need to stay public?”

Example Sentences

Reviewing a pull request: “This new target has no visibility restriction, so any package in the monorepo can depend on it — let’s scope it down to the two consumers that actually need it.”

Explaining a design decision: “We split the shared utility library into smaller targets by responsibility, so changing the logging helper doesn’t force a rebuild of every consumer of the larger library.”

Describing an incident: “The build was non-hermetic — a test was reading the system clock directly, which meant cached results were sometimes stale and gave false-positive passes.”

Professional Tips

• Say “hermetic” specifically when a build’s reproducibility is in question — it’s the precise term Bazel engineers use, more specific than “clean” or “isolated.”
• When debugging cache misses, ask “is there a non-deterministic input?” — timestamps, absolute paths, and environment variables are the usual suspects, and naming them speeds up triage.
• Use “build graph” rather than “dependencies” when discussing structural issues like cycles — it signals you’re thinking about the whole DAG, not just one edge.
• Distinguish “sandboxing” (isolating an action’s filesystem access) from “hermeticity” (a property the whole build should have) — sandboxing is a technique that helps enforce hermeticity.

Practice Exercise

1. Explain in two sentences why a non-hermetic build undermines Bazel’s remote cache.
2. Write a one-sentence code review comment flagging an overly broad target visibility.
3. Describe, in your own words, why splitting a monolithic target into smaller ones improves build times.