17 Building Projects WHAT'S IN THIS CHAPTER? Starting and stopping builds Selecting a build target and settings Navigating build transcripts, warnings, and errors Understanding build settings and build confi gurations Editing build settings Distributing builds to a workgroup Building projects is Xcode ’ s ultimate ambition. It might not be yours — you probably want your fi nished application to run fl awlessly and be wildly popular. While Xcode does provide additional tools for debugging and performance analysis that are covered in subsequent chapters — sorry, it can ’ t do much about your application ’ s popularity — its central purpose is to faithfully compile and assemble your fi nished application. This chapter explains how to choose what you want built and how to start, stop, and customize the build process. This chapter also explains build settings and build confi gurations, which are used to customize everything from compiler options to packaging, so your products come out just the way you want them to. Starting a build is relatively simple, and is described fi rst. After that, the chapter covers targets selection, the build window preferences, and build locations. Builds often don ’ t go fl awlessly, so the next sections describe how to dig into the details of your build transcript and navigate any warnings or errors. The bulk of this chapter explores the build settings: a multi - dimensional hierarchy of named values that control everything from the name of your application to what compiler errors are important. Knowing how to organize, fi nd, edit, and customize your build settings is critical to using Xcode effectively. This is followed by a section describing some of the more important build settings. ➤ ➤ ➤ ➤ ➤ ➤ c17.indd 373c17.indd 373 1/22/10 12:49:33 PM1/22/10 12:49:33 PM Download at getcoolebook.com 374 ❘ CHAPTER 17 BUILDING PROJECTS Finally, I describe how to distribute your builds to a network of other Xcode users for improved productivity. STARTING AND STOPPING A BUILD To build your project, choose one of the Build commands: Build ➪ Build (Command+B) Build ➪ Build and Analyze (Shift+Command+A) Build ➪ Build and Run (Command+Return) Build ➪ Build and Run - Breakpoints Off (Command+R) Build ➪ Build and Debug - Breakpoints On (Command+Y) Or from Interface Builder, File ➪ Build and Go in Xcode (Shift+Command+R) The Build ➪ Build command builds the currently active target of the currently active project using the currently active build confi guration. The section “ Selecting the Active Target and Build Confi guration ” describes how to change these. The Build ➪ Build command simply builds the active target and stops. All of the remaining commands fi rst build the active target, and then perform some other action, like running the active executable, starting the debugger, or initiating performance analysis tools. These are all shorthand commands for common sequences that you ’ ll repeat every day; the command Build ➪ Build and Run is identical to choosing Build ➪ Build followed by Run ➪ Run. The build performed in all cases is identical. These same commands can be invoked from toolbar buttons, as shown in Figure 17 - 1, if you fi nd that more convenient. Xcode provides three build buttons for toolbars: Build, Build and Run/Debug, and the Build (menu). The Build and the Build and Run/Debug buttons are the same as the Build ➪ Build, Build ➪ Build and Run - Breakpoints Off, and Build ➪ Build and Debug - Breakpoints On commands, respectively. Holding down the Option key turns the Build and Run button into the Build and Debug button, shown in the lower portion of Figure 17 - 1. ➤ ➤ ➤ ➤ ➤ ➤ FIGURE 17-1 c17.indd 374c17.indd 374 1/22/10 12:49:37 PM1/22/10 12:49:37 PM Download at getcoolebook.com The Build button with the drop - down triangles is a combination of a Build button and a drop - down menu of build and clean commands. The clean commands are described later in the “ Clean Builds ” section. Click it quickly to execute the Build command. Click and hold to select one of the other commands. This toolbar button is useful if you want to keep Build, Clean, and Clean All buttons in your toolbar, but are short on toolbar space. The progress and results of the build are displayed in the build window for the project. The build window is covered in detail in the “ The Build Window ” section. The progress of a build also appears in the Activity Viewer window, and in the status bar — at the bottom of many Xcode windows. The status bar shows a one - line summary of the build ’ s progress, as shown in Figure 17 - 2. At the right end of the bar is a small round progress indicator with Xcode ’ s estimate of how much of the build has been completed. FIGURE 17-2 When the build is fi nished, a completion statement replaces the progress message. If the build is successful, the message “ Build succeeded ” is displayed. If not, the message indicates that the build failed, possibly with an explanation of why. It may also include a count of the number of errors or warnings that were encountered. On systems with multiple processors, multi-core processors, or in a distributed build workgroup, Xcode will attempt to perform build tasks within a single target in parallel. By default, Xcode completes all of the phases in a target before building the next target. If you have many relatively independent targets, consider enabling the Build Independent Targets In Parallel option found in the General tab of the project’s Info window (see Figure 17-13). Xcode will then build dependent targets in parallel, whenever possible. You can build only one target in a project at a time, but you can start a build in multiple projects simultaneously. Selecting the Active Target and Build Confi guration All of the previously described build commands begin a build based on what ’ s “ active ” at that time. These fi ve items defi ne what the “ active ” target of the build is: The current project The active target ➤ ➤ Starting and Stopping a Build ❘ 375 c17.indd 375c17.indd 375 1/22/10 12:49:38 PM1/22/10 12:49:38 PM Download at getcoolebook.com 376 ❘ CHAPTER 17 BUILDING PROJECTS The active build confi guration The active architecture The active SDK The current project is implied. The active target is set using the Project ➪ Set Active Target menu, or from the toolbar — toolbar controls are described a little later. Xcode only builds a single target. If you need to build multiple targets you must create target dependencies to fi rst build the subordinate targets, or create an aggregate target to group several targets into one, as described in Chapter 16. Changing the active target may also change the active executable. The active executable is the executable product that will be launched by any of the Run, Debug, or Analyze commands. See Chapter 18 for more about executables. The active build confi guration is set using the Project ➪ Set Active Build Confi guration menu (or via the toolbar). The active build confi guration defi nes which set of build settings should be used to build the active target. Build settings and confi gurations are described later in this chapter. The active architecture and SDK can be set using the Project ➪ Set Active Architecture and Project ➪ Set Active SDK menus. These settings are actually overrides of standard build settings. You can effect the same changes by setting them in the Xcode interface or by editing the appropriate build setting for the active confi guration. These settings are handy, because you often want to build against a different SDK or for a different device architecture without having to alter your build settings. The active SDK settings have an explicit Use Base SDK setting, which defers to the Base SDK setting in your active build confi guration. If you ’ ve selected a specifi c SDK in your build settings, the menu will let you choose a newer, but not an older, SDK with which to build. In projects with multiple products, build confi gurations, and deployments, switching between different targets, build confi gurations, and architectures becomes a common activity. Xcode provides an entire family of toolbar controls to make those tasks easier, and to make the currently active settings readily visible. The toolbar in Figure 17 - 3 show all of the individual toolbar controls for build settings. ➤ ➤ ➤ FIGURE 17-3 c17.indd 376c17.indd 376 1/22/10 12:49:49 PM1/22/10 12:49:49 PM Download at getcoolebook.com From left to right in Figure 17 - 3, the toolbar controls display and let you set the active target, executable, build confi guration, architecture, and SDK. As you can see, this consumes a fair amount of toolbar space, so either remove the toolbar controls you don ’ t change often (ever), or consider the more compact Overview control, shown in Figure 17 - 4. The Overview toolbar control displays a compact summary of the current SDK, build confi guration, target, executable, and architecture. Its drop - down menu lets you individually change any of those settings. How many settings are displayed in the Overview control depend on what other individual build setting controls — that is, those shown in Figure 17 - 3 — you ’ ve added to your toolbar. It always shows the active SDK, build confi guration, and architecture settings but might not include the active target or executable if you also have individual target and executable controls in the same toolbar. Controlling the Build of Individual Items Xcode is constantly reevaluating what items need to be built. It does this in the background whenever changes are made to your project or to any of its source fi les — it doesn ’ t wait until you start a build to decide. Whenever Xcode has decided that a source fi le needs to be rebuilt, it sets the item ’ s build fl ag and marks it in the build (hammer) column of the details pane, as shown in Figure 17 - 5. FIGURE 17-4 FIGURE 17-5 Starting and Stopping a Build ❘ 377 c17.indd 377c17.indd 377 1/22/10 12:49:55 PM1/22/10 12:49:55 PM Download at getcoolebook.com 378 ❘ CHAPTER 17 BUILDING PROJECTS A check mark in the build column indicates that the source fi le will be built in the next build. You can manually uncheck that item, which tells Xcode to ignore the changes and treat the fi le as if it were up to date. Conversely, checking an unchecked item tells Xcode to rebuild it anyway. The Build ➪ Touch command — also accessible by Right/Control - clicking a source item, group, or target — can also be used to set the build fl ag of one or more source fi les. Right/Control - clicking an item also presents an Untouch command, treating the item as already built. You can use this ability as a more exacting alternative to a clean build, described later. By checking a source fi le ’ s build fl ag, you can force it to be rebuilt, even when Xcode is convinced that it doesn ’ t need to be. The new state of the build fl ag persists only until Xcode decides to reevaluate the condition of the fi le. For example, clearing the build fl ag for a fi le and then modifying it causes Xcode to, once again, mark the fi le to be built. Building an Inactive Target Although the build commands in the main menu and toolbar always apply to the active target, there is a shortcut for immediately building any of the other targets in your project. Control/ Right+click a target in the target ’ s smart group. In the contextual pop - up menu for the target you will fi nd Build, Build and Start, Build and Debug, and Clean build commands. Selecting any of these is equivalent to making that target active, starting a build, and then switching back to the previously active target. CLEAN BUILDS A “ clean ” build is a build that constructs everything in the product solely from the project ’ s source fi les. You might think this would be true of every build, but it isn ’ t. Xcode, like most Make systems, keeps all of the intermediate fi les that were produced during previous builds. It reuses these intermediate fi les to reduce the work required for subsequent builds: a C source fi le is compiled into an object fi le, which is later linked to form an executable. The C fi le is the source and the executable is the product, but the object fi le is an intermediate fi le. Xcode normally only recompiles the source fi le when its modifi cation date is later than the intermediate object fi le. Likewise, the executable is only re - linked if one or more of the intermediate objects are newer than the latest executable. Xcode does this to avoid recompiling everything in the project and all of its libraries and frameworks every time you make a single change. For large projects the difference can be a 20 - minute build versus a 5 - second build. However, it ’ s possible for Xcode to become confused. The classic example is to build a project and then to replace a source fi le with an earlier version. The source fi le is different and needs to be recompiled, but its modifi cation date is still earlier than the intermediate object fi le. Xcode does not recompile the fi le and much consternation ensues. Other c17.indd 378c17.indd 378 1/22/10 12:49:57 PM1/22/10 12:49:57 PM Download at getcoolebook.com actions, such as deleting or renaming components in a project, can also leave obsolete intermediate fi les behind. Some build systems have a “ build clean ” option that simply ignores the state of intermediate fi les and recompiles everything. In Xcode, this is a two - step process using the Clean (Command+Shift+K) command or Clean All Targets command followed by a new build. These two commands delete the product and all intermediate fi les generated by that target. The next time a build is executed, everything in the target will need to be rebuilt. The Clean command only applies to the active target. The Clean All Targets command cleans out all targets in the project. Both present the dialog box shown in Figure 17 - 6. FIGURE 17-6 Remember that the product will also be deleted, so you probably don ’ t want to clean a target while your application is still running. If you check the option Also Remove Precompiled Headers, the precompiled headers for the target are also deleted. Precompiling the system headers is a lot of work, so saving the precompiled headers will save a fair amount of time on the next build. Because the precompiled headers for most projects consist of just the headers from the system frameworks, they are also unlikely to have changed or be out of synchronization. On the other hand, it is also possible to include your own headers and symbols in your precompiled headers and, though rare, system frameworks do change from time to time. In any case, clearing the headers is the safest choice. The other option is Also Clean Dependencies. If checked, any targets the active target depends on are also cleaned. Clean Builds ❘ 379 c17.indd 379c17.indd 379 1/22/10 12:49:57 PM1/22/10 12:49:57 PM Download at getcoolebook.com 380 ❘ CHAPTER 17 BUILDING PROJECTS It’s worth noting that running the Clean command is not equivalent to deleting the contents of your build folder, and is one reason that Xcode provides a command to do this. There are two potential pitfalls to avoid here: the Clean command might not erase all intermediate items, and deleting the build folder might have unintended consequences. The build folder is also the repository for other project support fi les, possibly fi les from other projects. The support fi les are used to provide auto-completion, data modeling, predictive compilation, and other intelligent features of Xcode. Problems can arise if you impulsively delete these support fi les while Xcode is running. Conversely, if you issue a Clean command after removing a target the products of the target you deleted won’t be removed, because they are no longer part of the project. If you want to ensure that everything in your project is clean, and do so in a way that won’t confound Xcode, follow these steps: 1. Close the project. 2. Trash the project’s build folder. 3. Re-open and build the project. Xcode automatically re-creates the build folder, along with whatever support fi les it needs. The build folder is normally the folder named “build” inside the project folder — unless you’ve relocated it. The “Build Locations” section explains how to change or identify a project’s build location. PARTIAL BUILDS There are a few commands for compiling a single fi le without committing a full build. These commands are: Build ➪ Compile (Command+K) Build ➪ Preprocess Build ➪ Show Assembly Code Each is enabled whenever you are editing, or have selected, a program source fi le that belongs to the project. Selecting one of these commands compiles the fi le using the current, or only, target that compiles that fi le. The Compile and Preprocess commands are quick ways of checking that this source fi le compiles, without waiting for any other fi les or dependent targets to be built. The Preprocess command only runs the fi le though the compiler looking for errors. It does not replace the object code last compiled for the fi le, nor does it perform any other build - related steps. The Show Assembly Code command is a little different. It compiles the source fi le using fl ags that cause the compiler to output assembly source code for the fi le instead of a compiled object fi le. This can be instructive if you need to examine the actual machine code produced by the compiler. The assembly source fi le exists in the build directory and will be overwritten by the next Show Assembly ➤ ➤ ➤ c17.indd 380c17.indd 380 1/22/10 12:49:58 PM1/22/10 12:49:58 PM Download at getcoolebook.com . critical to using Xcode effectively. This is followed by a section describing some of the more important build settings. ➤ ➤ ➤ ➤ ➤ ➤ c17.indd 37 3c17.indd 37 3 1/22/10 12:49 :33 PM1/22/10 12:49 :33 PM Download. active target ➤ ➤ Starting and Stopping a Build ❘ 37 5 c17.indd 37 5c17.indd 37 5 1/22/10 12:49 :38 PM1/22/10 12:49 :38 PM Download at getcoolebook.com 37 6 ❘ CHAPTER 17 BUILDING PROJECTS The active. in the lower portion of Figure 17 - 1. ➤ ➤ ➤ ➤ ➤ ➤ FIGURE 17-1 c17.indd 37 4c17.indd 37 4 1/22/10 12:49 :37 PM1/22/10 12:49 :37 PM Download at getcoolebook.com The Build button with the drop - down