that many professional software teams use a common build location to share built products. At the very least, maintenance is easier if your projects don ’ t override the build location defi ned in the Xcode Preferences. Any change that needs to be made can be made in one place: the Xcode Preferences. The second solution sets the custom build location only in those projects that need to share built products. Although this would appear to be the most concise solution, you are going to have problems sharing those projects with other developers. Project - specifi c custom build locations are absolute paths stored in the project document. Give that project to another developer, and the project won ’ t build if the path to its build location doesn ’ t exist on their system. More than likely, it won ’ t — unless you ’ ve colluded with the other developer beforehand to ensure that it does. Using the single build location defi ned in the Xcode Preferences (the fi rst strategy) works because the only information stored in each project document is a fl ag to use the global build location defi ned by the current user — a location that can be different for every developer. This is, in a fashion, similar to the philosophy of source trees described in Chapter 21 and requires only that all of the developers have a custom build location defi ned in their preferences. On the other hand, defi ning a centralized build location for all projects prevents any project from using the project folder for its build location. After you set the Xcode Preferences to a custom build location, you lose the convenience of using the local build folder for all of your projects. If you have just a few projects that need to share built products, and you don ’ t need to share those projects with other developers, consider setting the build location for those projects individually. The rest of your projects can continue to use their local build folder. The third option is somewhat of a trick, but works well for small, self - contained, projects. When you place two or more projects in the same project folder, they all share the same local build folder without having to defi ne a custom build location in Xcode or any of the projects. There ’ s no confi guration required and the projects build regardless of the current Xcode preferences. When you ’ re considering your options, think about why you need to break up your work into multiple projects. If the goal is to reuse libraries and frameworks or share projects with other developers, then one of the aforementioned solutions will meet your needs. However, if you are subdividing your project merely for the sake of organization, consider for a moment if you even need separate projects. You may be able to achieve the same goals using multiple targets, source groups, and build confi guration fi les in a single project, eliminating all multi - project problems and complexities. BUILD SETTINGS Build settings have been mentioned numerous times, so you ’ ll probably be glad to fi nally be getting around to fi nding out about them in detail. At the risk of sounding monotonous, build settings are a set of named values used to customize the build process. So what are build settings used for? Build settings are used by targets to determine what and how to construct their product, by the compile phases to control various compiler options, and by Xcode itself to control where fi les are written. Build settings are passed to compile scripts and external build processes, so those scripts and tools can make decisions and alter their behavior based on Build Settings ❘ 393 c17.indd 393c17.indd 393 1/22/10 12:50:29 PM1/22/10 12:50:29 PM Download at getcoolebook.com 394 ❘ CHAPTER 17 BUILDING PROJECTS those settings. You can defi ne your own settings, passing those values to the compiler and your own custom build scripts. A better question might be “ what are build settings not used for? ” Later sections enumerate some of the more important build settings and describe what they do. For now, all you need to know is that build variables are named values, usually written as SETTING_ NAME = value — although it ’ s unusual to actually write build settings yourself. To understand the interface for build settings, you need to understand how build settings are related to other build settings and how build confi gurations group them. The two key concepts to understand are: Build settings are a hierarchy of named values collections Build confi gurations are distinct sets of build settings As you work through the next few sections, keep these core concepts in mind. Build settings and confi gurations are notorious for confounding new Xcode users. If you grasp these basic relationships, you ’ ll be using them like a pro in no time. Build settings form a layered hierarchy. Each layer has its own collection of build settings. A value in a higher layer overrides the value with the same name in lower layers. The layers, from top to bottom, are Command Line, Target, Target Confi guration File, Project, Project Confi guration File, Xcode Default, and Environment. Figure 17 - 14 shows the layers and their order. The top layer is formed by the command - line parameters passed to the xcodebuild tool. This is signifi cant only if you are building Xcode projects from the command line. When you ’ re building from within the Xcode application, this layer does not exist and can be ignored. “ The xcodebuild Tool ” section, later in this chapter, explains how to override build settings using the command line. The next layer is the build settings for the current target. Most targets have a set of build settings. Aggregate targets do not have any confi gurable build settings — it is assumed that an aggregate target doesn ’ t actually build anything. Every target with build settings can also inherit a set of build settings from an Xcode confi guration fi le. An Xcode confi guration fi le is just another set of build settings stored in a source fi le. Creating and adding confi guration fi les to your project is covered a little later in the “ Confi guration Settings Files ” section. If a target is based on a confi guration fi le, the settings in that fi le form the next layer in the hierarchy. If the target is not based on a confi guration fi le, this layer is ignored. Multiple targets can be based on the same confi guration fi le. The next layer is the project layer. The project build settings are set in the project ’ s Info window. As the name implies, there is only one set of project build settings. Like a target, the project itself can ➤ ➤ FIGURE 17-14 c17.indd 394c17.indd 394 1/22/10 12:50:29 PM1/22/10 12:50:29 PM Download at getcoolebook.com be based on an Xcode confi guration fi le. If used, this confi guration fi le forms another layer below the project build settings. Below the project layer is a fi xed set of build settings provided by Xcode itself. These are the default values for all projects, and comprises most of what you see when you go to edit build settings. This layer also includes the build settings that Xcode generates dynamically, like the SRCROOT setting that contains the path of the project. At last count, there were more than 200 default build settings. Finally, the bottom layer is the environment layer. These are values found in Xcode ’ s or xcodebuild ’ s process environment. You can set these in the shell or as explained later in the “ Environment Settings ” section. Environment variables are a way of passing build settings to many or all projects. For the most part, the important layers — that is, the layers you will be working with on a daily basis — are the target and project layers. The remaining discussion often glosses over the other layers; just remember that if those layers are present, they behave just like any other layer. The Scope of Build Settings Each set of build settings has a scope, or lifetime, as described in the following table. Build settings that are out of scope when a particular target is being built are inaccessible and irrelevant. BUILD SETTING LAYER SCOPE Command - Line Present for the duration of the build started using the xcodebuild tool. Target and Target Confi guration File Present during the build phases of the target. Project and Project Confi guration File Present while building any target in the project. Xcode Defaults and Environment Always present. Any build settings established using the command - line arguments passed to the xcodebuild tool exist for the duration of the build. This may span the building of many targets. The build settings for a target only exist while fi les in that target are being processed. If dependencies cause another target to be built, the build settings used for the dependent target are the build settings belonging to that dependent target. Targets do not inherit, or in any way pass, their build settings to the build phases of other targets. The project build settings exist whenever a target in that project is being built. If a dependency causes a cross - project target to be built, that target will be built using the project build setting belonging to the external project. Projects do not inherit or pass build settings to other projects. Environment build settings are constant throughout a build. The environment settings used during a build are those that existed when Xcode or the xcodebuild tool was launched. When those build settings get created and their values are beyond Xcode ’ s control. Build Settings ❘ 395 c17.indd 395c17.indd 395 1/22/10 12:50:30 PM1/22/10 12:50:30 PM Download at getcoolebook.com 396 ❘ CHAPTER 17 BUILDING PROJECTS Build settings are passed to custom scripts and tools via the environment. Scripts and external build tools are free to alter any of the build settings that Xcode passes to them. However, changing them does not alter the build settings in the project. This is consistent with the UNIX model of shell variables: altering a variable in a sub-shell does not alter that value in its super-shell. External build tools can pass custom or modifi ed build settings to other builds using the command-line and environment layers. Build Setting Evaluation Every named build setting used by a target, script, or tool forms, essentially, an expression that Xcode converts into a value. The rules for evaluating build setting expressions are pretty simple, and most of the time are trivial. For simple build settings — those that don ’ t refer to other build settings — the rule is this: The highest layer that contains a build setting defi nes its value If more than one build setting layer contains a value with the same name, the value defi ned by the top layer is used. Take a look at the build settings shown in Figure 17 - 15 as an example. ➤ FIGURE 17-15 The INSTALL_MODE_FLAG setting is used to set the access permissions of executable product fi les. The default value of a - w,a+rX gives all users read and execute rights to the fi le, which is appropriate for most applications. However, this application includes a self - installing helper tool — an executable that will be copied to another location and executed there. For security purposes, you don ’ t want the program fi le in the application bundle to be executable, because it should never be launched from within the bundle. To accomplish this, the INSTALL_MODE_FLAG build setting is set to a - wX,a+r in the HelperTool target. When the Application target is built, the four sets of build settings — Command - Line, Application Target, Project, and Environment — are assembled. Only the project layer defi nes an INSTALL_ MODE_FLAG setting, so the value used when building the Application target is a - w,a+rX . When c17.indd 396c17.indd 396 1/22/10 12:50:30 PM1/22/10 12:50:30 PM Download at getcoolebook.com it comes time to build the HelperTool target, the build sets that are in scope — which this time includes the HelperTool target settings but not the Application target set — are assembled. This time, both the HelperTool target and the project defi ne a setting named INSTALL_MODE_FLAG . The defi nition of INSTALL_MODE_FLAG in the target set is in a higher layer than the project, so the value from the HelperTool target is used. When it ’ s all fi nished, the project produces an application that can be launched along with a BSD program fi le that can be read but not directly executed. Build Setting Value Substitution As you can see, the scope and precedence of build settings are pretty simple. That is, until build settings start referring to other build settings. This simultaneously makes build settings more powerful while signifi cantly complicating how build settings are resolved. The $( VAR_NAME ) syntax enables a build setting to refer to any other build setting. For example, the Other C++ Flags (OTHER_CPLUSPLUSFLAGS) build setting is normally set to the value $(OTHER_ CFLAGS) . This build setting effectively sets the Other C++ Flags setting to match the Other C Flags setting, so that any extra compiler fl ags you set for C compiles will also be used when compiling C++ fi les. Any custom C fl ags, regardless of what layer they are defi ned in, are automatically passed to the C++ compiler as well. Figure 17 - 16 illustrates the order and rules used to resolve build setting references. FIGURE 17-16 This project produces three applications: Problem Grapher, Algebra Solver, and Calculus Solver. Each application includes a copyright statement. Sharp Pencils wrote Problem Grapher and Algebra Solver, and Math Whiz wrote Calculus Solver. The project defi nes a COMPANY setting containing a company name and a YEARS setting defi ning a span of years. It also defi nes a COPYRIGHT_STATEMENT setting that forms a complete copyright statement using the values of the other two build settings. When the Problem Grapher target is built, the value of the COPYRIGHT_STATEMENT setting is constructed by substituting the values of the YEARS and COMPANY settings where their references appear in the value, as illustrated in Figure 17 - 17. Ultimately, the value of COPYRIGHT_STATEMENT is Copyright 2003, Sharp Pencils . Build Settings ❘ 397 c17.indd 397c17.indd 397 1/22/10 12:50:35 PM1/22/10 12:50:35 PM Download at getcoolebook.com 398 ❘ CHAPTER 17 BUILDING PROJECTS When the Calculus Solver target is built, things get a little more interesting. When Xcode resolves the references to YEARS and COMPANY , it fi nds values set in the Calculus Solver target (which is now in scope) that override the values in the project, as shown in Figure 17 - 18. Using those values instead, the COPYRIGHT_STATEMENT setting now resolves to Copyright 2000 - 2003, Math Whiz . Notice how a value defi ned in a higher layer can alter a defi nition defi ned in a lower one. FIGURE 17-17 FIGURE 17-18 Next is the Algebra Solver target. This target is interesting because the YEARS setting contains a self - referential value. That is, the value of YEARS refers to the value of the YEARS setting. Xcode resolves self - referential references by obtaining the value of the setting from a lower layer of build settings. When the COPYRIGHT_STATEMENT setting refers to the YEARS setting, Xcode fi nds it in the Algebra Solver target setting. When Xcode constructs the value for the YEARS setting for that target, it fi nds a reference to the YEARS setting. Xcode recursively searches for another defi nition of the YEARS setting, but ignores layers at or above the layer containing the reference, as shown in Figure 17 - 19. Ultimately, the $(YEARS) reference in the target ’ s YEARS setting is replaced with the YEARS value set in the project, resulting in a value of 2003 - 2005 . c17.indd 398c17.indd 398 1/22/10 12:50:36 PM1/22/10 12:50:36 PM Download at getcoolebook.com Recursive references are particularly useful for amending Xcode build settings. For example, the OTHER_CFLAGS build setting defi nes additional arguments that are passed to the gcc compiler. If you defi ned just a set of fl ags in your target, it would override whatever the value of this setting might be in the project. Instead, you can defi ne the value of this setting as $(OTHER_CFLAGS) — myflag in the target. The argument — myflag is merely appended to whatever the project or environment setting was, rather than replacing it. As described earlier, whatever your OTHER_CFLAGS ultimately resolved to would be transferred to OTHER_CPLUSPLUSFLAGS , even if the augmentation of OTHER_CFLAGS occurred in an higher layer. The special reference $(inherited) is the same as $(VAR), where VAR is self-referential, as in MY_ARGS= verbose $(inherited). If there were no lower layers that contained a YEARS setting, the reference $(YEARS) would be replaced with an empty string. In fact, any reference to an undefi ned or out - of - scope build setting is replaced with nothing. Referring to an undefi ned build setting does not cause a build error or produce any kind of warning. References to environment variables are treated like references to any other build setting. However, references in environment variables are a special case: references in an environment variable cannot refer to any non - environment layer build setting. In this example, the COPYRIGHT_STATEMENT setting could not be defi ned solely as an environment setting. If it was, the $(YEARS) and $(COMPANY) references would only be substituted if there were YEAR and COMPANY settings in the environment layer as well. Any values for YEAR and COMPANY in any other layer would be ignored. Conditional Build Settings There ’ s a special kind of build setting that creates an additional quasi - layer of settings: conditional build settings. A conditional build setting is keyed to some other combination of build settings. If those other build settings match a given pattern, it substitutes a different value for that setting. The general textual form for conditional build settings is: BUILD_SETTING [ condition = pattern ] = value FIGURE 17-19 Build Settings ❘ 399 c17.indd 399c17.indd 399 1/22/10 12:50:37 PM1/22/10 12:50:37 PM Download at getcoolebook.com 400 ❘ CHAPTER 17 BUILDING PROJECTS This isn ’ t a general - purpose mechanism. In fact, Xcode only recognizes three conditions and these conditions are only evaluated and passed to certain native build phases. The conditions that Xcode evaluates are: arch (Processor Architecture) sdk (Software Development Kit) variant (Product Variant) The pattern portion of the condition is the name of the architecture, sdk, or variant. The pattern can include a “ * ” wildcard character to match groups of possible condition values. A setting can have multiple conditionals, as in SOME_SETTING[sdk=iphonesimulator*][variant=debug] = YES . Consider the following build setting and variant: GCC_USE_INDIRECT_FUNCTION_CALLS = NO GCC_USE_INDIRECT_FUNCTION_CALLS[arch=ppc*] = YES When the target is being built for any non - PowerPC architectures (Intel, Arm, and so on) the conditional build setting doesn ’ t match the pattern and is ignored; in these cases GCC_USE_ INDIRECT_FUNCTION_CALLS evaluates to NO . Whenever the target is compiled for any PowerPC architecture ( ppc , ppc64 , ppc7400 , ppc970 , and so on) the condition matches the pattern ( ppc* ) and the build setting evaluates to YES . Logically, conditional build settings create another layer, immediately above the current layer, with alternate build settings that are only in scope when their condition patterns are satisfi ed. You cannot refer to conditional build settings in references; they ’ re simply alternate settings that supersede the base setting under certain circumstances. Conditional build settings cannot be used by custom build rules or Run Script phases. Furthermore, only those build settings that apply to native compilation phases can be made conditional. The possible values for each condition change from release to release, but the Xcode build settings editor knows what they are and will let you choose them from a menu. If you want to know what patterns are available, take a peek by creating a conditional build setting — described later in the “ Create a Conditional Build Setting ” section — then look at the resulting build setting statement by copying it to the clipboard. Variable Build Settings Variable build setting names are an alternative to conditional build settings. This works by using a build setting value as all, or part, of a build setting name. Consider the following build settings: VALUE_FOR_COND_1 = YES VALUE_FOR_COND_2 = NO VALUE_FOR_COND_3 = MAYBE MY_CONDITION = 2 MY_VALUE = $(VALUE_FOR_COND_$(MY_CONDITION)) Build setting values are evaluated recursively. The expression $(VALUE_FOR_COND_$(MY_ CONDITION)) is fi rst replaced with $(VALUE_FOR_COND_2) , which then evaluates to NO . Thus, setting the MY_CONDITION setting to 2 ultimately causes MY_VALUE to be NO . Setting it to 3 would cause MY_VALUE to be MAYBE . ➤ ➤ ➤ c17.indd 400c17.indd 400 1/22/10 12:50:42 PM1/22/10 12:50:42 PM Download at getcoolebook.com This isn ’ t quite as fl exible or sophisticated as using conditional build variables, but it works with all build settings. Using this technique, you can create a set of related build setting and then select one of them via the value of another setting. BUILD CONFIGURATIONS Build confi gurations are complete sets of build settings. If you imagine build settings forming a two - dimensional tree of build settings, each build confi guration creates a new plane of build settings in a third dimension. Each named build confi guration represents an independent collection of build settings for the project and all of its targets. The previous example had a project for four sets of build settings: one set for the project and three sets for the targets. If that project had three build confi gurations — named Alpha, Beta, and Release — it would actually contain 12 complete sets of build settings, as shown in Figure 17 - 20. FIGURE 17-20 While you are editing your project or target build settings, keep this in mind: every target and project has an independent set of build settings for each named build confi guration. Only the build settings for the active build confi guration, which you choose using the Project ➪ Set Active Build Confi guration menu, are in scope. This lets you create build settings for a target or project that changes depending on which build confi guration is active. If you create a new target, that target gets a set of build settings for each confi guration in the project. If you create a new confi guration, a new set of build settings is added to the project and every target. Think of build settings as values written on a sheet of paper. Every page is a build confi guration. Add a confi guration, and you create a completely new page of build settings for everything in your project. When you build, you choose which page of build settings to use. If you have used Xcode or Project Builder in the distant past (prior to Xcode 2.1), read this section carefully. Older versions of Xcode used a system of build settings and build “styles.” There was only one set of build settings for each target. Each build style could then selectively override specifi c build settings. Although the two systems are effectively similar, the interface and conceptual structure of build styles and build confi gurations are signifi cantly different. Build Confi gurations ❘ 401 c17.indd 401c17.indd 401 1/22/10 12:50:43 PM1/22/10 12:50:43 PM Download at getcoolebook.com 402 ❘ CHAPTER 17 BUILDING PROJECTS You might be worried at this point that a complex project with fi ve targets and four build confi gurations would have an unmanageable number of build settings — at least 25 complete sets of build settings, in all. Don ’ t worry. Xcode provides several tools for visualizing build settings as a whole, editing build settings in multiple confi gurations at once, and moving build settings between layers. Each of these are covered shortly. The most common use of build confi gurations is to alter the compiler and linking options when producing an application for different purposes. For debugging, the application needs to be compiled with certain code optimizations turned off (code optimizations can interfere with source - level debugging) and with debug information included. Conversely, the released version of your application needs to be fully optimized, but does not need to include any debugger data — the end user doesn ’ t need it and it signifi cantly increases the size of the application. You may also need to produce an application that ’ s between these two extremes for performance testing. For that, you ’ ll want an application that is fully optimized (just like the fi nal version), but also includes all of the information used by the debugger to identify functions and variables. This use of build confi gurations is so common that these are exactly the build confi gurations provided by Xcode templates. All Xcode project templates include two confi gurations, named Debug and Release. The default values for the build confi gurations set the compiler and linking options to those you would typically want. In the Debug confi guration, optimization is turned off, debugging symbols are enabled, as are useful debugging features like Fix and Continue. The Release confi guration has just the opposite settings. Optimization and normal linking are turned on, and all of the debugging aides are disabled. EDITING BUILD SETTINGS Now that you understand the hierarchy of build settings and build confi gurations, you should now be able to make sense of the interface for editing build settings. Select a project or target and open its Info window; the easiest way is to double - click the project or target icon. Switch to the Build tab and a list of build settings is displayed, as shown in Figure 17 - 21. The name of each setting is in the Setting column and its value is listed in the Value column. The Confi gurations pop - up menu selects which set of build settings you are seeing or editing. You can choose a specifi c build confi guration, or whatever confi guration is currently active. The special All Confi gurations choice merges the build settings from all of your FIGURE 17-21 c17.indd 402c17.indd 402 1/22/10 12:50:46 PM1/22/10 12:50:46 PM Download at getcoolebook.com . based on Build Settings ❘ 39 3 c17.indd 39 3c17.indd 39 3 1/22/10 12:50:29 PM1/22/10 12:50:29 PM Download at getcoolebook.com 39 4 ❘ CHAPTER 17 BUILDING PROJECTS those settings. You can defi ne. are those that existed when Xcode or the xcodebuild tool was launched. When those build settings get created and their values are beyond Xcode ’ s control. Build Settings ❘ 39 5 c17.indd 39 5c17.indd. COPYRIGHT_STATEMENT is Copyright 20 03, Sharp Pencils . Build Settings ❘ 39 7 c17.indd 39 7c17.indd 39 7 1/22/10 12:50 :35 PM1/22/10 12:50 :35 PM Download at getcoolebook.com 39 8 ❘ CHAPTER 17 BUILDING