Working with Xcode Build Configurations files (XCConfigs)
Have you changed or tweaked your build settings in Xcode? Have you ever pushed Xcode build settings changes to git? Tweaking Xcode build settings can be a messy business.
Let’s say you’re working with multiple devs in the same Xcode project. Reviewing changes to the xcodeproj can be hard to read and to follow. Furthermore changing build configs on multiple branches can cause conflicts in the xcodeprojs. Resolving conflicts can lead to the risk of loosing build settings changes.
So how can we make it easier for developers to easily read and review changes to the build settings? How can we make derisk the chance of loosing build settings changes when xcodeproj conflicts occur? The answer is in the title of the post: Xcode Build Configurations files. The extension of these files are
.xcconfig thus these files are often referred to as xcconfigs.
XCConfig’s are simple files that can store build configuration separate to the your xcodeproj. Moreover these are readable and easy to follow.
In this post I will show you how to extract and save xcodeproj build configuration into XCConfig’s and link these against your Xcode project. In this post I will not cover what build configuration is. I won’t cover the different settings, value and their consequences to your app. I assume you understand this and you are familiar with Xcode project build settings and how to configure your builds in your Xcode project.
I have used Swift 5.6 and Xcode 13.3.1 for this article.
In this section I will show you how to extract build configuration from an existing Xcode project into an XCConfig file. We’ll then tell Xcode to use this XCConfig file as the build configuration.
Here are the steps we’ll take:
- Download the starter pack
- Create a build configuration file (xcconfig)
- Extract build configuration from the Xcode project into the
- Link the xcconfig file to our Xcode project
1. Download the starter pack
Let’s download an already existing iOS app project. Open a terminal and run the following commands:
curl https://github.com/anuragajwani/CryptoNav/archive/refs/tags/starter.zip -o starter.zip -L -s
unzip -q starter.zip
open -a Xcode CryptoNav.xcodeproj
2. Create a build configuration file
Next let’s create a build configuration file where we’ll capture the build settings for the CryptoNav app. From menu select File > New > File…
Then within the iOS tab search and select Configuration Settings File.
Then click Next and finally name the file MyConfig.
The created file contains a helpful link to documentation on xcconfig.
3. Extract build configuration from the Xcode project into an XCConfig file
In this section we’ll capture a few of the build settings of the
CryptoNav project into a build configuration file. First let’s take a look at some configuration settings in Xcode. Then we’ll replicate that setting in
To view build settings navigate to the project navigator. Then select CryptoNav project (top level item with a blue icon on the left hand side). You can find this under the first tab of the left hand pane.
Next within the main pane select CryptoNav under TARGETS section. Then select the Build Settings tab.
In this pane you will find a bunch of settings and their set values or empty if nothing is set.
We’re going to extract a single setting in this tutorial. Let’s take the product bundle identifier for example.
We need to find the key for such setting. So how do we find out the key? There are two ways:
project.pbxprojfile under the
xcodeprojdirectory (raw text form)
- Finding out the key by using xcodebuildsettings.com
Next, let’s state the key and value of the Product Bundle Identifier in
MyConfig.xcconfig. We will state the value a bit differently than the one stated in the project so we can test the
xcconfig setting the value for such key.
MyConfig.xcconfig and add the following line:
PRODUCT_BUNDLE_IDENTIFIER = com.anuragajwani.CryptoNavTest
Next let’s remove the key-value pair from the Xcode project. In the terminal run the following command:
open -a TextEdit $HOME/CryptoNav-starter/CryptoNav.xcodeproj/project.pbxproj
Then search and remove any lines containing
Next let’s check whether the build setting has taken effect. Once again open up the CryptoNav project, then within the main select
CryptoNav target followed by selecting the Build Settings tab.
No value is set. Why? We haven’t told the Xcode project to read from our build configuration file. Let’s do that next.
4. Link the XCConfig file to our Xcode project
In this step we’ll link our build configuration file–
MyConfig.xcconfig–to our Xcode project. To do so select
CryptoNav project from the project navigator, then within the main pane select
CryptoNav under “PROJECT”. Then select the
Then disclose Debug and Release under Configuration.
Finally, let’s set
MyConfig as the build configuration for both Debug and Release profiles for the
CryptoNav iOS app Target.
Go back to
CryptoNav project >
CryptoNav app target > Build Settings tab and search for
PRODUCT_BUNDLE_IDENTIFIER. You’ll notice that now Xcode is reading the build settings from our MyConfig file!
In this post we learned:
- What build configuration files are
- Why use build configuration files
- How to create build configuration files
- How to extract build settings into the build configuration file
- How to link build configuration file in our project