This document describes how to perform the workflows required to develop and publish your iOS apps, including running your app on development devices and sharing it with users for testing before publishing it on the App Store.
To run apps you’re developing on a device, you must set up the device for development. This process involves these main tasks, which you do in Xcode:
- Obtaining a developer certificate that allows you to sign apps
- Obtaining a provisioning profile that identifies your developer certificate, your device, and the applications you can run on the device
In preparing your device for development, Xcode creates or obtains the following digital assets:
- Certificate request. A certificate request (also known as a certificate signing request, or CSR) contains personal information used to generate your development certificate
- Development certificate. A development certificate identifies you as an app developer. When it’s stored in your keychain, it includes your private key. In your development team’s signing assets and in your provisioning profile, it includes only your public key. When Xcode builds your app for installation on a device, it looks for your developer certificate in your keychain. If it finds the certificate, Xcode signs your app. Otherwise, it reports a build error
- Provisioning profile. A provisioning profile associates one or more developer certificates and one or more devices with an app ID. To install applications signed with your developer certificate on a device, you must install at least one provisioning profile on the device. This provisioning profile must identify you (through your developer certificate) and your device (by listing its device identifier). If you’re part of a multimember iOS development team, other members of your team, if they have appropriately defined provisioning profiles, can run applications that you build on their devices.
Provisioning Your Device for Generic Development
For Administrators or the Team Agent:
- Choose Window > Organizer to open the Organizer window
- Click Devices to display the devices organizer
- Select Provisioning Profiles in the Library section
- Select the Automatic Device Provisioning option
- Plug in your device
- Select the device and click Use for Development
For Team Members
- Choose Window > Organizer to open the Organizer window
- Click Devices to display the devices organizer
- Plug in your device, and select it in the devices list
- Click Use for Development
- Copy your device identifier from the identifier text field
- Send a message containing your device identifier to your team agent requesting that of your device be added to the team’s list of devices
- Wait until the team agent tells you that the device has been added to the team’s devices list before continuing
- In the devices organizer, select Provisioning Profiles in the Library section, and click Refresh
- If you don’t have a developer certificate, Xcode offers to request one on your behalf:
- Have Xcode request the developer certificate for you
- Notify the team agent that Xcode requested a developer certificate for you
- Wait until the team agent tells you that your developer certificate has been issued before continuing
- Ensure that your device is plugged into your Mac, and that it’s listed in the devices organizer
- Select Provisioning Profiles in the Library section, and click Refresh
- Xcode installs your developer certificate in your keychain (if the certificate is not there already), and installs the team provisioning profile on your device
Setting Up Your Distribution-Only Assets
To distribute apps you need a distribution certificate and an distribution provisioning profile:
- Distribution certificate. A distribution certificate identifies your development team. When it’s stored in your keychain, it includes the team’s private key. In your team’s signing assets and in a distribution provisioning profile the distribution certificate includes only the team’s public key
- Distribution provisioning profile. A distribution provisioning profile includes your team’s distribution certificate and an app ID. If the provisioning profile is for user-testing (also known as an ad hoc hoc distribution profile), it identifies the devices on which testers can run the app identified by the app ID
To obtain your distribution assets:
Obtain your distribution certificate
Obtain your code signing certificates and provisioning profiles to run apps in development on your development device.
- In the devices organizer, select Provisioning Profiles in the Library section
- Click Refresh (available when the Automatic Device Provisioning option is selected)
- You must enter your development-team credentials so that Xcode can download the provisioning profiles that contain your development certificate
- If your team doesn’t have a distribution profile for the app you want to distribute, create it
- Download the distribution profile for the app you want to distribute
If your development team does not have a development certificate for you, Xcode requests one. If your keychain does not contain your development certificate but your team has the certificate, Xcode downloads it from your team.
- If your role in the development team is Member, inform the appropriate person in the team that there’s a pending certificate request. After the request is approved, follow the steps again to download your development certificate
- If you are the team distributor, Xcode requests and downloads, Xcode requests and downloads your team’s distribution certificate, in addition to downloading your development certificate.
Xcode does not download distribution provisioning profiles. You must download distribution provisioning profiles through your web browser and drag them to the Xcode icon in the Dock.
Each version of iOS (and its corresponding SDK) includes features and capabilities not present in earlier versions. As new versions of iOS are published, some users upgrade immediately while other users wait before moving to the latest version. You can take one of two strategies concerning the iOS version to target in developing your app:
- Target the latest iOS version. Targeting the latest version allows you to take advantage of all the features available in the latest version of iOS. However, this approach means a smaller set of users capable of installing your app on their devices because your apps cannot run on iOS versions that are earlier than the target version
- Target an earlier iOS version. Targeting an earlier version lets you publish your app to a larger set of users (because your app runs on the target OS version and later versions). However, targeting an earlier version may limit the iOS features your app can use
To specify the earliest iOS version on which you want your app to run:In the project navigator, select the project
- From the target list in the project editor, select the target that builds your app
- Click Summary
- From the Deployment Target pop-up menu, choose the iOS version you want to target
When you build your app, your deployment target selection is reflected in the MinimumOSVersion entry in the app’s Info.plist file. When you publish your app to the App Store, the store indicates the iOS version on which your app can run based on the value of this property.
The Devices setting identifies the type of devices you want the app to run on. There are two device types: iPhone and iPad. The iPhone type includes iPhone and iPod touch devices. The iPad type includes iPad devices. To specify the device families on which you want your app to be able to run:
- In the project navigator, select the project
- From the target list in the project editor, select the target that builds your app, and click Summary
- From the Devices pop-up menu, choose iPhone, iPad, or Universal (to target both families)
An iOS device uses one of a set of architectures, which include armv6 and armv7. The Architectures build setting identifies the architectures for which your app is built. You have two options for specifying the value of this setting:
- Standard. Produces an app binary with a common architecture, compatible with all supported iOS devices. This option generates the smallest app, but it may not be optimized to run at the best possible speed for all devices
- Optimized. Produces an app binary optimized for each supported iOS device. However, the build time is longer than when using the Standard option, and the app is also larger because multiple instruction sets are bundled into it.
The Build-and-Run Workflow
When you build your app, Xcode uses a build environment made up of frameworks, libraries, apps, command-line tools, and other resources. One of the main factors that determine how Xcode builds your app is the SDK used to build it. To ensure minimal reconfiguration of your projects as you adopt new SDK releases, instead of a specific SDK release, set the base SDK for your projects to Latest iOS. This way your project always uses the latest available SDK in the toolset.
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
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. 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.
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.
Specify the app data to place in the app’s sandbox before the app runs:
- From the Scheme toolbar menu, choose the scheme you want to use
- Select the Run action
- From the Application Data pop-up menu, choose the app-data archive you want to use
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:
- From the Scheme toolbar menu, choose the appropriate scheme
- Choose Product > Edit Scheme
- In the left column, select the Run action
- From the Default Location pop-up menu, select a location
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.
To start the build process, choose Product > Build. If the Build option is dimmed, choose a valid run destination. The activity viewer, in the middle of the workspace window toolbar, indicates the progress of the build and whether there are build problems. If the build fails or produces warnings, you can view details about the build in the log viewer:
- Choose View > Navigators > Log to display the log navigator
- In the list on the left, select the build task for which you want to view details
- The log viewer in the editor area lists the operations that are part of the build
If the build completes successfully, you can run your app.
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. 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.
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.