Configuring Your Xcode Project

To develop a Mac app, you create an Xcode project. An Xcode Project is a repository for all the files, resources, and information required to build your app (or one of a number of other software products). A project contains all the elements used to build your app and maintains the relationships between those elements. It contains one or more targets, which specify how to build the software. A project defines default build settings for all the targets in the project (each target can also specify its own build settings, which override the project build settings).

You create a new project using the Xcode File > New > New Project menu command, which invokes the New Project dialog. This dialog enables you to choose a template for your project, such as a Cocoa app, to name it, and to locate it in your file system. The New Project dialog also provides options, so you can specify whether your app uses the Cocoa document architecture or the Core Data framework. When you save your project, Xcode lets you to create a local Git repository to enable source code control for your project.

If you have two or more closely related projects, you should create an Xcode Workspace and add your projects to it. A workspace groups projects and other documents so you can work on them together. One project can use the products and shared libraries of another project while building, and Xcode does indexing across the entire workspace, extending the scope of content-aware features such as code completion.

Once you have created your project, you write and edit your code using the Xcode source editor. You also use Xcode to build and debug your code, setting breakpoints, viewing the values of variables, stepping through running code, and reviewing issues found during builds or code analysis.

When you create a new 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. Most developers never need to change the default of the vast majority of build settings, but there are a few basic settings that you should check for each target, such as the deployment target (platform, OS version, and architecture), main user interface, and linked frameworks and libraries.

You also need to set up one or more schemes to specify the targets, build configuration, and executable configuration to use when the product specified by the target is launched. You use the project editor and the scheme editing dialog to edit build settings and control what happens when you build and run your code. Building and Running Your Code explains how to work with Xcode build settings and schemes.

For more information about using Xcode to create, configure, build, and debug your project, as well as archiving your program to package it for distribution or submission to the Mac App Store, see Xcode Overview.

The Information Property List File

An information property list (Info.plist) file contains essential runtime-configuration information for the app. Xcode provides a version of this file with every Mac application project and configures it with several standard keys. Although the default keys cover several important aspects of the app’s configuration, most apps require additional keys to specify their configuration fully.

To view the contents of your Info.plist file, select it in the Groups & Files pane. Xcode displays a property list editor similar to the one in Figure 5-1 (which is from Xcode 3.2.5). You can use this window to edit the property values and add new key-value pairs. By default, Xcode displays a more user-friendly version of each key name. To see the key names that Xcode adds to the Info.plist file, Control-click an item in the editor and choose Show Raw Keys/Values from the contextual menu that appears.

Xcode automatically adds some important keys to the Info.plist file of all new projects and sets their initial values. However, there are several keys that Mac apps use commonly to configure their launch environment and runtime behavior. Here are some keys that you might want to add to your app’s Info.plist file specifically for OS X:

• LSApplicationCategoryType (required for apps distributed using the App Store)

• CFBundleDisplayName

• LSHasLocalizedDisplayName

• NSHumanReadableCopyright

• LSMinimumSystemVersion

• UTExportedTypeDeclarations

• UTImportedTypeDeclarations

For detailed information about these and other keys that you can include in your app’s Info.plist file, see Information Property List Key Reference.

The OS X Application Bundle

When you build your Mac app, Xcode packages it as a bundle. A bundle is a directory in the file system that groups related resources together in one place. A Mac app bundle contains a single Contents directory, inside of which are additional files and directories with the app’s code, resources, and localized content. Table 5-1 lists the contents of a typical Mac app bundle, which for demonstration purposes is called MyApp. This example is for illustrative purposes only. Some of the files listed in this table may not appear in your own application bundles.

A Mac app should be internationalized and have a language.lproj directory for each language it supports. Even if you provide localized versions of your resources, though, include a default version of these files at the top level of your Resources directory. The default version is used when a specific localization is not available.

At runtime, you can access your app’s resource files from your code using the following steps:

1. Obtain a reference to your app’s main bundle object (typically using theNSBundle class).

2. Use the methods of the bundle object to obtain a file-system path to the desired resource file.

3. Open (or access) the file and use it.

You obtain a reference to your app’s main bundle using the mainBundle class method of NSBundle. The pathForResource:ofType: method is one of several NSBundle methods that you can use to retrieve the location of resources. The following example shows how to locate a file called sun.png and create an image object using it. The first line gets the bundle object and the path to the file. The second line creates an NSImage object that you could use to display the image in your app.

NSString* imagePath = [[NSBundle mainBundle] pathForResource:@"sun" ofType:@"png"];

NSImage* sunImage = [[NSImage alloc] initWithContentsOfFile:imagePath];

For information on how to access and use resources in your app, see Resource Programming Guide. For more information about the structure of a Mac app bundle, see Bundle Programming Guide.

Internationalizing Your App

The process of preparing a project to handle content in different languages is called internationalization. The process of converting text, images, and other content into other languages is called localization. Project resources that are candidates for localization include:

• Code-generated text, including locale-specific aspects of date, time, and number formatting

• Static text—for example, strings you specify programmatically and display in parts of your user interface or an HTML file containing app help

• Icons (including your app icon) and other images when those images either contain text or have some culture-specific meaning

• Sound files containing spoken language

• Nib files

Users select their preferred language from the Language and Text system preference, shown in Figure 5-2.

Your application bundle can include multiple language-specific resource directories. The names of these directories consist of three components: an ISO 639-1 language code, an optional ISO 3166-1 region code, and a .lproj suffix. For example, to designate resources localized to English, the bundle would be named en.lproj. By convention, these directories are called lproj directories.

Each lproj directory contains a localized copy of the app’s resource files. When you request the path to a resource file using the NSBundle class or the CFBundleRef opaque type, the path you get back automatically reflects the resource for the user’s preferred language.

For more information about internationalization and how you support localized content in your Mac apps, see Internationalization and Localization Guide.