0.3.1 Anatomy of a BUILD File

A BUILD.bazel file is easiest to read as a small declaration with a predictable shape: imports at the top, package-wide defaults if the package needs them, then a flat list of target declarations. This top-to-bottom shape declares what targets exist in the package and how they relate. It is not an execution script.^1,2

load("@rules_java//java:defs.bzl", "java_binary", "java_library")

package(default_visibility = ["//app:__subpackages__"])

java_library(
    name = "core",
    srcs = ["Core.java"],
)

java_binary(
    name = "cli",
    srcs = ["Main.java"],
    main_class = "app.Main",
    deps = [":core"],
)

Read that example in two passes. First, notice the anatomy: load() header, optional package(), then target declarations. Second, notice the meaning of deps = [":core"]: it records that :cli depends on :core. It does not mean "build :core now, then move to the next line." A real file with the shorter load() -> rules shape is app/BUILD.bazel. The visual below combines both reads: file anatomy first, declarative meaning second.

Rule Calls Declare Targets

A BUILD file looks enough like Python that beginners often read it as a script^2,3. When Bazel evaluates a call such as java_library(...), it creates a target declaration in the package with a rule kind, a name, and attributes that other targets can refer to^2,4. It does not immediately compile code.

The rule is the type (java_library). The target is one concrete instance created by calling that rule with name = "core" and the rest of the attributes⁴. Similarly, deps = [":core"] declares a graph edge that Bazel uses later when it analyzes and executes the build. It does not schedule an imperative step^4,5.

During loading, Bazel reads those declarations and derives the target graph. Only later phases turn that graph into concrete actions and decide which ones actually need to run⁵. In simple BUILD files, many declarations can therefore be reordered without changing behavior². The targets and attribute values that exist when package evaluation finishes determine the package description. Bazel can then analyze dependencies, cache results, parallelize independent work, and avoid rebuilding targets whose inputs have not changed⁵.

The Header: load() Then package()

Many BUILD files begin with one or more load() statements, which import symbols from .bzl files into the current file^3,6. The first argument is a label pointing at the .bzl file, so the label syntax from 0.2.1 Label Anatomy already matters before you define a single target⁶. load() belongs at top level, and the style guide treats all load() calls as the first structural block in the file^1,6.

If the package needs defaults, the next slot is package()^1,7. That call does not declare a target. It declares metadata for the whole package, which is why it belongs in the file header rather than mixed into the body below⁷. In Level 0, the default you will most often notice is default_visibility. The detailed semantics are covered in 0.2.6 package() Function.

The Body Is Target Declarations

Below the header, a BUILD file is mostly a series of top-level rule or macro calls. That body reads more like a manifest than a shell script. You are not telling Bazel "first compile this, then run that". You are declaring which targets exist in the package, and with what attribute values, in a form Bazel can analyze later^2,4.

That is also why BUILD files stay intentionally boring. The detailed rule kinds and attribute roles come next in 0.3.2 Rules and 0.3.3 Attributes & Semantic Roles. At this level, the important thing is to recognize that each call contributes one more declaration to the package, not one more step to execute.

The official examples repository makes that progression concrete: its staged C++ tutorial starts with one target, then introduces a library and the explicit deps edge that connects a binary to it.⁸ The directory is tutorial evidence for this declarative shape, not a claim that every real repository should use the same package layout.

Still Starlark, But Deliberately Smaller

BUILD files use Starlark, but not the full language surface you might expect from Python-like syntax^2,3. They cannot contain function definitions, top-level for or if statements, *args / **kwargs, or arbitrary I/O². The restriction is intentional: Bazel wants BUILD-file evaluation to stay hermetic and predictable, and the reduced language makes parallel loading possible without hidden side effects^2,3,4.

BUILD files can still use simple variables, list comprehensions, and if expressions in the limited places Bazel allows². Those constructs are fine when they support target declarations rather than turning the file into a miniature program.

That design choice also explains why BUILD files tend to stay flat. If one starts looking like a small application, move reusable logic into a .bzl file and bring its symbols in with 0.3.5 Load Statements. Later, custom Starlark abstractions provide a structured home for more substantial logic.

Boring BUILD Files Are Easier To Maintain

Explicit, repetitive-looking BUILD files are preferable to clever abstractions^9,10. Duplication is often acceptable because both people and tools such as Buildifier, dependency updaters, and BUILD-file generators maintain these files^9,10.

BUILD files therefore favor DAMP over DRY, keep a simple structural order, and avoid patterns that make target definitions harder to read or rewrite automatically^1,10.

The build-syntax-error snippet makes the parser boundary reproducible. Its unbalanced filegroup fails before target analysis begins.