always shows and edits whatever the active build confi guration is. Changing the build confi guration using Project ➪ Set Active Build Confi guration immediately changes the build settings in the Info window to match. One of the most useful views is the All Confi gurations view. When you select this view, the Build tab shows a composite view of all of the settings from all confi gurations. It does this the same way items in a multi - item Info window are displayed. Settings with values that are different between confi gurations are displayed as < Multiple values > . Boolean options whose values are set with a check box show a hyphen. You can quickly scan the list to see which settings differ between confi gurations. More importantly, when you are in this view, any change you make to a setting sets that value in every confi guration of the target or project. This mode is extremely useful for setting project and target settings in multiple confi gurations simultaneously, but it also requires some care. You can easily overwrite settings that were created for a specifi c confi guration. It is also easy to unintentionally create new build settings. In the All Confi gurations view, editing the value of a setting also creates that setting (with the same value) in every confi guration that did not previously contain that setting. Similarly, deleting a setting in the All Confi gurations view deletes that setting from every confi guration. EDITING BUILD CONFIGURATIONS You manage build confi gurations in the Confi gurations tab of the project ’ s Info window, shown in Figure 17 - 30. The Edit Confi guration List shows the build confi gurations defi ned in the project. You can get to this by opening the Info window for the project. You can also jump there by selecting the conveniently placed Edit Confi gurations item in the Confi guration menu of any build settings editor. You create a new confi guration by selecting an existing confi guration and clicking the Duplicate button at the bottom of the pane. Remember that a build confi guration represents a complete set of build settings for every target and for the project itself — you really wouldn ’ t want to create a completely empty set of build settings. Select the confi guration that is closest to the settings you want for your new confi guration, duplicate it, and then go fi x the differences in the build settings of the project and each target. FIGURE 17-30 Editing Build Confi gurations ❘ 409 c17.indd 409c17.indd 409 1/22/10 12:50:53 PM1/22/10 12:50:53 PM Download at getcoolebook.com 410 ❘ CHAPTER 17 BUILDING PROJECTS To delete a build confi guration, select it in the list and click the Delete button. A project must have at least one build confi guration, so you can ’ t delete them all. You can rename a build confi guration using the Rename button or by double - clicking the confi guration ’ s name. At the bottom of the pane is a default confi guration selection, declared as the Command - Line Builds Use setting. Use this to select the default build confi guration for the project. This setting may be signifi cant when building cross - project targets or when you ’ re building a project using the xcodebuild tool. When you ’ re building a project directly within the Xcode application, the active build confi guration unambiguously determines the build confi guration that will be used. However, subprojects and projects built with the xcodebuild tool are not always as defi nitive. When a cross - project dependency causes a target in another project to be built, Xcode tries to use the build confi guration in the external project with the same name as the one it is using for the current target. What if a build confi guration with that name doesn ’ t exist in the other project? Likewise, when using the xcodebuild tool, you are not required to specify which build confi guration you want to use, forcing Xcode to choose for you. In both of these situations, Xcode uses the default build confi guration you ’ ve specifi ed in your project. If the default confi guration is set to “ none, ” the default build confi guration is undefi ned and unpredictable; fi x this by choosing a confi guration from the menu. CONFIGURATION SETTINGS FILES Target and project build settings can be based on a confi guration settings fi le. A confi guration settings fi le is nothing more than a specially formatted text fi le containing a collection of build settings. The following code demonstrates a confi guration settings fi le that defi nes the same build settings used in an earlier example: COMPANY = Sharp Pencils YEARS = 2003 COPYRIGHT_STATEMENT = "Copyright $(YEARS), $(COMPANY)" The format of the fi le is simple. Each line contains a build setting variable name, an equals sign ( = ), followed by the setting ’ s value. Any amount of white space before or after the = and at the end of the line is ignored. Placing quotes around values with special characters is optional. Everything between the = and the end of the line, ignoring any leading or trailing white space, becomes the value for the setting. The fi le cannot contain anything else, except blank lines and C++ - style comments. There is no support for multi - line values, escaped characters, or any other syntax that you would normally associate with a property list or source fi le. If even a single line fails to conform to this simple format, the entire fi le is ignored. The encoding of a confi guration fi le must be ASCII or UTF - 8. UFT - 8 allows confi guration settings fi les to contain non - ASCII characters. You cannot localize confi guration settings fi les. A confi guration settings fi le has an extension of .xcconfig and must be a source fi le in the project, although it should not be included in any targets. After you ’ ve added a confi guration settings fi le to your project, you can set any target or project build settings to be based on that confi guration settings fi le by selecting it in the Based On menu as shown in Figure 17 - 31. c17.indd 410c17.indd 410 1/22/10 12:50:53 PM1/22/10 12:50:53 PM Download at getcoolebook.com The build settings in the confi guration settings fi le form a layer of build settings immediately below the target or project layer you ’ ve adopted them in. The Based On option is build confi guration specifi c, so you can use different confi guration settings fi les for each confi guration. A project or target that is based on a confi guration settings fi le can still override any of the settings in the fi le by defi ning its own setting — exactly as it would override a setting from any lower layer of build settings. The All Confi gurations view may not display a <multiple values> value for the confi guration fi le of the target or project. Changing the Based On setting while you’re in the All Confi gurations view dutifully sets the confi guration fi le for all confi gurations to the new choice. Adding a Confi guration Settings File Create an empty confi guration settings fi le and add it to your project by choosing the File ➪ New File command. Find and choose the Xcode Confi gurations Settings File template. Give the fi le a name and add it to your project. When asked, do not add the fi le to any targets. Confi guration settings fi les are not input fi les to the target ’ s build phases; they are only used to populate the build settings. If you already have a confi guration settings fi le that exists but hasn ’ t been added to the project, simply add it to the project like any other source fi le. See Chapter 5 for a quick refresher on adding source fi les. Again, do not add the confi guration settings fi le to any targets when adding it to the project. Confi guration settings fi les are part of the build infrastructure; they are not the thing being built. FIGURE 17-31 Confi guration Settings Files ❘ 411 c17.indd 411c17.indd 411 1/22/10 12:50:54 PM1/22/10 12:50:54 PM Download at getcoolebook.com 412 ❘ CHAPTER 17 BUILDING PROJECTS Using Confi guration Settings Files Use confi guration settings fi les when you have a number of targets or projects that each need a uniform, or at least very similar, set of build settings. Confi guration settings fi les are most useful when you have a large number of projects, targets, or build confi gurations, and maintaining common settings across all of those projects/targets/confi gurations becomes cumbersome. Targets and projects can be based on a single confi guration settings fi le. Confi guration settings fi les cannot be linked to other confi guration settings fi les, nested, or otherwise combined, so don ’ t try to design a hierarchical structure of confi guration settings fi les; it won ’ t work. Confi guration settings fi les are only an adjunct to the build settings layer hierarchy already defi ned by Xcode. Consider these best practices when creating confi guration settings fi les: Common build settings for similar product types. For example, you might want to create a confi guration settings fi les for all your Cocoa applications. Regularly used compiler or debug settings. All of your Debug build confi gurations in different projects could share a single MyFavoriteDebugSettings.xcconfig fi le. Build settings that are maintained externally or that can be generated programmatically. Build settings containing things like company product codes could be generated or updated by an external process. Keep in mind the project or target can override anything defi ned in the settings fi le on which it is based. Settings fi les don ’ t have to contain exactly the values needed by all of the targets, projects, or confi gurations that are based on it. They only need to defi ne the preferred values for the settings you regularly set. Think of them as your own layer of defaults, much like Xcode ’ s default settings layer. MOVING BUILD SETTINGS AROUND Eventually, you ’ ll discover that you have a build setting in a target that really needs to be in the project build settings or a build confi guration fi le. Moving build settings around couldn ’ t be easier, although it may not be immediately obvious as to how. The trick is to use the clipboard. You can cut, copy, and paste build settings between build settings panes and confi guration fi les. When Xcode copies a build setting to the clipboard, it places a textual representation of the build setting in the clipboard using the format required by confi guration fi les. Because of this, you can copy build settings from a build settings pane and paste them into another build settings pane, a confi guration settings fi le, or vice versa. Pasting in a build settings pane replaces any other settings defi ned with the same name. Cutting a build setting is equivalent to copying the setting to the clipboard and then deleting the setting. Note that cutting an inherited setting results in a copy, because there ’ s no setting to delete at this level. Copying a value in the All Confi gurations view may result in copying the value < Multiple values > , which you ’ ll have to edit. ➤ ➤ ➤ c17.indd 412c17.indd 412 1/22/10 12:50:57 PM1/22/10 12:50:57 PM Download at getcoolebook.com ENVIRONMENT SETTINGS The environment layer of build settings must be set up outside of Xcode and they must be set before the Xcode application or xcodebuild tool are launched. Xcode uses any environment variable that conforms to the build settings naming convention. Specifi cally, a variable name must begin with a letter or underscore and contain only letters, numbers, or underscore characters. All letters should be uppercase. How you set environment variables before launching the xcodebuild tool depends on the calling process. Shells such as bash and tcsh typically use some form of “ export ” command. For Perl, C, Java, or similar programming languages, environment variables are usually assembled into a collection that is passed to the function that launches the tool. Regardless of how it is accomplished, whatever environment values are passed to the xcodebuild tool will be accessible to the build phases of each target built. The beginning of the “Build Settings” section stated that target and project build setting are never inherited or passed to other targets or projects. This may not always be true if your build involves shell scripts. Whenever Xcode starts an external process — a custom build script or external tool — all of the build settings for that target are resolved and passed to that process as environment variables. If that external process causes another Xcode target to be built using the xcodebuild tool, that build inherits all of the build settings as environment settings, regardless of their original scope. Thus, a setting that is defi ned as a target setting in one project can appear as an environment setting in a second if the second target was built by the fi rst target using a custom build script or external build tool. How you set environment variables for use with the Xcode application itself isn ’ t immediately obvious. That ’ s because you don ’ t normally think of GUI applications of having an “ environment ” the way shell and BSD tools do. In fact, OS X provides a simple — albeit obscure — technique for defi ning whatever environment variables you want. These variables are available to all running applications. You can read more about it at http://developer.apple.com/mac/library/qa/ qa2001/qa1067.html . The magic fi le is named ~/.MacOSX/environment.plist . The .MacOSX folder is an invisible folder in your login account ’ s home directory. The environment.plist fi le is an XML property list fi le containing a list of key/value pairs. Each pair defi nes an environment variable that gets defi ned when you log in. All applications you launch include these variables in their environment. You can edit the environment.plist fi le using the Property List Editor application or any good text editor. However, you might prefer to use a little utility called RCEnvironment, shown in Figure 17 - 32, which is available free from Rubicode at http://www.rubicode.com/Software/ RCEnvironment/ . It ’ s a System Preferences panel that lets you edit your environment.plist fi le very much like you would edit build settings in Xcode. Remember that changes only take effect when you log in. After making changes, remember to save the fi le, log out, and then log back in again. Environment Settings ❘ 413 c17.indd 413c17.indd 413 1/22/10 12:50:57 PM1/22/10 12:50:57 PM Download at getcoolebook.com 414 ❘ CHAPTER 17 BUILDING PROJECTS CUSTOMIZING THE BUILD Using build settings, and a few specialized Xcode settings, it ’ s possible to customize hundreds of details about your build. There are literally hundreds of build settings — and the number grows with each release of Xcode. Finding the build setting you ’ re looking for can sometimes be a challenge. The build settings tab displays a description of the selected build setting, and is the fi rst place to look when you ’ re hunting for a build setting or wondering what a build setting does. You can also set the search fi eld to search the descriptions of build settings, which might also help you fi nd what you ’ re looking for. The next few sections cover many common ways of customizing your build process and products. A few are special features of the Xcode application, but most are confi gured using build settings. The later sections cover some of the more important build settings, especially ones that control the build process itself and ones that might have non - obvious relationships. This book can ’ t possibly explain them all. The following sections hit the highlights and point you toward the documentation for the rest. Per - File Compiler Flags The per - fi le compiler fl ags setting is a special place where the compilation of a single source fi le can be modifi ed. These are literal command - line arguments, set for a particular source fi le and target, and passed to the compiler only when that source fi le is compiled. Each source fi le has a separate compiler fl ags setting for each target in the project, so you can specify one compiler fl ag when the fi le is being compiled for one target and a different compiler fl ag when it is compiled for another. There are no templates or documentation for these options in Xcode. You will need to consult the compiler ’ s documentation to compose your argument list correctly. Open the Info window for a source fi le. If the source belongs to the active target, a Build tab appears in the Info window, as shown in Figure 17 - 33. You can only edit the compiler fl ags for the active target. To edit the compiler fl ags for a different target, you must close the Info window, choose a new active target using the Project ➪ Set Active Target menu, and then open the Info window for the source fi le again. FIGURE 1732 c17.indd 414c17.indd 414 1/22/10 12:51:03 PM1/22/10 12:51:03 PM Download at getcoolebook.com . the new choice. Adding a Confi guration Settings File Create an empty confi guration settings fi le and add it to your project by choosing the File ➪ New File command. Find and choose the Xcode Confi. Likewise, when using the xcodebuild tool, you are not required to specify which build confi guration you want to use, forcing Xcode to choose for you. In both of these situations, Xcode uses the default. more about it at http://developer.apple.com /mac/ library/qa/ qa2001/qa1067.html . The magic fi le is named ~/.MacOSX/environment.plist . The .MacOSX folder is an invisible folder in your login