Settings Bundles Management in Xcode

What is a Settings bundle? A Settings bundle is a special kind of bundle provided by Apple to allow developers to add their app preferences into the iOS Settings app.

With the current state of iOS app development, almost always we will have multiple build configurations such as debug, beta, and release. Or we might even have multiple app targets within an Xcode project for various purposes.

With the situation mentioned above, how should one go about loading the desired Settings bundle for the respective build configuration?

In this article, let’s look into how we should manage the Settings bundles in the following situations:

Load Settings bundle only for debug configuration.
Load different Settings bundles for debug and release configuration.
Load different Settings bundles for different app targets.

The Concept Behind Settings Bundle

Before we start getting into Settings bundles management, let’s have a quick look at the concept behind Settings bundle.

Settings bundle is considered as resources of the app bundle. Every time when you build your project, Xcode will copy the Settings bundle into the app bundle and the iOS Settings app will display the app preferences based on the Settings bundle.

The following diagram illustrates the workflow behind the scene when you build your Xcode project.

The concept behind settings bundle in iOS — The concept behind settings bundle

By understanding the concept behind Settings bundle, you should be able to follow along with this tutorial without any problem.

Load Settings Bundle Only for Debug Configuration

Sometimes you might want to expose certain app preferences in the iOS Settings app just for testing or debugging purposes. However, this kind of app preferences should not be accessible to normal users.

In this kind of situation, you can include all those special app preferences into the Settings bundle and make the Settings bundle only available for debug configuration. To achieve that, you can run a shell script at the end of the Xcode build phases to delete the Settings bundle from the app bundle during a release build.

Adding Shell Script

Adding a shell script in the Xcode build phase is pretty easy. You can start by selecting your project in the project navigator. Open the “Build Phases” tab and click the “+” sign to add a new run script phase.

Copy and paste the following shell script into the scripting box so that it will run every time when Xcode builds your project.

BUILD_APP_DIR="$BUILT_PRODUCTS_DIR/$PRODUCT_NAME.app"

if [ $CONFIGURATION == "Release" ]; then
    rm -rf "$BUILD_APP_DIR/Settings.bundle"
fi

Basically what the above shell script does is to remove the Settings bundle (Settings.bundle) from the app bundle when the project is built with configuration named “Release”.

At this point, you might wonder where do these build configurations being defined. Head over to the project info tab, there you should see the “Configurations” section where it lists out all the build configurations available.

List of Xcode configuration — List of Xcode build configurations

Switching Build Configuration for Testing

By default, when you build and run (⌘R) a project, the project will be built using the “Debug” configuration. Go ahead and run the project using the “Debug” configuration, you should see the Settings app showing all the app preferences defined in the Settings bundle.

Displaying app preferences in iOS Settings app

Next, let’s switch the build configuration to “Release” by editing the app target scheme.

Change build configuration in Xcode — Change build configuration

After changing the build configuration to “Release”, build and run your project again. This time you should not see any app preferences being added to the Settings app because the shell script has removed the Settings bundle from the app bundle.

Shell Script Debugging

If the shell script is not behaving as you expected, most probably the shell script is not getting the correct app bundle path. In this kind of situation, for debugging purposes, you can print out the BUILD_APP_DIR using the echo command.

You can check the printed out BUILD_APP_DIR value at Xcode report navigator.

Shell script echo result in Xcode — Shell script echo result

Lastly, if you found that the shell script is not taking effect even though you have updated it, cleaning the build folder (⇧⌘K) then rebuild the project should do the trick.

Load Different Settings Bundles for Debug and Release Configuration

Similar to the situation mentioned in the previous section, you want to enable certain app preferences just for debugging purposes. However, this time you do have some other end users related app preferences that you want to include in the release build.

In this kind of situation, you will have to create 2 Settings bundles, remove them from the “Copy Bundle Resources” build phase and then run a shell script to manually copy the respective Settings bundle to the app bundle.

Let’s say you have created 2 Settings bundles for your project as shown in the image below:

Settings bundles for debug and release build configuration in Xcode — Settings bundles for debug and release build configuration

Head over to the app target build phases tab and remove the 2 Settings bundles from the “Copy Bundle Resources” list.

Remove Settings bundle from bundle resources in Xcode — Remove Settings bundle from bundle resources

Lastly, copy the following shell script and paste it into the scripting box.

BUNDLE_DIR="$PROJECT_DIR/$PRODUCT_NAME/Settings Bundles"
BUILD_APP_DIR="$BUILT_PRODUCTS_DIR/$PRODUCT_NAME.app"

if [ $CONFIGURATION == "Release" ]; then
    # Copy Settings bundle in "Release" folder into the app bundle
    cp -rf "$BUNDLE_DIR/Release/Settings.bundle" "$BUILD_APP_DIR/Settings.bundle"
else
    # Copy Settings bundle in "Debug" folder into the app bundle
    cp -rf "$BUNDLE_DIR/Debug/Settings.bundle" "$BUILD_APP_DIR/Settings.bundle"
fi

Now, Go ahead and run your project in “Debug” or “Release” configuration and see the app preferences in the Settings app change accordingly.

Something to Take Note

The Settings bundle must be named as “Settings.bundle” in the app bundle, any other naming will not work and you won’t see your app being listed in the iOS Settings app.

If you bump into the following compiler error, most probably the path defined in the shell script is not pointing to the Settings bundle.

Command PhaseScriptExecution failed with a nonzero exit code

Compiler error when copy Settings bundle with shell script in Xcode — Compiler error when copy Settings bundle with shell script

What you can do is to print out the respective path using echo and fix the problem accordingly.

Load Different Settings Bundles for Different App Targets

In the last section of this article, let’s look at how to manage multiple Settings bundles in a multiple app targets environment.

Let’s say you have an Xcode project with 2 app targets (Paid and Free). On top of that, each app target will have its own Settings bundle.

In order to let Xcode know which Settings bundle belongs to which target, you just need to set the Settings.bundle target membership correctly, then you are good to go.