TARGET DESCRIPTION Aggregate An empty Aggregate target. Copy Files An Aggregate target with a single Copy Files build phase. External A Jam - based External target. External targets run some external process (like make) to build the target. They cannot have build phases. Shell Script An Aggregate target with a single Run Script build phase. Legacy If you upgraded an earlier version of Xcode, your installation may contain additional target templates that have since been removed from the Xcode Developer Tools. These might include Java Applet, Carbon, and other deprecated targets. For the most part, Xcode still supports these legacy target templates, but may not in the future. Duplicating Targets You can also create a new target by duplicating an existing one. This is especially useful if you need a new target that is very similar to one that already exists. Select the target in the Targets smart group. In the Right/Control+click contextual menu choose the Duplicate command. A duplicate of the target is created with the suffi x “ copy ” appended to the target ’ s name. Note that the new target is an exact duplicate except, of course, for its name. If the original target produced a product, the new target will produce the same product. Assuming you want the targets to build separate products, remember to edit the settings of the target so the two products don ’ t overwrite one another. Deleting Targets To delete a target, select the target in the Targets smart group. Press the Delete key or choose Delete from the Right/Control+click contextual menu. Xcode presents a warning that removing a target will also remove the reference to it in any targets that depend on it. Click the Delete button to acknowledge the warning and delete the target. BUILD PHASES Build phases defi ne the steps that must occur in order to build a target. Build phases tend to paint with a broad brush. Targets typically have one Compile Sources build phase that compiles all of the source fi les for that target, even if that includes source fi les from many different languages. Consequently, targets rarely have more than three or four build phases. Use the disclosure triangle next to the target ’ s name in the Targets smart group to reveal the build phases for the target, as shown in Figure 16 - 9. The list of fi les on which a build phase will operate, or depends, is referred to as the phase ’ s input fi les. Selecting a build phase lists the input Build Phases ❘ 353 c16.indd 353c16.indd 353 1/21/10 3:55:58 PM1/21/10 3:55:58 PM Download at getcoolebook.com 354 ❘ CHAPTER 16 TARGETS fi les in the details pane of the project window. Alternatively, you can use the disclosure triangle on a build phase to list the input fi les in the Groups & Files list. The number of input fi les is listed in parentheses after the name of the build phase. Note that this applies only to build phases that process fi les using Xcode ’ s internal build system. The input fi les listed for a build phase include only those source fi les that you have explicitly added to the build phase. Intermediate fi les produced by another build phase are not listed or counted. FIGURE 16 - 9 Build phases occur in the order in which they appear in the target. Build phases can be reordered by dragging a build phase to a new position in the target. Be very careful when doing this. The reason build phases exist is because build steps have to occur in a specifi c order for the build to be successful — you can ’ t link code before it ’ s compiled. About the only time you ’ ll fi nd yourself reordering build phases is if you add your own build phase and need that phase to occur before or after another phase. You can also reorder the fi les that a build phase includes. For some build phases, this may be a signifi cant change. For others, the order of fi les is superfl uous. You cannot drag build phases into other targets, nor can you copy them via the clipboard. New build phases are simple to add. Select a target and choose a new build phase from the Project ➪ New Build Phase menu or Right/Control+click an existing target or build phase, and choose an item from the Add ➪ New Build Phase menu. Not all build phase types can be added to all target types. An aggregate target can only contain Copy Files and Run Script build phases. An external target cannot have any build phases. The New Build Phase menu lists only those phases appropriate to the selected target. After you ’ ve added the build phase, drag it to set its order in the target and then confi gure the new phase as desired. To remove a build phase, select it and press the Delete key or choose Delete from the Right/ Control+click contextual menu. Files in a Build Phase Every build phase has a set of preferred source fi le types. A Compile Sources phase prefers the source fi le types it has build rules for ( .c , .cpp , .m , .l , and so on) — build rules are described later in the “ Build Rules ” section. The Copy Bundle Resources phase prefers the resource fi les one typically c16.indd 354c16.indd 354 1/21/10 3:55:59 PM1/21/10 3:55:59 PM Download at getcoolebook.com copies into an application ’ s bundle ( .tiff , .icn , .png , and so on). When you add a source fi le to a target, the fi le becomes an input fi le for the fi rst phase that prefers that fi le type the most. If a target contains both a Copy Headers phase and a Copy Files phase, adding an .h fi le to that target adds the fi le to the Copy Headers phase. The Copy Headers phase is more specifi c than the Copy Files phase, and prefers .h fi les more than the Copy Files phase does. If a target contains only two Copy Headers phases, adding an .h fi le adds it to the fi rst Copy Headers phase in the target, because both phases prefer an .h fi le equally. Adding Items to Targets You typically add fi les to targets via the targets list that appears when the fi le is created, added to the project, in the Info window for the fi le, or using the target check box column in the project window. This is usually foolproof and effective, allowing Xcode to choose automatically the appropriate phase to add the fi le to. If a target has no phases that prefer a source fi le ’ s type, that fi le cannot be added to that target using any of the aforementioned dialogs. Precisely Controlling Target Phase Membership Using the target group, you have more precise control over what input fi les are included in what phases, and you can occasionally break the rules. You can add a source fi le to a build phase by dragging the fi le into that phase and dropping it. Figure 16 - 10 shows the Image1.png fi le being added to the Copy Bundle Resources phase. You can move or copy a fi le from one phase to another. In the previous example, where there was both a Copy Files and a Copy Headers phase, you may really have wanted a specifi c header fi le to be in the Copy Files phase, not the Copy Headers phase. Just adding the fi le to the target puts it in the Copy Headers phase. Grab the fi le in the Copy Headers phase and move it into the Copy Files phase. Hold down the Option key before dropping it, and Xcode duplicates the reference, adding the fi le to both phases. Using drag and drop, you can include a fi le in more than one phase and you can include the fi le in phases that don ’ t prefer it. Let ’ s say you have developed a Java application that dynamically produces executable Java code by manipulating a source fi le template and then compiling it. You want the Java source template fi le, GenericTransformTemplate.java , to be included in the application ’ s bundle as a resource fi le. To accomplish this, drag the GenericTransformTemplate .java fi le into the Copy Bundle Resources phase. When the application is built, this Java source fi le is copied into the resource bundle of the fi nished application, something that would normally never happen. Removing an Item from a Target You can remove a source fi le from a target by selecting it and pressing the Delete key or choosing Delete from the Right/Control+click contextual menu. You will receive a warning from Xcode FIGURE 16 - 10 Build Phases ❘ 355 c16.indd 355c16.indd 355 1/21/10 3:55:59 PM1/21/10 3:55:59 PM Download at getcoolebook.com 356 ❘ CHAPTER 16 TARGETS asking if you want to delete the item. Don ’ t panic. You are only deleting the phase ’ s reference to the source fi le, not the source fi le itself. If you have added a source fi le to any phase of a target, Xcode indicates that it is a member of that target. Removing (unchecking) a target in a target list removes that fi le from every phase it is included in. It’s possible to create a paradox if you have manually forced a source fi le to be included in a target that has no phases that prefer that fi le type; the target for that source fi le will indicate that it is a member, but the check box control for the target will be disabled (because there are no phases that prefer that type). To remove a fi le from a target under these circumstances, you must delete the fi le directly from the build phase or phases. Build Phase Types There are nine build phase types: Compile Sources, Compile AppleScripts, Link Binary With Libraries, Copy Headers, Copy Bundle Resources, Copy Files, Build Java Resources, Build ResourceManager Resources, and Run Script. Compiler Phases The Compile Sources phase is the most sophisticated of the build phases. It is responsible for compiling any kind of source fi le. The kinds of sources fi les it will compile and what compiler it will use for each are determined by the build rules for the target, described later in the “ Build Rules ” section. The Compile Source phase understands a vast array of build settings that apply to the compilers. It parses all of these and makes the appropriate adjustments to the parameters passed to each compiler. The Compile AppleScripts phase is similar to Compile Sources, but it only compiles AppleScript source fi les. The Build ResourceManager Resources phase is another specialized compiler phase just for resource defi nitions fi les. It compiles and merges legacy .r and .rsrc fi les to produce a resource fi le in the product ’ s bundle, or inserts them into the resource fork of the product fi le. You ’ re not likely to run across any ResourceManager Resource phases unless you ’ re working on older Carbon projects. The Link Binary With Libraries phase is the companion to the Compile Sources phase. It takes whatever intermediate fi les were produced by the Compile Sources phase and links them together, along with whatever libraries and frameworks they need. The input fi les to the link phase are the external libraries and frameworks that the object fi les (from the previous phase) need to be linked to. Copy Phases The Copy Headers, Copy Bundle Resources, and (legacy) Build Java Resources phases are specialized versions of the Copy Files phase. Their sole purpose is to copy fi les into the product ’ s bundle. c16.indd 356c16.indd 356 1/21/10 3:56:00 PM1/21/10 3:56:00 PM Download at getcoolebook.com Copy Headers is designed for use with framework and library targets. It uses the “ role ” of its input fi les, be they public or private, and copies them to the appropriate location in the output project. The role of a header is set using the role column of the details pane with that fi le or phase selected. Copy Bundle Resources copies any input fi le into the Resources folder of the product ’ s bundle. This is the phase to use if you want a literal copy of a fi le stored in your bundle ’ s resource folder for access at run time. This phase is also responsible for constructing and copying the Info.plist fi le into the product ’ s bundle. (See the “ Properties ” section later in this chapter for more about how to confi gure the Info.plist fi le.) The Copy Files phase is a utilitarian phase that copies all of the phase ’ s input fi les or folders to the destination of your choice. That destination is set in the Info window of the phase, as shown in Figure 16 - 11. The destination location can be either an absolute path or a path relative to the product ’ s location. For targets that produce a bundle, predefi ned locations are provided that will target many of the standard locations in the product ’ s bundle. An absolute path is just that. Use this to copy fi les to a particular installation or test location. Relative paths require a bit of an explanation. The build location — the location to which the product of a target will be written — is unique for each build confi guration. If you have two build confi gurations, Debug and Release, every target will produce two different products: a Debug product and a Release product. The remaining paths in the destination menu are all relative to the product ’ s output directory. The choices are the output directory itself or one of the standard folders inside a bundle, assuming the target produces a bundle. (See Chapter 17 for a complete explanation of build locations and build confi gurations.) The path fi eld can be left blank for any choice other than Absolute. Any folders that do not exist when the phase executes are automatically created. The path can also contain build variables using the form $(BUILD_VAR) . The macro will be substituted for its actual value when the build phase runs. By using build variables in the path, you can customize the normal destination location calculated by Xcode. Speaking of build locations, remember when Chapter 5 mentioned that product- relative references are based on the active build confi guration and target? This fact is most applicable to product fi le references used as input fi les to a Copy Files phase. Product references also change based on the active build confi guration, making both the source and destination locations of the phase variable. An example would be an application that includes a BSD executable in its bundle. A Copy Files phase could be used to copy the project-relative product produced by the BSD target into the resource bundle being produced by the application target. Both the source (product reference) and the destination (application bundle) are variable. When built using the Debug build confi guration, the Debug version of the BSD product is copied into the Debug version of the application bundle. When the Release confi guration is active, the Release version of the BSD product is copied into the Release version of the application bundle. FIGURE 16 - 11 Build Phases ❘ 357 c16.indd 357c16.indd 357 1/21/10 3:56:11 PM1/21/10 3:56:11 PM Download at getcoolebook.com 358 ❘ CHAPTER 16 TARGETS If the Copy Only When Installing option is set, the copy phase is only executed when the build is being performed with the install option set. You can do this from within Xcode by turning on the DEPLOYMENT_LOCATION build setting or passing the install option to the xcodebuild tool. Both of these are described in Chapter 17. Script Phase The Run Script phase is the “ backdoor ” by which you can interject virtually any custom build procedure. You confi gure a Run Script phase using the Info window of the phase, as shown in Figure 16 - 12. The Shell fi eld determines the shell, or interpreter, that will be used to execute the script. Below that is the shell script that will be executed. When the phase is built, the shell executable is put on a so - called “ she - bang ” line ( #! /path/to/shell ) and the remaining script is appended to it. The whole thing is written into an executable script fi le and run using the sh tool. One side effect is that the zeroth argument to the script will be the path to the temporary script itself, which makes it relatively uninformative. The Shell fi eld can be any valid interpreter. It could be perl, ruby, awk, or php. It doesn ’ t matter, as long as the given interpreter can execute the script fi le. Most of the build settings are transferred into environment variables before the script is executed, so your script has unfettered access to your build settings. If you ’ re interested, or are having trouble with the build settings passed to your script, check the Show Environment Variables In Build Log option. This option dumps the entire shell environment prior to execution into the build log for later analysis. Checking the Run Script Only When Installing option prohibits the script from running unless the DEPLOYMENT_LOCATION build setting is turned on or the install command is passed to the xcodebuild tool. Xcode, of course, has no idea what your script will do, what fi les it needs, or what it produces. Assuming that the script produces some output fi les from some input fi les, Xcode would like to optimize the build by skipping this build phase if the modifi cation dates of the output fi les are newer than the input fi les. You can satisfy Xcode ’ s curiosity by manually setting the Input Files and Output Files for the phase. Click the + button to add an input or output fi le to the list. When the new entry appears, enter the fi le ’ s path. Sadly, you can ’ t drag a source fi le from the project window into the list. However, once an entry is created you can drag a source fi le into the fi eld and then edit the path. It can be an absolute path or a path relative to the project directory. The script is run only if the modifi cation date of one or more of the input fi les is more recent than the oldest output fi le. If either list is empty, the script runs every time. FIGURE 16 - 12 c16.indd 358c16.indd 358 1/21/10 3:56:16 PM1/21/10 3:56:16 PM Download at getcoolebook.com The fi les in the Input Files list are not passed to the script as parameters, nor are they piped to it via stdin. They are used by Xcode solely to determine if the script should be run. It is up to the shell script to read the listed Input Files and produce all of the fi les promised in the Output Files. If you want to reuse a script in multiple targets and need a variable list of input or output fi les, defi ne them in a custom build setting. BUILD RULES Build rules defi ne the transformation of source fi les into their compiled results. The compiler phase uses the target ’ s build rules to determine which compiler should be used to compile each source fi le. For example, a build rule might specify that all C source fi les (C, C++, and Objective - C) are compiled using the gcc compiler. A build rule applies to all the fi les of a specifi c type. The type of a fi le is determined by its extension or the fi le type assigned to that source fi le. A fi le ’ s type is typically in agreement with the fi lename extensions, but it doesn ’ t have to be. You can change the fi le type of a .java source fi le to sourcecode.cpp . The Compile Sources phase will then apply the sourcecode.cpp rule to that fi le as if it were a C++ source fi le — probably without much success. You ’ ll probably never need to alter the build rules in Xcode. However, there are several reasons why you might want to: Force Xcode to use an older, newer, or custom compiler. Add a rule to compile a source type that is not normally compiled by Xcode. Add a pre - or post - processing script to every compilation. Defi ne your own transformation. You can examine and alter the build rules, previously shown in Figure 16 - 4, for a target in the target ’ s Info window. When it comes time to compile an input fi le, the fi le is tested against each rule starting from the top of the list. The fi rst rule that matches a particular input fi le is the rule used to compile that fi le. Each target has one set of build rules, shared by all of the build phases in that target. You cannot create different rules for different phases of the same target. Every set of build rules includes a set of system rules that cannot be edited. The system rules are always at the bottom of the list. You can add your own custom rules to a target. These custom rules can only be added to the top of the list and are always evaluated before any of the system rules. If you defi ne a rule that matches the same type of fi le as a system rule, your custom rule is used instead. Click and drag the title of a custom rule to reorder it in the list. ➤ ➤ ➤ ➤ Build Rules ❘ 359 c16.indd 359c16.indd 359 1/21/10 3:56:17 PM1/21/10 3:56:17 PM Download at getcoolebook.com . a build phase lists the input Build Phases ❘ 35 3 c16.indd 35 3c16.indd 35 3 1/21/10 3: 55:58 PM1/21/10 3: 55:58 PM Download at getcoolebook.com 35 4 ❘ CHAPTER 16 TARGETS fi les in the details pane. or choosing Delete from the Right/Control+click contextual menu. You will receive a warning from Xcode FIGURE 16 - 10 Build Phases ❘ 35 5 c16.indd 35 5c16.indd 35 5 1/21/10 3: 55:59 PM1/21/10 3: 55:59. application bundle. FIGURE 16 - 11 Build Phases ❘ 35 7 c16.indd 35 7c16.indd 35 7 1/21/10 3: 56:11 PM1/21/10 3: 56:11 PM Download at getcoolebook.com 35 8 ❘ CHAPTER 16 TARGETS If the Copy Only When