This walk-through will cover:
- How to organize your project
- Integration of Google Test
- Explanation of the basic Buck commands
Browse the project files on GitHub, or clone them onto your system:
git clone firstname.lastname@example.org:njlr/buck-cpp-example.git
Install existing Buck ports from Buckaroo.pm.
How Buck Works
Before we start, it might be helpful to understand how Buck works. Rather than retread old ground, take a look at this talk from the Buck devs.
The official guide for installing Buck is available on their website. However, the quickest way is probably to use Homebrew or Linuxbrew.
- If you are using Linux, you can install Linuxbrew using a one-liner on their website.
- Ditto for Homebrew on macOS.
Once you have a “brew” installed, add the Facebook tap and install Buck:
brew tap facebook/fb
brew install --HEAD facebook/fb/buck
Verify your installation with:
Organizing Your Files
Once Buck is installed, it’s time to create the project folders. Buck makes it easy to support any folder structure you like, but for this demo we will be following the C/C++ convention of
This project will consist of two parts:
demo— an executable that computes
3 + 4and prints the result
mathutils— a library that provides simple adding functionality
Note: This is a simple example for demonstration purposes; Buck is capabable of building complex C/C++ projects!
First, create the following structure somewhere on your drive:
Using the command-line:
That’s quite a few files — let’s run through them:
.buckconfigis required before you can run any Buck commands. It tells Buck where the root of your project is and can also be used to configure any settings that are global to your project. For now we can leave it empty.
BUCKfile is where we will define the target for our binary. There can be multiple
BUCKfiles in a Buck project, which is useful when you want to seperate the build logic for different aspects of your project, such as libraries and tests.
demo/includeis where we will be putting any headers used by the binary.
demo/srcis where we will be putting our translation-units (in this case
.cppfiles) for the binary.
demo/src/main.cppwill be the entry-point for our application.
To get started, we will write a simple hello-world program. Paste the following into
To build the
main.cpp file, we need to write a Buck target for it. Into the
BUCK file, paste the following:
BUCK files are written in a dialect of Python 2, with a few extensions. When you call
buck build, Buck will execute the Python and record any targets the are defined. Once the list of targets has been resolved, each target is built in accordance with its type.
You can see the full list of target-types in the Buck docs, but the important ones for C/C++ are
cxx_binary— a bundle of C/C++ translation-units and headers that contain an entry-point (e.g.
int main()). A
cxx_binarycan be executed once compiled. It should not be a dependency.
cxx_library— a bundle of C/C++ translation-units that can be used by other targets. Unlike a
cxx_binary, a library also defines a list of
exported_headers, which are the header-files made available to its dependents.
prebuilt_cxx_library— like a
cxx_library, but with an optional object-file in the place of translation units. Header-only libraries are implemented as a
prebuilt_cxx_librarywith no object-file.
Now that the
BUCK file is in place, Buck can build the target. Run the following:
buck build //:demo
The command tells Buck to build the target
:demo found in the
BUCK file adjacent to
Buck uses a simple addressing system for targets based on the actual folder-structure of the project. For example,
//examples/basic/:demo refers to the target
demo defined in
After the build completes, you should find an executable at
buck-out/gen/demo. You can build and run this using:
buck build //:demo && ./buck-out/gen/demo
Or, Buck can do it for you:
buck run //:buck-cpp-example
You will notice that running the build for a second time is extremely fast. This is because Buck caches everything, including the output of the Python scripts!
Adding a Dependency
mathutils so that we can use it in the demo application.
Create the following folder structure in your project:
│ └── add.hpp
Using the command-line:
And the files themselves:
There are a few important points about this
header_namespaceis set to
'mathutils'. This puts every header-file that the library exports into a folder with that name, making file-name collisions with other libraries less likely.
globrules are rooted at the
src/**/*.cppactually corresponds to
mathutils/src/**/*.cppfrom the project root.
- The visibility is set to
//...so that the target can be taken as a dependency by all other targets in the project. In English it means “this library is visibile to every other target below root”.
Using the Add Function
Now we can use the
mathutils library in the
First, declare the dependency of
mathutils. Change the
BUCK file at the root of the project to:
Use Buck to run
demo to see the result. You will notice that Buck knows how to link
mathutils for you.
Our application is working, but to be diligent we should add some unit-tests!
Buck supports all C/C++ testing frameworks via
buck run, but it provides additional integration with Google Test.
Fetching the Google Test Source-code
Git provides a simple way to grab the Google Test source-code using submodules. We will be using a fork that contains a
BUCK file, but you can use the master and write your own if desired.
git submodule add email@example.com:njlr/googletest.git
git checkout 48072820e47a607d000b101c05d796ebf9c4aad2
Now we need to tell Buck where to find the Google Test sources. Open the
.buckconfig and add the following:
This tells Buck where to find the Google Test target that it can use for your tests. There are other config properties that can be set; have a browse in the Buck docs.
Writing a Test
We will put the tests into a
│ └── add.hpp
│ └── add.cpp
Using the command-line:
And the test itself:
Finally, we need to declare the test in the
Now the tests can be run by Buck:
buck test //mathutils/test:add
Or, to run all tests:
And that’s it! Buck is a powerful tool that will save you hours of waiting over the development cycle of a project. To learn more, read the docs or watch some of the Buck presentations.