16 Targets WHAT'S IN THIS CHAPTER? Creating targets Adding source items to targets Defi ning target dependencies Customizing targets Targets are the engines of Xcode. They defi ne the steps that will transform your source code and resource fi les into a fi nished product. Targets can be very complex or ridiculously simple. Xcode comes with targets that automatically take care of the myriad details needed to produce standard products such as application bundles, or you can take complete control and choose a target that abdicates all of the responsibility for building a product to you. The purpose of a target is to produce something. Most targets produce a product. There are different types of targets, depending on what kind of product is being produced. Each target refers to the source fi les and resources required to produce its product, along with the instructions on how those source fi les get transformed, how the product is assembled, and the order in which all of those things happen. Targets appear in the Targets smart group of the project window, as shown in Figure 16 - 1. Most project templates come with a target already defi ned, appropriately confi gured for that project type. If you stick to developing simple applications and tools you may never need to add a target to an existing project. Nevertheless, understanding what a target is and does is a prerequisite to customizing one and is fundamental to understanding the build process as a whole. ➤ ➤ ➤ ➤ c16.indd 339c16.indd 339 1/21/10 3:55:50 PM1/21/10 3:55:50 PM Download at getcoolebook.com 340 ❘ CHAPTER 16 TARGETS TARGETS VS. SUB - PROJECTS Anytime you have a project that makes two or more products, you have a very important decision to make: you can add a new target to your existing project or you can create a new project. Which you choose will have far reaching consequences on your project ’ s structure and maintenance. My advice is always: add a new target to your existing project unless there is a compelling need to confi ne the product in its own project. In other words, if you can ’ t think of a good reason to make it a separate project, make it a target. Managing, editing, building, and testing a project with multiple targets is generally easier and more effi cient than separating the parts into individual sub - projects. The following table lists some of the pros and cons of adding a target to a project versus creating a sub - project: CONCERN TARGET SUB - PROJECT Project Folders Targets share the same project and build folders. Projects generally have independent project folders, but you can place multiple project documents in the same project folder. If separate, source references between them will have to extend outside the project folder. If shared, they must be confi gured to either peacefully share build folders or use independent build folders. Source Items Targets can refer to or share any of the project ’ s source items. Projects cannot share source items. Any common items will have to be defi ned twice, and maintained in parallel. FIGURE 16 - 1 c16.indd 340c16.indd 340 1/21/10 3:55:53 PM1/21/10 3:55:53 PM Download at getcoolebook.com Targets vs. Sub - Projects ❘ 341 CONCERN TARGET SUB PROJECT Source Files The source fi les referred by source items are inherently shared by all targets. Source fi les can be shared through duplicate source items, but Xcode may not recognize them as being the same fi le. Build Settings Each target has its own build settings, but shares the common build settings for the project. Projects have independent build settings. Build settings common to multiple projects must be maintained in parallel. Build Confi gurations All targets share the same matrix of build confi gurations. Build confi gurations in sub - projects must be coordinated so that they match, or appropriate default confi gurations defi ned. Source Control All source items in a project share the same source control management repository. Source control for separate projects must be confi gured independently, but could (potentially) share the same SCM repository, or a branch therein. Xcode Management All targets and source items belong to the open project. Common items shared by two open projects belong to one or the other, but not both. This can sometimes lead to some confusion about which project is active. The Ideal Single - Project Project 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 confi gurations, and smart groups. Examples of this kind of project are: A Cocoa application project that contains an embedded Spotlight indexing plug - in A project that produces a pair of applications, like a client and server A project that builds a suite of POSIX command - line tools In each of these projects, the benefi ts of keeping everything in a single project are clear: Targets easily share common source fi les Centralized build settings and confi gurations Unifi ed source control management and snapshots Multi - fi le searches across all targets A single Code Sense index ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ c16.indd 341c16.indd 341 1/21/10 3:55:54 PM1/21/10 3:55:54 PM Download at getcoolebook.com 342 ❘ CHAPTER 16 TARGETS It is likely that these kinds of projects will need to share common source fi les, header fi les, and other resources. They are also likely to all use the same, or a similar, set of build settings. Changing a source fi le or build setting will correctly rebuild all dependent targets. The Ideal Multi - Project Project 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: A Cocoa application that uses an open - source processing engine A suite of applications where each component is being developed by a separate team of engineers A framework used by other applications In the fi rst situation, you have your Cocoa application and another large collection of source fi les 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 specifi cally designed to be development resources. A project using the framework has access to its API (in the form of header fi les), resource fi les, and even documentation without the need to explicitly include those fi les 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. The Project in the Middle 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 confi gure 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 specifi c 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. ➤ ➤ ➤ c16.indd 342c16.indd 342 1/21/10 3:55:54 PM1/21/10 3:55:54 PM Download at getcoolebook.com THE ANATOMY OF A TARGET Targets consist of several interrelated parts: dependencies, build phases, build settings, build rules, and a product, as described in the following table. Different target types may include all, some, or only one of these parts. All of the components are described in detail later in this chapter. COMPONENT DESCRIPTION Dependencies The other targets on which this target depends. Build phases Defi nes the steps required to build a target. Each phase defi nes a procedure and the source fi les involved. Build settings Variables available to the build phases that can be used to customize the build. Build rules Rules that defi ne how fi les of a particular type are compiled or transformed. Product The end result of the target. You edit most of these parts using various tabs in the target ’ s Info window or via the Inspector palette. To open a target ’ s Info window, select the target and choose Get Info from the File menu or the Right/Control - click contextual menu. For native targets (which are explained later), you can just double - click the target or select it and press the Return key. If the target you want to edit is the active target, use the Project ➪ Edit Active Target ‘ TargetName ’ (Option+Command+E) command. Every target has a name. You can change the name of a target by selecting the target group in the project window and choosing Rename from the Right/Control - click contextual pop - up menu. You can also edit it in the General tab of the target ’ s Info window. Target Dependencies 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 fi les and the source fi les used to produce them. These are calculated by the target and are not under your control. Whenever possible, a target only recompiles fi les 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 fi les that need to be rebuilt. The Anatomy of a Target ❘ 343 c16.indd 343c16.indd 343 1/21/10 3:55:54 PM1/21/10 3:55:54 PM Download at getcoolebook.com 344 ❘ CHAPTER 16 TARGETS Target Build Phases 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 defi ne the broad order in which steps will occur during a build. For example, all of your C source fi les must be compiled into object fi les before those object fi les can be linked together. All of the object fi les must be linked together before the fi nal executable can be copied into the application ’ s bundle, and so on. The order of steps within a build phase is entirely up to that phase. The order within some phases is fi xed, whereas others are very dynamic. A build phase that compiles a gaggle of source fi les may compile them in alphabetical order or in the order in which they were most recently modifi ed. 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. Target Membership 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: Adding an item to a target adds that item to the (hopefully) appropriate build phase of the target. Removing an item from a target simply deletes all references to that item from all build phases of the target. If a target is disabled for an item, it means that no build phases in that target are compatible with that item ’ s type. 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 fi x 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. ➤ ➤ ➤ FIGURE 16 - 2 c16.indd 344c16.indd 344 1/21/10 3:55:55 PM1/21/10 3:55:55 PM Download at getcoolebook.com Target Build Settings 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 The Anatomy of a Target ❘ 345 Targets can also have multiple sets of settings called build confi gurations. The project itself has multiple sets of build settings. Because build settings and build confi gurations are not unique to targets, the editing of build settings, the management of build confi gurations, and how they all interact with each other are explained in Chapter 17. Target Build Rules Targets that compile fi les have a set of build rules. Build rules tell a target what compiler or translator to use when building each source fi le. The build rules can be modifi ed in the Rules tab of the target ’ s Info window, shown in Figure 16 - 4. Each rule is a pairing of a fi le type, which you select using the Process menu, and a compiler, which you select using the Using menu. If necessary, you can defi ne your own rules or redefi ne standards. c16.indd 345c16.indd 345 1/21/10 3:55:55 PM1/21/10 3:55:55 PM Download at getcoolebook.com 346 ❘ CHAPTER 16 TARGETS Target Product 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. TARGET TYPES It ’ s diffi cult to classify target types in Xcode neatly, because the types form a kind of spectrum. However, the spectrum of target types can be roughly divided between the native and non - native targets. Native targets are at one extreme of the spectrum. They are sophisticated, are tightly integrated into Xcode, are highly confi gurable, have a fl exible number of build phases, and produce complex products (like frameworks). At the other extreme is the non - native external target. An external target simply launches some external process with the understanding that said process will do whatever is necessary to build the target. Xcode doesn ’ t know what an external process will do, what fi les it depends on, or even if it produces anything. An external target has no build phases and is not confi gurable (from within Xcode). In between these two extremes are target types such as aggregate targets and the legacy Jam - based targets. The sophistication of these target types varies. They may have some of the same parts as native targets but are usually simpler and are not as tightly integrated into Xcode. FIGURE 16 - 4 c16.indd 346c16.indd 346 1/21/10 3:55:56 PM1/21/10 3:55:56 PM Download at getcoolebook.com . need to be rebuilt. The Anatomy of a Target ❘ 34 3 c16.indd 34 3c16.indd 34 3 1/21/10 3: 55:54 PM1/21/10 3: 55:54 PM Download at getcoolebook.com 34 4 ❘ CHAPTER 16 TARGETS Target Build Phases A. or redefi ne standards. c16.indd 34 5c16.indd 34 5 1/21/10 3: 55:55 PM1/21/10 3: 55:55 PM Download at getcoolebook.com 34 6 ❘ CHAPTER 16 TARGETS Target Product Most targets produce a product. The. understanding the build process as a whole. ➤ ➤ ➤ ➤ c16.indd 33 9c16.indd 33 9 1/21/10 3: 55:50 PM1/21/10 3: 55:50 PM Download at getcoolebook.com 34 0 ❘ CHAPTER 16 TARGETS TARGETS VS. SUB - PROJECTS Anytime