Lập trình Wrox Professional Xcode 3 cho Mac OS part 54 doc

402 ❘ CHAPTER 17 BUILDING PROJECTS You might be worried at this point that a complex project with fi ve targets and four build confi gurations would have an unmanageable number of build settings — at least 25 complete sets of build settings, in all. Don ’ t worry. Xcode provides several tools for visualizing build settings as a whole, editing build settings in multiple confi gurations at once, and moving build settings between layers. Each of these are covered shortly. The most common use of build confi gurations is to alter the compiler and linking options when producing an application for different purposes. For debugging, the application needs to be compiled with certain code optimizations turned off (code optimizations can interfere with source - level debugging) and with debug information included. Conversely, the released version of your application needs to be fully optimized, but does not need to include any debugger data — the end user doesn ’ t need it and it signifi cantly increases the size of the application. You may also need to produce an application that ’ s between these two extremes for performance testing. For that, you ’ ll want an application that is fully optimized (just like the fi nal version), but also includes all of the information used by the debugger to identify functions and variables. This use of build confi gurations is so common that these are exactly the build confi gurations provided by Xcode templates. All Xcode project templates include two confi gurations, named Debug and Release. The default values for the build confi gurations set the compiler and linking options to those you would typically want. In the Debug confi guration, optimization is turned off, debugging symbols are enabled, as are useful debugging features like Fix and Continue. The Release confi guration has just the opposite settings. Optimization and normal linking are turned on, and all of the debugging aides are disabled. EDITING BUILD SETTINGS Now that you understand the hierarchy of build settings and build confi gurations, you should now be able to make sense of the interface for editing build settings. Select a project or target and open its Info window; the easiest way is to double - click the project or target icon. Switch to the Build tab and a list of build settings is displayed, as shown in Figure 17 - 21. The name of each setting is in the Setting column and its value is listed in the Value column. The Confi gurations pop - up menu selects which set of build settings you are seeing or editing. You can choose a specifi c build confi guration, or whatever confi guration is currently active. The special All Confi gurations choice merges the build settings from all of your FIGURE 17-21 c17.indd 402c17.indd 402 1/22/10 12:50:46 PM1/22/10 12:50:46 PM Download at getcoolebook.com confi gurations into the single list. Changing a setting in this mode changes that setting in every build confi guration . A setting with values that vary between confi gurations displays < Multiple values > for its value. Filtering Build Settings Build settings are organized into groups to make it easier to fi nd the settings you ’ re looking for. You can fi lter out uninteresting settings by name or value by typing something into the search fi eld. By default, the search fi eld will match any setting ’ s name, title, value, defi nition, or description. Use the search fi eld ’ s menu to limit the scope of the search, if necessary. For example, type “ gar ” into the search fi eld to quickly locate the Objective - C Garbage Collection settings. The Show menu can be set to one of three choices: All Settings Settings Defi ned at This Level User - Defi ned Settings When All Settings is chosen, the list shows every build setting that Xcode knows about. This will be far more build settings than are set in the level (project or target) you are editing. Those actually defi ned at this level are displayed in bold. The settings in normal text are those inherited from lower levels, showing you all of the existing settings that you might want to redefi ne at this level. To narrow your focus to just the build settings defi ned in this level, change the Show setting to Settings Defi ned at This Level. All of the inherited settings are hidden. User - Defi ned Settings is the same as All Settings, but fi lters out all of the standard settings that Xcode knows about. The resulting display lists only custom build settings that you ’ ve defi ned. Again, the settings in bold are defi ned at this level and non - bold values are inherited from lower levels. Viewing Names and Defi nitions Every build setting has a name and an optional title. The name is the actual variable name defi ned in the collection, like OTHER_CFLAGS . Its title is a more human readable title supplied by Xcode, like “ Other C Flags. ” Build settings that Xcode does not recognize are always displayed using their name, which naturally includes all user - defi ned settings. You can have Xcode list build settings by name or by title. Right/Control+click any build setting — anywhere in the row, but it can ’ t be an empty row. The pop - up menu has two commands: Show Setting Names/Titles Show Defi nitions/Values The fi rst command toggles the Title column between displaying the title of the setting and its name, both shown in Figure 17 - 22. ➤ ➤ ➤ ➤ ➤ Editing Build Settings ❘ 403 c17.indd 403c17.indd 403 1/22/10 12:50:46 PM1/22/10 12:50:46 PM Download at getcoolebook.com 404 ❘ CHAPTER 17 BUILDING PROJECTS The second command toggles the Value column between displaying the resolved value for the setting and its actual defi nition, as shown in Figure 17 - 23. FIGURE 17-22 FIGURE 17-23 c17.indd 404c17.indd 404 1/22/10 12:50:47 PM1/22/10 12:50:47 PM Download at getcoolebook.com Values are resolved using the current level and any lower (inherited) levels; build settings that refer to values in higher levels, like our YEAR example earlier, won ’ t display the correct build time value in the Info window. This is rare, however. Most of the time, the values expressed in the Info window are exactly what they will be at build time. You can test references by editing other build setting layers and immediately see the results. A Peek - A - Boo Build Script When editing complex sets of interrelated build settings, it ’ s sometimes diffi cult to tell what the end result will be. If you ’ re wondering what value a particular build setting gets resolved to at build time, add a custom Run Script phase to your target, like this: 1. In the target of interest, add a new Run Script build phase. 2. Edit the phase ’ s script so it ’ s something like: echo 'The build settings containing TEST:' env | fgrep -i TEST | sort exit 0 When your target is built, it will run the script, dumping all of the environment variables that contain the word “ test ” to the build transcript, which you can examine in the build window. This works because, before running an external script or tool, Xcode resolves every build setting that ’ s currently in scope and converts each one into an environment variable. This environment is then passed to the child process. If you already have a Run Script phase that ’ s doing something, consider checking the Show Environment Variables in Build Log option of the build phase. This option dumps all of the environment variables (which includes the build settings) to the build transcript prior to running the script. There are a million variations on these techniques. Just keep in mind that if you ever want to know exactly what a build setting ’ s value is, dump it from a script. Changing Build Setting Values Editing build settings values depends somewhat on the display mode, as explained in the earlier section “ Viewing Names and Defi nitions. ” When the values of settings are displayed, Xcode shows — whenever possible — an intelligent setting control. This is true for Boolean values, lists, and values that have a known set of acceptable values. All three are shown in Figure 17 - 24. FIGURE 1724 Editing Build Settings ❘ 405 c17.indd 405c17.indd 405 1/22/10 12:50:48 PM1/22/10 12:50:48 PM Download at getcoolebook.com 406 ❘ CHAPTER 17 BUILDING PROJECTS In Figure 17 - 24, the Build Active Architecture Only setting is a Boolean value that appears as a simple check box. Tick the box to set it to YES and untick it to set to NO . Xcode recognizes that the Valid Architectures settings is a list. Double - clicking the value cell presents an editable list, as shown on the right in Figure 17 - 25. Add, remove, and edit members of the list in the dialog sheet. Xcode assembles the list into a single space - delimited value. The Debug Information Format setting is known to have three valid settings, which Xcode presents as a pop - up menu, as shown on the left in Figure 17 - 25. Select the one you want and Xcode substitutes the correct value. Notice that the value is not the same as the description. Like build setting titles, Xcode has a known set of values for which it substitutes more easily read titles. FIGURE 17-25 Under other circumstances, Xcode may simply present you with a free - form editing dialog, or let you edit the value directly in the value cell of the table. This can happen because you ’ re displaying the defi nitions of the settings rather than their values, Xcode doesn ’ t have a specialized editor for the value, you single - click a selected value rather than double - click, and so on. Either way, you ’ re now editing the raw value, before any references have been resolved and sans any translation. Figure 17 - 26 shows the same three values in Figures 17 - 24 and 17 - 25 being edited in their raw form. FIGURE 17-26 c17.indd 406c17.indd 406 1/22/10 12:50:48 PM1/22/10 12:50:48 PM Download at getcoolebook.com Changing a build setting defi nes that build setting in the level where you edited it, even if you set it back to its inherited value. Once a build setting is defi ned, it remains defi ned at that level until you delete it (see the section “Deleting a Build Setting”). This is a problem when you change a build setting for a target, change it back to its default, and then edit the same build setting in the project build settings. You might think you are now changing that setting for all targets, but the target where the build setting is still defi ned won’t change because its setting — with the old value — overrides the one in the project. Finally, there ’ s an Edit Defi nition At This Level command in the action pop - up menu in the lower - left corner of the Info window. It has the same effect as double - clicking a setting. Creating a Conditional Build Setting As mentioned earlier in the “ Conditional Build Settings ” section, certain build settings can be conditional. That is, they will take on different values under specifi c combinations of SDK and processor architecture. To create a conditional build setting, select a build setting that ’ s defi ned at this level and choose the Add Build Setting Condition command from the action menu. The variant appears underneath the existing setting, as shown in Figure 17 - 27. FIGURE 17-27 The conditional setting is defi ned by two pop - up controls that let you choose the circumstances under which the conditional setting is used. Choose an SDK, processor architecture, or combination using the pop - up menus. The Xcode interface does not let you choose a variant condition, nor can you use wildcard conditions to match multiple conditions. To do that, you ’ ll have to use a confi guration settings fi le, described later in this chapter. Editing Build Settings ❘ 407 c17.indd 407c17.indd 407 1/22/10 12:50:49 PM1/22/10 12:50:49 PM Download at getcoolebook.com 408 ❘ CHAPTER 17 BUILDING PROJECTS Creating a Custom Build Setting To create a new build setting for your own purposes, simply choose the Add User - Defi ned Setting from the action menu at the bottom - left corner of the Info window. A new build setting is added to the table, and Xcode lets you edit its name and value, as shown on the left in Figure 17 - 28. The name cannot duplicate any existing build setting, and once created you can ’ t rename it. To rename a user - defi ned setting, delete the old setting and create a new one. Build setting names must conform to the C macro naming convention and are traditionally all uppercase. If they don ’ t, Xcode presents the warning dialog shown in Figure 17 - 29. Xcode will allow you to create multiple settings that differ only in case, but settings may be case - insensitive in some circumstances, so avoid doing that whenever possible. Deleting a Build Setting To delete a build setting, select the setting in the list and choose the Delete Defi nition At This Level command from the action menu, or simply press the Delete key. Deleting a build setting does exactly what the command says: it deletes the defi nition of that build setting at this level . Build settings defi ned by Xcode or in other levels continue to exist. If you ’ re showing all settings, the build setting will turn from a bold setting (one defi ned at this level) to a normal setting (one inherited from some lower level). The only time deleting a build setting will make it totally disappear is when you ’ re deleting the only defi nition of a user - defi ned setting. Naturally, if you have the Info window set to show only settings defi ned at this level it will also disappear, but the setting still exists elsewhere. Switching Between Build Confi gurations Most of what ’ s been discussed so far about editing and creating build settings has assumed that that you only have one build confi guration. A project with three build confi gurations means that there are three sets of build settings for each target. As mentioned earlier, you select the build confi guration you are editing using the Confi guration pop - up menu at the top of the Build tab. To edit the build settings for a particular confi guration, select that confi guration from the list. You can also select the Active ( name ) item. The Info window FIGURE 17-29 FIGURE 17-28 c17.indd 408c17.indd 408 1/22/10 12:50:52 PM1/22/10 12:50:52 PM Download at getcoolebook.com always shows and edits whatever the active build confi guration is. Changing the build confi guration using Project ➪ Set Active Build Confi guration immediately changes the build settings in the Info window to match. One of the most useful views is the All Confi gurations view. When you select this view, the Build tab shows a composite view of all of the settings from all confi gurations. It does this the same way items in a multi - item Info window are displayed. Settings with values that are different between confi gurations are displayed as < Multiple values > . Boolean options whose values are set with a check box show a hyphen. You can quickly scan the list to see which settings differ between confi gurations. More importantly, when you are in this view, any change you make to a setting sets that value in every confi guration of the target or project. This mode is extremely useful for setting project and target settings in multiple confi gurations simultaneously, but it also requires some care. You can easily overwrite settings that were created for a specifi c confi guration. It is also easy to unintentionally create new build settings. In the All Confi gurations view, editing the value of a setting also creates that setting (with the same value) in every confi guration that did not previously contain that setting. Similarly, deleting a setting in the All Confi gurations view deletes that setting from every confi guration. EDITING BUILD CONFIGURATIONS You manage build confi gurations in the Confi gurations tab of the project ’ s Info window, shown in Figure 17 - 30. The Edit Confi guration List shows the build confi gurations defi ned in the project. You can get to this by opening the Info window for the project. You can also jump there by selecting the conveniently placed Edit Confi gurations item in the Confi guration menu of any build settings editor. You create a new confi guration by selecting an existing confi guration and clicking the Duplicate button at the bottom of the pane. Remember that a build confi guration represents a complete set of build settings for every target and for the project itself — you really wouldn ’ t want to create a completely empty set of build settings. Select the confi guration that is closest to the settings you want for your new confi guration, duplicate it, and then go fi x the differences in the build settings of the project and each target. FIGURE 17-30 Editing Build Confi gurations ❘ 409 c17.indd 409c17.indd 409 1/22/10 12:50:53 PM1/22/10 12:50:53 PM Download at getcoolebook.com . choose the circumstances under which the conditional setting is used. Choose an SDK, processor architecture, or combination using the pop - up menus. The Xcode interface does not let you choose. set to one of three choices: All Settings Settings Defi ned at This Level User - Defi ned Settings When All Settings is chosen, the list shows every build setting that Xcode knows about. This. your own purposes, simply choose the Add User - Defi ned Setting from the action menu at the bottom - left corner of the Info window. A new build setting is added to the table, and Xcode lets you