Buck: Overview

Overview

Fundamentals

Buck has a number of fundamental concepts:

  • A build rule describes how to produce an output file from a set of input files. Most build rules are specific to a particular language or platform. For example, you would use the cxx_binary rule to create a C++ binary, but you would use the android_binary rule to create an Android APK.
  • A build file defines one or more build rules. In Buck, build files are typically named BUCK. A BUCK file is analogous to the Makefile used by the Make utility. In your project, you will usually have a separate a BUCK file for each buildable unit of software—such as a binary or library. For large projects, you could have hundreds of BUCK files.
  • A build target is a string that uniquely identifies a build rule. It can be thought of as a URI for the build rule within the Buck project.
  • The root of your Buck project contains a global configuration file called .buckconfig. This location of the .buckconfig file identifies the root directory of your Buck project.

Buck's dependency graph

Every build rule can have zero or more dependencies. You can specify these dependencies using, for example, the deps argument to the build rule. For more information about specifying dependencies, consult the reference page for the build rule you are using.

These dependencies form a directed graph, called the target graph. Buck requires the graph to be acyclic. When building the output of a build rule, all of the rule's transitive dependencies are built first. This means that the graph is built in a "bottom-up" fashion. A build rule knows only which rules it depends on, not which rules depends on it. This makes the graph easier to reason about and enables Buck to identify independent subgraphs that can be built in parallel. It also enables Buck to determine the minimal set of build targets that need to be rebuilt.

For more information about how Buck leverages the graph of build dependencies, see What Makes Buck so Fast.

Multiple Buck projects in a single repository

Buck is designed to build multiple deliverables from a single repository—that is, a monorepo—rather than from multiple repositories. Therefore, your repository could contain multiple Buck projects, each with a separate root, defined by a .buckconfig file.

It is Facebook's experience that maintaining all dependencies in the same repository makes it easier to ensure that all developers have the correct version of the code, and simplifies the process for making atomic commits.