Skip to main content

​
Configuration Files

Buck uses .buckconfig files to configure build behavior. These files use an INI-style format with sections and key-value pairs.

​
.buckconfig Structure

The main configuration file is located at the repository root:
.buckconfig
[cxx]
  default_platform = iphonesimulator-x86_64
  cflags = -g -fmodules -fobjc-arc -D BUCK -w $(config code_coverage.clang_flags)
  cxxflags = -fobjc-arc -std=c++14 -D DEBUG -g $(config code_coverage.clang_flags)
  combined_preprocess_and_compile = true
  pch_enabled = false
  ldflags = -Xlinker -objc_abi_version -Xlinker 2 -fobjc-arc -fobjc-link-runtime $(config code_coverage.ldflags)

[swift]
  version = 5
  compiler_flags = -DBUCK -whole-module-optimization $(config custom.optimization) $(config custom.config_swift_compiler_flags) $(config code_coverage.swift_flags)
  use_filelist = true

[apple]
  use_swift_delegate = false
  use_header_maps_in_xcode = false
  generate_missing_umbrella_headers = true
  iphonesimulator_target_sdk_version = 14.0
  iphoneos_target_sdk_version = 14.0
  provisioning_profile_read_command = security cms -Di
  xctool_default_destination_specifier = platform=iOS Simulator,OS=latest
  xctool_path = tools/xctool/bin/xctool

[parser]
  polyglot_parsing_enabled = true
  default_build_file_syntax = SKYLARK

[project]
  ide_force_kill = always
  project_schemes = true
  ide = xcode
  allow_symlinks = forbid
  ignore = tools, \
           .git, \

[build]
  threads = 4

[custom]
  config = debug
  optimization = -Onone
  config_swift_compiler_flags = -DDEBUG -enable-testing -g
  code_coverage_cflags = -fprofile-instr-generate -fcoverage-mapping
  code_coverage_cxxflags = -fprofile-instr-generate -fcoverage-mapping
  code_coverage_ldflags = -fprofile-instr-generate
  code_coverage_swift_compiler_flags = -profile-generate -profile-coverage-mapping

​
Configuration Sections

​
C/C++ Settings ([cxx])

Controls compilation of C and C++ code: 
default_platform = iphonesimulator-x86_64
Sets the default build platform. Options include:
  • iphonesimulator-x86_64 - iOS Simulator (Intel)
  • iphonesimulator-arm64 - iOS Simulator (Apple Silicon)
  • iphoneos-arm64 - Physical iOS devices
Precompiled headers are disabled with pch_enabled = false to ensure reproducible builds.

​
Swift Settings ([swift])

Configures Swift compilation:
.buckconfig (lines 9-12)
[swift]
  version = 5
  compiler_flags = -DBUCK -whole-module-optimization $(config custom.optimization) $(config custom.config_swift_compiler_flags) $(config code_coverage.swift_flags)
  use_filelist = true
  • -DBUCK - Defines BUCK compilation flag
  • -whole-module-optimization - Optimizes across all files in a module
  • $(config custom.optimization) - References custom optimization level (-Onone for debug)
  • $(config custom.config_swift_compiler_flags) - Additional flags from custom section
  • use_filelist = true - Uses file lists instead of command line arguments (required for large projects)

​
Apple Platform Settings ([apple])

Configures iOS/macOS specific build options:
.buckconfig (lines 14-22)
[apple]
  use_swift_delegate = false
  use_header_maps_in_xcode = false
  generate_missing_umbrella_headers = true
  iphonesimulator_target_sdk_version = 14.0
  iphoneos_target_sdk_version = 14.0
  provisioning_profile_read_command = security cms -Di
  xctool_default_destination_specifier = platform=iOS Simulator,OS=latest
  xctool_path = tools/xctool/bin/xctool

iphonesimulator_target_sdk_version = 14.0
iphoneos_target_sdk_version = 14.0
Sets minimum iOS version to 14.0 for both simulator and device builds.

​
Parser Settings ([parser])

Controls how Buck parses build files:
.buckconfig (lines 24-26)
[parser]
  polyglot_parsing_enabled = true
  default_build_file_syntax = SKYLARK
SKYLARK (also called Starlark) is a Python-like configuration language that provides better structure and type safety than the legacy Python syntax.

​
Project Settings ([project])

Configures Xcode project generation:
.buckconfig (lines 28-34)
[project]
  ide_force_kill = always
  project_schemes = true
  ide = xcode
  allow_symlinks = forbid
  ignore = tools, \
           .git, \

ide = xcode
project_schemes = true
Generates Xcode projects with schemes.

​
Build Settings ([build])

Controls build parallelism:
.buckconfig (lines 36-37)
[build]
  threads = 4
Adjust the threads value based on your CPU core count for optimal build performance.

​
Custom Settings ([custom])

Project-specific configuration:
.buckconfig (lines 39-46)
[custom]
  config = debug
  optimization = -Onone
  config_swift_compiler_flags = -DDEBUG -enable-testing -g
  code_coverage_cflags = -fprofile-instr-generate -fcoverage-mapping
  code_coverage_cxxflags = -fprofile-instr-generate -fcoverage-mapping
  code_coverage_ldflags = -fprofile-instr-generate
  code_coverage_swift_compiler_flags = -profile-generate -profile-coverage-mapping
Debug Configuration:
config = debug
optimization = -Onone
config_swift_compiler_flags = -DDEBUG -enable-testing -g
  • No optimization (-Onone) for faster compilation
  • Debug symbols enabled (-g)
  • Testing enabled (-enable-testing)
For Release: Change to:
config = release
optimization = -O
config_swift_compiler_flags = -DRELEASE
Code coverage settings instrument binaries to track which code paths are executed:
code_coverage_cflags = -fprofile-instr-generate -fcoverage-mapping
code_coverage_swift_compiler_flags = -profile-generate -profile-coverage-mapping
These flags are referenced in the main compiler flags:
cflags = ... $(config code_coverage.clang_flags)

​
Configuration Variables

You can reference configuration values using $(config section.key) syntax: 
[swift]
  compiler_flags = -DBUCK $(config custom.optimization)

[custom]
  optimization = -Onone
This makes it easy to reuse values and create build variants.

​
Build Variants

Create different configurations for debug and release: 
[custom]
  config = debug
  optimization = -Onone
  config_swift_compiler_flags = -DDEBUG -enable-testing -g

​
Configuration in Build Rules

Build rules can access configuration through custom configs:
App/BUCK
load("//Config:configs.bzl", "app_binary_configs", "library_configs")

apple_library(
    name = "ExampleAppLibrary",
    configs = library_configs(),  # Applies library-specific configs
    # ...
)

buck_local_binary(
    name = "ExampleAppBinary",
    configs = app_binary_configs("ExampleApp"),  # Applies binary configs
    # ...
)
These config functions are defined in Config/configs.bzl and combine settings from .buckconfig with rule-specific requirements.

​
Configuration Best Practices

Instead of hardcoding flags everywhere, define them once in [custom] and reference them:
[custom]
  my_common_flag = -DFEATURE_ENABLED

[swift]
  compiler_flags = $(config custom.my_common_flag)
Ensure simulator and device SDK versions match:
iphonesimulator_target_sdk_version = 14.0
iphoneos_target_sdk_version = 14.0
Add comments to explain non-obvious configuration choices:
# Disable PCH for reproducible builds
pch_enabled = false
Create .buckconfig.ci with CI-specific settings like increased parallelism or different optimization levels.

​
Debugging Configuration

View the effective configuration: 
buck audit config
View a specific section: 
buck audit config swift
View a specific key: 
buck audit config swift.version

​
Next Steps

Buck Basics

Review fundamental Buck concepts

Build Targets

Learn about different target types

Build docs developers (and LLMs) love

Get started for freeTalk to us