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. The important catch is that this top-to-bottom shape is not an execution script. A BUILD file tells Bazel what targets exist in the package and how they relate, so Bazel can derive the build graph later.^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.

First Fix The Mental Model

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

That distinction is why the word target matters. 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⁴. The same goes for deps: deps = [":core"] does not schedule an imperative step. It declares a graph edge that Bazel uses later when it analyzes and executes the build^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². What matters is not "which line ran first", but which targets and attribute values exist by the time package evaluation finishes. Once Bazel has that description, it can 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.

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.

Declarative does not mean "no syntax at all". 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 the file starts looking like a small application, it is probably carrying logic that belongs in 0.3.5 Load Statements or, later, in custom Starlark abstractions rather than in the BUILD file itself.