Run Your App

To build and run your iOS or Mac app, choose a scheme and a run destination in the workspace toolbar, and click the Run button. Clicking the Stop button causes your app to quit.

../art/SchemeMenuWithCallouts_2x.png

If you are running an iOS app, Xcode launches it either in iOS Simulator or on an iOS device connected to your Mac. If you are running a Mac app, Xcode launches it directly on your Mac.

Choose a Scheme to Build Your App

A scheme is a collection of settings that specify the targets to build for a project, the build configuration to use, and the executable environment to use when the product is launched. When you open an existing project (or create a new one), Xcode automatically creates a scheme for each target. The default scheme is named after your project and includes settings to perform five actions:

Each action includes building the app as an executable product. To choose the scheme, use the Scheme menu in the Xcode workspace toolbar. (You’ll use the Scheme menu to choose a destination, too.)

Choose a Destination to Run Your App

When you build an app, the destination determines where the app runs after it’s built. For Mac apps, the destination is the Mac on which the app is built. For iOS apps, the destination can be a provisioned iOS device connected to the Mac, or iOS Simulator. Installed as part of the Xcode tools along with the iOS SDK, iOS Simulator runs on your Mac and simulates an iPhone or iPad environment.

../art/SchemeMenu_2x.png

The Scheme menu lets you select a combination of scheme and destination, but the two settings are distinct. A scheme does not include a destination. In the screenshot above, Adventure iOS is selected as the scheme, and the iPhone Retina (4-inch) simulation environment is selected as the destination. As a result, the Adventure iOS scheme builds an iOS executable that runs on a simulated iPhone in OS Simulator. As shown below, the same scheme could be used to run the app on a different destination, such as a simulated iPad or a connected iOS device.

../art/NewRunDestination_2x.png

Run Your App

Click the Run button in the workspace toolbar to compile, link, and execute your code. If the app builds successfully, Xcode runs it and starts a debugging session.

Depending on your destination, Xcode launches your iOS app either in iOS Simulator or on a connected iOS device.

../art/AdventureLaunchediPhone_2x.png

Xcode launches a Mac app on your development Mac.

../art/AdventureLaunchedMac_2x.png

Xcode displays any errors or warnings it encounters in the issue navigator, available by clicking ../art/XG_NavArea_Issue_icon_2x.png in the navigator selector bar. If there are errors during the compilation or link phase, Xcode doesn’t run your code.

Run Your App in iOS Simulator

iOS Simulator enables you to simulate several iPhone and iPad devices and several versions of the iOS operating system. You interact with iOS Simulator by using the keyboard and trackpad to emulate taps, device rotation, and other actions. For example, you can use the Hardware menu in iOS Simulator to:

  • Rotate the simulator to the left and right

  • Simulate a user shaking the device

  • Send the frontmost app a simulated low-memory warning

As a preliminary tool for use before testing your app on devices, iOS Simulator allows you to prototype and test builds of your iOS app during the development process. Although you can test your app’s basic behavior in iOS Simulator, the simulator is limited as a test platform. Therefore while developing your app, it is essential that you run and test it on connected iOS devices.

Run Your App on a Connected Device

To run your iOS app on a device (an iPad, iPhone, or iPod touch) during development, the device must be connected to your Mac, and the device must be provisioned for development by Apple. If your Mac app uses certain Apple technologies—such as iCloud, Game Center, and In-App Purchase—your Mac must be provisioned.

Apple implements an underlying security model to protect user data and to protect your app from being modified and distributed without your knowledge. Throughout the development process, you create assets and enter information that Apple uses to verify the identify of you, your devices, and your apps. These assets include provisioning profiles, which identify your development devices.

To obtain a provisioning profile for a device, you need an Apple Developer Program membership.

Add an Apple Developer Program Account to Xcode

If you’re not already a member, you can join an Apple developer program in Xcode. To join, choose Xcode > Preferences, and click Accounts. Click the Add button (+) in the lower-left corner, and select Add Apple ID from the pop-up menu. Click “Join a Program” in the lower-left corner of the dialog.

../art/JoinProgramButton_2x.png../art/JoinProgramButton_2x.png

Your default browser displays the Apple Developer Programs enrollment webpage. In your browser, click the developer program you want to join and follow the instructions.

If you’re already a member of an Apple developer program, add your account to Xcode. Choose Xcode > Preferences, and click Accounts. Click the Add button (+) in the lower-left corner, and select Add Apple ID from the pop-up menu. Enter your credentials, and click Add.

If you're developing a Mac app, Xcode then automatically provisions the Mac that’s running Xcode. If you’re developing an iOS app, you need to provision the devices that you’ll run and test your app on during development.

Provision an iOS Device for Development

To provision an iOS device in Xcode, choose Window > Organizer, and click Devices to display the Devices organizer. For an iOS app, connect your device to your Mac. In the Devices section of the Devices organizer, select your device. Click the “Use for Development” button (or if the device was previously used for development, click the “Add to Member Center” button). Select the checkbox next to your Apple developer program account name, and click Choose.

../art/5_addtoportal.png

Choose Your Device for the Run Destination

After provisioning your device for development, tell Xcode to launch your app on the device. When you plug the device into your Mac, the device’s name and the iOS release it’s running appear as a destination in the Scheme menu. Choose your device as the destination, and then click the Run button to build and run your app on the device.

Edit, Create, and Manage Schemes

To edit a scheme, choose Edit Scheme from the Scheme menu. The left column of the scheme configuration dialog lists the actions that the scheme can perform. You can modify settings for each action. In the screenshot, the Run action is modified to simulate the location of Mexico City when Xcode launches the app.

../art/EditSchemeDialog_2x.png../art/EditSchemeDialog_2x.png

You can edit a scheme so that it performs such actions as:

A convenient way to create a new scheme is to click the Duplicate Scheme button. This button uses the active scheme as a template for you to rename, edit, and save.

If you create schemes, you can manage them by clicking the Manage Schemes button in the scheme configuration dialog or by choosing Manage Schemes from the Scheme menu. You can rename or reorganize how schemes appear in the Scheme menu. You can also specify whether a scheme should be displayed in the menu, where a scheme is stored in the project or workspace, and whether a scheme should be shared, such as with team members accessing a project from a source code repository. You can click the Autocreate Schemes Now button to make Xcode create schemes for any targets that don’t have them.

Step-by-step instructions for creating, editing, and managing schemes are available by Control-clicking anywhere in the scheme configuration dialog.

../art/SchemeHelp_2x.png../art/SchemeHelp_2x.png