Extract Build Configuration From Unreadable Xcodeproj Files Into Readable Xcconfigs | by Anurag Ajwani | Jul, 2022

Working with Xcode Build Configurations files (XCConfigs)

Photo by Jimmy Nilsson Masth on Unsplash

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.

Reviewing xcodeproj files

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. These more 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:

  1. Download the starter pack
  2. Create a build configuration file (xcconfig)
  3. Extract build configuration from the Xcode project into the xcconfig file
  4. 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:

cd $HOME
curl https://github.com/anuragajwani/CryptoNav/archive/refs/tags/starter.zip -o starter.zip -L -s
unzip -q starter.zip
cd CryptoNav-starter
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.

Search and select “Configuration Settings File”

Then click Next and finally name the file MyConfig.

Name the file MyConfig

The created file contains a helpful link to documentation on xcconfig.

Example of text on the generated file

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 MyConfig.xcconfig.

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.

Select CryptoNav project from the project navigator tab

Next within the main pane select CryptoNav under TARGETS section. Then select the Build Settings tab.

Select CryptNav Target and then Build Settings tab within the main pane

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:

  1. Inspecting project.pbxproj file under the xcodeproj directory (raw text form)
  2. Finding out the key by using xcodebuildsettings.com
Product Bundle Identifier key and value in project.pbxproj
Product Bundle Identifier settings in 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.

Open 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 PRODUCT_BUNDLE_IDENTIFIER.

Remove any entries for PRODUCT_BUNDLE_IDENTIFIER

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 Info tab.

Navigate to the CryptoNav PROJECT settings

Then disclosed 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

Leave a Comment