Glossary of Terms
.buckconfig
The root of your project must contain a configuration file named
.buckconfig
. Before executing, Buck2 reads this file to incorporate specified
customizations. See .buckconfig for more info.
Action
An individual, cacheable, ideally hermetic command that's run during the
build. It takes artifacts as inputs and produces
other artifacts as outputs. An example command could be gcc -o main main.c
,
which takes the artifact main.c
(a source file) and produces the artifact
called main
(the compiled binary).
Action digest
Encoded action representation. It is sent to remote execution. Used among other things to retrieve action inputs and to check for cache hits
Action graph
The dependency graph of all actions belonging to a target: it can be
queried with buck2 aquery
.
Artifact
A single input or output of an action. These are files that participate as inputs or outputs of a build and can be source files or build outputs. For more information, see the Artifact API.
Attribute
Declared by a rule and used to express the properties of a particular instance of a rule to create a target. For example, srcs, deps and copts, which declare a target's source files, dependencies, and custom compiler options, respectively. The available attributes for a target depend on its rule type.
BUCK file
A BUCK
file (the name is configurable, some projects use TARGETS
) is the
main configuration file that tells Buck2 what to build, what their dependencies
are, and how to build them. Buck2 takes a BUCK
file as input and evaluates the
file to declare targets, which are then used to create a graph of
dependencies and to derive the actions that must be completed to
build intermediate and final software outputs. A BUCK
file marks a directory
and any sub-directories not containing a BUCK
file as a package.
BXL
BXL (Buck eXtension Language) scripts are written in Starlark (a restricted subset of Python) and give integrators the ability to inspect and interact directly with the buck2 graph.
BXL scripts can query the action graph, configured graph, and unconfigured graph. They can also create actions and trigger builds.
Cell
Originally intented to allow for migration of repositories with different setups into one monorepo.The cell root always contains a .buckconfig, although the presence of a .buckconfig file doesn't in itself define a cell. Cells are specified in the .buckconfig for the Buck project.
Configuration
Configurations consist of a set of 'constraint values' that are used to resolve
select
attributes prior to evaluating rule
implementations: the attribute takes the value of the first branch in the
select
that matches the configuration.
Configurations are instantiated by rules that produce a PlatformInfo
provider. Once created, targets can receive their configuration
through a variety of mechanisms, such as:
- Inheritance - by default, when following a dependency edge A -> B, B inherits A's configuration.
- The
default_target_platform
attribute and--target-platforms
command line flag. - Transitions (see below).
Configurations allow a single target to exist in multiple variants in the configured graph (for example, to build a given binary at differing optimization levels or targeting different CPU architectures).
Configured graph
The configured target graph is generated by configuring target nodes in the
unconfigured target graph. That is, selects
are fully
resolved and configurations applied. The configured graph includes information
about the configurations and transitions
involved in building targets. The same target may appear in multiple different
configurations (when printed, the configuration is after the target in
parentheses).
Constraint
A constraint represents a property that may differ across different target or build contexts, such as CPU architecture, the version of a system-installed compiler, optimization level, which version of a particular library to use, etc.
Daemon
The Daemon process lives between invocations and is designed to allow for cache reuse between Buck2 invocations, which can considerably speed up builds. For more information, see Daemon (buckd).
Dependency
A directed edge between two targets. A target A
can have a
dependency on target B
, for example, if any dep
attribute of A
mentions
B
. A target's dependence on another target is determined by the
visibility of the latter.
Execution platform
A type of rule that includes information such as what execution types a target supports, which can be remote, local, and hybrid execution. Also, whether it supports cache uploads, which allows users to get cache hits for things that executed locally.
Hybrid execution
Allows Buck2 to race local and remote execution and get whichever finishes first (unless there's a cache hit, then it will get output from cache). This can provide substantial speedup by eliminating the overhead of going to remote execution when there is enough capacity to service the build locally.
Isolation dir
Instances of Buck2 share a daemon if and only if their isolation directory is identical. The isolation directory also influences the output paths provided by Buck2. See Isolation dir for more info.
Modifiers
It's a modification of a constraint from the existing configuration to obtain a new configuration. They provide a unified way to specify build settings on a project, target, and command line level. It is intended to replace target platforms and most use cases of .buckconfigs.
Package
A directory that contains a Buck2 BUCK file and all source files belonging to the same directory as the BUCK file, or any of its subdirectories that do not contain a BUCK file themselves.
Prelude
The prelude is a unique .bzl
file located at prelude//prelude.bzl
. Buck2
implicitly loads all the symbols defined in the prelude whenever it loads a
BUCK
file. Symbols defined outside the prelude can be imported
via a load()
statement.
When you create a Buck2 project using buck2 init --git
, it will contain the
same prelude used internally at Meta by Buck2 users. It is viewable at
https://github.com/facebook/buck2/tree/main/prelude.
Project
The Outermost directory where there is a .buckconfig: also known
as the root cell. The .buckconfig for the project specifies the
cells that constitute the Buck2 project. Specifically, these cells are
specified in the '[cells]' section of the .buckconfig
. All command invocations
are executed from the project root.
Provider
Data returned from a rule function. It's the only way that information from this rule is available to other rules that depend on it (see dependency). For more information, see Providers.