Building Your App Using Build Configurations and .xcconfig

Creating a Staging Environment Configuration

To configure and create test builds of the app, you need a staging build configuration.

Open the Project Editor and select the NinjaCounter PROJECT. Open the Info tab.

This is where you define build configurations. They’re global and shared among targets. Click + to add a new one.

Select Duplicate “Debug” Configuration. Name the new configuration Staging.

You’ll see the new Staging configuration. Select the NinjaCounter target and switch to the Build Settings tab.

The settings now have new values for the new build configuration. You duplicated the build configuration from Debug, so they have the same values.

Now that you’ve created your staging environment, it’s time to add .xcconfig files.

Creating Configuration Settings Files

Using the Build Settings tab to modify settings has some disadvantages. Searching through long lists with different scopes is time-consuming, especially when you have multiple targets, build configurations and settings to manage. .xcconfig files are an alternative that simplifies this process.

Select the NinjaCounter group in Project navigator. Create a new group. Name the group Config Files. This is where you’ll place your configuration files.

Click File ▸ New ▸ File….

Select Configuration Settings File in the file templates list.

Name the file Debug.xcconfig. For this app, you need to create an .xcconfig file for each configuration. Create Staging.xcconfig and Release.xcconfig.

Next, you’ll set your configuration files in Xcode.

Working With Configuration Settings Files

To use configuration files you need to set them in Xcode. Before that, add a setting for the app display name.

Open Debug.xcconfig. Add the setting below and save.

APP_NAME = Ninja Counter

Settings in .xcconfig files use the following syntax: SETTING_NAME = VALUE.

Open the Project Editor and select the NinjaCounter project. Click the Info tab.

The Configurations section is where you set configuration files.

As you can see, you can use configuration files at the project level as well as at each target level, for each environment.

Under Based on Configuration File, click on a configuration file option.

Xcode shows you the list of .xcconfig files you’ve created. Set the corresponding configuration file for each build configuration to the app and widget targets, as shown below:

• Debug
• NinjaCounter: Debug
• WidgetExtension: Debug
• Staging
• NinjaCounter: Staging
• WidgetExtension: Staging
• Release
• NinjaCounter: Release
• WidgetExtension: Release

• NinjaCounter: Debug
• WidgetExtension: Debug

• NinjaCounter: Staging
• WidgetExtension: Staging

• NinjaCounter: Release
• WidgetExtension: Release

At this point, you’ve created a configuration file for each environment. Good job! Next, you’ll customize the settings for each environment.

Creating a User-Defined Setting to Change the Bundle Display Name

As a developer, you use and work with your app in all its phases. When you switch between different builds, it can be confusing to know which build you currently have installed. For that reason, having different display names is useful.

Open Debug.xcconfig. Change APP_NAME‘s value to Ninja CounterDev. This is the app display name you’ll see when you install a debug build.

Now, you’ll know at a glance that this is the development build that you’re working on with the top-secret and next-gen features! :]

Next, you need to change the names for the other configurations. Open Staging.xcconfig and add the following line:

APP_NAME = Ninja CounterQA

Finally, open Release.xcconfig and update the setting with the production display name:

APP_NAME = Ninja Counter

Next, select the project itself in the Project navigator. Select the NinjaCounter app target.

Open the Build Settings tab. Scroll to the end of list.

Now, you can see your user-defined build setting APP_NAME and a new scope of settings that shows values at the configuration files level. If you see the values you set in the configuration file here, you’re on the right track!

The last step to changing the app display name is to set Bundle display name to refer to your user-defined setting.

Open NinjaCounter’s Info.plist. Add the Bundle display name property. Set the value of the property to $(APP_NAME).

Optionally, you can also add it from the Info tab from the Project Editor.

Make sure you set NinjaCounter as the active scheme.

Build and run. Press Shift-Command-H to enter to the home screen.

Now, you can see your development build app name.

It’s time to test the app in the Staging environment. Option-click the the run button in the Xcode task bar.

Next, select the Run action, then the Info tab and click the Build Configuration drop-down menu. Your new staging configuration is in the list. Select Staging as the building configuration.

Click Run, wait for the app to start, then return the iOS home screen.

The app display name is now NinjaCounterQA, showing you immediately which build you are using.

Next, you’ll create a base configuration file to avoid redundant values.

Retaining Values With Inheritance

In your configuration file, you set the APP_NAME for your different builds to Ninja CounterDev, Ninja CounterQA and Ninja Counter. The release build name, NinjaCounter, is the base value, which you repeat in each name.

It’s a best practice to set general build settings at the project level. Then, reuse those settings in different configurations to avoid redundancy. In this case, you’ll change APP_NAME in each build configuration to inherit from the base value.

Right-click the Config files group. Select New file…. Create a new configuration file named Base.xcconfig and add the following line:

APP_NAME = Ninja Counter

Next, replace the content of the other configuration files as follows below.

Debug.xcconfig:

#include "Base.xcconfig"

APP_NAME = $(inherited)Dev

Staging.xcconfig:

#include "Base.xcconfig"

APP_NAME = $(inherited)QA

Release.xcconfig:

#include "Base.xcconfig"

Here, you changed the three configuration files to inherit and reuse the base settings from Base.xcconfig. You did this by using $(inherited) and appending the part of the name specific to each build.

Finally, build and run the app in Staging.

The app name displays correctly. Note that you didn’t need to add the APP_NAME definition to Release.xcconfig. That’s because the settings fall back to the inherited values.

To see how the settings display in Xcode, open the Project Editor. Select the NinjaCounter target, then Build Settings. Scroll to the User-defined section.

The resolved values don’t look correct despite displaying correctly when the app runs. That’s because Base.xcconfig isn’t set in the Configurations part of the Project Editor. However, the inheritance resolves as expected in runtime.

To fix this, select the project in the project editor. Under Configurations, set Base.xcconfig at the project level of all three configurations.

Now, go back to the Build Settings of the app target.

The values display correctly now in Xcode. Note the new scope shows the project-level configuration file.

Next, you’ll add more custom settings.