Configuration Settings File (xcconfig) format

A Configuration Settings File (a file with a .xcconfig file extension), also known as a build configuration file or xcconfig file, is a plain text file that defines and overrides the build settings for a particular build configuration of a project or target. This type of file can be edited outside of Xcode and integrates well with source control systems. Build configuration files adhere to specific formatting rules, and produce build warnings if they do not.

Comments

Use single-line comments to include notes or other information that should be ignored by the build system. Each comment begins with two forward-slashes (//) and continues until the end of the line is reached. For example:

////  Config.xcconfig//  My iOS App////  Created by Johnny Appleseed on 11/15/16.//  Copyright © 2018 Apple. All rights reserved.//

A comment can reside on a line by itself or it can follow a build setting value. For example:

ASSETCATALOG_COMPILER_APPICON_NAME = MyAppIcon // This is a comment.

Specify a Build Setting Value

A build configuration file doesn’t need to list all possible build settings. It only needs to include ones you want to customize. Each build setting value is defined on a single line in the format:

BUILD_SETTING_DECLARATION_NAME = BUILD_SETTING_VALUE_DEFINITION

For example:

ONLY_ACTIVE_ARCH = YES

There are numerous value types, but the following are the most common:

Value type	Description
`Boolean`	A value of `YES` or `NO`.
`string`	A specified text value.
`enumeration (string)`	A predefined text value.
`string list`	A space-separated list of `string` values. If a `string` within a `string list` contains spaces, then the `string` must be surrounded by quotes.
`path`	A file or directory path, in POSIX form.
`path list`	A space-separated list of `path` values. If a `path` within a `path list` contains spaces, then the `path` must be surrounded by quotes.

For both the build setting name and its value definition, leading and trailing spaces are ignored. If the same build setting with the same conditions (see Add a platform condition to a value) is defined multiple times, the final instance is used and all others are ignored.

Note: Build setting names are displayed in the Quick Help inspector when you select a build setting in the Build Settings pane of the project editor. You can also find build setting names in Build settings reference. In the Build Settings pane, you can toggle between the build setting titles and names.

Prevent a value from being overridden

To retain an existing project or target build setting value as part of a newly defined value, use the $(inherited) variable in the format:

BUILD_SETTING_DECLARATION_NAME = $(inherited)ADDITIONAL_VALUE

For example:

OTHER_SWIFT_FLAGS = $(inherited) -v

Reference the value of another build setting

To reference the value of another build setting, refer to the other build setting name in the format:

BUILD_SETTING_DECLARATION_NAME = $(OTHER_BUILD_SETTING_DECLARATION_NAME)

For example:

OBJROOT = $(SYMROOT)

Other build setting values can be referenced inline as follows:

DSTROOT = /tmp/$(PROJECT_NAME).dst

Or:

CONFIGURATION_BUILD_DIR = $(BUILD_DIR)/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)

Add a platform condition to a value

A project may need to build differently when targeting one platform versus another. To allow for this, the build system supports the following conditionals:

Conditional	Condition value
`sdk`	An SDK, such as `macos10.12` or `iphoneos10.2`. To match any SDK of a given platform, provide an asterisk (``) instead of a version. For example, a condition value of `macos` matches any macOS SDK.
`arch`	An architecture, such as `x86_64` or `arm64`.

Conditions appear after the build setting name and are enclosed within brackets. For example:

BUILD_SETTING_DECLARATION_NAME[CONDITIONAL=CONDITION_VALUE] = VALUE_DEFINITION

For example, the following line sets the value of the OTHER_LDFLAGS build setting to -lncurses when building with any macOS SDK:

OTHER_LDFLAGS[sdk=macosx*] = -lncurses

Multiple conditions can also be specified using the format:

BUILD_SETTING_DECLARATION_NAME[CONDITIONAL1=CONDITION_VALUE1][CONDITIONAL2=CONDITION_VALUE2] = VALUE_DEFINITION

For example, the following line sets the value of the OTHER_LDFLAGS build setting to -lncurses whenever the SDK matches a value of macosx* and the architecture matches a value of x86_64:

OTHER_LDFLAGS[sdk=macosx*][arch=x86_64] = -lncurses

Include Settings from Other Build Configuration Files

A build configuration file can import build settings from other build configuration files. To import settings from another file, use the prefix #include, followed a reference to the file in quotes. For example:

#include "MyOtherConfigFile.xcconfig"

If the specified file isn’t found at build time, build warnings are produced. To suppress warnings for missing build configuration files, place a question mark (?) after the #include prefix. For example:

#include? "MyOtherConfigFile.xcconfig"

You can refer to other build configuration files using file names, relative paths, and absolute paths.

Reference type	Description	Example
File name	The name of a build configuration file in the same folder as the current build configuration file.	`#include "MyOtherConfigFile.xcconfig"`
Relative path	The path to a build configuration file relative to the location of the current build configuration file.	`#include "../MyOtherConfigFile.xcconfig"`
Absolute path	An absolute path to a build configuration file on disk.	`#include "/Users/MyUserName/Desktop/MyOtherConfigFile.xcconfig"`

Note: References to other build configuration files are processed before interpreting any build settings.