Build and Run Your App

Create, Edit, and Manage Schemes

In Xcode, before you build, you select a scheme, which specifies which targets to build, what build configuration to use, and the executable environment to use when the product specified by the target is launched. You also select a run destination. When you create a new Mac OS X project, Xcode provides a default scheme and two run destinations: local 32-bit and local 64-bit. For an iOS application, the run destinations are devices and simulators.

You can add as many additional schemes as you want. For example, you might want one scheme that builds both your application and a plug-in before running, and another that builds the product without the plug-in. Or if you have two different but commonly used Instruments templates, you might have one scheme for profiling with one of the templates and a different scheme for the other one.

You use the Scheme pop-up menu in the upper-left corner of the workspace window (Figure 6-1) to select a scheme and run destination. Choose the scheme you want to edit and then choose Edit Active Scheme from that menu to edit an existing scheme. Choose Manage Schemes to change the list of schemes, where they’re stored, and whether they’re shared. Choose New Scheme to add a scheme to your project. Alternatively, you can choose Edit Scheme, New Scheme, or Manage Schemes from the Product menu.

The left column of the scheme editing dialog (referred to hereafter for brevity’s sake as the scheme editor) has a list of actions you can perform, plus the Build item, which you use to determine which targets are built for each type of action. Each action can be set to produce either a debug or release build (or, if you’ve added more build configurations, those are listed as well). There are options for building, running, testing, profiling (using Instruments), analyzing, and archiving your products.

You can execute scripts and have Xcode send emails before or after a build or any of the actions in the scheme editor.

To set up pre- or post-actions

1. In the scheme editor, open the disclosure triangle next to Build or any of the actions in the left pane.

2. Click the Add button at the bottom of the right pane and choose New Run Script Action or New Send Email Action.

3. In the template that opens, fill in the fields.

   The figure shows two pre-run actions: an email that’s sent and a script that’s executed before the product is launched.

   

4. For a Run Script pre-or post-action, if your script needs to access values from target build settings, choose the target from the “Provide build settings from” pop-up menu.

   

Specify Which Targets Are Built for Each Type of Action

By default, Xcode creates one scheme per target in your project or workspace, and the Targets column shows the target for which the scheme was created. However, you can add as many targets from your project or workspace to a single scheme as you wish.

Edit a scheme to determine which targets are built when you choose Run, Test, Profile, Analyze, or Archive from the Product menu.

To build multiple targets

 

Rename or Reorganize Your Schemes

By choosing Manage Schemes from the Product menu (or from the Scheme pop-up menu) you can see a list of all the schemes in the project. You can rename or reorganize the schemes in the menu. You can also specify whether each scheme should be displayed in the pop-up menu, where the scheme is stored (in the project or workspace) and whether the scheme should be shared with others using the project or workspace.

The Manage Schemes dialog has four settings for each scheme plus several other controls, as shown in “The manage schemes dialog.”

The four columns in the Manage Schemes dialog are used as follows:

Show	Displays or hides the scheme in the Scheme menu.
Scheme	Specifies the name of the scheme. You can edit this name.
Container	Specifies whether a scheme should be stored in a project—in which case it’s available in every workspace that includes that project—or in the workspace—in which case it’s available only in that workspace.
Shared	Specifies that the scheme is visible to anyone using that project or workspace (depending on where the scheme is stored). Be sure to check with other people using the project or workspace before deleting or modifying a shared scheme.

You can drag the schemes to reorder their appearance in the dialog and the Scheme menu.

The Add (+) button allows you to create a new scheme or duplicate the selected scheme. The Remove (–) button allows you to delete the selected scheme. The Action menu allows you to export the selected scheme or import an exported scheme.

The Edit button dismisses this dialog and displays the selected scheme in the scheme editor.

If the Autocreate schemes checkbox is selected, when you add a new target to your project, Xcode automatically creates a scheme for it. If the checkbox is not checked, then you can click the Autocreate Schemes Now button to have Xcode create new schemes for any targets that don’t have them.

Specify How to Build Your Product

Most developers can get by with the default build settings, except for the few that must be set—or at least checked—for every project (see “Set the Basic Product Settings”). You may have special needs, however, that require anything from tweaking a setting or two to creating an entirely new build configuration. To check or change build settings, click the project in the project navigator to open the project editor. Control-click in the left column of the project editor where the projects and targets are listed to see a list of project editor help topics.

You can edit build settings at the project or target levels. Most build settings have a system default. If you click Levels in the build settings header bar, Xcode shows you the resolved value for each build setting and indicates with green highlighting the level at which the value was set.

Customize aspects of your product’s build process by editing its build settings.

To edit a build setting

 

You can see documentation on a build setting in the Symbol inspector in the utility area.

Find concise documentation for a build setting using Quick Help.

To see documentation on a build setting

 

Control the Order in Which Xcode Builds Your Products

Xcode detects when one of your products is dependent on another and automatically builds them in the correct order. However, in the unusual event that you need to control the order in which Xcode builds your products, you can create explicit target dependencies by using the Build Phases pane of the project editor.

Ensure that targets are built in the proper order using target dependencies. In a complex project, you may have several targets that create related products. Frequently, these targets need to be built in a specific order.

To ensure products are built in the correct order

 

The Build Phases pane of the project editor also lets you specify the order in which files are compiled and linked, specify which bundle resources are copied and in what order, and so forth. You can drag the build phases into a different sequence if you wish, and you can drag the individual files in each build phase into whatever order you want. Doing so is advisable only if you have a good reason to do so and know exactly what you’re doing.

The Build-and-Run Workflow

This section describes each of the steps in the build-and-run workflow.

Specifying the Buildtime Environment

When you build your app, Xcode uses a build environment made up of frameworks, libraries, apps, command-line tools, and other resources. Each revision of the iOS SDK makes improvements to this environment to, for example, add user-interface features or improve compilers and resource-processing tools. In addition to these resources, you can specify whether you want to build your app to debug it or to distribute it to customers. This section describes how to set your build-time environment.

Setting the SDK Used to Build Your App

One of the main factors that determine how Xcode builds your app is the SDK used to build it.

To specify the SDK to use to build your app, set the Base SDK build setting to the appropriate SDK.

Base SDK Missing

If your project has its Base SDK setting set to a particular iOS SDK release, when you open that project with a later Xcode toolset distribution in which that SDK release is not available, the Base SDK setting has no valid value. In this case, the issue navigator lists a Missing SDK issue, as shown in “Create User Interface Classes.” To fix the Missing SDK issue, set the base SDK for the target to an available SDK release or to Latest iOS.

Setting Your Code Signing Identity

When you build your app to run it on a device, Xcode signs it with a development certificate (also known as a code signing identity) stored on your keychain. To learn how to obtain and install development certificates, see “Provisioning a Device for Development.”

The Code Signing Identity build setting specifies the provisioning profile and code signing identity Xcode uses to sign your binary. Xcode looks for code signing identities in your default keychain.

The possible values for the Code Signing Identity build setting are:

• Don’t Code Sign. Choose this option to build only for a simulator.

• Automatic Profile Selector. Choose an option under this selector to select a provisioning profile whose name starts with “iPhone Developer” or “iPhone Distribution.”

• Specific Profile. Choose the code-signing identity under a specific provisioning profile when your app requires special entitlements. Expired or otherwise invalid provisioning profiles are dimmed and cannot be used.

  Figure 4-3 shows a set of options for the Code Signing Identity build setting with a provisioning profile for specialized development selected.

  

Project templates are configured to use the automatic selector to set the signing identity. You need to change the value of the Code Signing Identity build setting only when your app uses a specialized provisioning profile. See App Distribution Guide for details on using specialized provisioning profiles.

Specifying the Runtime Environment

Three aspects of your app’s runtime environment are: where your app runs, what app-data is placed in its sandbox, and what location or track the Core Location framework reports to it.

Specifying the Run Destination

Before building your app, Xcode has to know where you want to run it. You specify this run destination in the Scheme toolbar menu. Using that menu you can switch from running your app in a simulator to running it on your device to, for example, test the device performance of your app.

When you plug into your Mac a device with a valid provisioning profile, its name and the iOS version it’s running appear as an option in the Scheme toolbar menu. Use the menu to switch between running your app on a device or in a simulator.

Specifying the App Data

The Run action in a scheme determines the app data Xcode places in your app’s sandbox before running it. Using a particular app-data archive is particularly useful in application unit tests, which check for the correct operation of critical units of code in your application. Basing your tests on a known data set allows you perform detailed unit tests without having to configure the test data in the tests themselves.

To specify the app data to place in the app’s sandbox before the app runs:

1. From the Scheme toolbar menu, choose the scheme you want to use.

2. Select the Run action.

3. From the Application Data pop-up menu, choose the app-data archive you want to use.

Specifying a Location or Track

To test a location-based app, you can specify a location or a track the run destination reports to the app when it launches and as it runs.

A GPS eXhange Format (GPX) file specifies a single location (a single waypoint) or a track (an ordered collection of waypoints). When you simulate track, the simulator or the device reports the waypoints in the order they are specified in the track.

To make a GPX file available for use in your project, add it to the project, or add a new GPX file to the project and specify the location or track details.

Customize Your Build and Run Workflow

You can specify behaviors that affect your build and run workflow through the Xcode Behaviors preferences. The Behaviors preferences pane lets you specify what should happen when a variety of events occur (“Behaviors preferences”)—including, but not limited to, scheme actions.

For example, you can have Xcode display the debug area when your code pauses at a breakpoint, or Xcode can display the issue navigator when a build fails. If you are searching for text or a symbol name in a large project, you can set preferences to let you know when the search has completed, either with or without results.

You can name a tab and specify that tab as the display to use when an event occurs. Then you can set up the display in that tab exactly as you want it. If the tab doesn’t exist when the alert is triggered, Xcode creates the tab for you, set up as it was when you created it. For example, in “Behaviors preferences,” Xcode is configured to play a sound and open a tab named SketchDebug when the run pauses (such as when a breakpoint is triggered). The tab will have the debug area and debug navigator open. If you configure the tab to include an assistant editor and to display the debug area with the log pane closed, then every time a breakpoint is triggered, a tab named SketchDebug opens with those characteristics.

To name a tab

• To give a custom name to a tab, double-click the title of the tab and type the new name.

  Tab names are case sensitive in the Show Tab field of the Behaviors preferences.

  

Xcode remembers the state of the named tab—including which window it was in—when it reopens the tab. By naming a tab in a separate window, you can use the “Show tab” option in Behaviors preferences to automatically open a new window.

To automatically open a new window

1. Open and name a new tab.

2. Drag the tab out of the workspace window to create a new window.

   

3. Set up the new window exactly as you want it.

4. In Behaviors preferences, select the event for which you want the new window to open.

5. For that event, select the Show tab checkbox and type the name of the tab.

You can also can design custom behaviors that are triggered by menu items or their key equivalents.

To create a custom behavior

1. In the Behaviors preferences pane, click the plus button at the bottom of the left column.

2. type the name of the new behavior and press Return.

3. Select checkboxes to specify what should happen when you invoke this behavior.

   

For example, you can create a "Unit Testing" behavior that creates a snapshot and runs your unit tests. After you’ve created a behavior, it appears in the Xcode > Behaviors menu.

You can assign a key equivalent for each of your custom behaviors.

To assign a key equivalent to a custom behavior

1. In the Key Bindings preferences pane, select the Customized tab to find the behavior for which you want to assign a key equivalent.

   

2. Click the Key column on the line of the behavior in order to open a text field.

3. With the text field selected, press the keys you want to use for the key binding.

   

4. Click outside the text field to complete the operation.

Manage App Data in iOS Devices

When an app is first installed on a device or in a simulation environment, iOS creates a sandbox (also known as the app home directory) for it. As described in “File and Data Management” in iPhone Application Programming Guide, an iOS app can access only files that reside in its sandbox.

Xcode doesn’t remove app data as it reinstalls an app. But you may need to erase that information as part of testing your app the way users will use it. To do so, remove the app from the Home screen. See “Add Build Rules” for details.

You may also want to replace the app data in your app’s sandbox with a known configuration to test specific conditions, such as when performing application unit tests. The first step is to create an archive of the app data from a development device (you cannot generate app-data archives from simulators). Then you can change the app data on your Mac and copy it back to the device.

To access your app’s simulation-environment sandbox, navigate to the directory ~/Library/Application Support/iPhone Simulator/<sdk_version>/Applications in the Finder. Then open each directory in the Applications directory to find your app’s binary file. Alongside the binary file are the directories that make up your app’s sandbox, including Documents and Library.