Using .xcconfig files and custom schemes for your Xcode project

When you create a project, Xcode provides two standard project-level build configurations: debug and release. These two build configurations are probably sufficient for your product development needs. But sometimes you need to use configuration files and new schemes additional to your project target scheme.

For instance, you give a test app to your testers for their regular tests and you provide a qa application to them for your server side release controls and finally make a test flight version of your application for submission controls. There could be some values that can vary within test, qa and production version of your app, such as application id (com.example.myapptest, com.example.myapp), preprocessor macros (DEBUG =1, DEBUG=0), entitlement values, codesign identities (developer team ids), provisioning profile names, server environment definitions (local, test, qa, prod server addresses) and so on.

A configuration file is the best way to store values of variables for different versions of your application.

Firstly, you should decide how many different configuration/states your application needs. In my example, it is 3 – test, qa, production states. We should create one scheme and one configuration file per each state.

– Creating configuration file and define variables

Go to File > New File > Other > Configuration Settings File, click Next and name the configuration file. In the second dialog box, don’t select any target, leave it empty.

Screen Shot 2015-09-23 at 23.09.51– Prepare your xcconfig files for all states.

Configuration Files

– Creating configurations and adding them to the project.

Select Project on the Navigator, Go to Project > Info > Configurations section. Click “+” button for adding a new configuration. To make this you should duplicate an existing one. I prefer Duplicate “Release” Configuration option.

Screen Shot 2015-09-23 at 23.31.51

After duplicating and naming the configuration, select the xcconfig configuration file to use with, so in the project build settings, you can use your variables that you defined in this config files. Xcode will use their values automatically in build settings.

Screen Shot 2015-09-23 at 23.34.05

After adding multiple configurations to project, Go to Target > Project Settings. You’ll see there will be extra lines for your new configurations in each section.

– Using config variables in the project

You can use your configuration variables in project settings, info.plist and entitlement files. In this example, my application id, codesing identity and provision profile value will change from one state to another, so i define and use $PROVISIONING_PROFILE_NAME, $CODESIGN_IDENTITY in project file and $APP_ID in info.plist file. If you assign config variables to preprocessor macros, you can also shape your code blocks that can change accordingly states of your application. A sample TST xcconfig file is as follows.

Screen Shot 2015-09-24 at 15.39.29

In project build settings..

Screen Shot 2015-09-24 at 00.19.06

Screen Shot 2015-09-24 at 00.19.47

– Creating custom schemes and using custom configurations

For saying Xcode that “I will use TST configuration for building my test app”, you should create custom schemes and say use my TST configuration variables in your build!

First Go to Product > Scheme > Manage Schemes, select your default scheme and click settings Duplicate, name configuration and in Run and Archive settings, change Build Configuration appropriately.

Screen Shot 2015-09-24 at 14.59.01Screen Shot 2015-09-24 at 14.59.29

While your project is getting bigger and bigger, using config files is more manageable and more clear to see your configuration parameters. Using custom schemes will be more flexible if you’ll use Xcode command lines tools for automated builds.

Have a good coding..

PS: If you find this article useful please use like button 🙂 and if you have a question or a comment, don’t hesitate to share it!


One thought on “Using .xcconfig files and custom schemes for your Xcode project

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s