Getting Started

Unfortunately, Apple only lets you develop for iOS on a Mac.

This is a quick start guide for getting up and running with Buck. This article is light on details, instead focusing on the commands that you need to run to install Buck and build your first application from scratch using Buck.

While not a prerequisite for installing Buck itself, in order to build iOS applications, you will also need to install Xcode.

This is a quick start guide for getting up and running with Buck. This article is light on details, instead focusing on the commands that you need to run to install Buck.

While not a prerequisite for installing Buck itself, to build Android applications, you will also need at least the Android SDK, which can be installed via Chocolatey or manually downloaded and installed.

This is a quick start guide for getting up and running with Buck. This article is light on details, instead focusing on the commands that you need to run to install Buck.

This is a quick start guide for getting up and running with Buck. This article is light on details, instead focusing on the commands that you need to run to install Buck and build your first application from scratch using Buck.

While not a prerequisite for installing Buck itself, to build Android applications, you will also need at least the Android SDK, which can be installed via Homebrew or manually downloaded and installed.

While not a prerequisite for installing Buck itself, to build Android applications, you will also need at least the Android SDK, which can be installed via apt-get (or your distro's package manager) or manually downloaded and installed.

You can find a more detailed explanation about each step in the development process by reading the individual articles on more specific topics.

The commands in this guide are designed to be copy-pasteable, idempotent, and usable on its representative operating system (OS X, Windows, Linux). Sometimes this results in some unusual constructions (such as using echo instead of vi or emacs to create a file). Bear in mind that this is a quick start guide, so few things are quicker than copy-and-paste!

You can find a more detailed explanation about each step in the development process by reading the individual articles on more specific topics.

The commands in this guide are designed to be copy-pasteable, idempotent, and usable on its representative operating system (OS X, Windows, Linux). Sometimes this results in some unusual constructions (such as using echo instead of vi or emacs to create a file). Bear in mind that this is a quick start guide, so few things are quicker than copy-and-paste!

Currently, there is no way to download a precompiled binary for Buck.

Install with Homebrew

Buck is available as bottle on Homebrew.

Prerequisites

• Command Line Tools
• Java Runtime Environment

# Install command line tools. NOTE: If you have Xcode installed, these may
# already be installed.
xcode-select --install
# Install Java - this installs the JDK, a superset of the JRE
brew tap caskroom/cask
brew cask install java

If for some reason you do not have Xcode installed and you get an error error: active developer path ("/Applications/Xcode.app/Contents/Developer") does not exist, then run xcode-select --reset to reset the command line tools path to where command line tools is installed.

Brew install

You have two choices when using Homebrew. You can choose to get the latest binary release:

brew tap facebook/fb
brew install buck

Or, you can get the latest and greatest code and build it locally.:

brew update
brew tap facebook/fb
brew install --HEAD buck

Build from Source

Prerequisites

To manually build Buck, download and install the following prerequisites:

• Command Line Tools
• Oracle Java Development Kit
• Apache Ant 1.9 (or newer)
• Python 2.7
• Git
• Watchman

With watchman, Buck will use a daemon which will prevent Buck from parsing all of your build files every time and cache some other things as well. It is strongly recommended that you install Watchman.

You can use Homebrew to install many of the prerequisites on a Mac.

# Install Command Line tools first. NOTE: If you have Xcode installed, these may
# already be installed.
xcode-select --install
# Then the JDK (superset of the JRE)
brew update
brew tap caskroom/cask
brew install java
# Then...
brew install ant python git watchman

If for some reason you do not have Xcode installed and you get an error error: active developer path ("/Applications/Xcode.app/Contents/Developer") does not exist, then run xcode-select --reset to reset the command line tools path to where command line tools is installed.

Build

Once you have the above tools installed, you can install Buck as follows:

git clone https://github.com/facebook/buck.git
cd buck
ant
./bin/buck --help

If everything worked correctly, you should see something like:

buck build tool
usage:
  buck [options]
  buck command --help
  buck command [command-options]
available commands:
  audit       lists the inputs for the specified target
  build       builds the specified target
  cache       makes calls to the artifact cache
  clean       deletes any generated files
  fetch       downloads remote resources to your local machine
  install     builds and installs an application
  project     generates project configuration files for an IDE
  query       provides facilities to query information about the target nodes graph
  root        prints the absolute path to the root of the current buck project
  run         runs a target as a command
  server      query and control the http server
  targets     prints the list of buildable targets
  test        builds and runs the tests for the specified target
  uninstall   uninstalls an APK
options:
 --help         : Shows this screen and exits.
 --version (-V) : Show version number.

Because you will likely be running ./bin/buck often, you should add it to your path so that you can simply run buck from the command line.

Build from Source

Prerequisites

To manually build Buck, download and install the following prerequisites:

• Oracle Java Development Kit
• Apache Ant 1.9 (or newer)
• Python 2.7
• Git
• Watchman

With watchman, Buck will use a daemon which will prevent Buck from parsing all of your build files every time and cache some other things as well. It is strongly recommended that you install Watchman.

You can use Chocolatey to install many of the prerequisites on Windows.

choco install jdk8 ant python git
# install watchman as stated in the watchman prerequisite link above

You can use your distro's package manager (e.g., apt) to install many of the prerequisites on Linux. For example on Ubuntu 16.04, you can run the following:

sudo apt-get update
sudo apt-get install default-jdk ant python git
# install watchman as stated in the watchman prerequisite link above

For some distros, the default packages may be older than what you would like. In those cases, either build those packages from source, or find third party repositories beyond the default that is used by apt-get via sudo add-apt-repository (or however you add new repositories on your distro).

Environment Variables

You will need to tell Buck where to find our SDK and NDK. Buck will look at the value of the ANDROID_HOME environment variable to locate the SDK files on your system. Buck will look at ANDROID_NDK to find a specific version of the NDK, and ANDROID_NDK_REPOSITORY to find an appropriate NDK from a directory containing multiple NDK versions.

Build

Once you have the above tools installed, you can install Buck as follows:

git clone https://github.com/facebook/buck.git
cd buck
ant
.\bin\buck --help

git clone https://github.com/facebook/buck.git
cd buck
ant
./bin/buck --help

If everything worked correctly, you should see something like:

buck build tool
usage:
  buck [options]
  buck command --help
  buck command [command-options]
available commands:
  audit       lists the inputs for the specified target
  build       builds the specified target
  cache       makes calls to the artifact cache
  clean       deletes any generated files
  fetch       downloads remote resources to your local machine
  install     builds and installs an application
  project     generates project configuration files for an IDE
  query       provides facilities to query information about the target nodes graph
  root        prints the absolute path to the root of the current buck project
  run         runs a target as a command
  server      query and control the http server
  targets     prints the list of buildable targets
  test        builds and runs the tests for the specified target
  uninstall   uninstalls an APK
options:
 --help         : Shows this screen and exits.
 --version (-V) : Show version number.

Because you will likely be running .\bin\buck often, you should add it to your path so that you can simply run buck from the command line.

Because you will likely be running ./bin/buck often, you should add it to your path so that you can simply run buck from the command line.

Trying Buck

Now that Buck is installed, it is time use Buck in a sample project.

Clone Buck Samples Repo

git clone [email protected]:fbsamples/bucksamples.git
cd bucksamples/cross-platform-scale-2015-demo/

Key iOS Files

This sample app has all the files necessary to use Buck to build an iOS project. From the root directory, you will find:

• ios/main.m: The main iOS file supported by other views, controllers and associated resources.

• ios/BUCK: The build file is what makes Buck work. It defines all the build rules for your source code. A build rule may also include dependencies (via deps), which may be from other build files.

• .buckconfig: A .buckconfig file allows for various flag and alias settings for any project (even beyond iOS) within the root directory.

Build the iOS Sample

In order to build the app, you use the buck build command, specifying your app as the target. The target may be defined in the [alias] section in the .buckconfig file or it would be the name of your iOS project prepended by //[the directory where your project is located]: (e.g., //ios:BuckDempApp).

# From the root `cross-platform-scale-2015-demo/` directory
# demo_app_ios is an alias in .buckconfig for //ios::BuckDemoApp. Either works.
buck build demo_app_ios

You should see output similar to:

buck build demo_app_ios
[-] PROCESSING BUCK FILES...FINISHED 0.0s [100%]
[-] DOWNLOADING... (0.00 B/S AVG, TOTAL: 0.00 B, 0 Artifacts)
[-] BUILDING...FINISHED 0.7s [100%] (1/1 JOBS, 0 UPDATED, 0 [0.0%] CACHE MISS)

The first time you build, you will most likely see a longer time and cache misses. Subsequent builds should be much faster, with minimal cache misses.

Buck outputs its results in the buck-out/ directory.

Run the Built iOS App

Now that you know your app has built successfully, you can install and run the app with buck install. This command both compiles and installs the application on the iOS simulator. Using the --run flag will launch the simulator as well.

buck install --run demo_app_ios
Successfully launched demo_app_ios. To debug, run: lldb -p 50240
[-] PROCESSING BUCK FILES...FINISHED 0.0s [100%]
[-] DOWNLOADING... (0.00 B/S AVG, TOTAL: 0.00 B, 0 Artifacts)
[-] BUILDING...FINISHED 0.3s [100%] (1/1 JOBS, 0 UPDATED, 0 [0.0%] CACHE MISS)
[-] INSTALLING...FINISHED 38.7s

Success!

If all goes well, you should see something similar to:

Trying Buck

Now that Buck is installed, it is time use Buck in a sample project.

Clone Buck Samples Repo

git clone [email protected]:fbsamples/bucksamples.git
cd bucksamples/cross-platform-scale-2015-demo/

Key Android Files

This sample app has all the files necessary to use Buck to build an Android project. From the root directory, you will find:

• android/java/com/facebook/buck/demo/Hello.java: The main Java file supported by other associated resources.

• android/BUCK: The build file is what makes Buck work. It defines all the build rules for your source code. A build rule can also include dependencies (generally via deps), which may be from other build files, as in the case of this app.

• .buckconfig: A .buckconfig file allows for various flag and alias settings for any project (even beyond Android) within the root directory.

Build the Android Sample

In order to build the app, you use the buck build command, specifying your app as the target. The target may be defined in the [alias] section in the .buckconfig file or it would be the name of your Android project prepended by //[the directory where your project is located]: (e.g., //android:demo-app).

# From the root `cross-platform-scale-2015-demo/` directory
# demo_app_android is an alias in .buckconfig for //android:demo-app. Either works.
buck build demo_app_android

You should see output similar to:

export ANDROID_NDK=$HOME/android-sdk
buck build demo_app_android
[-] PROCESSING BUCK FILES...FINISHED 0.0s [100%]
[-] DOWNLOADING... (0.00 B/S AVG, TOTAL: 0.00 B, 0 Artifacts)
[-] BUILDING...FINISHED 0.7s [100%] (1/1 JOBS, 0 UPDATED, 0 [0.0%] CACHE MISS)

The first time you build, you will most likely see a longer time and cache misses. Subsequent builds should be much faster, with minimal cache misses.

Buck outputs its results in the buck-out/ directory.

Run the Built Android App

Now that you know your app has built successfully, you can install and run the app with buck install. This command both compiles and installs the application on the Android emulator. Using the --run flag will launch the emulator as well.

buck install --run demo_app_android
Installing apk on emulator-5554 (android-emulator).
[-] PROCESSING BUCK FILES...FINISHED 0.1s [100%]
[-] DOWNLOADING... (0.00 B/S AVG, TOTAL: 0.00 B, 0 Artifacts)
[-] BUILDING...FINISHED 0.8s [100%] (1/1 JOBS, 0 UPDATED, 0 [0.0%] CACHE MISS)
[+] INSTALLING...0.9s
Successfully ran install apk //android:demo-app on 1 device(s)
Starting activity com.facebook.buck.demo/.App...
Successfully ran start activity on 1 device(s)

If you get an error either that you do not have certain Android add-ons (e.g., Google APIs) or that there is no emulator to run, you should launch the Android SDK Manager (e.g., android sdk) and install the appropriate packages and/or run your emulator (usually found under Tools | Manage AVDs).

Success!

If all goes well, you should see something similar to:

Trying Buck

Now that Buck is installed, it is time use Buck in a sample project. In particular, we are going to build a simple Java "Hello Buck" library and application.

Clone Buck Samples Repo

git clone [email protected]:fbsamples/bucksamples.git
cd bucksamples/hello-buck-java/

Key Java Files

We are going to be building a Java application that prints out "Hello Buck". The code to build the application consists of both a library and app component. To build this Java application, the code you cloned has all the files necessary. From the hello-buck-java directory, you will find:

• com/facebook/buck/demo/HelloBuckJava.java: The main Java application file.

• com/facebook/buck/demo/HelloStringJava.java: A simple Java library with one function that the main app calls.

• com/facebook/buck/demo/BUCK: This build file is what makes Buck work and is the trigger for building the application. It defines all the build rules for your source code. The key rules you will see in this file is java_binary and java_library. A build rule may also include dependencies (generally via deps), which may be from other build files.

• .buckconfig: A .buckconfig file allows for various flag and alias settings for any project (even beyond this Java application, if they existed) within the hello-buck-java directory.

Build the Java Application

In order to build the library, you use the buck build command, specifying your app as the target. The target may be defined in the [alias] section in the .buckconfig file or it would be the name of your Java application prepended by //[the directory where your project is located]: (e.g., //com/facebook/buck/demo:hello-buck-java).

# From the root `hello-buck-java/` directory
# hello_buck_java is an alias in .buckconfig for //com/facebook/buck/demo:hello-buck-java. Either works.
buck build hello_buck_java

You should see output similar to:

[-] PROCESSING BUCK FILES...FINISHED 0.0s [100%]
[-] DOWNLOADING... (0.00 B/S AVG, TOTAL: 0.00 B, 0 Artifacts)
[-] BUILDING...FINISHED 0.8s [100%] (1/1 JOBS, 0 UPDATED, 0 [0.0%] CACHE MISS)

The first time you build, you will most likely see a longer time and cache misses. Subsequent builds should be much faster, with minimal cache misses.

Buck outputs its results in the buck-out/ directory.

Run the Built Java Application

Now that you know your app has built successfully, you can install and run the app with buck run. This command both compiles and runs the application.

buck run hello_buck_java
[-] PROCESSING BUCK FILES...FINISHED 0.0s [100%]
[-] DOWNLOADING... (0.00 B/S AVG, TOTAL: 0.00 B, 0 Artifacts)
[-] BUILDING...FINISHED 0.4s [100%] (1/1 JOBS, 0 UPDATED, 0 [0.0%] CACHE MISS)
Hello Buck

Success!

If all goes well, you should see something similar to:

Hello Buck