The root of your project must contain a configuration
.buckconfig. Before executing, Buck2 reads this file to incorporate
any customizations it specifies.
Performance impact of Buck2 configuration changes
Because configuration settings are sometimes included in the cache keys that Buck2 uses in its caching system, changes to Buck's configuration can invalidate previously-built artifacts in Buck's caches. If this occurs, Buck2 rebuilds those artifacts, which can impact your build time.
The .buckconfig file uses the INI file format
.buckconfig file uses the
INI file format. That is, it is divided
into sections where each section contains a collection of key names and key
.buckconfig implementation supports some modifications to the
INI file format; these are discussed below.
Other INI file parsers
As mentioned previously, we have extended the INI file parser that Buck2 uses to parse configuration files. As a result, INI file parsers provided by other languages or libraries are often not able to parse Buck's configuration files successfully.
Dot character not supported in section names
We do not support the use of the dot character (
.) in section names within
Buck2 configuration files. For example, the following is not
supported—although Buck2 does not issue a warning or error.
Note that sometimes you might need to define your own custom sections, such as
for platform flavors for C++ or Python. These scenarios are examples of when you
should be careful not to introduce the dot character in section names. This
constraint is because Buck2 uses the dot character to delimit section names and
key names in other contexts such as the
--config command-line parameter.
To ensure that any character can be encoded in a
.buckconfig key value, you
can use escape sequences to encode characters that would otherwise be
problematic. The following escape sequences are supported.
|Unicode character with code point ## (in hex)|
|Unicode character with code point #### (in hex)|
|Unicode character with code point ######## (in hex)|
Key values as lists
Although the standard INI format supports only key values that represent a
single item, Buck2 supports key values that represent a list of items. The
syntax is to separate the items in the list using the space (
For example, a key value for the list of command-line flags to be passed to a
compiler could be represented as a list of the flags separated by spaces:
flags = -foo -bar -baz -qux
When a key value is parsed as a list instead of a single item, the separator
character is interpreted as a separator only when it occurs outside of double
quotes. For example, if
flags is a key value interpreted as a list of items
separated by spaces, then
flags = -foo "-bar \u0429"
results in the two strings:
-bar Щ; the space character between
\u0429 is not interpreted as a separator.
Transclusion of values from one key to another
Values from other keys can be transcluded into the current key using the following syntax inside the current key value.
For example, to use the
[go].vendor_path in a custom setting:
[custom_section]custom_value = $(config go.vendor_path)
In addition to the semicolon (
;), you can use the pound sign (
#), as a
comment character in
The root of your project may contain a second
configuration file named
.buckconfig.local. Its format is the same as that of
.buckconfig, but settings in
.buckconfig.local override those in
.buckconfig. In practice,
.buckconfig is a version-controlled file that
contains settings that are applicable to all team members, whereas
.buckconfig.local is excluded from version control to allow users to define
personal settings, such as personal aliases.
Other initialization files
In addition to the
.buckconfig.local files in the project
root, Buck2 reads configuration settings from the following additional
locations, some of which are actually directories:
.buckconfig.dlocated in the project root directory.
.buckconfig.dlocated in the current user's home directory which, on Unix-like systems, is available from the
HOMEenvironment variable or through the
buckconfig.dlocated in system directory
Buck2 treats any file—irrespective of name—in a
buckconfig.d) directory (excluding files found in
subdirectories) as a Buck2 configuration file, provided that it adheres to
.buckconfig syntax. Note that a
.buckconfig.d directory is distinct from the
.buckd directory which is used by the
Buck2 Daemon (
buckd) . For a description of how Buck2 resolves
collisions between settings in these configuration files, see the section
Precedence of Buck2 configuration specifications
Command-line control of configuration
In addition to the above configuration files, Buck2 supports specifying
additional configuration files from the Buck2 command line using the
--config-file parameter. You can also specify configuration settings
individually on the Buck2 command line using the
Furthermore, you can aggregate these settings into flag files using the
--flagfile parameter. A flag file provides similar functionality to a
configuration file but uses a different syntax. Flag files are sometimes called
mode files or at (
Precedence of Buck2 configuration specifications
The following list shows the order of precedence for how Buck2 interprets its
configuration specifications. Settings specified using a method closer to the
top of the list have higher precedence and will override those lower on the
list. For example, the
.buckconfig file in the repo overrides a
file in the user's
- Configuration specified on the command line using
--flagfile. Configuration specified later on the command line overrides configuration specified earlier.
.buckconfig.localin the repo.
.buckconfigin the repo.
- Files in a
.buckconfig.dfolder of the repo.
- Files in a
.buckconfig.dfolder in user's
- The global file
- Files in the global directory
Files in a
buckconfig.d) directory have precedence according
to the lexicographical order of their file names. Files later in the
lexicographical order have precedence over files earlier in that order.
Configuration files can include other files
Any of the configuration files that we've discussed so far can also include by
reference other files that contain configuration information. These included
files can contain complete
.buckconfig sections or they can contain a group of
key name/value pairs that constitute part of a section. In this second use case,
you'll need to ensure that the included file is referenced beneath the
appropriate section in the including file. Because of this additional
complexity, we recommend that you include only files that contain complete
sections. Note: Inclusion of files is a Buck-specific extension to the INI
file parser that Buck2 uses. Therefore, if you use this feature, your Buck2
configuration files will probably not be parsable by other more-generic INI file
parsers. The syntax to include a file is
where path-to-included-file is either a relative path from the including file
(recommended) or an absolute path from the root of the file system. You can also
specify that the file should be included only if it exists by prefixing with a
question mark (
If you use this prefix, it is not an error condition if the file does not exist;
Buck2 just silently continues to process the rest of the configuration file. In
the following example, the
.buckconfig file includes the file
cxx-other-platform.include which exists in the subdirectory
.buckconfig file will also include the file
future-platform from the directory
future-platform.include if that file