Buck: Flavors

Flavors

Flavors in Buck are a way to specify different variations of a build that otherwise share most configuration specifications.

Flavors can also be used to simultaneously build for two different platforms, such as iOS and watchOS. Being able to build for both of these at the same time is important because iOS application can have a dependency on the Watch application.

Flavors fall into a number of different categories:

Syntax for flavors

A flavor is specified as a suffix to a build target, with the hash mark (#) used as a separator between the target and flavor. Examples:

buck build :cxx_gr_name#default
buck build :cxx_gr_name#iphonesimulator-x86_64

You can specify multiple flavors for a single target by separating the flavors with commas:

buck build Libraries/3rdParty/openssl:ssl#android-armv7,static-pic
buck build Libraries/3rdParty/openssl:ssl#android-x86,static-pic
buck build :bundle#iphoneos-x86_64,strip-all,dwarf-and-dsym

NOTE: Buck supports a build target pattern,..., as in, //apps/..., that specifies that Buck should recurse through build files in subdirectories, building all build targets in any build files it finds. This build target pattern does not support specifying flavors.

Default flavors

The cxx_library and apple_library rules support specifying default flavors, which pertain if a build target is specified 1) explicitly-that is, not using a build target pattern-and 2) without a flavor.

Syntax for Flagfile Flavors

A flavor may also be specified as a suffix to an @file or --flagfile argument. These flavors are used within the flagfile only and do not directly change the target flavor. The separator is '#' as above, and if the separator and flavor are present, the @file (aka flagfile) must end in ".py" and be a Python script. The script will be called as follows:

python /path/to/flagfile.py --flavors 

Platform flavors #

These flavors denote a toolchain to use for compiling. You can also use them to control conditional fields in the Buck target's rule.

FlavorMeaning
android-armv732-bit Android device
android-x8632-bit Android emulator
iphoneos
iphoneos-armv732-bit iPhone device
iphoneos-arm6464-bit iPhone device
iphoneos-i386
iphoneos-x86_64
iphonesimulator
iphonesimulator-i386Simulator on 32-bit Mac
iphonesimulator-x86_64Simulator on 64-bit Mac
macosx-x86_64Native x86_64 OSX application
macosx-arm64Native arm64 OSX application
windows-x86_64Native Windows application

Sighted in the wild:

buck build :main#android-arm64,shared

Linker flavors #

Static

static

Static library (.a)

Position-independent code (PIC)

static-pic

Static library that generates position-independent code (PIC). Note that on the Apple platforms, everything is PIC.

Shared

A shared library (so) or dynamically-loaded module (.dylib on Mac, .dll on Windows).

Shared interface

shared-interface

A stub library that only lists the imports and exports of a shared library. You can link against this library, but it doesn't have any executable code.

Linker Map

no-linkermap

Specifying this flavor suppresses the generation of a LinkMap.txt file, which is normally generated by the Apple linker (ld).

Analysis flavors #

Rust language

check

The Rust compiler has a build mode which quickly checks syntax and type correctness, but avoids codegen (which is the slowest phase of Rust compilation). This flavor invokes check on the suffixed build target.

save-analysis

The #save-analysis flavor is an extension of #check. It performs the same actions as a #check build, but also emits a .json file containing full type/symbol cross-reference information, for consumption by tools like RLS (Rust Language Services).

doc

The #doc flavor is the equivalent of the cargo doc command. It uses the rustdoc tool to generate documentation for a target and its dependencies.

Compilation database

If you specify one of these flavors, Buck generates analysis information about your build.

compilation-database

Produces a JSON file that contains (an approximation of) the compiler commands for compiling each file. The output is in the clang compilation database format.

Infer

infer-analyze
infer-capture-all

These flavors run Facebook's Infer tool and generate intermediate Infer output.

Symbol stripping flavors#

These flavor control how symbols are stripped from an output binary.

Strip debug

strip-debug

Strip debug symbols; equivalent to strip -S.

Strip debug and non-external

strip-non-global

Strip debug and non-external symbols; equivalent to strip -x.

Strip all

strip-all

Strip all the things; equivalent to strip with no arguments.

Header Flavors#

These flavors are used with C++ header files, in the deps or exported_deps attributes of a Buck target.

Headers used to compile a libraries own files

private-headers

Symlink tree, or header map, of headers used for compiling a library's own files.

Headers used to compile files that depend on this library

headers

Symlink tree, or header map, of headers used to compile files for other libraries that depend on this library.

Apple debug flavors#

Selects the actual binary used to represent a cxx_binary.

Stripped binary

no-debug

Selects the stripped binary

Unstripped binary

dwarf

Selects the unstripped binary

Unstripped + dsym

dwarf-and-dsym

Selects the unstripped binary, and the dsym file.

Other

apple-debuggable-binary

Could be stripped and unstripped, depending on requirements.

Apple bundles flavors#

These flavors are legacy methods of creating app and framework bundles.

You should not use these.

Instead of these flavors, we now use the Buck rule, apple_bundle

App

app
binary#app

Generates an app bundle.

Framework

framework
library#framework

Generates a framework.