Getting Started
Installing Buck2
The latest set of buck2
executables can be found under the
latest
release page.
Additionally, for each bi-monthly release there is a dotslash file that is appropriate for checkin to a repository. This will automatically fetch the correct version and architecture for each user, and ensures a consistent build environment for each commit in the repo.
To get started, first install rustup, then compile the
buck2
executable:
rustup install nightly-2024-06-08
cargo +nightly-2024-06-08 install --git https://github.com/facebook/buck2.git buck2
The above commands install buck2
into a suitable directory, such as
$HOME/.cargo/bin
, which you should then add to your $PATH
:
Linux / macOS
export PATH=$HOME/.cargo/bin:$PATH
Windows Powershell
$Env:PATH += ";$HOME\.cargo\bin"
With Buck2 installed, you can build projects with buck2
!
Windows configuration
Some of our rules use symlinks, which are disabled by default for non-admin Windows users. You can fix that by enabling Developer Mode.
Compiling your first project
This section covers the building of a 'hello_world' example project that contains a simple C++ binary. If you are interested in seeing how other languages can be built, take a look at the prelude example project, which contains Rust, C++, Python, and OCaml targets.
First, clone the buck2 repository and cd into the 'hello_world' project:
git clone https://github.com/facebook/buck2.git
cd buck2/examples/hello_world
buck2 init --git
is all the setup you need to start building. This will use
git submodule to pull buck2-prelude
into your project:
buck2 init --git
To use another version control system, run buck2 init
and manually download
buck2-prelude into prelude
at
root.
buck2 init
To build the entire project, run:
Note: Requires clang and lld to be in the path
buck2 build //...
Note that this uses a
simple C++ toolchain
that requires a recent version of clang
to be installed on your system. This
can be installed with any package manager (ex. apt install clang
,
xcode-select --install
on macOS, choco install llvm
). After installing any
external tools or changing your PATH
, run buck2 kill
before running a build.
To list all targets available in the project, run:
buck2 targets //...
To run the main C++ binary, run:
buck2 run //:main
The newly built binary can be found with the --show-output
flag:
buck2 build //:main --show-output
Output:
Build ID: 0e890477-5b7f-4829-9ffe-662e572320a0
Jobs completed: 3. Time elapsed: 0.0s.
BUILD SUCCEEDED
root//:main buck-out/v2/gen/root/9f4d83578bb24895/__main__/main
Creating your first hello_world project
This section demonstrates how to create a simple C++ 'hello_world' project.
To get started, make a new folder for your project and cd into it.
mkdir hello_world
cd hello_world
Next, run buck2 init --git
to initialize the project. This command will set up
your project with git
and pull in
buck2-prelude as a submodule.
Additionally, it will generate multiple files with default values.
buck2 init --git
Next, add the source code main.cpp
,
#include <iostream>
int main() {
std::cout << "Hello from a C++ Buck2 program!" << std::endl;
}
Then, define a cxx_binary
in the root BUCK
file:
# BUCK
cxx_binary(
name = "main",
srcs = ["main.cpp"],
link_style = "static",
)
If you try to build //:main
at this point, you'll see an error about buck2
not being able to find toolchains//:cxx
.
The final step is to define the necessary toolchain targets. For that project,
you need system_cxx_toolchain
and system_python_bootstrap_toolchain
, which
will pick up the necessary tools (clang++, python, and so on) from the system.
# toolchains/BUCK
load("@prelude//toolchains:cxx.bzl", "system_cxx_toolchain")
load("@prelude//toolchains:python.bzl", "system_python_bootstrap_toolchain")
system_cxx_toolchain(
name = "cxx",
visibility = ["PUBLIC"],
)
system_python_bootstrap_toolchain(
name = "python_bootstrap",
visibility = ["PUBLIC"],
)
At this point, your project should have the following files:
$ tree -a -I "buck-out|prelude|.git"
|-- .buckconfig
|-- .gitmodules
|-- BUCK
|-- main.cpp
`-- toolchains
`-- BUCK
Now, you're ready to see the build in action.
To build the main C++ target, run:
buck2 build //:main
To run the main C++ target, run:
buck2 run //:main
In summary, a buck2
project requires:
- A
.buckconfig
file in the root which has a[cells]
section listing out cells - A
prelude
directory, which contains a collection of rules of your choice.buck2 init
will pull in the buck2-prelude as a git submodule by default - If using the buck2-prelude,
a
toolchains
directory that declares relevant toolchains. We provide some basic toolchains in prelude/toolchains BUCK
files that specify targets for your project
buck2 init --git
will generate all of these with reasonable default values.
Learning More
You should now be ready to explore Buck2 for use in your own projects. You can explore the examples folder. Look out for more tutorials in the future.