A function that takes artifacts as inputs, and produces artifacts as outputs. Includes the command line arguments, action key, environment variables, and declared input/output artifacts.
The cache key of an action. Computed based on action metadata, such as command line that will be executed, compiler flags, library locations and system headers. Enables Bazel to cache or invalidate individual actions deterministically.
The cache of action metadata to action execution result. Lives on disk in Bazel's output base directory, and thus survives Bazel server restarts.
An in-memory logical graph of actions and the artifacts
these actions read and generate. These artifacts may include file targets as
well as intermediate artifacts that are not mentioned in
BUILD files. Produced during the
analysis phase and used during the execution
phase.
The second phase of a build. Processes the target dependency graph specified in
BUILD files to produce an in-memory action graph that
determines the order of actions to run during the execution
phase.
A file used or derived by Bazel. Can also be a directory of files, also known as tree artifacts. Tree artifacts are black boxes to Bazel, that is, Bazel does not treat the files in tree artifacts as individual artifacts and thus cannot reference them directly as action inputs / outputs. An artifact can be an input to multiple actions, but must only be generated by at most one action.
A mechanism for rules to create additional action in their
dependencies. Most commonly used for build metadata generation for IDEs, and
linting. 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.
An aspect composition mechanism, where aspects can be applied on
other aspects. Commonly used by IDE aspects to generate files using
information also generated by aspects, like the java_proto_library aspect.
For an aspect A to inspect aspect B, aspect A must declare the
providers it needs from aspect B (with required_aspect_providers
attribute), and aspect B must declare the providers it returns (with
provides attribute).
An input argument of a rule or aspect. Attributes are declared as part of rule/aspect definition. Attribute declaration includes its type, visibility, default value and other parameters.
The main build configuration file containing rule declarations (e.g.
cc_binary, go_library). When BUILD files are evaluated and analyzed, the
rules create new targets in the target dependency graph. A BUILD
file can load and use Starlark-defined rules from .bzl files. A
BUILD file marks a directory as a package.
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.
Context information that may affect a build. Every build has at least one configuration specifying the host/target platform, action environment variables, as well as taking input from the default set of flag and attribute values of the build. Additional configurations may be created, for example, in a cross-compilation build.
Configuration-aware variant of bazel query. Allows querying configured targets
in the post-analysis phase graph, which means configuration flags like
--platforms and --toolchains affect the result of the query.
A directed edge between two targets. A target //:foo has a
target dependency on another target //:bar if the attribute values of
//:foo contain a reference to //:bar. This dependency can also be in the
form of an action dependency. That is, if an action that produces a file in
//:foo depends on an input artifact that is an output artifact of an action in
//:bar, then //:foo has an action dependency on //:bar by way of the
derived artifact between the two actions.
A data structure for collecting data on transitive dependencies. Optimized to be time and space efficient around merging, because it’s common to have very large depsets, scaling to hundreds of thousands of files. Implemented to recursively refer to other depsets for space efficiency reasons. Rule implementations should not flatten depsets to lists unless they are at the top level. Flattening large depsets incur huge memory consumption. Also known as Nested Sets in Bazel's internal implementation.
An local on-disk blob store for the remote caching feature. Can be used in conjunction with an actual remote blob store.
A read-only directory containing files that Bazel would otherwise fetch from the internet using repository rules. Enables fully offline builds in an air-gapped environment.
An execution strategy that wraps both the local and remote execution strategy, and through various heuristics, uses the execution result of the faster successful strategy. Certain actions are better executed locally (e.g. linking), and others remotely (highly parallelizable compilation), so the dynamic execution strategy provides the best possible incremental and full build times.
The third phase of a build. Deriving from the action graph produced during the analysis phase, execute actions in order using external tools (compilers, scripts, etc). Reads and writes artifacts. Spawn strategies control how these actions are executed: locally, remotely, dynamically, sandboxed, docker, and so on.
The lack of external influences during a build or test for the goal of producing a deterministic and correct result. This could mean only allowing access to declared input artifacts, making timestamps and timezones fixed, restricting access/resetting environment variables, and using fixed seeds for random number generators.
An identifier for a target. A fully qualified label
(//path/to/package:target) consists of // to mark the workspace root
directory, path/to/package as the directory that contains the BUILD file
declaring the target, and :target as the name of the target declared in the
aforementioned BUILD file. It can optionally be prefixed with
@my_repository//<..> to indicate that the target is declared in an external
repository named my_repository.
The first phase of a build. Parse WORKSPACE, BUILD and .bzl files to expand macros and instantiate an internal cache of packages. Usually interleaved with the second phase of the build, the analysis phase, to build up a target dependency graph.
A mechanism to compose multiple predefined rule target declarations together under a single Starlark function. Expanded to the underlying rule target declarations during the loading phase.
A short human readable string to quickly understand what an action
is doing. Can be used as identifiers for spawn strategy selections. For
example: Javac, CppCompile, AndroidManifestMerger.
See depset.
A directory containing a BUILD file. A package can contain subpackages, or
subdirectories containing BUILD files, thus forming a package hierarchy.
A target representing a set of packages, and therefore has a label usually
referenced in visibility attribute values.
A set of information passed from a rule target to other rule targets. Usually contains information like: compiler options, transitive source files, transitive output files, and build metadata. Frequently used in conjunction with depsets.
A directory containing a WORKSPACE file.
The property that a set of inputs will always produce the same set of outputs every time, regardless of time, method or environment. Not that the outputs may not be correct or the desired ones.
A function implementation that registers a series of actions to be performed
on inputs to produce a set of outputs. Rules can read values from
attributes as inputs (e.g. deps, testonly, name). Rule
targets also produce and pass along information that may be useful to other rule
targets in the form of providers (e.g. DefaultInfo provider).
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.
The core parallel, functional, and incremental evaluation framework of Bazel.
A feature to embed additional information into Bazel-built artifacts. Commonly
used for source control, build time and other workspace-related information for
release builds. Enable through the --workspace_status_command flag and rules
that support the stamp attribute.
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 (e.g. no def function definitions). Formerly known as Skylark.
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.
A buildable unit. Can be a rule target, file target, or a package group.
Rule targets are instantiated from rule declarations in BUILD files. Depending
on the rule implementation, rule targets can also be testable or runnable.
Every file used in BUILD files is a file target. Targets can depend on other
targets via attributes (most commonly but not necessarily deps).
A configured target is a pair of target and build configuration.
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.
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 (e.g. test environment variables, test result collection methods) is specified in the Test Encyclopedia.
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.
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.
Defines whether a target can be depended upon by other targets. By default, target visibility is private. That is, the target can only be depended upon by other targets in the same package. Can be made visible to specific packages or completely public.
A directory on your filesystem that contains source code for the software you want to build.
Defines a directory to be a workspace directory. Can be empty, although usually contains external repository declarations to fetch additional dependencies from the network or local filesystem.
- Michelle Irvine, Google (for the original glossary)
- Greg Estren, Google (for the configurability glossary)
- Jon Brandvein, Google (contributions to the original glossary)
- Artem Zinnatullin, external (contributions to the glossary)