Skip to main content

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​

The directory tree of one or more Buck2 packages. A Buck2 build can involve multiple cells. The cell root always contains a .buckconfig, although the presence of a .buckconfig file doesn't in itself define a cell. Rather, the cells involved in a build are defined at the time Buck2 is invoked; they 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.

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.

Platform​

A named set of constraints, defining a specific runtime environment. E.g. cpu=x86_64, os=windows

Remote execution (RE)​

Distributed execution of actions on remote workers. It can speed up builds significantly by scaling the nodes available for parallel actions, and by caching action outputs across Buck2 users.

Rule​

A rule consists of an attribute spec and an implementation, which is a Starlark function.

The attribute spec declares what attributes the rule expects to receive. The rule implementation receives the attributes of a target and the providers of its dependencies. It can declare new actions and artifacts and must return providers that can be used to pass data to its dependents or to Buck2 itself.

Rules are instantiated in BUCK files to declare targets and set their attributes. The rule implementation is called when Buck2 needs its providers, which can happen when the target is built, or when one of its dependents is.

As an example, the cxx_binary rule could be used to create a C++ binary, but android_binary rule would be used to create an Android APK

Starlark​

Starlark is a dialect of Python originally developed by Google for the Bazel build tool. It is the configuration language of the Buck2 build system and the language you use in .bzl and BUCK files to define and instantiate rules.

There are many reasons why Meta has chosen Starlark, as detailed in The Rust Starlark library article.

The Buck2 project maintains and uses an open source Starlark interpreter in Rust.

Subtarget​

Collection of providers that can be accesed by name. The subtargets can have their own subtargets as well, which can be accessed by chaining them, e.g.: buck2 build cell//foo:bar[baz][qux].

Target​

An object that is defined in a BUCK file. Targets represent the buildable units of a build from the perspective of the end user. Declared by instantiating a rule with attributes. A target has dependencies, which are references to other targets.

Target label​

The identifier for a target. Structured as cell_alias//path/to/package:target, where cell_alias// maps to a cell root path (as defined in the ./buckconfig of the cell this target belongs to), path/to/package is the package directory that contains the BUCK file declaring the target (relative to the mapped cell alias), and :target is the target's name.

Target pattern​

A string that resolves to a set of targets. They can be used as arguments to commands such as buck2 build and buck2 uquery. They can also be used in the visibility argument of a rule. For more information, see Target pattern.

Target platform​

Represents the platform that the final output is built for residing and executing. If buck2 is a chef, and the output is the meal, the target platform would be the people that eat the meal.

Target universe​

A set of configured targets and their transitive deps. In the context of cquery and build in the Buck2 CLI, any literals are resolved to all matching targets within the universe. Target universe can be passed explicitly on the Buck2 CLI via --target-universe. If omitted, the target universe will be inferred by constructing a universe using all the target literals (and their transitive deps) within the query string for cquery.

Transition​

Allows the configuration to change across a dependency edge. That is, normally, if target A depends on target B, then if the configuration for A is X, then B is configured using X too. By using a transition, you can produce X to configure B instead.

Unconfigured graph​

A graph of targets before configurations are applied. Can be queried via buck2 uquery.

Visibility​

Determines whether a target can include another target as its dependency. For more information, see Visibility.