A single-project project is one where everything produced by the project is contained in a single project folder and described in a single project document. A separate target produces each product of the project. Target dependencies determine the build order. They all share the same source control management, object browser, project search window, build configurations, and smart groups. Examples of this kind of project are:

In each of these projects, the benefits of keeping everything in a single project are clear:

It is likely that these kinds of projects will need to share common source files, header files, and other resources. They are also likely to all use the same, or a similar, set of build settings. Changing a source file or build setting will correctly rebuild all dependent targets.

The kind of project that should be subdivided into multiple projects are those where you want to explicitly isolate one from the other. Idea examples would be:

In the first situation, you have your Cocoa application and another large collection of source files that belong to an open source project. The open source project is probably under its own source control management system, it might require special compiler settings to build, and probably includes a large number of internal functions that your application shouldn't use directly.

Frameworks are particularly well-suited to being sequestered into separate projects because frameworks are specifically designed to be development resources. A project using the framework has access to its API (in the form of header files), resource files, and even documentation without the need to explicitly include those files in the project.

In these situations, it's advantageous to isolate the open source code, individual applications, or frameworks into their own projects, which you can then make your project targets dependent on.

Often, your decision won't be so cut and dried. A good example would be a project that produced a service, like a streaming media server, and a desktop application to control and configure that server.

There may not be that much code, if any, shared by the two products. It isn't clear that they need to be built using a common set of build settings, or whether having separate build settings might not be an advantage. Is each version of the desktop application intimately tied to specific versions of the server, or are the two loosely interoperable? Does one team of programmers work on the server and another on the desktop application?

These are the questions you need to ask when deciding on whether to start a second project or not. If you can't decide, start with a single project and multiple targets. It's much easier to split a project into two than trying to combine two projects into one. To split a project, start by making a copy of the entire project folder. Rename the project document, and then delete all "B" assets from project A and all "A" assets from project B.

A target may depend on other targets. A target dependency is a target, either in this project or an external project, which must be built before this target can be built. Target dependencies appear in the target group before the target's build phases — an allusion to the order of build events. They are also listed in the General tab of the target's Info window.

A target build phase may also maintain its own set of internal dependencies. These are the implicit dependencies between intermediate files and the source files used to produce them. These are calculated by the target and are not under your control. Whenever possible, a target only recompiles files affected by changes made since the last build. You can see the internal dependencies at work in the details pane of the project window. The small hammer column displays a check mark for files that need to be rebuilt.

A target can have one or more build phases. You can see a target's build phases by expanding the target's group in the project window, as shown in Figure 16-2. Build phases define the broad order in which steps will occur during a build. For example, all of your C source files must be compiled into object files before those object files can be linked together. All of the object files must be linked together before the final executable can be copied into the application's bundle, and so on.

Figure 16-2. FIGURE 16-2

The order of steps within a build phase is entirely up to that phase. The order within some phases is fixed, whereas others are very dynamic. A build phase that compiles a gaggle of source files may compile them in alphabetical order or in the order in which they were most recently modified. It may compile them one at a time or compile twenty at a time using a network of distributed build servers. Intelligent build phases try to optimize the order whenever possible. Your only guarantee is that all of the work performed in a phase will be completed before the next phase begins.

Here's an important concept about targets and target membership: a source item is a member of a target if, and only if, it is included in one or more build phases of that target.

You see the target membership of items in your project — usually as a check box — in many places: its Info window, in the details pane, in the source group, when you add an item to your project, and elsewhere. It might seem like target membership is a Boolean property of the individual source items, but it isn't. The targets that refer to an item imply its target membership.

Changing an item's target membership has the following effects:

For most targets, adding and removing an item from a target is a simple and predictable operation. In the case of a target that contains two or more build phases compatible with an item, you might need to fix the target membership in the target — a simple add might not insert the item into the correct phase, or phases. This is described in detail in the "Files in a Build Phase" section, later in this chapter.

If a target includes build settings, you can edit those settings in the Build tab of the Info window or Inspector palette for that target, as shown in Figure 16-3.

Figure 16-3. FIGURE 16-3

Targets can also have multiple sets of settings called build configurations. The project itself has multiple sets of build settings. Because build settings and build configurations are not unique to targets, the editing of build settings, the management of build configurations, and how they all interact with each other are explained in Chapter 17.

Targets that compile files have a set of build rules. Build rules tell a target what compiler or translator to use when building each source file. The build rules can be modified in the Rules tab of the target's Info window, shown in Figure 16-4. Each rule is a pairing of a file type, which you select using the Process menu, and a compiler, which you select using the Using menu. If necessary, you can define your own rules or redefine standards.

Figure 16-4. FIGURE 16-4

Most targets produce a product. The kind of product produced is determined by the type of the target. Application targets produce applications, library targets produce libraries, command-line targets produce UNIX executables, and so on. A special type of target, called an aggregate target, doesn't produce anything itself. It exists solely to group other targets so they can be treated as a single target. In other words, it's a target that "produces" other targets.

The native target types in Xcode are Application, Command-Line Tool, Dynamic Library, Static Library, Framework, Bundle, Kernel Extension, and IOKit Kernel Extension. Native targets are easily identified by their colorful and emotive target icons. Application targets have a small application icon, Command-Line Tool targets are represented by a little terminal screen, Framework targets have a toolbox icon, and the remaining targets appear as plug-ins. Native targets usually have a full complement of parts (build phases, settings, rules, and dependencies). Native targets that include an Info.plist file in their product also include a set of properties. See the "Properties" section, later in this chapter, for more details.

An external target defines a build target that is produced by some external process. This was designed to permit Xcode to integrate with existing workflows based on build tools like Make or Ant. The target is little more than a placeholder. It specifies the tool that will perform the build and the arguments that are passed to it, as shown in Figure 16-5. Xcode has no knowledge of what files the process requires, what it does, or what it will produce. You cannot add project files or build phases to an external target. The section "Java and Other Jam-Based Targets" has more information.

Figure 16-5. FIGURE 16-5

Aggregate targets, as the name implies, group several targets together using dependencies. An aggregate target that depends on several different targets can be used to build all of those targets as a unit. Suppose you have developed a suite of BSD command-line tools, each produced by a separate target. To build all of these tools at once, you would create an aggregate target, say it's named "Tools," that depends on all of the Command-Line Tool targets. Now whenever you want to build all of the tools, you simply build the one Tools target. Likewise, you might have applications or other projects that depend on having all of those tools built. Making those targets dependent on the single Tools target is much easier to maintain than adding each tool target to every target that depends on them.

Aggregate targets can also be used for utilitarian purposes. Aggregate targets don't produce a product, but they can still be made to do useful work by adding Copy Files or Shell Script build phases. These build phases are executed whenever the target is built, regardless of whether it has any dependencies. See the section "Build Phases" for more details about adding build phases to a target.

Xcode still includes support for the legacy Jam build system, which it inherits from its predecessor, Project Builder. A Jam-based target is a non-native target; the target's build logic is external to Xcode, and the target's configuration isn't integrated with the rest of Xcode. Jam-based targets are used to implement the external and aggregate target types, and to support legacy targets that were created in Project Builder or obsolete versions of Xcode.

Upgrading Jam-Based Targets

Except for the external and aggregate targets, you'll probably want to upgrade any other Jam-based targets to native targets whenever possible.

Convert your Jam-based targets into a native target using either the Project

The conversion also results in a report, an example of which is shown in Figure 16-6. In addition to making a new target, the conversion process may duplicate project files. The example in Figure 16-6 shows that a duplicate of the Info-StockMarketTicker.plist file was made and was named Info-StockMarketTicker__Upgraded_.plist. Delete the original .plist file when you delete the original target. You may also want to rename the new .plist file, which requires editing the new target's settings to match.

Figure 16-6. FIGURE 16-6

Target templates are organized into groups to make them easier to locate. Start by choosing the group that most closely describes the type of development you are doing (Cocoa, Cocoa Touch, BSD), and then choose your template. Be careful of similarly named templates. The Application template in the Cocoa group produces a significantly different product than the Application template in the Cocoa Touch group.

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 suffix "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.

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.

Every build phase has a set of preferred source file types. A Compile Sources phase prefers the source file 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 files one typically copies into an application's bundle (.tiff, .icn, .png, and so on). When you add a source file to a target, the file becomes an input file for the first phase that prefers that file type the most. If a target contains both a Copy Headers phase and a Copy Files phase, adding an .h file to that target adds the file to the Copy Headers phase. The Copy Headers phase is more specific than the Copy Files phase, and prefers .h files more than the Copy Files phase does. If a target contains only two Copy Headers phases, adding an .h file adds it to the first Copy Headers phase in the target, because both phases prefer an .h file equally.

Precisely Controlling Target Phase Membership

Using the target group, you have more precise control over what input files are included in what phases, and you can occasionally break the rules. You can add a source file to a build phase by dragging the file into that phase and dropping it. Figure 16-10 shows the Image1.png file being added to the Copy Bundle Resources phase.

Figure 16-10. FIGURE 16-10

You can move or copy a file 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 specific header file to be in the Copy Files phase, not the Copy Headers phase. Just adding the file to the target puts it in the Copy Headers phase. Grab the file 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 file to both phases.

Using drag and drop, you can include a file in more than one phase and you can include the file 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 file template and then compiling it. You want the Java source template file, GenericTransformTemplate.java, to be included in the application's bundle as a resource file. To accomplish this, drag the GenericTransformTemplate .java file into the Copy Bundle Resources phase. When the application is built, this Java source file is copied into the resource bundle of the finished application, something that would normally never happen.

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.

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 files into the product's bundle.

Copy Headers is designed for use with framework and library targets. It uses the "role" of its input files, 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 file or phase selected.

Copy Bundle Resources copies any input file into the Resources folder of the product's bundle. This is the phase to use if you want a literal copy of a file stored in your bundle's resource folder for access at run time. This phase is also responsible for constructing and copying the Info.plist file into the product's bundle. (See the "Properties" section later in this chapter for more about how to configure the Info.plist file.)

The Copy Files phase is a utilitarian phase that copies all of the phase's input files 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, predefined 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 files to a particular installation or test location.

Figure 16-11. FIGURE 16-11

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 configuration. If you have two build configurations, 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 configurations.) The path field 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.

Note

Speaking of build locations, remember when Chapter 5 mentioned that -product-relative references are based on the active build configuration and target? This fact is most applicable to product file references used as input files to a Copy Files phase. Product references also change based on the active build -configuration, 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 configuration, the Debug version of the BSD product is copied into the Debug version of the application bundle. When the Release configuration is active, the Release version of the BSD product is copied into the Release version of the application bundle.

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 configure a Run Script phase using the Info window of the phase, as shown in Figure 16-12. The Shell field determines the shell, or interpreter, that will be used to execute the script. Below that is the shell script that will be executed.

Figure 16-12. FIGURE 16-12

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 file 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 field 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 file. 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 files it needs, or what it produces. Assuming that the script produces some output files from some input files, Xcode would like to optimize the build by skipping this build phase if the modification dates of the output files are newer than the input files. 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 file to the list. When the new entry appears, enter the file's path. Sadly, you can't drag a source file from the project window into the list. However, once an entry is created you can drag a source file into the field 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 modification date of one or more of the input files is more recent than the oldest output file. If either list is empty, the script runs every time.

Warning

The files 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 files promised in the Output Files. If you want to reuse a script in multiple targets and need a variable list of input or output files, define them in a custom build setting.

To add a new rule, click the + button at the bottom of the screen. A new, undefined rule is created. Another way to create a new rule is to modify one of the system rules; Xcode balks and warns you that you cannot edit system rules, as shown in Figure 16-13. Click the Make a Copy button and Xcode duplicates the system as a new custom rule, which you are free to alter.

Figure 16-13. FIGURE 16-13

Choose the type of file that the rule will process from the Process menu. This can be one of the Xcode file types, as set in the source file's properties, or it can be a filename pattern. To match a filename pattern, choose the Source Files With Names Matching option at the bottom of the menu and a filename pattern field appears, as shown in Figure 16-14. Enter the filename pattern, such as *.xml. This field is a globbing pattern like you would use in the shell; it is not a regular expression. The pattern is case-sensitive. By using filename patterns, it is possible to partially override system rules. For example, the "C source files" type encompasses C (.c), C++ (.cpp), and Objective-C (.m) files. By creating a custom rule that matches only *.c files, you can redirect plain C files to an alternate compiler while allowing C++ and Objective-C files to "fall through" and match the default system rule for compiling any kind of C file.

Figure 16-14. FIGURE 16-14

#!/bin/bash

# Xcode compile script
# Run the input file through the java XSLT transformer
# The KeyPatternToLEX.sxlt file contains a transform that
# will convert the pattern record into LEX syntax.

XSLT = "Source/Transforms/KeyPatternToLEX.sxlt"
IN = "$INPUT_FILE_PATH"
OUT = "${DERIVED_FILES_DIR}/${INPUT_FILE_BASE}.l"

java org.mycompany.patterns.Transformer "$XSLT" "$IN" > "$OUT"

Assume a hypothetical application, called PrimeRules, that needs a precompiled table of prime numbers. You've already written a shell script that generates the C source code for a table of prime numbers between 2 and some arbitrary limit. Now you could run that script manually, capture the output, save it as a file, and add that to the project. If the maximum number ever changed, you'd have to repeat the process. The solution is awkward, and the generated C table could (potentially) be huge.

What you'd like is simply to set the maximum prime number somewhere in the project and have the build automatically generate the table of primes, compile it, and link the results into your application. One solution is to use a custom build rule:

Figure 16-15. FIGURE 16-15

The project is now finished, and should look something like the one in Figure 16-16.

Figure 16-16. FIGURE 16-16

When the PrimeRules target is built, the Compile Sources phase runs each of its source items through the build rules for the target. The main.c file gets compiled as you would expect. Because of your custom build rule, the knownprimes.primetable file runs the compilePrimeTables.sh script, which produces an intermediate .c file. The intermediate file is run back through the rules again, and is eventually compiled by the C compiler.

The two final object files, main and knownprimes, are linked together to form the finished executable.

To add a dependency to a target, open the target's Info window. The General tab contains the Direct Dependencies list. Drag a target, or targets, from the project's Groups & Files list into the list. Or, you can click the + button just below the list and Xcode presents a list of targets from which to choose, as shown in Figure 16-17. Select one or more targets from the list and click the Add Target button. To remove a target, select it in the list and click the - button.

Figure 16-17. FIGURE 16-17

Xcode (cleverly) prevents you from creating circular dependencies. Targets in the list that contain a dependency to the target you are editing, either directly or indirectly through other targets, are disabled and cannot be added.

After you've added target dependencies, they also appear along with the other build phases of the target. This brings up the second way of creating target dependencies; you can add dependencies by dragging one target directly into another target's group.

Logically, all dependent targets are built before any of the target's build phases begin, and the order in the target group reflects this. Just as you can reorder build phases, you can reorder dependent targets to control the order in which they are built. However, you cannot move a dependent target after a build phase.

You can also make a target dependent on a target in a different project. This is called a cross-project dependency. Before you can create a cross-project dependency, you must first add the sub-project to your project using any of the techniques described in Chapter 5. The easiest methods are to use the Project

Figure 16-18. FIGURE 16-18

After you've added the sub-project, it appears in the list of potential target dependencies as a group of targets, as shown in Figure 16-19. Select and add any of the cross-project targets. When a cross-project target is listed in the target's dependencies, Xcode lists the target name and the project that contains it.

Figure 16-19. FIGURE 16-19

Some potentially important differences exist in how a project target and a cross-project target are built. The primary consideration is the build settings that will be used. Every target in the same project shares the same set of build configurations, so the Deployment version of one target always depends on the Deployment version of its dependent target. This is not necessarily true of cross-project targets, which might have a completely different set of build configurations. See Chapter 17 for a discussion on how Xcode handles build settings in other projects as well as shared build locations.

Target dependencies serve a number of purposes. They:

The most common reason for a project to have multiple targets is because it produces multiple products. These are often intermediate products that are later combined into a final product by another target. For example, an application that includes two executable BSD command-line programs in its resource bundle requires three targets: an application target and two command-line targets. To produce the bundle, the application target depends on the other two command-line targets. The products of the two command-line targets are added to the application's Copy Bundle Resources phase. Whenever the application target is built, Xcode ensures that the two command-line tools are built first; then during the Copy Bundle Resources phase, it copies the two tools into the final product while constructing the application's bundle.

Large projects can be made more manageable by isolating common code into libraries or separate projects, which can be built using a single target. All of the other products that rely on that common code will have a dependency on that single target. Whenever any of those products are built, Xcode first makes sure that the common library target is built first.

Target dependencies also impose order on the build process. All dependent targets must be completely and successfully built before a target begins to build. In the "Build Rules" section, you added rules to turn XML files into object files. The assumption was that the individual source files and their outputs are all independent of each other. It didn't matter which source files, or in what order, Xcode decided to build these files. Often, as in the case of C source files, this doesn't matter, but what if it did? In the Copy Bundle Resources phase example, used earlier, the phase clearly expects all of the source items to be built already. You solve this by moving the compilation of the prerequisite files into another target, and then create a target dependency to ensure that these are all built beforehand.

Aggregate targets depend on other targets, but don't build anything themselves. An aggregate target effectively groups other targets so that you, or another target, can build multiple targets by referring to a single target. When you build in Xcode, you always build the single active target. If your project produces several products, which aren't dependent on one another, you can create an aggregate target to build them all at once. Let's say you have a project that produces two applications, a client and a server. To build both the client and server at once, create an aggregate target that depends on both. Setting the active target to the aggregate targets causes both applications to be built using a single build command.

By combining target dependencies, you can create large trees of targets. It would not be uncommon to have an aggregate target that builds five applications, each of which depends on a single common framework, which in turn depends on building several libraries. The Xcode build system is intelligent and eliminates all excess building of targets. Building that single top-level aggregate target will only cause the common framework target to be built once. As Xcode progresses through the build, it knows what targets have already been built. Before the first application is built, Xcode first builds the framework target, which in turn builds its dependent targets. However, the other four applications can then be built without rebuilding the framework target.