Clicking an issue ’ s icon in the gutter toggles the display of that single message bubble. The remaining commands selectively hide or reveal all of the message bubbles, or message bubbles of a particular class. The command settings change the message bubbles display for all windows and are remembered between builds. All of the commands in the View ➪ Message Bubbles menu are also available in the Right/Control+click contextual menu of the editor pane. BUILD PREFERENCES The Build tab in the Xcode Preferences, as shown in Figure 17 - 11, is where you ’ ll fi nd a number of global build preferences. FIGURE 17-11 Establishing Common Build Locations The Place Build Products In and Place Intermediate Build Files In options defi ne the default build locations projects. If you have special build locations that should be used for all projects, set them here. Otherwise, leave them set to Project Directory and With Build Products. The meanings of these locations are described in the “ Build Locations ” section, later in this chapter. Build Preferences ❘ 387 c17.indd 387c17.indd 387 1/22/10 12:50:11 PM1/22/10 12:50:11 PM Download at getcoolebook.com 388 ❘ CHAPTER 17 BUILDING PROJECTS Automating Build Window Behavior The Build Results Window options let you choose when the build window for the project is automatically opened and closed. The choices for automatically opening the build window are: Always Never On Errors On Issues The Always and Never choice will, or will not, automatically open the project ’ s build window whenever a build is started, respectively. The other two choices open the build window only when the build concludes with one or more errors or issues, respectively. There is also a set of choices for automatically closing the build window at the conclusion of a build. These choices are: Never Always On Success On No Errors On No Issues The Never choice leaves the build window alone. The remaining choices will automatically close the build window at the end of every build, only if the build is successful, only if there are no errors, or only if there are no issues, respectively. If you like to follow and interact with the build process in the build window, I suggest settings the open option to Always and the close option to either On Success or On No Issues. This will open the build window at the beginning of the build and close it automatically if successful, or leave it open if there were problems. If you want to let your builds run quietly in the background, set the open option to On Issues and the close option to Never. With this confi guration, the build will run quietly until it completes or encounters a problem. If issues arise, the build window will automatically open to show them to you. Other Global Build Options The Continue Building After Errors option permits phases like Compile Sources to continue compiling source fi les even after one has failed. It ’ s usually more effi cient to concentrate on fi xing the errors of just one fi le at a time, so stopping the build as soon as a compilation fails makes sense. However, there are rare occasions when an error in a second fi le is the root cause of the error in the fi rst, in which case you ’ ll want Xcode to show them all. Or maybe you simply prefer to fi x as many errors as you possibly can before building again. For any of these cases, turn this option on. This is a global setting that affects all projects. ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ ➤ c17.indd 388c17.indd 388 1/22/10 12:50:18 PM1/22/10 12:50:18 PM Download at getcoolebook.com The Use Predictive Compilation option enables anticipatory compilation of source fi les while you are editing them, which was explained in the “ Partial Builds ” section earlier in this chapter. Handling Unsaved Files The For Unsaved Files option, on the right, controls the automatic saving of source fi les in the project before a build begins. You have four choices: Ask Before Building presents a standard Save All dialog if there are any unsaved source fi les. (See Chapter 6 for information about the Save All dialog window.) Always Save automatically saves all open source fi les without asking. Never Save builds the project without regard to unsaved changes in source fi les. Cancel Build simply blocks the build from starting if there are fi les with unsaved changes. If you choose Cancel Build, there ’ s almost no indication that the build was canceled — besides the obvious fact that it didn ’ t start. I recommend using either the Ask Before Building or Always Save; the Never Save choice is a very hazardous one, and will inevitably result in your making a change to a fi le and then building your product without that change. This can be immensely frustrating during development. The automatic save options only save fi les belonging to the active project. This is a concern if your project contains cross-project target dependencies. If you have other projects open and have modifi ed fi les in those projects, starting a build in your active project will not save the fi les belonging to those other projects. If you are using multiple projects with cross-project dependencies, you should cultivate the habit of manually saving all of your fi les before beginning a build. BUILD LOCATIONS When you start a build, Xcode (hopefully) begins producing a lot of fi les. The build locations determine where those fi les get written. There are two build locations. The product location is where the fi nal products of a target are written. The intermediate fi les location is where all of the derived and intermediate fi les, like individual object fi les, are saved between builds. Wherever the build location is, it has the same structure. Within the product location folder, Xcode creates one product folder for each build confi guration. Build confi gurations are discussed later in this chapter, but you should know that build confi gurations can produce variations of a single product. Xcode keeps each variant separate by creating a folder for each, as shown in Figure 17 - 12. In this example, there are two versions of the Brick House application: one built using the Debug build confi guration and a second using the Release confi guration. Within the intermediate fi les location, Xcode creates a single .build folder for each project. Within that folder are individual subfolders for each build confi guration. Again, these are used to separate the intermediate fi les produced by a single target built with different build confi gurations. This ➤ ➤ ➤ ➤ Build Locations ❘ 389 c17.indd 389c17.indd 389 1/22/10 12:50:18 PM1/22/10 12:50:18 PM Download at getcoolebook.com 390 ❘ CHAPTER 17 BUILDING PROJECTS location is also used by the project to store its project and symbol index fi les. The product and intermediate fi les location can be the same location or different locations. As was shown in Figure 17 - 9, both the product and intermediate fi les locations are the same, so all of the build subfolders coexist in one place. The default for a new installation of Xcode is to use a build folder within each project ’ s folder as the location for both products and intermediate fi les. Technically, the build location is set to $(SRCROOT)/build ( SRCROOT is a build variable set to the path of your project ’ s folder). This is a foolproof setting and works fi ne for all independent projects of any size or complexity. You many never have to change this setting. The various build locations and intermediate directory structures are actually controlled by a group of build settings. As you’ll see later in this chapter, you have a great deal of control over build settings and can customize many of the standard build location paths. However, I suggest that you don’t attempt to do that; changing build paths can have many unexpected consequences. Set the build location using the settings provided in the General tab of the project’s Info window, and let Xcode defi ne the rest of its build locations relative to those. There are, however, some very good reasons why you might need to alter these locations. The most obvious is to resolve cross - project product references. All product references in Xcode are relative to the product location. Within a single project this will never fail, because all of the targets in a project share a single build location — another reason for why single - project projects are easier to maintain. Two projects that have separate build locations, however, cannot refer to each other ’ s products because their build locations will be different. Say you have two projects. Project A builds a static library that Project B needs to link to. In the target of the Project B you create a dependency on Project A (to make sure it ’ s up to date before linking), and then add the product of Project A to the link phase of Project B. With the default Xcode build locations, the link phase fails with a “ library not found ” error. Why? Because Xcode is expecting the library to be in the products location of Project B, along with the rest of the products, but it isn ’ t. It ’ s in the products location of Project A where it was produced. This problem extends beyond Xcode. An application that loads plug - ins may be expecting those plug - ins to be in the same folder as the application. If the plug - ins are produced by a different project, they could be somewhere else when you test your application. Or maybe your project fi les are on a (relatively) slow network volume and you ’ d like your intermediate fi les written to your (relatively) fast local hard drive. The point is that there are lots of reasons for relocating your build folders. FIGURE 17-12 c17.indd 390c17.indd 390 1/22/10 12:50:21 PM1/22/10 12:50:21 PM Download at getcoolebook.com The straightforward way of fi xing these and similar dilemmas is to defi ne a common build location, so the products from all projects are written to the same location. Products produced by Project A will be accessible to Project B just as if targets in Project B had produced them. So where do you change the build locations for a project? The fi rst option is to change the global build locations in the Build tab of the Xcode Preferences, as previously shown in Figure 17 - 11. The defaults are to use the project folder for the products location and to use that same location for the intermediate fi les. You can specify a different location for the products folder by clicking the Customized Location radio button and then entering an absolute path to the desired location, or by clicking the Choose button and browsing to a folder. The intermediate fi les location can be the same as the products location, or it can be independent. Again, select the Customized Location and choose a location. Unfortunately, you can ’ t set a common location for the products while keeping the intermediate fi les location relative to the project. The problem is that you just redefi ned the build locations for every project you open with this installation of Xcode. (That ’ s not entirely true, but the caveat will have to wait a moment.) This may never be a problem, but there are some serious pitfalls to watch out for. The biggest problem is project and product name collisions. The intermediate and index fi les for a project are kept in a .build folder derived from the project ’ s name. If you have two or more projects with the same name, they will all try to use the same index and intermediate build fi les. Just as bad is the situation of two or more projects that produce products with identical names. The product of one project will simply overwrite the product of the other project. These consequences can range from amusing to disastrous. Alternatively, you can set the build locations for an individual project. You do this through the Info window of the project, as shown in Figure 17 - 13. The choices for the Place Build Products In setting are: Default Build Products Location Custom Location The default option refers to the setting in the Xcode Preferences pane you saw earlier. The custom option lets you to specify an absolute path by entering it into the fi eld below the radio button, or by clicking the Choose button. Whenever you create a new project in Xcode, its build location is set to use the default products location. Changing the global preference changes the build location for all projects that use the default location, but it doesn ’ t affect projects with custom locations. ➤ ➤ FIGURE 17-13 Build Locations ❘ 391 c17.indd 391c17.indd 391 1/22/10 12:50:24 PM1/22/10 12:50:24 PM Download at getcoolebook.com 392 ❘ CHAPTER 17 BUILDING PROJECTS Similarly, the Place Intermediate Build Files In setting has three choices: Default Intermediates Location Build Products Location Custom Location The default location refers to the global default, which could be the project location or a custom location. The Build Products Location is whatever location was chosen for the products — in other words, whatever location was ultimately decided on by the build products location settings. Finally, the custom choice allows you to select an arbitrary location. Whenever you change the build locations for a project, do a little housecleaning. Close the project and delete all of the project’s build folders. This saves disk space and you won’t have, potentially, thousands of orphaned fi les cluttering up your development folder. Xcode automatically re-creates whatever build folders it needs. Xcode conveniently uses the two custom location path fi elds to preview the location of your build folders. If you select anything other than Custom Location, the disabled path fi eld will display the actual path that Xcode intends to use — calculated using the project ’ s folder location, the project location settings, and global location settings in the Xcode Preferences. BUILD LOCATION STRATEGIES Although you might have other reasons, the primary reason for redefi ning build locations is to share a single location with two or more projects. The three basic strategies for sharing build locations between multiple projects are as follows: Set the global build location to an absolute path and have all projects use the default location. This is ideal for reusing libraries and frameworks, and for sharing them between multiple projects or developers. Set the global build location to use a project - relative build folder, and then override the build location specifi cally for the projects that need to share a build location. This is a good solution for sharing build products between a limited number of projects for a single user, without abandoning local build folders for your remaining projects. Set the global build location to use a project - relative build folder and then share a single project folder. This is a handy trick for subdividing a single, self - contained, project into multiple projects while avoiding most of the build location issues inherent with the other two solutions. The fi rst solution is the simplest, and is probably the best choice when you ’ re dealing with a large number of projects or developers. You ’ ll have to decide what a “ large number ” is, but keep in mind ➤ ➤ ➤ ➤ ➤ ➤ c17.indd 392c17.indd 392 1/22/10 12:50:25 PM1/22/10 12:50:25 PM Download at getcoolebook.com 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 . and tools can make decisions and alter their behavior 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 . with custom locations. ➤ ➤ FIGURE 17- 13 Build Locations ❘ 39 1 c17.indd 39 1c17.indd 39 1 1/22/10 12:50:24 PM1/22/10 12:50:24 PM Download at getcoolebook.com 39 2 ❘ CHAPTER 17 BUILDING PROJECTS Similarly,. also a set of choices for automatically closing the build window at the conclusion of a build. These choices are: Never Always On Success On No Errors On No Issues The Never choice leaves