All of the previously described build commands begin a build based on what's "active" at that time. These five items define what the "active" target of the build is:

The current project is implied.

The active target is set using the Project

The active build configuration is set using the Project

The active architecture and SDK can be set using the Project

The active SDK settings have an explicit Use Base SDK setting, which defers to the Base SDK setting in your active build configuration. If you've selected a specific 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 configurations, and deployments, switching between different targets, build configurations, 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. FIGURE 17-3

From left to right in Figure 17-3, the toolbar controls display and let you set the active target, executable, build configuration, 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.

Figure 17-4. FIGURE 17-4

The Overview toolbar control displays a compact summary of the current SDK, build configuration, 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 configuration, 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.

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 files — it doesn't wait until you start a build to decide. Whenever Xcode has decided that a source file needs to be rebuilt, it sets the item's build flag and marks it in the build (hammer) column of the details pane, as shown in Figure 17-5.

Figure 17-5. FIGURE 17-5

A check mark in the build column indicates that the source file will be built in the next build. You can manually uncheck that item, which tells Xcode to ignore the changes and treat the file as if it were up to date. Conversely, checking an unchecked item tells Xcode to rebuild it anyway. The Build

You can use this ability as a more exacting alternative to a clean build, described later. By checking a source file's build flag, 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 flag persists only until Xcode decides to reevaluate the condition of the file. For example, clearing the build flag for a file and then modifying it causes Xcode to, once again, mark the file to be built.

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 find 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.

The build transcript is a structured view of the build log produced by the Xcode tools. It takes the (often voluminous) text output the by the various compilers, tools, and scripts; digests it; compacts it; and presents it as an intelligent, organized summary of the results. Xcode displays five types of messages in the build transcript window:

Progress messages are transient messages displayed only while a build step (compile, link, copy, and so on) is in progress. Once that step in complete, the progress message is replaced by a completed build step or it simply disappears. Progress messages appear as grey text and let you follow the activity of your build in detail. The CompileXIB statement in Figure 17-8 is a progress message.

Figure 17-8. FIGURE 17-8

The persistent items that appear in your build transcript are the results of the build. These are described in the following sections, and are shown in Figure 17-7 and Figure 17-8.

A build step appears for each completed step in the build, distinguished by a green check mark. If the step is associated with a specific source file, selecting the step displays that file in the editor pane.

As mentioned early, the build results that you see in the build window isn't the actual output of the build. It's an interpreted version, with the important bits highlighted and the minutia hidden.

Sometimes, however, the details of what went wrong are buried in that minutia. When this happens, you'll want to examine the raw output of the build process. There are three techniques for digging into the details of the build transcript.

Reveal the Source Build Output

To the right of some messages is a reveal transcript button, as shown in Figure 17-9. Clicking it reveals the source build output that the message, or messages, were constructed from.

Figure 17-9. FIGURE 17-9

Right/Control+clicking any message in the build transcript reveals two commands: Expand All Transcripts and Collapse All Transcripts. These commands reveal, or hide, the transcripts for every message in the window.

Having a concise summary of the problems in your project is only half the battle. You have to get to the source of the problems and fix them. Xcode provides a number of navigation shortcuts for quickly getting to the root of your build issues.

Build Window Editor Pane

The build window editor pane is probably the simplest and quickest way to fix small problems. Select any single message in the build transcript; the associated source file (if it has one) is immediately displayed in the editing pane, with the suspect text selected. Use the editor to fix the problem and move on.

Note

The View

Though message bubbles were mentioned briefly in Chapter 6, this is where they become useful — or annoying, depending on the circumstances. Each build issue that's associated with a particular location in a source file appears as a message bubble at that location. A build issue indicator appears in the gutter, and a message bubble describing the issue appears to the right of, or below, the suspect text, as shown in Figure 17-10.

Figure 17-10. FIGURE 17-10

While having the description of the problem appear right where the problem lies is exceptionally handy, the message bubbles can get in the way of serious editing — particularly when several errors occur on a single line. There are a number of ways to hide, and later reveal, them if they become a hindrance:

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.

Note

All of the commands in the View

The Place Build Products In and Place Intermediate Build Files In options define 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.

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:

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:

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 configuration, 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.

The Continue Building After Errors option permits phases like Compile Sources to continue compiling source files even after one has failed. It's usually more efficient to concentrate on fixing the errors of just one file 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 file is the root cause of the error in the first, in which case you'll want Xcode to show them all. Or maybe you simply prefer to fix 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.

The Use Predictive Compilation option enables anticipatory compilation of source files while you are editing them, which was explained in the "Partial Builds" section earlier in this chapter.

The For Unsaved Files option, on the right, controls the automatic saving of source files in the project before a build begins. You have four choices:

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 file and then building your product without that change. This can be immensely frustrating during development.

Each set of build settings has a scope, or lifetime, as described in the following table. Build settings that are out of scope when a particular target is being built are inaccessible and irrelevant.

Any build settings established using the command-line arguments passed to the xcodebuild tool exist for the duration of the build. This may span the building of many targets.

The build settings for a target only exist while files in that target are being processed. If dependencies cause another target to be built, the build settings used for the dependent target are the build settings belonging to that dependent target. Targets do not inherit, or in any way pass, their build settings to the build phases of other targets.

The project build settings exist whenever a target in that project is being built. If a dependency causes a cross-project target to be built, that target will be built using the project build setting belonging to the external project. Projects do not inherit or pass build settings to other projects.

Environment build settings are constant throughout a build. The environment settings used during a build are those that existed when Xcode or the xcodebuild tool was launched. When those build settings get created and their values are beyond Xcode's control.

Every named build setting used by a target, script, or tool forms, essentially, an expression that Xcode converts into a value. The rules for evaluating build setting expressions are pretty simple, and most of the time are trivial. For simple build settings — those that don't refer to other build settings — the rule is this:

If more than one build setting layer contains a value with the same name, the value defined by the top layer is used. Take a look at the build settings shown in Figure 17-15 as an example.

Figure 17-15. FIGURE 17-15

The INSTALL_MODE_FLAG setting is used to set the access permissions of executable product files. The default value of a-w,a+rX gives all users read and execute rights to the file, which is appropriate for most applications. However, this application includes a self-installing helper tool — an executable that will be copied to another location and executed there. For security purposes, you don't want the program file in the application bundle to be executable, because it should never be launched from within the bundle. To accomplish this, the INSTALL_MODE_FLAG build setting is set to a-wX,a+r in the HelperTool target.

When the Application target is built, the four sets of build settings — Command-Line, Application Target, Project, and Environment — are assembled. Only the project layer defines an INSTALL_MODE_FLAG setting, so the value used when building the Application target is a-w,a+rX. When it comes time to build the HelperTool target, the build sets that are in scope — which this time includes the HelperTool target settings but not the Application target set — are assembled. This time, both the HelperTool target and the project define a setting named INSTALL_MODE_FLAG. The definition of INSTALL_MODE_FLAG in the target set is in a higher layer than the project, so the value from the HelperTool target is used. When it's all finished, the project produces an application that can be launched along with a BSD program file that can be read but not directly executed.

As you can see, the scope and precedence of build settings are pretty simple. That is, until build settings start referring to other build settings. This simultaneously makes build settings more powerful while significantly complicating how build settings are resolved.

The $(VAR_NAME) syntax enables a build setting to refer to any other build setting. For example, the Other C++ Flags (OTHER_CPLUSPLUSFLAGS) build setting is normally set to the value $(OTHER_CFLAGS). This build setting effectively sets the Other C++ Flags setting to match the Other C Flags setting, so that any extra compiler flags you set for C compiles will also be used when compiling C++ files. Any custom C flags, regardless of what layer they are defined in, are automatically passed to the C++ compiler as well.

Figure 17-16 illustrates the order and rules used to resolve build setting references.

Figure 17-16. FIGURE 17-16

This project produces three applications: Problem Grapher, Algebra Solver, and Calculus Solver. Each application includes a copyright statement. Sharp Pencils wrote Problem Grapher and Algebra Solver, and Math Whiz wrote Calculus Solver.

The project defines a COMPANY setting containing a company name and a YEARS setting defining a span of years. It also defines a COPYRIGHT_STATEMENT setting that forms a complete copyright statement using the values of the other two build settings.

When the Problem Grapher target is built, the value of the COPYRIGHT_STATEMENT setting is constructed by substituting the values of the YEARS and COMPANY settings where their references appear in the value, as illustrated in Figure 17-17. Ultimately, the value of COPYRIGHT_STATEMENT is Copyright 2003, Sharp Pencils.

Figure 17-17. FIGURE 17-17

When the Calculus Solver target is built, things get a little more interesting. When Xcode resolves the references to YEARS and COMPANY, it finds values set in the Calculus Solver target (which is now in scope) that override the values in the project, as shown in Figure 17-18. Using those values instead, the COPYRIGHT_STATEMENT setting now resolves to Copyright 2000-2003, Math Whiz. Notice how a value defined in a higher layer can alter a definition defined in a lower one.

Figure 17-18. FIGURE 17-18

Next is the Algebra Solver target. This target is interesting because the YEARS setting contains a self-referential value. That is, the value of YEARS refers to the value of the YEARS setting. Xcode resolves self-referential references by obtaining the value of the setting from a lower layer of build settings. When the COPYRIGHT_STATEMENT setting refers to the YEARS setting, Xcode finds it in the Algebra Solver target setting. When Xcode constructs the value for the YEARS setting for that target, it finds a reference to the YEARS setting. Xcode recursively searches for another definition of the YEARS setting, but ignores layers at or above the layer containing the reference, as shown in Figure 17-19. Ultimately, the $(YEARS) reference in the target's YEARS setting is replaced with the YEARS value set in the project, resulting in a value of 2003-2005.

Figure 17-19. FIGURE 17-19

Recursive references are particularly useful for amending Xcode build settings. For example, the OTHER_CFLAGS build setting defines additional arguments that are passed to the gcc compiler. If you defined just a set of flags in your target, it would override whatever the value of this setting might be in the project. Instead, you can define the value of this setting as $(OTHER_CFLAGS) -myflag in the target. The argument -myflag is merely appended to whatever the project or environment setting was, rather than replacing it. As described earlier, whatever your OTHER_CFLAGS ultimately resolved to would be transferred to OTHER_CPLUSPLUSFLAGS, even if the augmentation of OTHER_CFLAGS occurred in an higher layer.

If there were no lower layers that contained a YEARS setting, the reference $(YEARS) would be replaced with an empty string. In fact, any reference to an undefined or out-of-scope build setting is replaced with nothing. Referring to an undefined build setting does not cause a build error or produce any kind of warning.

References to environment variables are treated like references to any other build setting. However, references in environment variables are a special case: references in an environment variable cannot refer to any non-environment layer build setting. In this example, the COPYRIGHT_STATEMENT setting could not be defined solely as an environment setting. If it was, the $(YEARS) and $(COMPANY) references would only be substituted if there were YEAR and COMPANY settings in the environment layer as well. Any values for YEAR and COMPANY in any other layer would be ignored.

There's a special kind of build setting that creates an additional quasi-layer of settings: conditional build settings. A conditional build setting is keyed to some other combination of build settings. If those other build settings match a given pattern, it substitutes a different value for that setting. The general textual form for conditional build settings is:

BUILD_SETTING[condition=pattern] = value

This isn't a general-purpose mechanism. In fact, Xcode only recognizes three conditions and these conditions are only evaluated and passed to certain native build phases. The conditions that Xcode evaluates are:

The pattern portion of the condition is the name of the architecture, sdk, or variant. The pattern can include a "*" wildcard character to match groups of possible condition values. A setting can have multiple conditionals, as in SOME_SETTING[sdk=iphonesimulator*][variant=debug] = YES.

Consider the following build setting and variant:

GCC_USE_INDIRECT_FUNCTION_CALLS = NO
GCC_USE_INDIRECT_FUNCTION_CALLS[arch=ppc*] = YES

When the target is being built for any non-PowerPC architectures (Intel, Arm, and so on) the conditional build setting doesn't match the pattern and is ignored; in these cases GCC_USE_INDIRECT_FUNCTION_CALLS evaluates to NO. Whenever the target is compiled for any PowerPC architecture (ppc, ppc64, ppc7400, ppc970, and so on) the condition matches the pattern (ppc*) and the build setting evaluates to YES.

Logically, conditional build settings create another layer, immediately above the current layer, with alternate build settings that are only in scope when their condition patterns are satisfied. You cannot refer to conditional build settings in references; they're simply alternate settings that supersede the base setting under certain circumstances.

Conditional build settings cannot be used by custom build rules or Run Script phases. Furthermore, only those build settings that apply to native compilation phases can be made conditional.

The possible values for each condition change from release to release, but the Xcode build settings editor knows what they are and will let you choose them from a menu. If you want to know what patterns are available, take a peek by creating a conditional build setting — described later in the "Create a Conditional Build Setting" section — then look at the resulting build setting statement by copying it to the clipboard.

Variable build setting names are an alternative to conditional build settings. This works by using a build setting value as all, or part, of a build setting name. Consider the following build settings:

VALUE_FOR_COND_1 = YES
VALUE_FOR_COND_2 = NO
VALUE_FOR_COND_3 = MAYBE
MY_CONDITION = 2
MY_VALUE = $(VALUE_FOR_COND_$(MY_CONDITION))

Build setting values are evaluated recursively. The expression $(VALUE_FOR_COND_$(MY_CONDITION)) is first replaced with $(VALUE_FOR_COND_2), which then evaluates to NO. Thus, setting the MY_CONDITION setting to 2 ultimately causes MY_VALUE to be NO. Setting it to 3 would cause MY_VALUE to be MAYBE.

This isn't quite as flexible or sophisticated as using conditional build variables, but it works with all build settings. Using this technique, you can create a set of related build setting and then select one of them via the value of another setting.

Build settings are organized into groups to make it easier to find the settings you're looking for. You can filter out uninteresting settings by name or value by typing something into the search field. By default, the search field will match any setting's name, title, value, definition, or description. Use the search field's menu to limit the scope of the search, if necessary. For example, type "gar" into the search field to quickly locate the Objective-C Garbage Collection settings.

The Show menu can be set to one of three choices:

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 defined 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 redefine at this level.

To narrow your focus to just the build settings defined in this level, change the Show setting to Settings Defined at This Level. All of the inherited settings are hidden.

User-Defined Settings is the same as All Settings, but filters out all of the standard settings that Xcode knows about. The resulting display lists only custom build settings that you've defined. Again, the settings in bold are defined at this level and non-bold values are inherited from lower levels.

Every build setting has a name and an optional title. The name is the actual variable name defined 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-defined 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:

The first command toggles the Title column between displaying the title of the setting and its name, both shown in Figure 17-22.

Figure 17-22. FIGURE 17-22

The second command toggles the Value column between displaying the resolved value for the setting and its actual definition, as shown in Figure 17-23.

Figure 17-23. FIGURE 17-23

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.

When editing complex sets of interrelated build settings, it's sometimes difficult 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:

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.

Editing build settings values depends somewhat on the display mode, as explained in the earlier section "Viewing Names and Definitions." 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. FIGURE 17-24

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. 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 definitions 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 Figure 17-24 and Figure 17-25 being edited in their raw form.

Figure 17-26. FIGURE 17-26

Finally, there's an Edit Definition 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.

As mentioned earlier in the "Conditional Build Settings" section, certain build settings can be conditional. That is, they will take on different values under specific combinations of SDK and processor architecture.

To create a conditional build setting, select a build setting that's defined 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. FIGURE 17-27

The conditional setting is defined 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 configuration settings file, described later in this chapter.

To create a new build setting for your own purposes, simply choose the Add User-Defined 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.

Figure 17-28. FIGURE 17-28

The name cannot duplicate any existing build setting, and once created you can't rename it. To rename a user-defined 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.

Figure 17-29. FIGURE 17-29

To delete a build setting, select the setting in the list and choose the Delete Definition 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 definition of that build setting at this level. Build settings defined 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 defined 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 definition of a user-defined setting. Naturally, if you have the Info window set to show only settings defined at this level it will also disappear, but the setting still exists elsewhere.

Most of what's been discussed so far about editing and creating build settings has assumed that that you only have one build configuration. A project with three build configurations means that there are three sets of build settings for each target.

As mentioned earlier, you select the build configuration you are editing using the Configuration pop-up menu at the top of the Build tab. To edit the build settings for a particular configuration, select that configuration from the list. You can also select the Active (name) item. The Info window always shows and edits whatever the active build configuration is. Changing the build configuration using Project

One of the most useful views is the All Configurations view. When you select this view, the Build tab shows a composite view of all of the settings from all configurations. It does this the same way items in a multi-item Info window are displayed. Settings with values that are different between configurations 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 configurations. More importantly, when you are in this view, any change you make to a setting sets that value in every configuration of the target or project. This mode is extremely useful for setting project and target settings in multiple configurations simultaneously, but it also requires some care. You can easily overwrite settings that were created for a specific configuration. It is also easy to unintentionally create new build settings. In the All Configurations view, editing the value of a setting also creates that setting (with the same value) in every configuration that did not previously contain that setting. Similarly, deleting a setting in the All Configurations view deletes that setting from every configuration.

Create an empty configuration settings file and add it to your project by choosing the File

If you already have a configuration settings file that exists but hasn't been added to the project, simply add it to the project like any other source file. See Chapter 5 for a quick refresher on adding source files. Again, do not add the configuration settings file to any targets when adding it to the project. Configuration settings files are part of the build infrastructure; they are not the thing being built.

Use configuration settings files when you have a number of targets or projects that each need a uniform, or at least very similar, set of build settings. Configuration settings files are most useful when you have a large number of projects, targets, or build configurations, and maintaining common settings across all of those projects/targets/configurations becomes cumbersome.

Targets and projects can be based on a single configuration settings file. Configuration settings files cannot be linked to other configuration settings files, nested, or otherwise combined, so don't try to design a hierarchical structure of configuration settings files; it won't work. Configuration settings files are only an adjunct to the build settings layer hierarchy already defined by Xcode. Consider these best practices when creating configuration settings files:

Keep in mind the project or target can override anything defined in the settings file on which it is based. Settings files don't have to contain exactly the values needed by all of the targets, projects, or configurations that are based on it. They only need to define the preferred values for the settings you regularly set. Think of them as your own layer of defaults, much like Xcode's default settings layer.

The per-file compiler flags setting is a special place where the compilation of a single source file can be modified. These are literal command-line arguments, set for a particular source file and target, and passed to the compiler only when that source file is compiled. Each source file has a separate compiler flags setting for each target in the project, so you can specify one compiler flag when the file is being compiled for one target and a different compiler flag when it is compiled for another. There are no templates or documentation for these options in Xcode. You will need to consult the compiler's documentation to compose your argument list correctly.

Open the Info window for a source file. If the source belongs to the active target, a Build tab appears in the Info window, as shown in Figure 17-33. You can only edit the compiler flags for the active target. To edit the compiler flags for a different target, you must close the Info window, choose a new active target using the Project

Figure 17-33. FIGURE 17-33

Per-file compiler flags are like build settings in that they have a specific scope; they are only passed to the compiler when that specific file is being compiled for a specific target. In terms of customizing the build process to your needs, compiler flags can be thought of as the very highest layer of build settings, overriding even the compiler settings in the command-line layer. Just keep in mind that compiler flags settings are not part of the build settings architecture: they are not named variables, cannot refer to other build settings, are not added to the execution environment, and are not accessible to build scripts or external processes. They are a feature supplied by the Compile Sources phase as one more way of fine-tuning the build process.

Personally, I try to avoid per-file compiler flags when possible. It's an obscure feature that's difficult to document and correlate to the source file. These per-file compiler flags are stored in the project document as part of source item, which presents another potential problem; removing the source item or adding the file to another project will discard its settings.

Today, many compiler options can be specified in the source file itself using #pragma, __attribute__, and other compiler-specific syntax. My first choice would be set any module-specific compiler options in the source file, and use per-file compiler flags only as a last resort.

In Xcode, cross-development refers to developing a program for use in one or more different versions of Mac OS X. It does not mean cross-platform development, or writing a program that runs on a multitude of different operating systems or architectures. Cross-development allows you to produce a program that runs on a specific range of operating system versions (Mac OS X 10.3.4 through Mac OS X 10.5.0, for example). You can also produce applications that run only on a specific version or an application that will run on any version that supports the features it requires.

Installing Cross-Development SDKs

Before you can even think about doing cross-development, you have to install the cross-development SDKs. The standard Xcode Developer Tools installation includes recent cross-development SDKs, but SDKs for older operating systems may be optional installs, as shown in Figure 17-34. If you did not install the SDKs when you installed Xcode, quit Xcode and run the latest Development Tools installer again. At the Custom Install screen, choose the optional Cross-Development support package or packages.

Figure 17-34. FIGURE 17-34

To use cross-development, you need to choose two boundaries: the earliest version of the operating system that your application can run on, and the latest version of the OS that it utilizes.

Choosing a Target SDK

The latest OS version that your project uses is called the Target SDK. For example, you might be writing and developing your application using Mac OS X 10.6, but your application only uses features and APIs that were present in Mac OS X 10.5, which should allow it run smoothly on both. In this situation, your target SDK should be set to Mac OS X 10.5. The Target SDK setting is set for the entire project in the project's Info window, as shown in Figure 17-35. You can set it using the Base SDK build setting for individual build configurations, or use the General tab to set it for all configurations, as shown at the bottom of Figure 17-35.

Figure 17-35. FIGURE 17-35

When you set the target SDK, the compiler and linker will fail if you refer to symbols, functions, or types that did not exist when that version of the operating system was released. Understand that this in no way prevents your application from running on later versions of the operating system.

It simply means that Xcode compiles your source code using the headers and frameworks defined by an older version of the OS. This ensures that you're unlikely to use any newer APIs or constants that might cause your application to fail when run on an older OS. There may be other reasons it won't run, but the Target SDK isn't one of them.

Warning

It should be noted that the iPhone provides two target SDKs for each major release of the iPhone OS: a native device SDK and a companion simulator SDK. When you build your iPhone or iPod Touch application for the simulator, you're building your application using a different set of frameworks than those used by the actual device. Be aware that there are some subtle differences between the two, and you should thoroughly test all aspects of your application on a real iPhone or iPod.

Choosing a Deployment Target

The other boundary is the deployment target, set using the Mac OS X Deployment Target (MACOSX_DEPLOYMENT_TARGET) or iPhone OS Deployment Target (IPHONEOS_DEPLOYMENT_TARGET) build setting, as shown in Figure 17-36. This sets the earliest version of the operating system your application will successfully run on. Whereas the Target SDK setting is purely a build time setting, the Deployment Target setting is both a development setting and a run time setting. At build time, this setting flags certain framework and library references as weak. A weak library reference lets your application link to a function that was introduced in a later OS, but still load on an earlier system that lacks that function. (That doesn't mean you can successfully call that function in the legacy environment, it just means the program will load and start running without it.) This setting is also included in the Info.plist of your application bundle and tells the operating system not to allow your application to load if the minimum operating system requirement is not met. This may not have anything to do with what features your application uses; maybe you have simply never tested your application on Mac OS X version 10.4 and you don't want anyone else trying.

Figure 17-36. FIGURE 17-36

Both of these boundaries have defaults that are set for new projects. The default for the Target SDK is Current OS. In other words, it compiles and links using the operating system frameworks and libraries currently installed on your development system. The default for the Deployment Target is Compiler Default, which really means "none." The operating system will do its best to load and link your application to the available APIs at run time. Your application will fail to load if it has "hard" links to APIs that don't exist.

#include <Carbon/Carbon.h>

Prior to 2004, Xcode only produced PowerPC executable binaries. That's because this was the only processor architecture that Mac OS X supported. Since then, Apple Computer has added two new architectures to its OS pantheon (64-bit PowerPC, Intel 32- and 62-bit), along with new processors (ARM) for its consumer lines of iPhone and iPod Touch products. Xcode can compile your program for any or all of these architectures when you build your project. It does so by repeatedly compiling your application, once for each architecture, and then storing all of the resulting versions in a single multi-architecture binary (MAB) file — a file format that Mac OS X has supported for a long time. Binaries that contain executable code for multiple architectures are referred to as Universal Binaries.

Build settings, like so many other details in software development, are easy to find — as long as you already know where to look. The catch-22 occurs when you're trying to find something and don't know what it is or where to find it. The following sections highlight hand-selected build settings that you should be familiar with, or are notoriously difficult to find in the documentation.

When listing Xcode-defined build settings, this book uses the form "Full Title (NAME)" to describe each setting. Use its title when you're looking for a setting in the Xcode documentation. Use its name when referring to build settings in scripts or in build-setting value expressions. Remember that copying a build setting will place its definition (NAME=value) on the clipboard.

Browsing the build settings in the Build tab of the target or project can be very instructional. The major build settings are described here. If you see a build setting that's not covered in this chapter, search the Xcode documentation for its name. The Xcode release notes cover most new and existing build settings. There is also a Build Setting Reference document included in the Xcode documentation that describes many of these same settings.

#ifdef __OBJC__
 #import <Cocoa/Cocoa.h>
#endif

To use the xcodebuild tool, the working directory must be set to the project folder. The tool does not accept a path to a project folder or document elsewhere. When you execute xcodebuild, you can optionally specify the name of the project, the target, and the build configuration to be built as arguments. If any are omitted, xcodebuild will choose a project, target, and build configuration for you.

A project name can be specified using the -project projectname argument. This name is the complete filename of the project document, including its extension. If this argument is absent, xcodebuild finds and builds the one and only project document in the folder. If there is more than one project, xcodebuild throws an error and stops. This argument is only needed for project folders that have multiple project documents.

You can choose a target using the -target targetname argument. If this argument is omitted, the first target defined in the project is built. For projects you intend to build using xcodebuild, arrange your targets so that your top-level aggregate target is the first target in the Targets group. That way, you don't have to specify a target for your most common builds. Alternatively, you can use either the -activetarget or -alltargets switch. The -activetarget switch builds the last active target set in the Xcode application. The -alltargets switch builds all of the targets in your project; something you can't do in Xcode, except for clean builds.

The -configuration configurationname switch selects a build configuration to use. You can specify the build configuration or use the -activeconfiguration switch instead. These switches select either the named build configuration or the last active build configuration set in the Xcode application. If both are omitted, the default build configuration is used. Go to the Configurations tab of the project's Info window to set the default build configuration for your project.

Two additional arguments are used to modify the build. The first is the build action. This can be one of the values described in the following table.

If you don't specify any action, build is assumed. You can specify more than one action. The actions will be executed in order, just as if you had invoked the xcodebuild tool multiple times. For example, xcodebuild clean build first runs a clean build followed by a normal build.

You can also pass build settings to the xcodebuild tool using the following guidelines:

The following listing shows xcodebuild being passed two build settings: DSTROOT and DEPLOYMENT_LOCATION:

xcodebuild DSTROOT=/ DEPLOYMENT_LOCATION=YES install

There are many other miscellaneous xcodebuild options. Three you might be interested in are listed in the following table:

xcodebuild is capable of building .xcodeproj (Xcode 2.1 and later) documents as well as earlier .xcode project documents. If you run xcodebuild without specifying a project document name, it first searches for an .xcodeproj document and reads that if found. If there are no .xcodeproj documents present, it looks for an .xcode document. In the latter case, xcodebuild internally upgrades the .xcode document, turning it into an .xcodeproj document, and then builds using that .xcodeproj document. The intermediate .xcodeproj document exists only in memory, and is discarded once the build is complete.

In order to share your computer — offer to compile files for other developers — you must first unlock the padlock in the lower-left corner. You are asked to supply an administrator username and password. Authenticating as an administrator allows Xcode to install the background services that provide distributed building.

Check the box next to the Share My Computer for Shared Workgroup Builds option to make this computer available on the network to perform builds for other developers. The pop-up menu next to the option allows you to choose a process priority for the distributed build process. If you regularly perform time-sensitive, CPU-intensive, tasks such as multi-media processing, you might consider setting this to medium or low priority. Lowering the priority also gives local builds an edge over builds for other developers. Remember that process priority only comes into play when two or more processes are competing to use the CPU. If the computer is idle, it doesn't matter what the priority is; the build will use all of the available CPU time.

In the lower portion of the pane is a list of computers you can distribute builds to. Available computers are organized into sets, listed on the left. The Bonjour set is a smart set that lists all active build providers on the local subnet. This set is assembled using the Bonjour (ZeroConfig) protocol, and automatically adjusts to reflect the available build providers on the local subnet. For most installations, this is the only set you will need.

The computers in the list display their status and suitability. The Host column contains the IP address of the system. The OS and Resources columns list the versions of the provider's operating system and compilers. You can only distribute a build to a computer with the same version of OS and compiler. The compiler in question will be the compiler required by the target being built. In the example in Figure 17-38, the computer marchhare.local has a compatible version of gcc 4.0.1, but an incompatible version of gcc 4.2.1. This computer could accept builds for targets that use the gcc 4.0.1 compiler, but not ones that required gcc 4.2.1. The computer mini.local, on the other hand, is running an older operating system and cannot accept any builds. Incompatible computers, tools, and Xcode installations are listed in red.

If you want to limit the distribution of builds to a specific subset of local computers, or if you want to add computers that do not appear in the Bonjour list, you need to create a custom set. Click the + button below the list of sets to create a new set, and then give the set a name. You can also duplicate an existing set. Selecting a set, or sets, lists only the computers in those sets. The list is always a union of the sets selected, so computers in multiple sets are listed only once. To delete a set, select it and click the – button. You cannot delete the Bonjour set.

To add a computer to a custom set, either drag a computer from the list into the set, or click the + button below the list with that set selected. Enter the address of the new system, using either a domain name or a numeric address. Xcode adds the new system to every set currently selected and automatically queries the system to discover its status and suitability. To remove a computer from a set, select it in the list and click the – button. You cannot add or remove computers from the Bonjour set. Consequently, having the Bonjour set selected disables both the add and remove buttons for all sets. To add or remove computers from the list, select only custom sets.

To distribute your builds to other computers, check the box next to Distribute Building Via Shared Workgroup Builds, and then check the box next to each set that you want Xcode to include in distributed builds. The computers in all of the checked sets will be considered when Xcode distributes builds to other computers.

That's all there is to it. If you've elected to distribute your builds with other computers, your next build will employ distributed building. Figure 17-39 shows the build of a large project on a laptop computer. Normally, it would only compile one or two files at a time, but with distributed building, it can now compile a score of files simultaneously by exploiting the other computer systems in its workgroup.

Figure 17-39. FIGURE 17-39