Setting Default Build Locations

When you first start up Xcode, it asks you to specify the directories in which it places the files generated by the build system, both intermediate files and built products. These build locations are used for all new projects.

Each project can specify a value for its build products directory and intermediate build files directory. However, new projects defer to the default values for these settings, specified in Building preferences (see General Project Attributes). Therefore, setting custom build locations in Building preferences, sets the build locations for new projects. For example, to set shared build locations for all the projects you create, set those locations in Building preferences. And, for projects that don’t need to share those locations, you can customize their build location, as described in Setting Project-Specific Build Locations.

See Building Preferences for details.

Setting Project-Specific Build Locations

Each time you create a project, Xcode sets the build locations for that project to the default build locations specified in the Building pane of Xcode preferences. You can, however, override these default build locations on a per-project basis. By taking advantage of this feature, you can choose default build locations that works best for most of your projects, and specify other default build locations for individual projects as needed.

To override the default location for a project’s build products, use the build locations settings in the Project Info window.

• Place Build Products In. Sets the project’s build products directory.

• Place Intermediate Build Files In. Sets the project’s intermediate build files directory.

To learn how to change the default build location used for projects that you create, see Setting Default Build Locations.

Viewing Build Settings

You can view and edit build settings at the target and project levels in the Build pane of the Info window for targets and projects. Figure 8-1 shows the Build pane for a target.

These are the components of the Build pane:

• Configuration menu. The Configuration pop-up menu indicates which of the target’s build configurations is currently displayed. Choosing Active from this menu displays the build settings defined for the active build configuration; for more information, see Build Configuration Overview. The build settings defined for the active configuration appear in the build settings table.

• Search field. The search field lets you search the build settings table for a keyword or other text string. As you type, Xcode filters the list to include only those build settings that match the text in the search field. For example, you can find all build settings related to search paths by typing search.

• Show menu. The Show pop-up menu lets you filter the list of build settings shown in the build settings table.

• Build settings table. The build settings table contains two columns:

  • Title. The Title column shows build setting titles, which are brief English-language descriptions for the build settings. You can display build setting names instead by Control-clicking anywhere in the table and choosing Show Setting Names from the shortcut menu.

    If you know the title of the build setting you are looking for and keyboard focus is in the build settings table, you can simply start typing the build setting name to select that build setting.

  • Value. The Value column shows build setting values. You can display build setting specifications by Control-clicking anywhere in the table and choosing Show Definitions from the shortcut menu.

• Action menu. The action menu lets you add or remove build setting specifications, including conditional build setting specifications.

• Research Assistant button. The Research Assistant button opens the Research Assistant, which displays information about the build setting selected in the build settings table. To learn more about the Research Assistant, see Using the Research Assistant.

• Based On menu. The Based On menu specifies the build configuration file upon which the active build configuration is based. (When the project contains no configuration files, this pop-up menu is dimmed.) When you base a build configuration on a configuration file, Xcode sets the default specifications of the build settings in the build configuration to the corresponding specifications in the configuration file.

You can modify build settings for multiple configurations of a target at once; to do so, choose All Configurations from the Configuration menu, as described in Managing Build Configurations.

You can also modify build settings in multiple targets at once; the build settings table supports multiple selection. To edit build settings for more than one target at a time, select those targets in the project window and open an Info window.

The build settings table supports copy and paste, as well as drag and drop, of build settings. If you have already configured a group of settings for a target, you can reuse them by selecting those build settings and dragging them into a text file, or by copying and pasting them between Info windows.

For a list of the available build settings, see Xcode Build System Guide.

Editing Build Setting Specifications

The interface for modifying a build setting’s specification in the build settings editor varies according to the possible values for that build setting. Depending on the value, Xcode may display, for example, a text field, a table, a checkbox, or a pop-up menu. This list describes the interface to edit the possible build setting value data types:

• String. If a build setting takes a string as its value, double-click the Value cell to edit it.

  If you are entering a file path, you can simply drag the file or folder from the Finder into the text field.

• List. If a build setting can have a list of items as its value, the Value column displays the value as a space-separated list. You can add or remove items from a lis of values by double-clicking anywhere in the row and using the plus and minus buttons in the dialog that appears.

  If you are entering file paths, you can simply drag the file or folder from the Finder into the list, instead of typing the paths in yourself.

• Boolean. If a build setting can have two states—on or off—the Value cell contains a checkbox. A checkmark indicates that the build setting is turned on.

• Choice. If a build setting has a finite number of possible values, the build setting’s Value cell contains a pop-up menu with the possible values.

  For some build settings, in addition to the standard values shown in the value pop-up menu, you may specify a custom value by choosing Other from the value list.

  

Adding and Deleting Build Settings

If you do not see the build setting you want to modify, or if you want to define custom build settings, you can add build settings to the build settings table in the Build pane of the Info window for a target or project.

To add a build setting definition to a target or project, choose Add User-Defined Setting from the Action menu in the bottom-left corner of the window.

To remove a build setting from a target or project, select the build setting definition to remove and choose Delete Definition at This Level from the Action menu.

If the build setting definition that you deleted is defined at a lower layer, Xcode continues to display that build setting in the build settings table. However, Xcode displays the build setting in nonbold text, indicating that it’s defined elsewhere.

Editing Conditional Build Settings

Conditional build settings let you specify the conditions under which you want particular build setting specifications to apply. For example, when building using a particular SDK or for a particular platform. For details, see Conditional Build Settings.

To add a conditional build setting definition:

1. In the build settings table, select the build setting to which you want to add a conditional definition. See Viewing Build Settings for details on how to find the appropriate build setting.

2. From the Action menu, choose Add Build Setting Condition.

   The build setting conditions appear below the build setting, as shown in Figure 8-2.

   

3. From the Any SDK and Any Architecture pop-up menus, choose the conditions under which you want the build setting specification to apply.

   For example, if you want the build setting to apply to any architecture and any release of the iOS Device SDK, choose “Any iOS Device” from the Any SDK pop-up menu (Figure 8-3). To specify a particular release of the iOS SDK—for example, the one for iOS 2.2—choose “Simulator - iOS 2.0.”

   

Editing Build Settings for Legacy and External Targets

You cannot configure build information for Jam-based Project Builder targets and external targets in the build settings table. To edit the build settings for Jam-based and external targets in Xcode, select the target in the Groups & Files list. If you have a text editor open in the project window, Xcode displays the Project Builder target editor. To view this target editor in a separate window, double-click the target.

On the left side of the External Target Info window (shown in Figure 8-4), Xcode displays a number of groups of target settings appropriate for the current target. Selecting any of these groups displays its settings in the editor on the right side of the Info window.

To view the build settings for an external target, select the Custom Build Settings group. To view the build settings for a legacy Project Builder target, select the Custom Build Settings item in the Settings group. The target editor displays a table of build settings:

• The Name column contains the build setting name.

• The Value column contains the build setting specification.

You can add and delete build settings using the plus (+) and minus (-) buttons below the table. To edit a build setting, double-click in the appropriate column and type the build setting name or specification. The target editor for legacy targets also includes a simpler interface for a number of common build settings in the Simple View.

Setting Build Factors

Before you start a build task, you should ensure that the build factors are set appropriately. A build factor is a setting that defines a particular aspect of a build. There are five build factors:

• Active target. Identifies the target (and dependent targets) that’s built when you execute the Build command. See Targets for details.

• Active SDK. Specifies the build environment, which includes the core and additional frameworks and libraries against which the targets’ source code is compiled and the command-line tools used to build the product.

• Active configuration. Specifies the build configuration to use when building the active target and its dependent targets. See Build Configuration Overview.

• Active architecture. Specifies the architecture for which the product is built, such as i386, x86_64, or ArmV6.

• Active executable. Specifies the executable environment to use for running the product after it’s built successfully. See Setting the Active Executable for details.

You can set a project’s build factors (except the active SDK) using the Project menu or the Overview toolbar menu.

Building a Target

After setting the active target and build configuration, you’re ready to build the target’s product. In a build, the target being built is known as the current target. The first time you build a target, the build system creates all the intermediate files, such as object files, needed to build the product. In subsequent builds of the same target, the build system processes only the files that have changed since the target’s previous build. For example, if the only change to the target since the last time it was built was a minor edit to a single source code file, the build system recompiles that file and relinks the object files to create the finished product. That is, changes to the contents of the file and changes to build settings that affect the way a source file is built cause the build system to rebuild the file.

To build the active target, execute one of the following commands from the Build menu:

• Build. Builds the target.

• Build and Analyze. Builds the target and performs static analysis on the target’s source files. For more information about static analysis, see Analyzing Code.

• Build and Run. Builds the target and launches the built product.

• Build and Run – Breakpoints Off. Builds the target and launches the built product with its breakpoints turned off. Execution continues through breakpoints.

• Build and Debug – Breakpoints On. Builds the target and launches the built product with its breakpoints turned on. Execution stops when the first active breakpoint is reached.

You may also build targets individually, regardless of which is the active target, by choosing the appropriate build command from the target shortcut menu in the Groups & Files list.

Xcode builds the current target in two major stages:

• Target dependencies. The build system builds the targets on which the current target depends.

• Build phases. The build system processes the current target’s build phases.

Building a target produces build messages, which include errors, warnings, and static-analyzer messages. See Viewing Build Results for information on how to view build messages, and how to address errors and warnings.

If your product does not build properly and there are no error messages, make sure your files have correct dates. Files with invalid dates (that is, dates before 1970) won’t compile correctly.

Viewing Preprocessor Output

You can see the preprocessor output for a C, C++, or Objective-C source files in the active target. To do so, select the files and choose Build > Preprocess.

Preprocessor output can also identify the #define directives (including predefined macros) in effect for a target’s source files. To include these directives, add -dM to the Other C Flags (OTHER_CFLAGS) build setting. For more information on the C preprocessor, see GNU C 4.0 Preprocessor User Guide.

Compiling Files

A full build can take a long time if you build target with many source files. You can compile a subset of a target’s source files to ensure that they build correctly without having to build the entire target. To compile a set of target files:

1. Select the target files (they must be part of the active target).

2. Choose Build > Compile.

Viewing Assembly Code

To see the assembly code output by the compiler for a source code file, select that file and choose Build > Show Assembly Code. Xcode compiles the file, and any additional files required to build it, and displays the assembly code generated by the compiler in an editor. You show assembly code for multiple files by selecting them in the project window.

Removing Build Products and Intermediate Build Files

As you learned in Building a Target, after the initial build of a target, the build system performs only those actions required to update changed files during subsequent builds. You can, however, force Xcode to do a full rebuild of the target by cleaning that target and rebuilding.

When you clean a target, the build system removes all the product files, as well as any object files (.o files) or other intermediate files created during the build process. The next time you build, every file in every build phase is processed according to the action associated with that phase.

To clean the active target, choose Build > Clean.

The Clean Target dialog appears. It contains two options:

• Also Clean Dependencies. Cleans the targets on which the target depends.

• Also Remove Precompiled Headers. Removes the precompiled header binaries used by the target.

To clean all targets in your project, choose Build > Clean All Targets.

Finding Header Files

All headers in your project are automatically accessible to your source code. You can also specify additional search paths at which to find headers using the Header Search Paths (HEADER_SEARCH_PATHS) build setting, described in Search Paths.

Note that you do not have to add headers to your target to include them in your source code. You should add header files to your target—as part of the Copy Header Files build phase—only if they are embedded in your product, as with a framework.

By default, Xcode searches user paths before system paths. This means that, by default, your project headers have precedence over system headers. Thus, if your project defines a header file named String.h, source code in your project that includes String.h incorporates your project’s version of the header, not the system version. You can override this behavior by turning off the Always Search User Paths (ALWAYS_SEARCH_USER_PATHS) build setting.

When Always Search User Paths is inactive, project headers can be incorporated into translation units only by surrounding the header filename with quotation marks. (A translation unit is a single source file with its imported/included files). (A translation unit is a source file with its imported/included header files.) For example, #include "String.h" incorporates the String.h header file defined in the project into generated translation unit. Furthermore, system headers can be incorporated into translation units only by surrounding the header filename with angle brackets. For example, #include <String.h> incorporates the String.h system header file into the generated translation unit.

Viewing Build Status

During a build, you want to see how that build is progressing. Especially for long build processes, it is useful to know the status of that process. Xcode displays the build status in the project window status bar. The status bar message lets you know the operation currently being performed. When the build is complete, Xcode displays the result of the build—namely, whether the build succeeded or failed and whether there were any errors or warnings—on the right side of the status bar.

You can click the build message in the status bar to see more detailed information about the build in the Build Results window. You can also click the progress indicator in the status bar during the course of the build to open the Activity Viewer, as described in Viewing the Progress of Tasks in Xcode.

In addition, Xcode displays a progress indicator that shows the status of the build in its Dock icon. If an error or warning occurs, Xcode indicates the number of errors or warnings with a red badge on the Dock icon.

Viewing Build Results

The Build Results window lets you see a more detailed account of the progress of a build. It shows each step of the build process, as well as the full output of the build system, and can take you directly to the source of any errors or warnings.

To open the build results viewer, choose Build > Build Results

Figure 8-7 shows the Build Results window.

These are the major user-interface elements of the Build Results window:

• Build results toolbar. The build results toolbar lets you specify the results you want to view.

• All Results button. Displays the results generated since the last clean was performed. Xcode remembers the results of multiple builds, which allows you to gauge your progress solving issues across several builds.

• Latest Results button. Displays the build results of the last build.

• By Step button. Displays the results by build operation. For example, each source-file compilation is a build step.

• By Issue button. Displays the results grouped by issue type when there are problems with the build, such as build errors and warnings, or static analyzer messages.

• Messages menu. The pop-up menu in the third section of the toolbar lets you filter the build results. Its options are:

  • All Messages. Displays all build results, which includes status messages, errors, warnings, and static-analyzer messages.

  • Issues Only. Displays errors, warnings, and static-analyzer messages.

  • Errors & Warnings Only. Displays errors and warnings.

  • Errors Only. Displays errors.

  • Analyzer Results Only. Displays static-analyzer messages.

• Build results. The build results pane build messages from the build system.

• Editor pane. The editor pane displays the file corresponding to the selected message in the build results pane.

To navigate through warning and error messages even when the Build Results window is hidden, use these commands:

• Build > Next Build Warning or Error

• Build > Previous Build Warning or Error

These commands select the next/previous error or warning in the Build Results window. They do not, however, bring the Build Results window forward if it is hidden. If you are working in the text editor, using these commands selects the line at which the error or warning occurred and opens the related file if it is not already open.

When viewing build results by step, you can display a step’s transcript by clicking the Show Transcript button (the button containing thin horizontal lines) on the right side of the build step. Figure 8-8 shows the transcript of a build step. To hide the transcript, click the Hide Transcript button (the button containing a triangle pointing up).

You can copy build transcripts to text files (such as an email messages) for further analysis:

• To copy a build-step transcript, select the build step and drag it to the desired location. Dragging a build step to the Desktop creates a text clipping.

• To copy the entire build transcript, choose Edit > Select All and drag the selection to the desired location.

Instead of dragging, you can use the Copy and Paste commands in the Edit menu to copy the transcript to the desired location.

Viewing Build Messages in the Text Editor

If you start a build from a text editor window, Xcode displays errors and warnings for the edited file directly in the editor. The text editor displays build messages as message bubbles (see Viewing Project Messages) next to the source code line that caused the problem, as shown in Figure 8-9.

To indicate whether to display build messages in the text editor and to specify the type of messages to display, use the View > Message Bubbles menu.

Building Projects Created with Early Versions of Xcode

The project file format, and the extension used for the project bundle, changed for Xcode 2.1. xcodebuild can build projects created by Xcode 2.0 or earlier (identified by the .xcode project bundle extension), as well as projects that have been upgraded. If the project directory contains both a .xcodeproj bundle and a .xcode bundle, xcodebuild uses the .xcodeproj bundle by default (to override this behavior use the xcodebuild -project option). If no .xcodeproj project package exists, xcodebuild opens the .xcode project package and creates an upgraded copy of it in memory. It uses this copy to build the project. The upgraded copy is not saved back to the file system.

Building with the xcodebuild Tool Versus with Xcode

When you build within Xcode, it uses the active target and build configuration; xcodebuild uses the first target in the project’s target list unless you specify a target (xcodebuild -target). You can specify which build configuration to use with the -configuration option. If you do not specify a build configuration, xcodebuild uses the target's default build configuration.

If you run xcodebuild as the root user, the preferences you set in Xcode preferences under another computer user are not used. Preferences are stored per user, and there are no preferences stored for the root user (unless you logged in as root and used Xcode at some point).