Action
A command to run during the build, for example, a call to a compiler that takes artifacts as inputs and produces other artifacts as outputs. Includes metadata like the command line arguments, action key, environment variables, and declared input/output artifacts.
See also: Rules documentation
Action cache
An on-disk cache that stores a mapping of executed actions to the outputs they created. The cache key is known as the action key. A core component for Bazel's incrementality model. The cache is stored in the output base directory and thus survives Bazel server restarts.
Action graph
An in-memory graph of actions and the artifacts that
these actions read and generate. The graph might include artifacts that exist as
source files (for example, in the file system) as well as generated
intermediate/final artifacts that are not mentioned in BUILD files. Produced
during the analysis phase and used during the execution
phase.
Action graph query (aquery)
A query tool that can query over build actions. This provides the ability to analyze how build rules translate into the actual work builds do.
Action key
The cache key of an action. Computed based on action metadata, which might include the command to be executed in the action, compiler flags, library locations, or system headers, depending on the action. Enables Bazel to cache or invalidate individual actions deterministically.
Analysis phase
The second phase of a build. Processes the target graph
specified in BUILD files to produce an in-memory action
graph that determines the order of actions to run during the
execution phase. This is the phase in which rule
implementations are evaluated.
Artifact
A source file or a generated file. Can also be a directory of files, known as tree artifacts.
An artifact may be an input to multiple actions, but must only be generated by at most one action.
An artifact that corresponds to a file target can be addressed by a label.
Aspect
A mechanism for rules to create additional actions in their
dependencies. For example, if target A depends on B, one can apply an aspect on
A that traverses up a dependency edge to B, and runs additional actions in B
to generate and collect additional output files. These additional actions are
cached and reused between targets requiring the same aspect. Created with the
aspect() Starlark Build API function. Can be used, for example, to generate
metadata for IDEs, and create actions for linting.
See also: Aspects documentation
Aspect-on-aspect
A composition mechanism whereby aspects can be applied to the results
of other aspects. For example, an aspect that generates information for use by
IDEs can be applied on top of an aspect that generates .java files from a
proto.
For an aspect A to apply on top of aspect B, the providers that
B advertises in its provides attribute
must match what A declares it wants in its required_aspect_providers
attribute.
Attribute
A parameter to a rule, used to express per-target build information.
Examples include srcs, deps, and copts, which respectively declare a
target's source files, dependencies, and custom compiler options. The particular
attributes available for a given target depend on its rule type.
.bazelrc
Bazel’s configuration file used to change the default values for startup
flags and command flags, and to define common
groups of options that can then be set together on the Bazel command line using
a --config flag. Bazel can combine settings from multiple bazelrc files
(systemwide, per-workspace, per-user, or from a custom location), and a
bazelrc file may also import settings from other bazelrc files.
Blaze
The Google-internal version of Bazel. Google’s main build system for its mono-repository.
BUILD File
A BUILD file is the main configuration file that tells Bazel what software
outputs to build, what their dependencies are, and how to build them. Bazel
takes a BUILD file as input and uses the file to create a graph of dependencies
and to derive the actions that must be completed to build intermediate and final
software outputs. A BUILD file marks a directory and any sub-directories not
containing a BUILD file as a package, and can contain
targets created by rules. The file can also be named
BUILD.bazel.
BUILD.bazel File
See BUILD File. Takes precedence over a BUILD file in the same
directory.
.bzl File
A file that defines rules, macros, and constants written in
Starlark. These can then be imported into BUILD
files using the load() function.
Build graph
The dependency graph that Bazel constructs and traverses to perform a build. Includes nodes like targets, configured targets, actions, and artifacts. A build is considered complete when all artifacts on which a set of requested targets depend are verified as up-to-date.
Build setting
A Starlark-defined piece of configuration. Transitions can set build settings to change a subgraph's configuration. If exposed to the user as a command-line flag, also known as a build flag.
Clean build
A build that doesn't use the results of earlier builds. This is generally slower than an incremental build but commonly considered to be more correct. Bazel guarantees both clean and incremental builds are always correct.
Client-server model
The bazel command-line client automatically starts a background server on the
local machine to execute Bazel commands. The server persists across
commands but automatically stops after a period of inactivity (or explicitly via
bazel shutdown). Splitting Bazel into a server and client helps amortize JVM
startup time and supports faster incremental builds
because the action graph remains in memory across commands.
Command
Used on the command line to invoke different Bazel functions, like bazel
build, bazel test, bazel run, and bazel query.
Command flags
A set of flags specific to a command. Command flags are specified
after the command (bazel build <command flags>). Flags can be applicable to
one or more commands. For example, --configure is a flag exclusively for the
bazel sync command, but --keep_going is applicable to sync, build,
test and more. Flags are often used for configuration
purposes, so changes in flag values can cause Bazel to invalidate in-memory
graphs and restart the analysis phase.
Configuration
Information outside of rule definitions that impacts how rules generate actions. Every build has at least one configuration specifying the target platform, action environment variables, and command-line build flags. Transitions may create additional configurations, such as for host tools or cross-compilation.
See also: Configurations
Configuration trimming
The process of only including the pieces of configuration a
target actually needs. For example, if you build Java binary //:j with C++
dependency //:c, it's wasteful to include the value of --javacopt in the
configuration of //:c because changing --javacopt unnecessarily breaks C++
build cacheability.
Configured query (cquery)
A query tool that queries over configured
targets (after the analysis phase
completes). This means select() and build flags (such as
--platforms) are accurately reflected in the results.
See also: cquery documentation
Configured target
The result of evaluating a target with a
configuration. The analysis phase produces
this by combining the build's options with the targets that need to be built.
For example, if //:foo builds for two different architectures in the same
build, it has two configured targets: <//:foo, x86> and <//:foo, arm>.
Correctness
A build is correct when its output faithfully reflects the state of its transitive inputs. To achieve correct builds, Bazel strives to be hermetic, reproducible, and making build analysis and action execution deterministic.
Dependency
A directed edge between two targets. A target //:foo has a target
dependency on target //:bar if //:foo's attribute values contain a
reference to //:bar. //:foo has an action dependency on //:bar if an
action in //:foo depends on an input artifact created by an
action in //:bar.
In certain contexts, it could also refer to an external dependency; see modules.
Depset
A data structure for collecting data on transitive dependencies. Optimized so that merging depsets is time and space efficient, because it’s common to have very large depsets (hundreds of thousands of files). Implemented to recursively refer to other depsets for space efficiency reasons. Rule implementations should not "flatten" depsets by converting them to lists unless the rule is at the top level of the build graph. Flattening large depsets incurs huge memory consumption. Also known as nested sets in Bazel's internal implementation.
See also: Depset documentation
Disk cache
A local on-disk blob store for the remote caching feature. Can be used in conjunction with an actual remote blob store.
Distdir
A read-only directory containing files that Bazel would otherwise fetch from the internet using repository rules. Enables builds to run fully offline.
Dynamic execution
An execution strategy that selects between local and remote execution based on various heuristics, and uses the execution results of the faster successful method. Certain actions are executed faster locally (for example, linking) and others are faster remotely (for example, highly parallelizable compilation). A dynamic execution strategy can provide the best possible incremental and clean build times.
Execution phase
The third phase of a build. Executes the actions in the action graph created during the analysis phase. These actions invoke executables (compilers, scripts) to read and write artifacts. Spawn strategies control how these actions are executed: locally, remotely, dynamically, sandboxed, docker, and so on.
Execution root
A directory in the workspace’s output base
directory where local actions are executed in
non-sandboxed builds. The directory contents are mostly symlinks
of input artifacts from the workspace. The execution root also
contains symlinks to external repositories as other inputs and the bazel-out
directory to store outputs. Prepared during the loading phase
by creating a symlink forest of the directories that represent the transitive
closure of packages on which a build depends. Accessible with bazel info
execution_root on the command line.
File
See Artifact.
Hermeticity
A build is hermetic if there are no external influences on its build and test operations, which helps to make sure that results are deterministic and correct. For example, hermetic builds typically disallow network access to actions, restrict access to declared inputs, use fixed timestamps and timezones, restrict access to environment variables, and use fixed seeds for random number generators
Incremental build
An incremental build reuses the results of earlier builds to reduce build time and resource usage. Dependency checking and caching aim to produce correct results for this type of build. An incremental build is the opposite of a clean build.
Label
An identifier for a target. Generally has the form
@repo//path/to/package:target, where repo is the (apparent) name of the
repository containing the target, path/to/package is the path
to the directory that contains the BUILD file declaring the
target (this directory is also known as the package), and target
is the name of the target itself. Depending on the situation, parts of this
syntax may be omitted.
See also: Labels
Loading phase
The first phase of a build where Bazel executes BUILD files to
create packages. Macros and certain functions like
glob() are evaluated in this phase. Interleaved with the second phase of the
build, the analysis phase, to build up a target
graph.
Legacy macro
A flavor of macro which is declared as an ordinary
Starlark function, and which runs as a side effect of executing a
BUILD file.
Legacy macros can do anything a function can. This means they can be convenient,
but they can also be harder to read, write, and use. A legacy macro might
unexpectedly mutate its arguments or fail when given a select() or ill-typed
argument.
Contrast with symbolic macros.
See also: Legacy macro documentation
Macro
A mechanism to compose multiple rule target declarations together under
a single Starlark callable. Enables reusing common rule declaration
patterns across BUILD files. Expanded to the underlying rule target
declarations during the loading phase.
Comes in two flavors: symbolic macros (since Bazel 8) and legacy macros.
Mnemonic
A short, human-readable string selected by a rule author to quickly understand
what an action in the rule is doing. Mnemonics can be used as
identifiers for spawn strategy selections. Some examples of action mnemonics
are Javac from Java rules, CppCompile from C++ rules, and
AndroidManifestMerger from Android rules.
Module
A Bazel project that can have multiple versions, each of which can have dependencies on other modules. This is analogous to familiar concepts in other dependency management systems, such as a Maven artifact, an npm package, a Go module, or a Cargo crate. Modules form the backbone of Bazel's external dependency management system.
Each module is backed by a repo with a MODULE.bazel file at its
root. This file contains metadata about the module itself (such as its name and
version), its direct dependencies, and various other data including toolchain
registrations and module extension input.
Module metadata is hosted in Bazel registries.
See also: Bazel modules
Module Extension
A piece of logic that can be run to generate repos by reading inputs from across the module dependency graph and invoking repo rules. Module extensions have capabilities similar to repo rules, allowing them to access the internet, perform file I/O, and so on.
See also: Module extensions
Native rules
Rules that are built into Bazel and implemented in Java. Such rules
appear in .bzl files as functions in the native module (for
example, native.cc_library or native.java_library). User-defined rules
(non-native) are created using Starlark.
Output base
A workspace-specific directory to store Bazel output files. Used to separate outputs from the workspace's source tree (the main repo). Located in the output user root.
Output groups
A group of files that is expected to be built when Bazel finishes building a
target. Rules put their usual outputs in the "default output group"
(e.g the .jar file of a java_library, .a and .so for cc_library
targets). The default output group is the output group whose
artifacts are built when a target is requested on the command line.
Rules can define more named output groups that can be explicitly specified in
BUILD files (filegroup rule) or the command line
(--output_groups flag).
Output user root
A user-specific directory to store Bazel's outputs. The directory name is derived from the user's system username. Prevents output file collisions if multiple users are building the same project on the system at the same time. Contains subdirectories corresponding to build outputs of individual workspaces, also known as output bases.
Package
The set of targets defined by a BUILD file. A
package's name is the BUILD file's path relative to the repo
root. A package can contain subpackages, or subdirectories containing BUILD
files, thus forming a package hierarchy.
Package group
A target representing a set of packages. Often used in visibility
attribute values.
Platform
A "machine type" involved in a build. This includes the machine Bazel runs on (the "host" platform), the machines build tools execute on ("exec" platforms), and the machines targets are built for ("target platforms").
Provider
A schema describing a unit of information to pass between
rule targets along dependency relationships. Typically this
contains information like compiler options, transitive source or output files,
and build metadata. Frequently used in conjunction with depsets to
efficiently store accumulated transitive data. An example of a built-in provider
is DefaultInfo.
See also: Provider documentation
Query (concept)
The process of analyzing a build graph to understand target properties and dependency structures. Bazel supports three query variants: query, cquery, and aquery.
query (command)
A query tool that operates over the build's post-loading
phase target graph. This is relatively fast,
but can't analyze the effects of select(), build flags,
artifacts, or build actions.
See also: Query how-to, Query reference
Repository
A directory tree with a boundary marker file at its root, containing source files that can be used in a Bazel build. Often shortened to just repo.
A repo boundary marker file can be MODULE.bazel (signaling that this repo
represents a Bazel module), REPO.bazel, or in legacy contexts, WORKSPACE or
WORKSPACE.bazel. Any repo boundary marker file will signify the boundary of a
repo; multiple such files can coexist in a directory.
The main repo is the repo in which the current Bazel command is being run.
External repos are defined by specifying modules in MODULE.bazel
files, or invoking repo rules in module
extensions. They can be fetched on demand to a predetermined
"magical" location on disk.
Each repo has a unique, constant canonical name, and potentially different apparent names when viewed from other repos.
See also: External dependencies overview
Repository cache
A shared content-addressable cache of files downloaded by Bazel for builds,
shareable across workspaces. Enables offline builds after the
initial download. Commonly used to cache files downloaded through repository
rules like http_archive and repository rule APIs like
repository_ctx.download. Files are cached only if their SHA-256 checksums are
specified for the download.
Repository rule
A schema for repository definitions that tells Bazel how to materialize (or
"fetch") a repository. Often shortened to just repo rule.
Repo rules are invoked by Bazel internally to define repos backed by
modules, or can be invoked by module extensions.
Repo rules can access the internet or perform file I/O; the most common repo
rule is http_archive to download an archive containing source files from the
internet.
See also: Repo rule documentation
Reproducibility
The property of a build or test that a set of inputs to the build or test will always produce the same set of outputs every time, regardless of time, method, or environment. Note that this does not necessarily imply that the outputs are correct or the desired outputs.
Rule
A schema for defining rule targets in a BUILD file, such as
cc_library. From the perspective of a BUILD file author, a rule consists of
a set of attributes and black box logic. The logic tells the
rule target how to produce output artifacts and pass information to
other rule targets. From the perspective of .bzl authors, rules are the
primary way to extend Bazel to support new programming languages and
environments.
Rules are instantiated to produce rule targets in the loading phase. In the analysis phase rule targets communicate information to their downstream dependencies in the form of providers, and register actions describing how to generate their output artifacts. These actions are run in the execution phase.
See also: Rules documentation
Rule target
A target that is an instance of a rule. Contrasts with file targets and package groups. Not to be confused with rule.
Runfiles
The runtime dependencies of an executable target. Most commonly, the executable is the executable output of a test rule, and the runfiles are runtime data dependencies of the test. Before the invocation of the executable (during bazel test), Bazel prepares the tree of runfiles alongside the test executable according to their source directory structure.
See also: Runfiles documentation
Sandboxing
A technique to isolate a running action inside a restricted and temporary execution root, helping to ensure that it doesn’t read undeclared inputs or write undeclared outputs. Sandboxing greatly improves hermeticity, but usually has a performance cost, and requires support from the operating system. The performance cost depends on the platform. On Linux, it's not significant, but on macOS it can make sandboxing unusable.
Skyframe
Skyframe is the core parallel, functional, and incremental evaluation framework of Bazel.
Stamping
A feature to embed additional information into Bazel-built
artifacts. For example, this can be used for source control, build
time and other workspace or environment-related information for release builds.
Enable through the --workspace_status_command flag and rules that
support the stamp attribute.
Starlark
The extension language for writing rules and macros. A
restricted subset of Python (syntactically and grammatically) aimed for the
purpose of configuration, and for better performance. Uses the .bzl
file extension. BUILD files use an even more
restricted version of Starlark (such as no def function definitions), formerly
known as Skylark.
See also: Starlark language documentation
Startup flags
The set of flags specified between bazel and the command,
for example, bazel --host_jvm_debug build. These flags modify the
configuration of the Bazel server, so any modification to
startup flags causes a server restart. Startup flags are not specific to any
command.
Symbolic macro
A flavor of macro which is declared with a rule-like attribute schema, allows hiding internal declared targets from their own package, and enforces a predictable naming pattern on the targets that the macro declares. Designed to avoid some of the problems seen in large legacy macro codebases.
See also: Symbolic macro documentation
Target
An object that is defined in a BUILD file and identified by a
label. Targets represent the buildable units of a workspace from
the perspective of the end user.
A target that is declared by instantiating a rule is called a rule
target. Depending on the rule, these may be runnable (like
cc_binary) or testable (like cc_test). Rule targets typically depend on
other targets via their attributes (such as deps); these
dependencies form the basis of the target graph.
Aside from rule targets, there are also file targets and package group
targets. File targets correspond to artifacts that are referenced
within a BUILD file. As a special case, the BUILD file of any package is
always considered a source file target in that package.
Targets are discovered during the loading phase. During the analysis phase, targets are associated with build configurations to form configured targets.
Target graph
An in-memory graph of targets and their dependencies. Produced during the loading phase and used as an input to the analysis phase.
Target pattern
A way to specify a group of targets on the command line. Commonly
used patterns are :all (all rule targets), :* (all rule + file targets),
... (current package and all subpackages recursively). Can be used
in combination, for example, //...:* means all rule and file targets in all
packages recursively from the root of the workspace.
Tests
Rule targets instantiated from test rules, and therefore contains a test executable. A return code of zero from the completion of the executable indicates test success. The exact contract between Bazel and tests (such as test environment variables, test result collection methods) is specified in the Test Encyclopedia.
Toolchain
A set of tools to build outputs for a language. Typically, a toolchain includes compilers, linkers, interpreters or/and linters. A toolchain can also vary by platform, that is, a Unix compiler toolchain's components may differ for the Windows variant, even though the toolchain is for the same language. Selecting the right toolchain for the platform is known as toolchain resolution.
Top-level target
A build target is top-level if it’s requested on the Bazel command
line. For example, if //:foo depends on //:bar, and bazel build //:foo is
called, then for this build, //:foo is top-level, and //:bar isn’t
top-level, although both targets will need to be built. An important difference
between top-level and non-top-level targets is that command
flags set on the Bazel command line (or via
.bazelrc) will set the configuration for top-level
targets, but might be modified by a transition for non-top-level
targets.
Transition
A mapping of configuration state from one value to another. Enables targets in the build graph to have different configurations, even if they were instantiated from the same rule. A common usage of transitions is with split transitions, where certain parts of the target graph is forked with distinct configurations for each fork. For example, one can build an Android APK with native binaries compiled for ARM and x86 using split transitions in a single build.
See also: User-defined transitions
Tree artifact
An artifact that represents a collection of files. Since these files are not themselves artifacts, an action operating on them must instead register the tree artifact as its input or output.
Visibility
One of two mechanisms for preventing unwanted dependencies in the build system:
target visibility for controlling whether a target can be depended
upon by other targets; and load visibility for controlling whether a BUILD
or .bzl file may load a given .bzl file. Without context, usually
"visibility" refers to target visibility.
See also: Visibility documentation
Workspace
The environment shared by all Bazel commands run from the same main repository.
Note that historically the concepts of "repository" and "workspace" have been conflated; the term "workspace" has often been used to refer to the main repository, and sometimes even used as a synonym of "repository". Such usage should be avoided for clarity.