Build Configuration Overview

Build configurations allow you to build two or more “flavors” of a product without having to create separate targets for each product flavor. When you build a target, Xcode uses the build settings defined by that target for the current build configuration.

A common use of build configurations is to build a given target differently to create debug and release versions of a product. There are a handful of build settings—for example, optimization settings for the compiler—whose values are different, depending upon whether you are building a product for debugging purposes or to release to customers. In each situation, the target you build is identical in every other way—files, build phases, and build rules—because the product you want to generate for each is essentially the same. The only difference is in how the source files of the target are processed to build that product.

If you were to create two targets—one for debugging and one for the final build—you would have to remember to keep both targets in sync. When you added a file to one target, you would have to remember to add it to the other, and so forth. With a build configuration, you can build using a different group of build settings without changing the target’s build phases or build rules. It is much simpler to create build configurations containing the build settings whose values you want to change, and then build based on the appropriate configuration.

The project defines the list of build configurations; all targets in a project share the same namespace for build configurations. The actual definition of any given build configuration—the particular build setting definitions in that configuration—is specific to each target. You can also define project-level configurations. As described in Build Setting Evaluation, build settings defined at the target level take precedence over any values assigned to those build settings at the project level. This gives you a great deal of flexibility. For example, you can use project-level build configurations to define build settings that apply to all or most targets in the project. You can then modify or override these build settings for individual targets at the target layer.

The active build configuration is the build configuration Xcode uses when building the active target and any targets it depends upon. When you initiate a build, Xcode builds the active target and any targets it depends upon. For each target, Xcode applies the build settings defined by that target for the active build configuration, as well as any build settings defined for the active build configuration at the project level. See Setting the Active Target and Build Configuration for a description of how to change the active build configuration.

For each target, Xcode evaluates the build settings defined by that target for the active build configuration, as well as any build settings defined for the active build configuration at the project level. As described in Managing Build Configurations, the list of build configurations is the same for all targets within a project. When building targets in a referenced project, Xcode uses the build settings defined in the corresponding build configuration of that project.

If your project includes cross-project references, it is possible that the referenced project defines a different set of build configurations from those of the current project; the active build configuration may not exist in the referenced project. In this case, Xcode falls back on the default configuration for the referenced project and its targets.

For each target and project involved in a build, here is how the build configuration is selected when building from the Xcode application.

1. Xcode checks for a build configuration with the same name as the active build configuration. If this configuration is found, Xcode uses it.

2. If no matching build configuration is found, Xcode then uses the default build configuration.

The process of selecting build configurations is similar when building from the command line with xcodebuild:

1. If a specific build configuration is passed as a command-line argument to xcodebuild , xcodebuild first looks for a build configuration with that name in the project. If that configuration is found, Xcode uses it.

2. If no build configuration is specified on the command line or if the project does not define the specified build configuration, xcodebuild uses the default configuration.

New Xcode projects contain two predefined build configurations, Debug and Release. You can edit those build configurations or define new build configurations of your own.

In addition to the predefined Debug and Release build configurations, you may need to define a special build configuration to satisfy particular needs, such as configuring an environment to measure the performance of your application. In such a build configuration you may define build settings that add a library or framework that gathers and logs performance-related information. You may also need to target your application to specific Mac OS X versions. In that case, you may need to build your product slightly differently for each version. For example, you can have build configurations named Mac OS X 10.3 and Mac OS X 10.4 that build a product tailored for Mac OS X v10.3 and Mac OS X v10.4, respectively, by setting Mac OS X Deployment target (MACOSX_DEPLOYMENT_TARGET), and any other build settings necessary, to the appropriate values.

Predefined Build Configurations

A debug build of a product may include debugging information to assist you in fixing bugs. However, this extra information can consume valuable space in a user’s system. A debug build should contain only the code necessary to run the application.

Some build settings tell Xcode to add debugging information to an executable or specify whether to optimize its execution speed. Other build settings turn on features such as Fix and Continue, which are useful only during debugging.

All Xcode project and target templates include two build configurations, the Debug build configuration and the Release build configuration. By default, the Debug build configuration turns on Fix and Continue, and debug-symbol generation, among others, while turning off code optimization. The Release build configuration turns off Fix and Continue. The code-optimization level is set to its highest by default, through the Optimization Level (GCC_OPTIMIZATION_LEVEL) build setting. Note that the Release build configuration doesn’t turn on Deployment Location (DEPLOYMENT_LOCATION); therefore, the product is not copied to the location where it would be installed on a user’s system. It also doesn’t turn on Deployment Postprocessing (DEPLOYMENT_POSTPROCESSING), which specifies whether to strip binaries and whether to set their permissions to standard values.

Managing Build Configurations

Generally, the predefined build configurations described in Predefined Build Configurations are enough for most people. You can use them as they are or add additional build settings to them. For example, you can specify that the Debug build configuration for a target or project display more compiler warnings.

If you’re thinking about creating a target, consider whether it might be best to create a build configuration instead. In general, create a target to create a product, and create a build configuration to modify how that product is built. If you’re creating targets that differ only in their build settings, consider creating one target with several build configurations. If you need to create targets that differ in other ways—such as build phases—you need to create separate targets.

To see the list of build configurations defined for a project, open the project editor, and display the Configurations pane, shown in Figure 4-1. The configuration list displays all of the build configurations defined in the current project. You can edit the list of configurations as described in Managing Build Configurations.

These are the components of the Configuration pane of the project editor:

• Configuration list. List of the project’s build configurations.

• Duplicate button. Duplicates the selected build configuration throughout the project. In this way, if you have a number of build settings common to all configurations in a target, you do not have to set them all up again.

• Rename button. Renames the selected build configuration name. throughout the project.

• Delete button. Deletes the selected build configuration from the project.

• Default configuration pop-up menu. Specifies which of the build configuration is the default build configuration.

  the default build configuration is used when the project being built does not have a definition for the active build configuration, as described in Build Configuration Overview.

Build Configuration Files

When you work on large software endeavors with several projects and targets, many of which sharing a number of common build setting definitions, it can be time-consuming and repetitive to define the same build settings over and over again. For this reason, Xcode allows you to base a build configuration on build configuration file. A build configuration file (or configuration file for short) contains a list of build setting definitions. Using build configuration files, you can easily share a set of build setting definitions among all the individuals working on your team, or quickly configure targets and projects with common build setting definitions.

When you base a target or project’s build configuration on a build configuration file, that build configuration automatically inherits the build setting definitions in that configuration file (and the configuration files it includes), as well as any subsequent changes to the configuration file (or the configuration files it includes). If you then modify the value of any of those build settings in the target or project, the new value is used instead of the value in the configuration file.

For example, if you have a standard list of debugging build settings that you use to build debug versions of all your products, you can define a configuration file—say MyDebugSettings.xcconfig —that contains these build settings. You can then base the Debug build configurations for all your targets on this file. Each Debug configuration inherits the build settings in the MyDebugSettings.xcconfig file. You can then modify any of these build settings for individual targets or projects, as necessary.

GENERATE_PROFILING_CODE = YES               // Turn on profiling code

// File: MyConfig.xcconfig

#include "/Network/ProductDevelopmentSpecs/TeamConfig"

ARCHS = ppc i386

#include "/Network/ProductPackagingSpecs/ProductConfig"

Build Setting Evaluation and Configuration Files

Build settings are defined in a number of different layers, with definitions in higher layers overriding definitions in lower layers.

Of course, build settings at the target and project layers can be defined in the Xcode user interface or inherited from build configuration files. Figure 4-3 shows the build setting layers and their relationship to the build settings defined in configuration files.

When you use configuration files, the target and project layers themselves are each divided into two separate build setting layers. These are:

1. Build setting definitions listed in the build settings editor. Build settings configured in the Xcode user interface override build settings defined in the configuration file for the same build configuration of the target or project. This lets you customize the build for one or more targets or projects that otherwise share a common set of build settings.

2. Build setting definitions in the configuration file on which the active build configuration for the target or project is based. You can use configuration files to share build setting definitions across one or more build configurations in multiple targets or projects.

To understand how to use configuration files effectively, you must understand how configuration files affect the evaluation of build settings. The following example builds on the example used in Multilayer Build Setting Definitions to show how Xcode evaluates build settings in a project that uses configuration files. Figure 4-4 shows how the build system would evaluate the LAYERED build setting when using xcodebuild.

To evaluate the LAYERED build setting, Xcode does the following:

1. Looks for a definition for LAYERED in the command-line layer (the highest available to xcodebuild). It finds the specification command line, $(LAYERED).

2. Resolves $(LAYERED) starting at the next layer down, the target layer. At this layer, it obtains the specification target, $(LAYERED); this is the specification defined in the Xcode application for the active build configuration of the target. Because the specification also references the value of the LAYERED build setting, the build system continues to look for the build setting specification. In this case, the build configuration is based on a configuration file, so the build system continues its search there.

3. Looks in the ConfigFile.xcconfig file on which the active build configuration of the active target is based. In the configuration file, it obtains the specification configuration file, $(LAYERED). Because this specification also references the value of the LAYERED build setting, the build system continues to look in lower layers for the build setting specification.

4. Resolves $(LAYERED) starting at the project layer, obtaining project, $(LAYERED).

5. Looks in the ConfigFile.xcconfig file on which the active build configuration of the project is based, again obtaining the specification configuration file, $(LAYERED). In this example, the project-level build configuration is based on the same configuration file as the target-level build configuration; however, they could just as easily be based on different configuration files.

6. Resolves $(LAYERED) starting at the environment layer, obtaining environment.

   The evaluation of LAYERED stops here because there are no build setting layers below the environment layer. When all the references are resolved, the final value of the build setting is computed as command line, target, configuration file, project, configuration file, environment.

Knowing how the build system evaluates build settings in configuration files lets you easily determine where to configure build settings. For example, say you have a configuration file that contains settings common to most of your Xcode projects. Imagine that, for a particular project, you want to override the value of a single setting in the configuration file. Rather than creating a separate configuration file that defines this one build setting differently, you can simply define that build setting in the project inspector for that project. Figure 4-5 shows how the build system evaluates the LAYERED build setting when that build setting is overridden in the project inspector of the Xcode application.

These are the steps the build system takes to evaluate the LAYERED build setting:

1. Looks for a definition for LAYERED in the command-line layer (the highest available to xcodebuild). It finds the specification command line, $(LAYERED).

2. Resolves $(LAYERED) starting at the next layer down, the target layer. At this layer, it obtains the specification target, $(LAYERED).

3. Looks in the ConfigFile.xcconfig file on which the active build configuration of the active target is based. In the configuration file, it obtains the specification configuration file, $(LAYERED).

4. Resolves $(LAYERED) starting at the project layer, obtaining project.

   The evaluation of LAYERED stops here because there are no references to other build settings in its specification. Even though LAYERED is configured in the project layer, that specification has been overridden in the target layer; therefore, it’s ignored. The final value of LAYERED in this example is command line, target, configuration file, project.