xcode-header

During development process, we usually have to work on a multiple environments namely; staging and production. These environments tend to have a few different parameters such as the server hostname, Bundle ID and third-party app API keys to name a few.

Previously, I tend to switch between this environments manually. Means, I manually replace the server URL parameters, API key, app bundle ID, well you got the idea. Repeating this task whenever you want to change between environments is quite time – consuming, error – prone and repetitive. To sums up, it’s problematic and unnecessary.

This guide will explain the method that I have been using to solve this problem and painlessly switch between different build environments.

We will use Xcode Scheme, Build Configuration and Build Settings to manage different builds; staging, production and App Store builds.

To make this guide easy to follow, I will start with a new project. If you already have an existing project, you can directly skip to step 2.

Step 1: Create a new project

When starting out a new project, fill in the empty fields with your project details eg.

Product Name: Your project name

Organization Name: Your organization name (Can be left blank)

Organization Identifier: com.company

screenshot-1

Create a new project

Click  Next . Choose your project location and click Create. Xcode will then set up your new project and open the editor for you.

Step 2:  Create Build Configurations

Firstly, navigate to your project info. And find the Configurations section. Your Configurations option will have a Debug option and Release option inside.

Look for the Configurations section

Look for the Configurations section

Then, click on the Add button (+) and select the duplicate the "Debug" configuration to create a new configuration.

screenshot-3

Click on the (+) button and duplicate the configuration

Rename the newly created configuration to Debug Staging by double clicking the configuration name.

screenshot-4

Rename the duplicated configuration.

Proceed this method to create 2 more different builds; Release Staging and App Store by duplicating the Release configuration.

As a result, we will have 5 different build configurations; Debug, Debug Staging, Release, Release Staging and App Store.

screenshot-5

5 Different build configurations

Step 3: Create User-defined Build Settings

Typically, we will create a user-defined settings for Bundle ID, app icon names, Facebook App ID, etc. So we will be able to assign different Bundle ID, icon names or Facebook App ID for different Build Configurations. To do so, navigate to project build settings, click on the Add button(+) and add User-defined Setting.

In this example, I create 3 different user-defined setting; BUNDLE_ID, NAME_SUFFIX and FB_APP_ID.

screenshot-6

Create a User-Defined setting.

After adding the new user-defined settings, edit the build configurations value inside each of the settings as you can see in the image below.

screenshot-7

Edit the configurations value

Step 4: Modify Info.plist file

All the user-defined settings defined in the previous step will be used in the project’s info.plist. Make sure you have done all the previous steps before proceeding.

Modify your info.plist by inserting the value defined in user-defined settings. So, for example if you define BUNDLE_ID in user-defined settings, modify your bundle identifier in info.plist with $(BUNDLE_ID).

Bundle Identifier : $(BUNDLE_ID)

Bundle display name: Demo App $(NAME_SUFFIX)

FacebookAppID: $(FB_APP_ID)

If your project’s info.plist is missing some of the fields, simply add a new one.

screenshot-8

Modify info.plist with the user-defined settings.

Step 5: Create Schemes with Build Configurations

Each of our app builds needs one Scheme, so we will create 3 Schemes; DemoAppStaging, DemoAppProduction and DemoAppStore, for staging build, production build and App Store build respectively.

Click on your project active scheme located on top left of the editor and click on “manage scheme”. Refer the image below if you can’t find it.

screenshot-9

Click on the “Manage Schemes” option

Then, create a new scheme named DemoAppStaging.

screenshot-10

Steps to create a new scheme

Proceed this step for each DemoAppProduction and DemoAppAppStore. Make sure that you check the Shared option so that these changes are added on Git repository.

screenshot-11

Make sure to tick on the “Shared” option for each scheme.

Step 6: Edit Schemes

Then, edit the schemes based on the build configurations. For example, DemoAppStaging use Debug Staging and Release Staging Build configurations. Make sure that you have edit each of the build configurations for Build, Run, Test, Profile, Analyze and Archive.

screenshot-12

Edit the schemes properly.

Edit each schemes based on the following configurations specified in the table below.

Schemes Configurations
DemoAppStaging Debug Staging
Release Staging
DemoAppProduction Debug
Release
DemoAppStore App Store

Now, we can easily switch between different builds by easily selecting the schemes that we have specified previously.

screenshot-13

Select the schemes to change between different builds.

Step 7: Define Preprocessor Macros

To easily switch the Base URL of API server, we can add a preprocessor macros to define the target’s environment. For example STAGING=1 for Staging schemes. To add the macros, search for Preprocessor Macros under the Apple LLVM6.0 - preprocessing section. Then add STAGING=1 in Debug Staging and Release Staging.

screenshot-14

Add “STAGING=1” in Debug Staging and Release Staging.

 

Finally, simply defines the Base URL as follows in Constant class or the project-Prefix.pch file, whichever one that fits your preferences.

That’s it. Now, you can switch between staging and production easily without having to manually change the parameters. If you have any questions or comments regarding this guide, feel free to post a comment below. Thanks!

Oh, and you can follow me on  Twitter!

13 comments on XCode: 7 Steps to Easily Switch Between Multiple Environments

      1. I too had a linker errors, and to solve it I’ve just created the same Configurations for Pods Project and it worked 😉

        So, just repeat the “Step 2: Create Build Configurations” , but for Pods instead for DemoApp.
        2. Product->Clean
        3. Product->Build/Run
        and that’s it

        1. Also, if you get “dyld: Library not loaded: ….” after that, check the end of yours
          “Pods-Brag-frameworks.sh”
          (located in Pods/Targets Support Files/Pods-{your_project_name}/ dir)
          for build configurations (Staging, AppStore & etc)

          if [[ “$CONFIGURATION” == “Debug Staging” ]]; then

          and add missing configs.

  1. Thanks for good article. If I will use this instructions for environments switches, then how I will deliver test build to testers using TestFlight.

  2. Thanks for this tutorial! For any Cocoapods users having trouble compiling after following the above steps please refer to this GH issue: https://github.com/CocoaPods/CocoaPods/issues/2633

    TL;DR here are the steps:

    gem update cocoapods ( to version 0.36.4 coming from 0.35.x )
    set the configurations for my targets to none
    closed my Xcode workspace
    ran pod install
    cocoapods fixed the none configurations correctly
    project compiles again, just like before

Hello there, anything to say? ;-)