How To Create the Xcode Configuration Settings File

The configuration of the Xcode project is saved into the project file (*.xcodeproj). It is enough for the normal scale application development, but if you develop the middle or large scale application, it may be not enought. You may want to control more flexible.

For example,

  • You would like to define the common macro across multiple projects.
  • You would like to change the search path of headers and/or libraries on each build machines.
  • You would like to not save the code signing configuration into the project file.
  • You would like to change the build configuration without Xcode.

You can write the configurations into the configuration settings file, and override the configurations of the project with it. This article explains how to create the Xcode configuration settings file.


Creating the configuration settings file

The configuration settings file is a text file. You can also create with the TextEditor, but you need to set it to the project file, so we create it with the Xcode.

Select the “New…” in the “New” of the “File” menu.
Select the “Configuration Settings File” in the template table and click “Next”.
Select the "Configuration Settings File" in the table
Select the “Configuration Settings File”
Uncheck the all items in “Targets”, select the destination, enter the file name and click “Create”.

The build configuration files are not targeted to a build target, even if the configuration is for a specific target.

Select the save destination and enter the file name
Select the save destination and enter the file name

The syntax of the configuration settings file

The syntax of the configuration settings file is simple. Write the configuration in each lines.

Configuration = Value

For example, if you would like to set the ONLY_ACTIVE_ARCH to be YES, write following line.



As with Swift code, everything after // until the end of the line is treated as a comment.

Types of the value

The type of values is different for each configurations. If you look at the build settings on Xcode, it could be a string or a number. It corresponds to that. The following types are defined.

  • Boolean (YES or NO)
  • String
  • Enumeration (The predefined text)
  • Space separated string list. If a string contains space, surround it with '.
  • Path. The file path and the directory path in the POSIX form.
  • Space separated path list. If a path contains space, surround it with '.

Reference to other configuration

If you would like to use the value of the other configuration setting, write in following form.

$(Other configuration)

Inherited value

If you don’t specify the target level configuration value, the project level configuration value will be used. If the project level configuration value is not defined too, the default value will be used. Like this, the inherited value may be used.

If you write the following as value, the inherited value will be used.


Use it for the configuration supporting multiple values such as the string list or the path list, you can add the element to the inherited value.

FLAGS = $(inherited) --no-timestamp

Platform specific configurations

If you would like to define the platform specific configurations, write the configuration in form of [platform=value]. The two platform is defined.

  • sdk : The cross platform sdk, such as macos10.12, iphoneos10.2 and so on. You can specify * as version for hit any versions.
  • arch : The CPU architecture. x86_64 or arm64.

Both of values can be spcified at one time, write in form as like configuration[sdk=macos10.12][arch=x86_64] = value.

Import other configuration files

If you would like to import other configuration files, use #include statement.

#include "Common.xcconfig"

In this case, the Common.xcconfig file is imported. If the file is missing, the warning will be displayed. If you write #include? statement, the warning will not be displayed even if the file is missing.

#include? "Option.xcconfig"

Assign the configuration settings file to the build target

To use the configuration settings file, assign it to the build target with the Xcode.

Open the project settings.
Open the disclosure button (with triangle icon) of the “Configurations”
Open the disclosure button
Open the disclosure button
Click “None” and select the configuration settings file.

For example, if you want to assign the Debug.xcconfig file to the Debug configuration, click the None in at the line “Example” project in theDebug configuration.

Assign the "Debug" to the debug configuration
Assign the “Debug” to the debug configuration

Configurations List

The configurations list is available in the Apple Developer Site.

Build Settings Reference | Apple Developer Documentation

Let's share this post !

Author of this article

Akira Hayashiのアバター Akira Hayashi Representative, Software Engineer

I am an application developer loves programming. This blog is a tech blog, its articles are learning notes. In my work, I mainly focus on desktop and mobile application development, but I also write technical books and teach seminars. The websites of my work and books are here -> RK Kaihatsu.