Configure Your Project

Update to Recommended Settings

When you open a project, Xcode evaluates it to determine whether there are any settings that should be updated. This feature provides an easy way to make sure your projects conform to the latest SDKs and best practices.

Open the issue navigator (Figure 3-1) to see whether anything in your project should be updated.

If the issue navigator lists the Validate Project Settings warning, click the warning to see a list of the recommended changes (Figure 3-2). Deselect any changes you don’t want to change, then click the Perform Changes button to update the project.

After performing the changes, whether you choose to make all the changes or not, Xcode does not show the warning again.

To validate project settings again, select the project in the project navigator and choose Editor > Validate Settings.

Specify the Targeted OS Version

Each version of iOS and OS X (and its corresponding SDK) includes features and capabilities not present in earlier versions. As new OS versions 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 OS version to target in developing your app:

• Target the latest OS version. Targeting the latest OS version allows you to take advantage of all the features available in the OS, including newly introduced features. However, this approach means that a smaller set of users is capable of installing your app on their devices because your apps cannot run on OS versions that are earlier than the target version.

• Target an earlier OS version. Targeting an earlier OS version lets a larger set of users install your app. However, targeting an earlier version may limit the operating system capabilities your app can use.

To specify the earliest OS version on which you want your app to run:

1. In the project navigator, select the project.

2. From the target list in the project editor, select the target that builds your app.

3. Click Summary.

4. From the Deployment Target pop-up menu, choose the OS version you want to target.

When you build the app, your deployment target selection is reflected in the MinimumOSVersion entry in the Info.plist file for the app. When you publish your app to the App Store, the store indicates the OS version on which your app can run based on the value of this property.

Use Automatic Reference Counting

Objective-C Automatic Reference Counting (ARC), introduced in Xcode 4.2, automates memory management for Objective-C objects. ARC makes memory management much easier, greatly reducing the chance that your program will have memory leaks. Xcode can update a non-ARC project to ARC, or can assist you in doing so. To add ARC to a new project, see “Preconfigure the New Project.”

To update a project so that it uses ARC:

1. Select the project in the project navigator.

2. Select the targets and source files you want to convert, and click the Check button.

   

3. Fix issues that prevent the conversion.

   If there are issues that prevent conversion, Xcode displays a dialog indicating the number of issues it found. To see all the memory-management issues that prevent conversion, select the “Continue building after errors” option in General preferences, and retry the conversion.

   

4. Review the recommended changes.

   If the conversion requires changes to source files, Xcode presents the comparison editor to show you the changes recommended for each of the selected source files. After reviewing the recommended changes, click Save.

   

   If the conversion does not require changes to source files, Xcode presents a dialog indicating so. Click the Update button to modify the settings required to build your app using ARC.

   

For more information on ARC, see Transitioning to ARC Release Notes.

Set the Basic Product Settings

When you create a project, it includes one or more targets, where each target specifies one build product and the instructions for how the product is to be built. You can use the project editor to specify every aspect of the build, from the version of the SDK to specific compiler options.

Most developers never need to change the default of the vast majority of the build settings. However, there are a few basic settings that you must check, and possibly edit, for each target. These settings are gathered into the Summary pane of the target editor and are somewhat different for Mac OS X and iOS projects.

To edit the basic settings for an app, select the project in the project navigator, and the app target in the project editor, and click the Summary button.

Basic Settings for OS X Apps

The Summary pane of the target editor groups the basic settings in three sections: OS X Application Target, Linked Frameworks and Libraries, and Entitlements.

The OS X Application Target section specifies:

• The app icon, the icon the OS uses to identify the app to the user

• The app category, the main classification for the app

• The bundle identifier, a string that identifies the app to the operating system and the App Store

• The version number under which to publish the app

• The build number, which identifies a particular build of the app

• The deployment target, which is the earliest OS X version on which the app runs

• The main user interface file, which is the user interface file to load when the app launches

• Code signing: Whether to code sign the app when it is built

The Linked Frameworks and Libraries section lists the frameworks and libraries to which to link the app when built.

The Entitlements section lists the entitlements the OS and the App Store use to grant the app access to restricted data and special capabilities, such as access to Address Book data and the camera. See App Distribution Guide for more information.

Basic Settings for iOS Apps

The Summary pane of the target editor groups the basic settings in five sections: iOS Application Target, iPhone / iPod Deployment Info, Linked Frameworks and Libraries, Entitlements, and Maps Integration.

The iOS Application Target section specifies:

• The bundle identifier, a string that identifies the app to the operating system and the App Store

• The version number under which to publish the app

• The build number, which identifies a particular build of the app

• The devices for which to build the app (iPhone, iPad, or Universal)

• The deployment target, which is the earliest iOS version on which the app runs

The iPhone / iPod Deployment Info section specifies:

• The main user interface file, the storyboard or nib file to load when the app launches

• User interface orientations, the orientations the app supports (portrait, upside down, landscape left, landscape right)

• Status bar appearance and behavior, the style, visibility, and color for the status bar

• App icons, the icons the OS uses to identify the app to the user

• Launch images, the screenshots of the app to present when the app launches

The Linked Frameworks and Libraries section lists the frameworks and libraries to which to link the app when built.

The Entitlements section lists the entitlements the OS and the App Store use to grant the app access to restricted data and special capabilities, such as access to iCloud data. See App Distribution Guide for more information.

The Maps Integration section specifies whether your app can accept routing requests and can provide directions to other apps on the user’s device. See Location Awareness Programming Guide for more information.

Add Build Configurations

When you create a project, Xcode provides two build configurations: Debug and Release, which differ primarily in the inclusion of debug information and in the degree to which the build is optimized. You might want to add more build configurations; for example, you might want a build that’s fully optimized but that includes debug information in order to debug the optimized code.

To add a new build configuration

1. Select the project in the project navigator to open the project editor.

2. Select the project in the project editor and click the Info button.

3. Expand the Configurations section in the Info pane, and click the Add (+) button at the bottom of the section.

   

4. Select one of the existing configurations from the pop-up menu as a starting point for the new configuration.

5. Select the name of the copy and type your preferred name for the configuration.

Configure a uniform set of build setting definitions across any number of targets or projects by using a configuration file. A configuration file is a plain text file with a list of build setting definitions, one per line. You can base a build configuration only on a configuration file that is in your project, not on an external file.

To base a build configuration on a configuration file

 

Add Build Rules

Xcode processes your source files according to the file type using a set of built-in rules. For example, property list (plist) files are copied into the product using the CopyPlistFile script located in the Xcode directory.

To see the default build rules for a target

1. Select the project in the project navigator.

2. In the project editor, select the target and click the Build Rules button.

   Because Xcode sets build rules on a per-target basis, no build rules are displayed when you select the project rather than a target.

3. In the filter bar of the Build Rules pane, click the All button.

   

In addition to the default build rules, you can add custom build rules to your target or copy default target build rules to your target.

Change the way files are processed with build rules.

To add a build rule

 

Link Frameworks Conditionally

There may be occasions when you need to configure your app target so that it links to a framework only if certain conditions are met.

To link a framework only when using a particular SDK, conditionally set the Other Linker Flags build setting to:

-framework <framework_name>

Use this setting in all configurations for the SDK you want the definition to apply to.

If you need to, you can add another condition to the Other Linker Flags build setting to specify a different SDK and framework.

Specify the Targeted iOS Devices

The Devices setting identifies the type of devices you want the app to run on (“Basic Settings for iOS Apps”):

For more information on configuring your app for iPhone, iPad, or both device families, see "Advanced App Tricks".

Specify the Targeted iOS Architecture

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.

If you need to build your app so that it contains executable code for a different set of architectures than these predefined values offer, you can choose Other from the Architecture build-setting value list and enter the custom iOS-device architecture names.

Compile Source Code Conditionally for iOS Apps

This section shows how to target code to a simulation or device environment and which frameworks (or libraries) to link to, depending on whether you’re building your app to simulate its operation or to run it on a device.

An iOS app can run in simulation environments or on iOS devices. You run your app in simulation environments to simulate the app’s execution on your Mac, and you run the app on devices to test its actual performance. The simulation and device environments are fundamentally different; therefore, when using technology that’s implemented differently in the two environments, you may need to tweak your code so that some of it runs in a simulation environment but not on a device.

There may be times when you need to run code in a simulation environment but not on a device, and the other way around. On those occasions, you can use the preprocessor macros TARGET_OS_IPHONE and TARGET_IPHONE_SIMULATOR to conditionally compile code for all iOS-based devices.

Listing 3-1 shows how to use the TARGET_IPHONE_SIMULATOR macro to determine whether code meant for iOS is being compiled for a simulator or a device.

Listing 3-1  Determining whether you’re compiling for a simulation environment or for a device

// Set hello to "Hello, <device or simulator>"!

#if TARGET_IPHONE_SIMULATOR

   NSString *hello = @"Hello, iOS Simulator!";

#else

   NSString *hello = @"Hello, iOS device!";

#endif

Listing 3-2 shows how to use the TARGET_OS_IPHONE macro in a source file to be shared between Mac OS X and iOS.

Listing 3-2  Using a single source file for iOS and Mac products

#if TARGET_OS_IPHONE

   #import <UIKit/UIKit.h>

#else

   #import <Cocoa/Cocoa.h>

#endif

The TARGET_OS_IPHONE and TARGET_IPHONE_SIMULATOR macros are defined in the TargetConditionals.h header file.