Xcode4 userguide Apple

Contents

About Xcode 12
At a Glance 12
Get Oriented to Xcode Organization and Features 13
Design the Look and Behavior of Your App 13
Debug and Refine Your Code 13
Safeguard Your Projects Using Source Control 13
Distribute Your App to App Testers or Publish it on the App Store 14
See Also 14

Get Oriented 15
Contextual Help: Your Shortcut to Answers 15
The Workspace Window: Where You Get Most of Your Work Done 16
Open Work in Tabs and Windows 18
Edit and View Many Types of Data 19
Find Information to View or Edit 31
Find Information that Supplements the Editor 47
Check on the Progress of Xcode Tasks 50
The Organizer Window: Managing Projects, Devices, and Documentation 51
Browse and Bookmark Documents 51
Browse for Task-Based Help 54
Work with Your Source Control Repositories 54
Organize Your Projects and Devices 55
Take a Snapshot of Your Project 55

Start a Project 56
Click New Project in the Xcode 4 Startup Screen to Create a Standalone Project 56
Create a Git Repository For Your New Project 58
Select Options While Creating a New Project 58
Create a Workspace to Work with Multiple Related Projects 59
Check Out a Working Copy from Your Source Control Repository 63
Modernize Your Project 63
Add Automatic Reference Counting 64
Close a Project or a Workspace 65

2012-09-19 | © 2012 Apple Inc. All Rights Reserved.

2

Contents

Configure Your Project 66
Add Build Configurations 66
Set the Basic Build Settings 69
Add Build Rules 72

Edit User Interfaces 76
Create Your User Interface 76
Display Your User Interface Objects 78
Connect to Other Files Using Placeholder Objects 79
Select Hidden Objects in an Interface File 82
Lay Out User Interface Controls Using Content-Driven Rules 84
Add New Constraints 87
Allow Objects to Maintain Their Intrinsic Content Size 90
Override Automatic Constraints 91
Set Priorities to Resolve Potential Conflicts 92
Design the User Interface of Your iOS App with Storyboards 92
Create User Interface Classes 97
Add a New Nib File 98
Add a Custom View 102
Add a New Controller 103
Simultaneously Design and Implement User Interface Objects Using Multiple Editors 117
Manage Connections Between User Interface Objects 106
Make Connections Directly Between IB Objects and Your Code Files 107
Add Outlets and Actions to Classes Programmatically 110
Use the Inspector or the Connections Panel to Make Connections 111
Configure Connections Between Model and View Objects 114
Create and Configure a Binding with the Bindings Inspector 115
Create a Binding by Dragging Directly to Your Header File 116
Key Paths Are Dependent on Your Data Model 117
Configure the Binding Attributes to Customize the Binding 118
Bind to Objects in a Custom Tree Data Structure 118
Bind to Your Application Preferences 119

Edit Source Code 121
Customize the Source Editor with Xcode Preferences 121
Modify Syntax-Aware Fonts and Text Colors 121
Set Your Text-Editing and Automatic Indentation Preferences 125
Enter Code Quickly and Accurately with the Help of the Source Editor 125
Speed Up Typing with Code Completion 125
Balances Delimiters Automatically 128


3

Contents

Have Fix-it Flag Errors as You Type 129
Find and Display Related Content 130
Open a FIle Quickly 130
Split the Editor Area to Display Related Content 132
Customize Keyboard Shortcuts to Determine Where a File’s Contents Are Displayed 134
Jump to a Symbol’s Definition 136
Find Related Items with the Jump Bar 138
Find Related Content Automatically 138
Use Assistant with Interface Builder and Data Models 140
Incorporate Other Source Editor Features into Your Workflow 141
Examine the Structure of Your Code with Code Folding 141
View Preprocessor or Assembly Output 143
View Documentation for a Symbol Using Quick Help 144
Automate Extensive Changes in Your Files 147
Incorporate Files and Code from the Xcode Libraries 148
Use Inspectors to View and Enter Data 152

Build and Run Your App 153
Create, Edit, and Manage Schemes 178
Specify Which Targets Are Built for Each Type of Action 155
Rename or Reorganize Your Schemes 156
Configure and Execute Actions 158
Run Your Application to Debug It 158
Run Unit Tests to Find Regressions 163
Profile Your Application to Find Problems and Optimize Your Code 168
Perform Static Analysis To Find Semantic Problems 169
Create an Archive for Sharing or Submitting Your Program 169
Initiate an Action 170
Customize Your Build and Run Workflow 172
Fine-Tune Your Builds 176
Control the Order in Which Xcode Builds Your Products 178

Debug Your App 180
Select a Debugger 180
Find Coding Mistakes 181
Locate Possible Semantic Problems 181
Locate and Display Build Issues 183
Manage Breakpoints 188
Add and Activate Breakpoints 188
Edit Breakpoints 190


4

Contents

Share Breakpoints 192
Set Preferences for Breakpoint Behavior 193
Customize the Debug Area 194
The Variables Pane 194
The Console Pane 195
Control Program Execution 195
Step Through Code with the Debug Bar 195
Set a Location in the Debug Bar 196
Step Through Code in the Source Editor 196
Suspend a Thread 197
Set Xcode Window Behavior 199
Examine Threads, Stacks, Variables, and Memory 200
Capture OpenGL ES Frames 206

Make Projectwide Changes 215
Replace Text Strings 215
Replace All Instances of a Text String 216
Replace Selected Instances of a Text String 218
Customize the Search 219
Improve Your Code’s Structure Through Refactoring 221
Select the Source Code to Refactor 221
Preview the Changes Before Executing the Operation 222
Run Unit Tests Before and After Refactoring 222
Choose a Refactoring Operation 223

Manage Your Devices 225
Set Up Your Device 226
Provision a Device 226
Restore or Install a Version of iOS on a Device 229
Run Your Application On the Device 230
Remove an Application from a Device 230
Download Your Application’s Data for Analysis 232
Capture and Use Screenshots from a Device 234
Set a Screenshot as Your iOS Application’s Launch Image 235
Export a Screenshot to Your File System 237
Identify Small UI Changes by Comparing Screenshots 238
Transfer Your Developer Profile to Another Computer 239

Save and Revert Changes to Files 244
Save when Editing 244


5

Contents

Revert to the Last Saved Version 244
Undo Changes Incrementally 246
Unlocking Files 247
Use Snapshots and SCM for Projectwide Change 249
Snapshots Archive Projectwide Changes to Documents and Configuration 249
SCM Repositories Manage Overall Change as Your Project Develops 249

Save and Revert Changes to Projects 251
Take a Snapshot of Your Project 252
Keep Track of Changes with Source Control 253
Why Use Source Control? 277
Choose Git or Subversion 254
Learn SCM Terminology 254
Manage Your Repositories 256
Find SCM Commands 258
Keep Track of Your Files’ SCM Status 260
Work with Git and Subversion 261
Set Up Git Version Control When You Create a New Project 261
Add Git or Subversion Version Control to an Existing Project 261
Clone or Check Out a Copy of a Project to Use Locally 264
Add an Existing SCM Working Copy of a Project to Xcode 265
Create a Branch to Isolate Risky Changes 265
Clone a Specific Branch 268
Add a Folder to a Subversion Repository 270
Commit Files to Add Them to a Repository 271
Reconcile Different Branches 272
Update Your Working Copy from a Remote Repository 273
Send Your Working Copy to the Remote Git Repository 277
Save Internal Project Files in Repositories 278
Compare Revisions 278
Select Specific Revisions 279
Review Individual Changes 280
View All Revisions Chronologically 281
Distribute Your Program 282

Distribute Your App 284
Archive Your App 287
Validate Your App 285
Distribute Your iOS App 287
Distribute Your Mac App 289


6

Contents

Document Revision History 291


7

Figures and Tables

Get Oriented 15
Figure 1-1
Figure 1-2
Figure 1-3
Figure 1-4
Figure 1-5
Figure 1-6
Figure 1-7
Figure 1-8
Figure 1-9
Figure 1-10
Figure 1-11
Figure 1-12
Figure 1-13
Figure 1-14
Figure 1-15
Figure 1-16
Figure 1-17
Figure 1-18
Figure 1-19
Figure 1-20
Figure 1-21
Figure 1-22
Figure 1-23
Figure 1-24
Figure 1-25
Figure 1-26
Figure 1-27
Figure 1-28
Figure 1-29
Figure 1-30
Figure 1-31
Figure 1-32
Figure 1-33

Contextual help 15
A newly opened Xcode window 16
The project contents in the Xcode project navigator 16
The utility area 17
The debug area 18
The source editor 21
Target information in the project editor 38
Build settings 23
Quick Help for key values 24
The data model editor 28
The mapping model editor 29
Interface Builder 30
Editor selector buttons 31
The navigators 31
A folder and groups in the project navigator 33
The project navigator filtered to show only .m files 36
Project navigation 36
The jump bar in Interface Builder 38
The related items pop-up menu 39
The Find Options dialog 42
The issue navigator 43
The breakpoint navigator 44
The debug navigator and associated editor and debug areas 45
Viewing a log 46
The utility button 47
Data model inspectors 48
Interface Builder inspectors 48
The library pane 49
The activity viewer 50
The activity pop-up window 50
Issues in the activity viewer 50
The Organizer button 51
The documentation navigator 51


8

Figures and Tables

Figure 1-34
Figure 1-35

The bookmarks navigator 52
Xcode help start screen 54

Start a Project 56
Figure 2-1
Figure 2-2
Figure 2-3
Figure 2-4
Figure 2-5

The option to add source control when creating a project 58
Options for a new project 59
A shortcut menu for a workspace 62
Modernization in the Issue navigator 63
Updates dialog 64

Configure Your Project 66
Table 3-1
Table 3-2

Mac OS X project editor Summary pane settings 70
iOS project editor Summary pane settings 72

Edit User Interfaces 76
Figure 4-1
Figure 4-2
Figure 4-3
Figure 4-4
Figure 4-5
Figure 4-6
Figure 4-7
Figure 4-8
Figure 4-9
Figure 4-10
Figure 4-11
Figure 4-12
Figure 4-13
Figure 4-14
Figure 4-15
Figure 4-16
Table 4-1

Interface Builder in the workspace window 77
Icon view for placeholders and objects in Interface Builder 78
Auto Layout 85
User constraint 88
Button set to maintain its intrinsic content size 90
Automatic constraints 91
User-added trailing constraint 91
User-added leading constraint 92
The Use Storyboard option 93
View controllers in the object library 94
Creating a storyboard 95
Attributes inspector for a segue 96
Storyboard for an iOS Application 97
Interface Builder and Assistant 106
Making a connection to source code from Interface Builder 107
Help articles in Interface Builder 110
Auto Layout constraints 88

Edit Source Code 121
Figure 5-1
Figure 5-2
Figure 5-3
Figure 5-4
Figure 5-5
Figure 5-6

Fonts & Colors preferences 122
Code completion 126
Quick Help for code completion 128
Placeholders in code completion text 128
The Assistant button 132
General preferences 134


9

Figures and Tables

Figure 5-7
Figure 5-8
Figure 5-9
Figure 5-10
Figure 5-11
Figure 5-12
Figure 5-13
Figure 5-14
Figure 5-15

The Single Assistant navigation chooser dialog 135
The navigation chooser dialog 136
The assistant editor used with a data model 140
The focus ribbon in use 142
Preprocessor output 143
Generated output in Assistant jump bar 144
The Quick Help window 145
A file template information pop-up window 149
The File inspector 152

Build and Run Your App 153
Figure 6-1
Figure 6-2
Figure 6-3
Figure 6-4
Figure 6-5
Figure 6-6

The Scheme pop-up menu 153
The manage schemes dialog 157
The scheme editor Run pane 158
Choosing a location in the scheme editor 163
Behaviors preferences 172
Project editor help topics 176

Debug Your App 180
Figure 7-1
Figure 7-2
Figure 7-3
Figure 7-4
Figure 7-5
Figure 7-6
Figure 7-7
Figure 7-8
Figure 7-9
Figure 7-10
Figure 7-11
Figure 7-12
Figure 7-13

The issue navigator 183
The debug area 194
Choosing a location in the debug bar 196
Xcode In Front window mode while the executable is running 199
Xcode In Front window mode while the executable is paused 200
Enabling OpenGL ES frame debugging 207
Frame capture button 208
OpenGL ES frame capture 209
Controls for stepping through draw calls 210
Shortcut menu 211
Wireframe view 212
Frame capture with two Assistant panes 213
Vertex Array Object detail 214

Make Projectwide Changes 215
Figure 8-1
Figure 8-2

Search and replace using the search navigator 215
The refactor preview dialog 222

Manage Your Devices 225
Figure 9-1

Devices organizer 225


10

Figures and Tables

Save and Revert Changes to Files 244
Figure 10-1
Figure 10-2
Figure 10-3
Figure 10-4

Workspace window with in-memory changes to files 245
Undo Typing command 246
File could not be unlocked 247
Locked file indicators 248

Save and Revert Changes to Projects 251
Figure 11-1
Figure 11-2
Figure 11-3
Figure 11-4
Figure 11-5
Figure 11-6
Figure 11-7
Figure 11-8
Figure 11-9
Figure 11-10

The Snapshots settings dialog 252
Snapshots listed in the Organizer window 253
The repositories pane in the Organizer window 256
The Source Control submenu of the File menu 259
The Source Control submenu of the project navigator shortcut menu 259
Repositories organizer buttons 259
Source control badges in the project navigator 260
A scheme in the commit dialog 278
Comparing two revisions of a file with the version editor 279
The archives organizer 283


11

About Xcode

Xcode is the integrated development environment (IDE) designed for developing iOS and Mac apps. The Xcode
IDE includes editors used to design and implement your app, such as a source code editor and a user interface
editor. Xcode also supports multiperson development using source control management (SCM) systems. As
you write source code, Xcode can show you mistakes in both syntax and logic, and even suggests fixes.
Xcode features a single window, called the workspace window , that holds most of the data you need.
Toolbar
Navigator
selector bar

Inspector
selector bar

Jump bars

Breakpoint gutter

Inspector pane

Focus ribbon
Editor
area

Navigator
area

Utility
area

Library
selector bar
Library pane

Debug
area

Filter bar

Debug bar

Read this guide to get started using Xcode.

At a Glance
Xcode has many features to make your job easier.
●

Single-window interface. You perform most of your development workflows in one window (you can
have multiple workspace windows and multiple tabs per window).


12

About Xcode
At a Glance

●

●

●

●

Graphical user interface design. With the Xcode user interface editor, called Interface Builder, you specify
most of the details of your app’s user interface, such as the layout of the user interface controls, and their
connection to your app’s business logic and the data it manages, using a powerful and intuitive graphical
user interface. Interface Builder works closely with other editors, such as the source code editor, to take
you from design to implementation as fast as possible.
Assisted editing. When you need to work on different aspects of the same component, such as user
interface layout and the implementation of the user interface functionality, you can use multiple editors
that open the content you need when you need it. For example, when you work on an implementation
file in the primary editor, Xcode can open the corresponding header file in a secondary editor pane.
Automatic error identification and correction. Xcode checks the source code you type as you type it.
When Xcode notices a mistake, the source code editor highlights it. You can then find out details about
the error and ask Xcode to fix it for you.
Source control. You can safeguard all your project files in Git and Subversion source code repositories.

Get Oriented to Xcode Organization and Features
Xcode is a powerful tool. But, as it’s true with any complex product, you need to know essential concepts and
workflows before you can start developing products efficiently.
Relevant Chapters: "Get Oriented" (page 15), "Start a Project" (page 56).

Design the Look and Behavior of Your App
Two of the most important tasks you perform while you develop your app is designing its user interface and
writing the business code that implements your app’s unique functionality.
Relevant Chapters: "Edit User Interfaces" (page 76), "Edit Source Code" (page 121).

Debug and Refine Your Code
Xcode provides a debugging environment that you can customize to automatically bring forward the parts of
your code in which you are interested the most.
Relevant Chapters: "Debug Your App" (page 180), "Make Projectwide Changes" (page 215).

Safeguard Your Projects Using Source Control
Xcode provides easy local backups with snapshots and the ability to work in a team using SCM.
Relevant Chapter: "Save and Revert Changes to Projects" (page 251).


13

About Xcode
See Also

Distribute Your App to App Testers or Publish it on the App Store
Share your app with other members of your development team or app testers, or publish it on the App Store.
Relevant Chapters: "Distribute Your App" (page 284).

See Also
Before developing your iOS or Mac app, you must be familiar with the design and coding practices required
by your target platform. See Developing for the App Store to learn the basics of app development.


14

Get Oriented

Once you’ve got your projects open in Xcode, you can start writing code. This chapter describes where to find
the most commonly used features of Xcode. The remaining chapters describe the use of some of these features
in more detail.

Contextual Help: Your Shortcut to Answers
In addition to being listed in the documentation browser in Xcode ("Browse for Task-Based Help" (page 54)),
many help articles are available from shortcut menus throughout the application. Control-click in any of the
main user-interface areas in the workspace or Organizer window to see a list of help articles available for that
area. Figure 1-1 shows contextual help for the source editor. If there are more articles than can be listed in the
shortcut menu, choose Show All Help Topics; the help opens in the Organizer window (Figure 1-35 (page 54)).
You can use this facility to find information about a specific task that you’re trying to accomplish, or just to
learn what tasks can be performed using that area of Xcode.
Figure 1-1

Contextual help


15

Get Oriented
The Workspace Window: Where You Get Most of Your Work Done

Before going any further, you need to get oriented to the Xcode workspace window (Figure 1-2).
Figure 1-2

A newly opened Xcode window

The left side of the window is the navigator area, opened to the project navigator in the figure. The project
navigator shows the contents of your project or workspace. Figure 1-3 shows some of the groups and files in
a project.
Figure 1-3

The project contents in the Xcode project navigator


16

Get Oriented

The right side of the window in Figure 1-2 (page 16) is the editor area. You can edit many types of information,
including source code, property lists (plists), Core Data models, and user interface (nib or storyboard) files, and
you can view many more.
To supplement the information in the editor area, you can open a utility area at the right of the workspace
window (Figure 1-4), which includes inspectors and libraries. Use the view selector (
to open and close the navigator, debug, and utility areas.
Figure 1-4

The utility area


17

) in the toolbar

Get Oriented

When you are running code, the debug area opens (Figure 1-5). When you stop at a breakpoint, the debug
navigator opens as well.
Figure 1-5

The debug area

Open Work in Tabs and Windows
For fast switches between different editors or files, you can add tabs to the Xcode workspace window, or you
can open additional windows. To activate tabs, choose View > Show Tab Bar, or add a new tab by choosing
File > New > New Tab. Choose File > New > New Window to open a new workspace window. Each tab or
workspace window can be customized independently of the others. For example, you can use one window to
debug and another to edit source code. If you open the same file in two tabs or two windows, the changes
you make in one tab or window are reflected in the other.
Tabs can be reordered, closed independently, or dragged out of the tab bar to create a new window, just as
they can in Safari. You can use items in the Window menu (or their keyboard equivalents) to move between
tabs. You can also give a tab a name for use in Behaviors preferences (see "Customize Your Build and Run
Workflow" (page ?)).
Xcode remembers the windows and tabs you had open when you last closed a workspace and reopens them
in the same configuration.


18

Get Oriented

Edit and View Many Types of Data
Xcode includes editors for many file types, including:
●

Source code

●

Project and build settings

●

Property list (plist) files

●

Rich text (rtf ) files

●

Core Data models

●

Core Data mapping models

●

User interface (nib) files

●

AppleScript files

●

Scripting dictionary files

There are viewers that can display graphics, videos, and a variety of other file types.
The use of each of these editors is briefly described in this section. Control-click in any of the editors to get a
list of help articles that further describe the use of the editor (Figure 1-1 (page 15)).

Select Any File
To open any of the editors or viewers, select a file in the project navigator. The editor or viewer for that file
type opens automatically in the editor area of the workspace window. Any file for which Xcode does not have
an editor is displayed using Quick Look. (Quick Look is also used by the Finder. In the Finder, select a file and
press the Space bar or choose Quick Look from the File menu to see it in use.)
Each document-type editor has custom commands in the Navigate and Editor menus to act on the information
in that type of document. Note that the Navigate menu—like several of the menus in Xcode—shows different
menu items when you hold down the Option, Shift, or Option and Shift keys.

Edit in Hexadecimal Format
You can view most file types in hexadecimal format by Control-clicking the file in the project navigator and
choosing Open As > Hex from the shortcut menu. Some file types that are not editable in the default viewer,
such as image files, can be edited in hexadecimal format.
You can edit the hexadecimal code directly, or you can edit in the plain text column. Editing either updates
the other.
When the hex editor has focus, you can use the Editor menu to customize its display.


19

Get Oriented

View and edit a file in its binary format by opening it in the hex editor.

To open a file with the hex editor . . .
1.

Control-click a file in the project navigator.

2.

Choose Open As > Hex.

The hex editor has three areas:
●

●

●

On the left, the line numbers
In the center, the hexadecimal representation of the bytes in the file, 32 bytes per line, one byte per
column
On the right, the plain-text (ASCII) representation of those bytes

From the Editor menu, you can hide the line numbers or the plain-text representation. You can also choose
to display the byte codes in groups of 2, 4, 8, 16, or 32.
The screenshot shows an image file in the hex editor.


20

Get Oriented

Write, Edit, and Debug Source Code
The Xcode source editor has many features to help you develop source code. Among other features, you can
write and edit source code (see "Edit Source Code" (page 121)), set and enable or disable breakpoints (see
"Manage Breakpoints" (page 188)), and control program execution during a debugging session (see "Control
Program Execution" (page 195)). Control-click in the source editor to see a list of help topics describing features
of the editor and tasks you can accomplish (Figure 1-1 (page 15)).
Figure 1-6

The source editor


21

Get Oriented

Note: When you edit a file in Xcode, the file’s icon is shaded in the project navigator to indicate
that there are unsaved changes. You can save the file, or if you quit Xcode or build the project, Xcode
automatically saves all changed files for you by default (you can change this behavior in the General
pane of Xcode preferences). To ensure you can return to a known state before you build your project,
create a snapshot (see "Take a Snapshot of Your Project" (page 55)).

Edit Build Settings
When you click the project icon in the project navigator, the project editor appears to the right of the project
navigator, displaying project and target information. Figure 1-7 shows some of the target information in the
project editor.
Figure 1-7

Target information in the project editor

Click the various buttons and icons in the project editor to see the information that’s in there.


22

Get Oriented

You can choose to view basic build settings or all settings. The values of build settings can be set at the default,
project, or target level. You can edit a build setting at the project or target levels. Click the Levels button to
see all the levels of build settings simultaneously, as in Figure 1-8. The setting that takes precedence is
highlighted in green and shown in the Resolved column. If you have changed or customized a setting, it’s
shown in boldface. Click the Combined button to see just the resolved build settings.
Figure 1-8

Build settings

See "To add a new build configuration" (page 66) for more information on using build settings.

Edit Keys and Values
In addition to the Info.plist file required for every application, the property list editor opens a variety of
other property list file types.
To edit a key or a value, double-click the item and type a new string into the text field. In some cases, a pop-up
menu is available, indicated by small vertical arrows. Click the arrows to see the choices.
You can add a new property or you can add a new child property for an array or dictionary. The property list
editor warns you if you attempt to add a key that already exists in the file.
Add a new property to a property list using the property list editor.

To add a property to a property list . . .
1.

In the property list editor, hold the pointer over an entry and click the Add (+) button.

2.

Choose a key name from the pop-up menu.


23

Get Oriented

3.

Choose a value from the pop-up menu in the Value column or enter a value.

If you are adding a property that is an array or dictionary, click the disclosure triangle and press Return to
add a child property.
You can add a property with a name that is not in the pop-up menu. To do so, type the key name in the
field at the top of the pop-up menu, choose the data type from the pop-up menu in the Type column, and
enter a value in the Value column.
Click the minus (–) sign next to any item to remove it from the file.
For known property list key types, the Key column in the property list editor shows a descriptive name of the
key instead of the key’s literal text. Choose Editor > Show Raw Keys & Values to display the literal text instead.
You can also see both the name and the raw key value in Quick Help in the utility area (Figure 1-9).
Figure 1-9

Quick Help for key values


24

Get Oriented

Control-click in the editor and select Property List Type to see a list of possible file types for property lists. The
type of the current file is indicated by a dash to the left of the file name. You can use this menu to change from
the default to a specific property type.
Set the property list type when creating or editing a property list. If Xcode cannot determine the type of a
property list, you may need to set the type manually.

To set the property list type . . .
1.

Select a property list in the project navigator.

2.

Control-click in the property list editor to display a contextual menu.

3.

From the Property List Type submenu, choose a new property list type.

Property lists that share the same system-defined structure are said to have the same type. In addition to
the Info.plist file required for every application bundle, the property list editor in Xcode supports a
variety of other types. The property list type determines the list of possible keys in the key’s pop-up menu.
In the Property List Type submenu, the current type is indicated by a dash to the left of the type name.


25

Get Oriented

Edit Rich Text Files
You can write, open, and edit rich text (.rtf) files in Xcode. The editor has a user interface and feature set
very similar to those of the Mac OS X TextEdit application, but without the capability of converting the file to
other formats such as plain text or HTML. Note that Xcode opens plain text (.txt) files with the source editor,
not the rich text editor.

Design Data Models Graphically
If your project uses the Core Data framework, you can use the data model editor to implement or modify your
Core Data model (see Core Data Starting Point ).
Get a jump-start on your Core Data-based project by using one of the project templates that incorporate Core
Data.

To create a project that uses Core Data . . .
1.

Choose File > New > Project.

2.

Select the project template for your iOS or OS X product, and click Next.

3.

If the Use Core Data option appears in the project options pane, select it and click Next.
Otherwise, Core Data is not available in the selected project template.

4.

Enter the project name, and specify its location in your file system.


26

Get Oriented

5.

Click Create.

The project templates that incorporate Core Data:
●

Link against the Core Data framework

●

Add a managed object model file

●

Add code to create and locate the various parts of the Core Data stack

Use the Core Data model editor to edit the managed object model.


27

Get Oriented

Important: Not all templates offer a Core Data option.
Core Data is an advanced technology that is not required for creating simple applications.
The managed object model is a representation of the schema that describes your model objects, including
the relationships between them. Figure 1-10 shows the data model editor.
Figure 1-10

The data model editor

The top-level components area lists the entities, fetch requests, and configurations defined in the model. You
can select one or more items at a time within a single group. You use the Add Entity button to add an entity,
fetch request, or configuration. To add a fetch request or configuration, press and hold the Add Entity button
until it shows the other options. The button retains the label from the last time it was used.
The detail area shows the attributes, relationships, and fetched properties associated with the item or items
you select in the top-level components area. You can select one or more items from the same group at the
same time. There are two styles for the detail area: table and graph. You select the style using the segmented
control at the lower right of the editor area. You can use the graph style only if you select an entity in the
top-level components area. You can use either style to edit the model, however the table style is typically
better for detailed editing and inspection, and the graph style is better for visualizing your schema.
The Core Data Model inspector in the utility area displays information about the item or items you select in
the detail area. By selecting more than one property in the detail area, you can edit several properties at the
same time. For example, you can set the Attribute Type for a number of attributes simultaneously.


28

Get Oriented

Define Rules Used in Data Store Migration
If you change your Core Data model extensively enough that you need a mapping between an old store and
a new one, you can use the Core Data mapping model editor to graphically create the mapping model.
A Core Data mapping model describes the transformations needed to convert data described by a Core Data
model to another Core Data model with a different schema. The Core Data mapping model editor provides
table-based tools to create and edit a mapping model.
Tip: Before you create a mapping model, you should consider whether you can transform your data using
lightweight migration (as described in Core Data Model Versioning and Data Migration Programming Guide ).
Lightweight migration is much simpler and more efficient than mapping model-driven migration. In some cases,
you can make custom transformations by first using lightweight migration, and then performing an additional
step in code.

The mapping model editor is shown in Figure 1-11.
Figure 1-11

The mapping model editor

The entity mappings list lists all the entity mappings defined in the model. You can edit the name of the
mapping by double-clicking the text.
The property mapping tables show the attribute and relationship mappings associated with the currently
selected entity mapping.


29

Get Oriented

The new entity mapping management area allows you to add a new entity mapping to the model.
Click the Add Entity Mapping button to display a series of dialogs that you use to configure the new mapping.
If necessary, you choose the source and destination models for the entity using the corresponding pop-up
menus.
For complete flexibility, you can implement a subclass of NSEntityMigrationPolicy to set it as the custom
policy for a mapping.

Design Your User Interface Graphically
Starting with the first version of Xcode, Apple provided a separate application—called Interface Builder—for
designing graphical user interfaces. In Xcode 4, Interface Builder is fully integrated into the workspace window
as an editor. Figure 1-12 shows Interface Builder in Xcode 4.
Figure 1-12

Interface Builder

Interface Builder creates files—called nib files—that are in a proprietary format (that is, you can’t read them
with the source editor or the hex editor). For more information on the use of Interface Builder, see "Edit User
Interfaces" (page 76).


30

Get Oriented

Display Files in a Split Editor Pane
You can display two or more different views of a file, two or more different files, or two different versions of
the same file in adjacent editor panes (side by side or one above the other). You use the editor selector buttons
(Figure 1-13) to switch between the standard editor, Assistant, and the version editor. Whereas the standard
editor uses a single editor pane, Assistant and the version editor use a split-pane editor. In addition, if you
Option-click a file in the project navigator or symbol navigator pane, that file opens in the assistant editor pane
(you can change this behavior in the General pane of Xcode preferences).
Figure 1-13

Editor selector buttons

Although you can specify which file to show in each pane of the split editor, it is often helpful to let Xcode find
a related file for you. Assistant can find, for example, the header file counterpart to the source code file you’re
viewing, or the source code file used to implement the control code for an Interface Builder file. For more
information about Assistant, see "Split the Editor Area to Display Related Content" (page 132).
If your project is under source control, the version editor can compare any two versions of the file; see "Compare
Revisions" (page 278) for details.

Find Information to View or Edit
Xcode provides two ways to navigate through your project: navigators and the jump bar. Many of the navigators
include text fields for searching through the project or filtering the items in the navigator; some include buttons
to restrict the scope of items displayed. The jump bar appears at the top of the editor pane and provides an
alternate way to navigate through the files and symbols in the project. Because the jump bar is always available,
you can use it to find items in the project even when the navigator area is closed.
The navigators are shown in Figure 1-14.
Figure 1-14

The navigators
Project

Search

Symbol

Issue

Debug

Log

Breakpoint

The use of each of these navigators and jump bars is briefly described in this section. Control-click in any of
the navigators to get a list of help articles that further describe the use of the navigator.


31

Get Oriented

View the Files in Your Project or Workspace
The project navigator shows projects, groups, folders, and files:
●

●

●

●

The project or projects in your workspace window are the highest level of the hierarchy in the project
navigator. Open the project’s disclosure triangle to see the groups, folders, and files in the project. Select
the project to display the project editor, where you can view and edit project and target settings.
A group appears in the project navigator as a yellow folder icon. The group does not represent a folder
on disk. Although you can organize your project in Xcode to reflect the organization of files on disk, moving
files into and out of groups does not affect the content of the folders on disk, and moving files on disk
into and out of folders does not affect the content of the groups in the project navigator.
A folder is a reference to a folder on disk and appears in the project navigator as a blue folder icon. The
contents of the folder in the project navigator reflect the contents of the folder on disk. It’s important to
note, however, that the files that appear in a folder icon in the project navigator are not part of your project
unless you have added them to the project explicitly (in which case they appear directly under the project
or in a group, as well as in the folder). You can view and edit the files in a folder, but to move files in and
out of the folder you must use the Finder.
A file in the project navigator is a reference to a file on disk.


32

Get Oriented

Figure 1-15 shows a project (FolderFinder) containing both a group and a folder named ExtraFiles.
Although in the figure the group contains the same files as the folder, you could modify the contents of either
the group or the folder without affecting the contents of the other container.
Figure 1-15

A folder and groups in the project navigator

To add existing files to a project
1.

In the project navigator, select the project or group to which you want to add the files.
Note that you can’t add files to a folder in the project navigator. When you add a folder reference to
the project navigator, any changes you make to the contents of the folder in the Finder are shown
immediately in the project navigator.

2.

Choose File > Add Files to “ProjectName ”
.

3.

In the dialog, select the file or files you want to add and click Add.
If the file is not in your project folder on disk, you can choose to copy the file into your project folder.


33

Get Oriented

If you select a folder in the dialog and select the “Create folder references for any added folders” radio
button, Xcode adds a folder reference to the project navigator. Although the project navigator shows
the files that are in that folder on disk, Xcode does not add those files to your project. To add all the
files in a folder to your project, either select the files individually, or select the “Create groups for any
added folders” radio button.

Click the New Folder button to add a folder to the disk and a reference to that folder to the project
navigator. Doing so does not add any files to your project.
You can use the project navigator to organize the files in your project into groups and to list the files and
groups in any order you like. The jump bar shows the same project organization as the project navigator down
to the file that’s open in the editor, and then shows the individual symbols in the file.
Click the name of a file in the project navigator to see the file in the editor pane. The type of editor or viewer
that displays the file depends on the type of file you selected.

To create a new group
Do one of the following:


34

Get Oriented

●

●

Place the cursor at the location in the project navigator where you want the group, Control-click, and
choose New Group from the shortcut menu. You can drag files into the group, and you can drag the
group to a new location in the navigator.
Select the files that you want to place in a new group, Control-click, and choose New Group from
Selection. Note that you can Command-click items in the navigator to get a discontinuous selection.

Click the name of the group to edit the name.


35

Get Oriented

The project navigator has filters for recently edited files, files with source control status, unsaved files, and
filename strings. Figure 1-16, for example, shows a project filtered to show only implementation (.m) files. The
filter field and buttons are at the bottom of the navigator area.
Figure 1-16

The project navigator filtered to show only .m files

Once you’ve navigated to a file in the project navigator, you can see the path to that file displayed in the jump
bar (Figure 1-17). You can use the jump bar to navigate through your project.
Figure 1-17

Project navigation


36

Get Oriented

Use a jump bar to directly navigate to items at any level in your workspace.

To use the jump bar . . .
1.

Click a level in the jump bar and choose a file to jump to.

2.

To open a related file in Assistant, hold down Option and choose that file.

3.

In the Assistant jump bar, choose a category of related files.

4.

Use the stepper arrows to advance to the desired file.

5.

Click the lock button to open a locked file, if appropriate.

See the HTML version of this
document to view the video.

A jump bar is an interactive, hierarchical mechanism for browsing items in your workspace. Each editor
area includes a jump bar, as do Interface Builder and the documentation organizer. The configuration and
behavior of each jump bar is customized for the context in which it appears. The basic configuration includes
three components:
●

The related items menu ( ) offers additional selections relevant in the current context, such as recently
opened files or the interface (.h) file for an implementation (.m) file you are editing.

●

Previous/next buttons (

) allow you to step back and forth through your navigation history.

●

Thehierarchicalpathmenu(forexample,
)
comprises one or more segments. Click a segment to choose from the menu of the items at that level
of the hierarchy.
An example of a basic jump bar is in the documentation organizer. It simply allows you to select documents
from installed libraries. Other jump bars have more components.
A jump bar may also include a stepper for iterating through a set of files (
(

) or issues. If a lock button

) appears, you can click it and authenticate to unlock the file, if appropriate.


37

Get Oriented

Hold down the Option key when selecting an item in the navigation bar to open Assistant and display that
item in the Assistant editor pane. In the Assistant jump bar, the path menu is rooted relative to the content
of the regular editor pane, and the root element (flagged with a light-bulb icon) offers selections similar to
a related items menu.
The video shows using the jump bar to view the class SKTCircle and then using the Assistant jump bar
to view its superclasses.
Tip: Hold down the Command key when selecting a level in the path menu to view its items
alphabetically.

Note that every element in the path in the jump bar is a pop-up menu that you can use to navigate through
your project. Hold down the Option key when selecting a file in the jump bar to open Assistant and display
the file in the assistant editor pane (you can change this behavior in the General pane of Xcode preferences).
The contents of the jump bar depend on the type of file you’re viewing. In Interface Builder, for example, the
jump bar lets you navigate to individual interface elements (Figure 1-18).
Figure 1-18

The jump bar in Interface Builder


38

Get Oriented

The jump bar also has back and forward buttons for moving through previously viewed files, and a pop-up
menu (

) that displays a variety of useful information about related items, as shown in Figure 1-19.

Figure 1-19

The related items pop-up menu

Browse to Project Symbols
Click the Symbol button in the navigator selector bar to browse through the symbols in your project. Note
that you need to wait until Xcode finishes indexing your project before you can use this feature.

To browse the class hierarchy
Do one of the following:
●

Display symbols in a hierarchical or flat list using the buttons at the top of the symbol navigator.
Refine which symbols are displayed using the buttons at the bottom of the navigator. Buttons are blue
when toggled on and black when off. Use the buttons in any combination:
●

—hides symbols other than classes and their members, including protocols, functions, structs,
enums, unions, types, and globals

●

—hides symbols defined only in external frameworks, displaying only symbols defined in the
project or workspace,

●

—hides member symbols defined within the classes such as methods, properties, and variables

Further refine the results list by typing into the filter field at the bottom of the navigator.
Select a symbol to display its header file definition in the source editor.


39

Get Oriented

The screenshot shows one button toggled on and the word “drawing” in the filter field. In the resulting
list, the bezierPathForDrawing method is selected and its definition is highlighted in the source
editor.

●

Click an element in the jump bar to see a list of symbols at that level in the project hierarchy.

Tip: Hold down the Option key when selecting a file in the jump bar to open Assistant and display the
file in the assistant editor pane (you can change this behavior in the General pane of Xcode preferences).


40

Get Oriented

FInd Text Strings
Find text strings in your project or workspace with the search navigator.
Search a workspace or a find scope for text that matches specific criteria.

To search for text in projects and frameworks . . .
1.

In the search field, enter the search term.

2.

Specify the find criteria.

3.

Specify the find scope.

4.

Press Return.

5.

If desired, refine the results by entering a filter term in the filter field.

Use the find criteria to specify the style (textual or regular expression), attributes, and capitalization of the
text to find.
Use the find scope to confine your search to a particular location or set of files.
Use a filter term to remove any results that do not match it from the search list.
The screenshot shows the find criteria and find scope areas open, and search results for NSArray filtered
by the text circle.


41

Get Oriented

Tip: Option-click a search result to see it displayed in the assistant editor pane.

To customize the search, click the magnifying glass in the search field and choose Show Find Options to get
the Find Options dialog. You can specify the type of text and the scope of the search.
Figure 1-20 The Find Options dialog

You can also replace text you’ve found. See "Replace Text Strings" (page 215) for details.

View Issues Discovered by Xcode
The issue navigator lists messages, warnings, and errors that Xcode identifies in your code and your project,
including issues found by Fix-it, the static analyzer, and the compiler.


42

Get Oriented

When a build fails, the issue navigator opens automatically, displaying all the issues found in the code. Click
an issue to see it displayed in the source editor. You can also navigate through the issues using the arrows and
pop-up menu in the right end of the source editor jump bar. See "Locate and Display Build Issues" (page 183)
for more information on the issue navigator.
Figure 1-21

The issue navigator

Manage Breakpoints
Whereas you set breakpoints in the source editor, the breakpoint navigator (Figure 1-22) is where you can see
all your breakpoints in one place. In addition, you use the breakpoint navigator to add conditions and options
to breakpoints.


43

Get Oriented

For more information on using breakpoints in debugging your code, see "Manage Breakpoints" (page 188).
Figure 1-22 The breakpoint navigator


44

Get Oriented

View Threads and Stacks
When your running code hits a breakpoint (or you use the debug bar in the debug area to pause execution),
the debug navigator shows the current state of the stack in each running thread. Click an item in the navigator
to see it in your source code and to see the values of variables in the debug area (Figure 1-23).
Figure 1-23 The debug navigator and associated editor and debug areas

For more information on using the debug navigator while debugging your code, see "Examine Threads, Stacks,
Variables, and Memory" (page 200).


45

Get Oriented

View Build, Source Control, and Debug Session Logs
When you perform an operation that is normally recorded, such as building or analyzing your code, or that
has output to the console, such as a source control operation or a debug session, the record of that operation
is listed in the log navigator. Select an item in the navigator to see the log in the editor pane (Figure 1-24).
Figure 1-24 Viewing a log

You can use the filter button and text field at the bottom of the navigator to limit the logs displayed to recent
logs or logs whose names match the text string you enter.
The log viewer has two distinct displays:
●

For noninteractive tasks, such as building and source control, the log viewer displays a scope bar that you
can use to specify the content to display (see Figure 1-24).
Successful operations have a checkmark icon next to them. Operations with warnings have a warning icon
(an exclamation mark in a yellow triangle). Operations with errors have an error icon (an exclamation mark
in a red octagon) next to them. The right side of the operation indicates the number of warnings and
errors the operation produced.
To view an operation’s warning or error messages, click the disclosure triangle on the left side of the
operation.
To view an operation’s transcript, click the transcript button (

●

) on the right side of the operation.

For interactive tasks, such as debugging sessions, the log viewer displays a transcript of the session.


46

Get Oriented

Find Information that Supplements the Editor
There are several types of information located in the utility area of the workspace window, including Quick
Help, the File inspector, Interface Builder inspectors, and libraries of file templates, code snippets, Interface
Builder objects, and media files.
To open the utility area, choose View > Utilities, or click the Utility button in the toolbar (Figure 1-25).
Figure 1-25 The utility button


47

Get Oriented

View and Edit the Properties of Specific Items
Inspectors are panes in the upper portion of the utility area that you can use to read or enter data about files
and Interface Builder objects, among other things. Which inspectors are available depends on which editor
you’re using. Compare, for example, the inspectors available for data models (Figure 1-26) with those for
Interface Builder (Figure 1-27).
Figure 1-26 Data model inspectors

Figure 1-27 Interface Builder inspectors


48

Get Oriented

Get Templates, Files, and Interface Builder Objects
The libraries in the lower portion of the utility area (Figure 1-28) provide file templates and code snippets that
you can drag into your project or workspace, user interface elements that you can use in Interface Builder, and
the media files (graphics, sound files, and so forth) used in your workspace. For more details on the use of the
libraries, see "Incorporate Files and Code from the Xcode Libraries" (page 148).
Figure 1-28 The library pane


49

Get Oriented

Check on the Progress of Xcode Tasks
The activity viewer in the workspace window toolbar shows the progress of any task Xcode is currently executing.
If two or more tasks are currently underway, a small number appears at the left edge of the activity viewer
(Figure 1-29). Click the number to open a pop-up window that shows the individual status of each current task
(Figure 1-30).
Figure 1-29 The activity viewer

Figure 1-30 The activity pop-up window

If there were any issues the last time you built or analyzed your code, an icon in the activity viewer indicates
the number and severity of issues found (Figure 1-31). Click the issues icon to see the issues in the issue
navigator.
Figure 1-31

Issues in the activity viewer


50

Get Oriented
The Organizer Window: Managing Projects, Devices, and Documentation

The Organizer Window: Managing Projects, Devices, and
Documentation
Xcode has two main windows. You’ve seen the workspace window (Figure 1-2 (page 16)), used for editing,
debugging, and interface design. The other main window, called the Organizer window , displays documentation,
source control, project organization, and for iOS, access to your mobile devices. To display the Organizer
window, choose Window > Organizer, or click the Organizer button in the toolbar (Figure 1-32).
Figure 1-32 The Organizer button

Browse and Bookmark Documents
To browse documentation, open the Organizer window, click the Documentation button in the toolbar, and
click the Browse button at the top of the navigation pane (Figure 1-33).
Figure 1-33 The documentation navigator


51

Get Oriented

While reading any page of documentation, you can choose Editor > Add Bookmark or Control-click and choose
Add Bookmark for Current Page to bookmark that page. Click the Bookmark button in the navigator pane to
see a list of bookmarks (Figure 1-34).
Figure 1-34 The bookmarks navigator

To select which documentation sets to download, use the Downloads pane in Xcode preferences.

To set documentation preferences
●

Set preferences for updating developer documentation using the Documentation tab of the Downloads
preferences pane.
Documentation is installed in the form of documentation sets, often called doc sets . Apple doc sets for
key developer libraries are installed with Xcode, and access to updates for them is controlled by
subscription. For your convenience, Xcode can automatically keep these subscriptions up to date. This
feature is controlled by the option “Check for and install updates automatically,” which is selected by
default. If this option is selected, Xcode displays the date and time of the last check.


52

Get Oriented

To check for updates manually, click the Check and Install Now button. If no new updates are available,
Xcode displays a message to that effect. When an update for a doc set is available but not yet installed
on your system, Xcode displays an Install button on the subscription line for that doc set. Click that
Install button to download and install the updated doc set on your system.
To install non-Apple documentation, subscribe to the associated documentation feed. First, obtain the
web (RSS) feed URL from the publisher. Click the Add (+) button, as shown in the figure, follow the
onscreen instructions to enter the URL, and click Add in the dialog.
To remove a doc set from your system, select the subscription entry for the doc set, then click the doc
set info button. Click the Installed Location link to show the doc set file in the Finder, then delete the
file from the Finder.
To unsubscribe from non-Apple documentation, select the subscription entry for the doc set, click the
Remove (-) button and confirm the removal operation.
Note: You can remove an Apple doc set from your system, but you cannot remove the subscription to
its doc set feed.
At the bottom of the pane, you can set a minimum font size for documentation organizer content by
selecting the option "Never use font sizes smaller than," and then choosing a font size from the pop-up
menu.


53

Get Oriented

Browse for Task-Based Help
Online help is available for the Xcode IDE. To browse the Xcode online help, open the Xcode 4 Developer Tools
Library in the documentation navigator, then open Tools and Languages, then IDEs (Figure 1-33 (page 51));
or choose Help > Xcode Help to get the start screen shown in Figure 1-35.
Figure 1-35 Xcode help start screen

Many of the articles in Xcode help include a short video that illustrates the described procedure. Click the video
thumbnail to play the video.
To help you discover and understand the many user interface features of Xcode, most of the help articles are
also available as contextual help. See "Contextual Help: Your Shortcut to Answers" (page 15) for details.

Work with Your Source Control Repositories
Click the Repositories button in the Organizer window toolbar to work with your source control repositories.
You can create local repositories, connect to and manage repositories on servers, and so forth. You can also
perform many common SCM operations, such as submitting files, from the workspace window. To do so, select
the file or files in the project navigator, Control-click, and choose Source Control from the menu. See "Keep
Track of Changes with Source Control " (page 253) for details.


54

Get Oriented

Organize Your Projects and Devices
Whereas Xcode allows you to have several workspace windows open simultaneously, there is only one Organizer
window. The Organizer window displays information for all your workspaces, projects, repositories, devices,
and documentation, regardless of how many projects you have and how many are open.
Click the Projects button in the toolbar to display all your projects, their snapshots, and archives.
If you’re working with iOS, the Xcode Organizer window also can display the devices that you have connected
to your computer. It indicates which of these devices are currently available and lets you select the one to use.
For more information on the use of iOS devices with Xcode, see "Manage Your Devices" (page 225).

Take a Snapshot of Your Project
To save a snapshot of your project, choose File > Create Snapshot. Note that you must have selected System
Tools in the Xcode installer in order to use snapshots. System Tools are selected by default.
To see what snapshots have been saved in Xcode, open the projects organizer and click the project in which
you’re interested. For more information on snapshots, see "Take a Snapshot of Your Project" (page 252).


55

Start a Project

This chapter tells you how to start a new Xcode 4 project, either by creating a new project from scratch, or by
opening an existing Xcode 3 project. Once you’ve got your projects open, go to "Get Oriented" (page 15) to
learn more about using Xcode 4.

Click New Project in the Xcode 4 Startup Screen to Create a
Standalone Project
If you want to start a new software development undertaking using Xcode 4, you need to first decide whether
you need a single Xcode project or multiple related projects. For a simple application or utility, a single project
should suffice. However, if you have several related executables that need to link against a custom library, you
probably want at least a separate project for the library and another for the executables, and possibly a separate
project for each executable.
Start developing a software product by creating a project. All software products require a project. The project
organizes the files and resources needed to build one or more products, such as applications, plug-ins, and
command-line tools.

To create a standalone project . . .
1.

Choose File > New > New Project.

2.

Select the project template for your iOS or OS X product, and click Next.

3.

Enter the product name and other project details, and click Next.

4.

Specify the project’s location in your file system, and click Save.



56

Start a Project
Click New Project in the Xcode 4 Startup Screen to Create a Standalone Project

The New Project dialog displays platforms, template families, project templates, and a description for the
selected project template. In the project options pane you enter information required by the template to
generate the project, such as the product name.
Note: The New Project dialog appears in the workspace window for the workspace to which
Xcode will add the project. When you create a project with no workspace window active, the
New Project dialog is attached to a new workspace window that contains only the new project.

The project location in your file system and its container in the workspace window are both derived from
your selection in the project navigator when you initiated the New Project command. That is, if you have
a project selected in the project navigator, Xcode places the new project inside the selected project. The
Save dialog lets you specify a different location and container for the new project before completing the
operation. For example, you can indicate that the container of the project be a group within your workspace
instead of the workspace itself.
The video shows how to create a project named MyProject and place the project directory on the Desktop.
After saving the project, Xcode places a folder containing the new project’s files at the location you specified.
Once you’ve created a project, you can add new source files and begin writing code.
If you have two or more closely related projects, you should create a workspace and add your projects to it, as
described in "Create a Workspace to Work with Multiple Related Projects" (page 59).


57

Start a Project
Click New Project in the Xcode 4 Startup Screen to Create a Standalone Project

Create a Git Repository For Your New Project
You can create a local Git repository when you save the new project (Figure 2-1). This is the easiest way to add
source control to a project (see "Keep Track of Changes with Source Control " (page 253) for more information).
Figure 2-1

The option to add source control when creating a project

Select Options While Creating a New Project
Both Mac OS X and iOS support use of the Core Data frameworks. To add core data modeling to your new
project, select the Use Core Data option in the New Project dialog. See "Design Data Models Graphically" (page
26) for more information.


58

Start a Project
Create a Workspace to Work with Multiple Related Projects

You can also choose to use automatic reference counting, include unit tests, or include Spotlight Importer in
your project (Figure 2-2). The files that Xcode creates for your new project depend on the options you select
in the new project dialogs.
Figure 2-2

Options for a new project

Note that Core Data is an advanced technology that is not required for creating simple applications.
To add automatic reference counting (ARC) to an existing project, see "Add Automatic Reference Counting" (page
64).

A major feature of Xcode 4 is the ability to create a container for multiple projects that you can use to group
Xcode projects and other files that are related. This container is referred to as an Xcode workspace . All the
projects in the workspace share the same build directory. Putting your related projects in the same workspace
affords you several benefits, including:
●

●

●

One project can use the products of another project while building.
If one project depends on the products of another in the same workspace, Xcode can detect this and
automatically build the projects in the correct sequence.
Because all the files in one project are visible to all the other projects in the workspace, you don’t need to
copy shared libraries into each project folder separately.


59

Start a Project

●

Indexing is done across the entire workspace, extending the scope of content-aware features such as code
completion.

To create a workspace
1.

If Xcode is not open, open it. You can ignore or cancel the startup screen. If you already have an Xcode
project open, go on to the next step.

2.

Choose File > New > New Workspace.

3.

In the New Workspace dialog, specify the location for the workspace file and the name of the workspace.
If your projects are in the same directory, it might be convenient to put the workspace file in there as
well. Click Save.
Tip: To avoid possible confusion with your projects, give the workspace a unique name.

You now have a workspace with no projects in it. You can add existing projects to the workspace, or create
new ones.
You can add any existing project to the workspace, or Control-click in the structure navigator below the existing
projects and select New Project to create a project in the workspace.


60

Start a Project

Add an existing project to a workspace to add a product to a multiproduct development endeavor. When you
need to work on two or more related projects, you can add them to a workspace so that you can create
interproject relationships.

To add an existing project to a workspace . . .
1.

In the project navigator, Control-click in the empty space below the list.

2.

Choose Add Files to “<WorkspaceName>”
.

3.

Navigate into the folder containing the project package.

4.

Select the project package and click Add.


For example, you can have a workspace with an application project, add a framework project to the
workspace, and make the application dependent on the framework. When you build the application, Xcode
builds the library first, if it needs to be built.
When adding a project to a workspace, you add the project package. A project package is a directory that
the Finder displays as a file. It contains information about the project, such as references to the files that
are part of the project, the project’s groups, build settings, and target definitions.
The video shows the process of adding a second project, called MyFramework, to a workspace called
MyWorkspace.
After you add a project to your workspace, the project appears in the project navigator.


61

Start a Project

Alternative: You can drag a project package from a Finder window or a workspace window to
the project navigator in a workspace window to add the project to the second workspace. When
doing so, ensure that you add the project package to the root of the project navigator and not
a project within it.

Note: If you choose File > New > New Project while any project is selected, or Control-click inside
an existing project and choose New Project, Xcode adds the project file inside the currently selected
project. The only way to undo this operation is to delete the new project. Figure 2-3 shows the
shortcut menu you get when you Control-click below the existing projects. Note that, in this case,
the Add Files menu item specifies the name of the workspace, not of one of the existing projects.
Figure 2-3

A shortcut menu for a workspace

Because each project retains its individual identity, a project can be included in more than one workspace or
removed from a workspace without affecting the project. The workspace file itself merely contains pointers to
the projects and other files that the workspace includes, plus a minimal amount of data such as schemes stored
in the workspace. The pointers to the source files, included libraries, build configurations, and other data are
stored in the project files.


62

Start a Project
Check Out a Working Copy from Your Source Control Repository

Tip: If you have an Xcode project and would like to create a workspace to contain it, choose File > Save as
Workspace. You can assign a new name to the workspace and specify a location for the workspace file. Doing so
does not alter the original project or prevent you from adding the project to another workspace as well.

If the build product of one project in a workspace is dependent on the build product of another project in the
workspace (for example, if one project builds a library used by the other project), Xcode discovers such implicit
dependencies and builds in the correct sequence. If you don’t want one project to use the product or files in
another project that’s in the same workspace, you need to adjust your build settings accordingly. See "To add
a new build configuration" (page 66) for help in finding and understanding the build settings interface in
Xcode.
Before you build, be sure you’ve created the scheme or schemes you need. See "Create, Edit, and Manage
Schemes" (page ?) for more information on schemes.

Check Out a Working Copy from Your Source Control Repository
If your Xcode project is in a Git or Subversion repository, you can check out your project from the repository
and open it in Xcode. See "Keep Track of Changes with Source Control " (page 253) for more information on
using source control in Xcode.

Modernize Your Project
When you open a project, Xcode 4 evaluates it to see 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 2-4) to see whether anything in your project needs to be updated. You can
also select the project in the project navigator and choose Editor > Check for Outdated Settings, or choose
the project from the the drop-down issues menu at the right end of the jump bar.
Figure 2-4

Modernization in the Issue navigator


63

Start a Project
Add Automatic Reference Counting

If the issue navigator lists modernization issues, click the issue to see a dialog that explains the updates that
should be made (Figure 2-5). Deselect any checkboxes for settings you don’t want to change, then click Perform
Changes to update the project to optimize it for Xcode 4.
Figure 2-5

Updates dialog

After you have clicked Perform Changes, whether you choose to make all the changes or not, Xcode does not
show the warning again. To rerun the check, select your project in the project navigator and choose Check for
Outdated Settings from the Editor menu.

Add Automatic Reference Counting
Xcode 4.2 and later includes a menu item to convert existing targets to use Automatic Reference Counting
(ARC), which automates memory management for Objective-C objects. ARC makes memory management
much easier, greatly reducing the chance that your program will have memory leaks. First, Xcode reviews your
project to determine whether there are items that cannot be converted (and that you must therefore change
manually). Then, Xcode rewrites your source code to use ARC. (To add ARC to a new project, see "Select Options
While Creating a New Project" (page 58).)
To initiate the process, enable Continue building after errors in the General Preferences pane, then choose
Edit > Refactor > Convert to Objective-C ARC. The targets that you convert are updated to build using the
Apple LLVM compiler. Xcode attempts to build your target and to determine what changes must be made to


64

Start a Project
Close a Project or a Workspace

use ARC. If it finds any issues that prevent conversion, Xcode displays a dialog directing you to review the
errors in the Issue navigator. After you correct the errors, choose the Convert to Objective-C Automatic Reference
Counting menu item again to restart the ARC-conversion workflow.
When Xcode successfully builds your application, it takes a snapshot of the current code so that you can revert
later if you want to. Then Xcode displays a preview dialog showing the changes it’s going to make. When you
accept the changes, Xcode converts your code to use ARC.
For more information on ARC, see Transitioning to ARC Release Notes .

Close a Project or a Workspace
Choose Close Project or Close Workspace from the File menu to close a project or workspace without closing
Xcode. In Xcode 4.1 and later, Xcode remembers which windows you had open and how they were configured,
and restores them when you reopen the project or workspace. Also in Xcode 4.1 or later, pressing
Command-Option-W or holding down the Option key and clicking the close box closes the project or workspace
without first closing all windows and tabs. In this way, your window configuration is restored the next time
you open the project.


65

Configure Your Project

During the course of developing an application, you need to build, run, and debug your code. As part of
optimizing your code and ensuring quality control, you might also run unit tests, perform static analysis, and
use profiling tools to find memory leaks, inefficient routines, and other run-time problems. Finally, you’ll
probably want to archive your application in order to share it with others or submit it for inclusion in the App
store.
In order to carry out all these actions, you need to edit a few basic build settings and set up one or more
schemes to specify the targets, build configuration, and executable configuration to use for each type of action.
In Xcode you use the project editor and the scheme editing dialog to customize your builds and control what
happens when you build and run your code.

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.


66


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.


67


6.

Click the Build Settings button to display the build settings for the project.

7.

To change the build settings in the new configuration for all the targets in the project, edit them at
the project level. To change the build settings for an individual target, select that target.

8.

Select each build setting you want to edit and click the disclosure triangle to display the list of build
configurations.

9.

Select the new configuration and edit the setting.

You can use a build configuration file to set and to share build configurations. A build configuration file is a
plain text file with the filename extension .xcconfig that contains a list of build setting definitions, one per
line. The build configuration file must be in your project.
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 . . .
1.

In the project editor, select the project for which you want to use a build configuration file.

2.

Click Info at the top of the project editor.

3.

In the Configurations section, navigate to the build configuration you want to base on a configuration
file.


68

Set the Basic Build Settings

4.

Choose a configuration file from the pop-up menu in the right column.


When you base a target or project’s build configuration on a configuration file, that build configuration
automatically inherits the build setting definitions in that configuration file (and any configuration files it
includes). If you then modify the value of any of those build settings in the target or project, the new value
is used instead of the value in the configuration file.
Build settings defined at the target level override any values assigned to those build settings at the project
level. Therefore, target-level configurations take precedence over any project-level configurations.
The video shows basing the Debug build configuration on a file called Config.xcconfig at the project
level.

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. 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 one pane in the project editor—labeled the Summary pane—and are somewhat different for Mac OS X
and iOS projects.

To edit the basic build settings for Mac OS X targets
1.

In the project editor, click the target.


69


2.

At the top of the project editor pane, click the Summary button.

3.

To select an icon for your product, Control-click the App Icon image well and choose Select File (or
drag an icon file directly to the image well).

4.

To add a linked framework or library to your target, click the Add (+) button at the bottom of the Linked
Frameworks and Libraries section.
For example, to provide your target with access to audio hardware, add the Core Audio framework.

Each setting in the Summary pane is also found in one of the other panes. When you edit a setting, Xcode
updates the other pane automatically. Table 3-1 lists each setting in the Mac OS X Summary pane along with
the corresponding target setting and location.
Table 3-1

Mac OS X project editor Summary pane settings

Summary pane setting

Target setting

Pane

Identifier

Bundle identifier

Info

Version

Bundle version

Info


70



Target setting

Pane

This app runs on Mac OS X

Mac OS X Deployment Target

Build Settings

Main interface

Main nib file base name

Info

App icon

Icon file

Info

Linked frameworks and libraries

Link Binary With Libraries

Build Phases

To edit the basic build settings for iOS targets
1.

In the project editor, click the target.

2.

At the top of the project editor pane, click the Summary button.

3.

Select an icon for your app.


71

Add Build Rules

Control-click one of the App Icons image wells and choose Select File (or drag an icon image into the
image well).
4.

Select a launch image.
Control-click one of the Launch Images image wells and choose Select File (or drag an image into the
image well). You can drag a launch image directly from the Screenshots library in the Devices pane of
the Organizer window.

5.

Choose a target device from the Devices pop-up menu.
Choose Universal to configure your iOS app to run on both iPhone and iPad.

As for Mac OS X projects, each setting in the Summary pane for an iOS project is also found in one of the other
panes. When you edit a setting, Xcode updates the other pane automatically. Table 3-2 lists each setting in
the iOS Summary pane along with the corresponding target setting and location.
Table 3-2

iOS project editor Summary pane settings


Target setting

Pane

Identifier

Bundle identifier

Info

Version

Bundle version

Info

Devices

Targeted Device Family

Build Settings

This app runs on iOS

iOS Deployment Target

Build Settings

Main Interface

Main nib file base name

Info

Supported Device Orientations

Supported interface orientations

Info

App Icons

Icon files

Info

Launch Images

Launch Image

Info

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.


72

Add Build Rules

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.

At the top left of the Build Rules pane, click the All button.

To customize a build rule for a target
1.

Display the default build rules for the target ("Add Build Rules" (page 72)).

2.

At the right margin of the build rule you wish to customize, click the Copy to Target button.

3.

Fill in the build rule template that appears.


73

Add Build Rules

4.

Click the Target button at the top of the Build Rules pane to see and edit the customized build rules
you’ve added.

You can click the Add Build Rule button at the bottom of the Build Rules pane to create a new build rule.
Change the way files are processed with build rules.

To add a build rule . . .
1.

In the project editor, select the target to which you want to add a build rule.

2.

Click Build Rules at the top of the project editor.

3.

Select Target at the top of the Build Rules pane.

4.

Click Add Build Rule in the lower-right corner.

5.

Choose a file type from the Process pop-up menu.


74

Add Build Rules

6.

Choose a compiler from the Using pop-up menu.

You can define build rules on a per-target basis. Target-specific build rules can specify files that the system
build rules do not directly address and can override the existing system build rules, which are predefined
and unmodifiable.
The Process and Using menus include many types of files and many compilers, but you can specify custom
file types or compilers by choosing “Source files with names matching:” from the Process menu or “Custom
script:” from the Using menu.
The screenshot shows a build rule that compiles C source files with GCC 4.2 rather than the default compiler.


75

Edit User Interfaces

You design user interfaces in Xcode using Interface Builder. Interface Builder is an Xcode editor that provides
a graphical interface for the creation of user interface files. Like other Xcode editors, Interface Builder is fully
integrated into the application, so you can write and edit source code and tie it directly to your user interface
without leaving the Xcode workspace window.
When you create a new Mac OS X or iOS application, Xcode includes one or more Interface Builder files in the
project. These files, called nib files, may have the filename extension nib or xib. Similarly, when you create a
new view controller, Xcode includes a nib file along with the header and implementation files for the new
class. For iOS applications, you can use storyboards instead of nib files, as described in "Design the User Interface
of Your iOS App with Storyboards" (page 92).

Create Your User Interface
Interface Builder, like other Xcode editors, has associated inspectors and libraries in the utility area. Interface
Builder appears in the editor area of the workspace window when you select a nib file or storyboard file in the
project navigator. When you open a nib or storyboard file, your user interface objects appear in the editor area
and the Interface Builder inspectors appear in the utility area. You use these inspectors to configure the interface
objects and to make connections between them. The Object and Media libraries in the library pane of the
utility area are also for use with Interface Builder—you use these libraries to add new objects to your user
interface design.


76


Figure 4-1 shows Interface Builder and associated panes open in the workspace window. You can select Interface
Builder objects and media files in the library pane and drag them onto the Interface Builder canvas. You can
also open an assistant editor, which shows a file or files associated with whatever object you’ve selected in the
Interface Builder pane.
Figure 4-1

Interface Builder in the workspace window


77


Display Your User Interface Objects
The dock on the left side of the Interface Builder pane shows the Interface Builder objects and placeholders in
your nib or storyboard file. The dock can display the high-level objects in an icon view (Figure 4-2) or in a list
(called the outline view ) showing all the objects nested in higher-level objects. Storyboard files show only the
outline view in the dock; however, each scene in the storyboard has its own scene dock displayed below it
when you select the scene (see, for example, Figure 4-11 (page 95)).
Figure 4-2

Icon view for placeholders and objects in Interface Builder

Add new objects to an Interface Builder document using the outline view, a hierarchical tree that reflects the
parent-child relationships between the objects in the nib file.

To add an object using the outline view . . .
1.

With a nib file open, toggle the dock to outline view, if necessary, by clicking the dock mode button
at the bottom of the dock.

2.

Navigate to the place in the outline where you want to add the object.


78


3.

Drag an object from the Object library (in the utility area) into the outline.


The video shows how to add a text formatter object to a text field cell using the outline view.

Tip: To return to the icon view, click the dock mode button (

) again.

Note that you can also use the Interface Builder jump bar to select any object in the interface.

Connect to Other Files Using Placeholder Objects
There are two kinds of objects displayed in the Interface Builder dock: Interface objects and placeholder objects.
Interface objects are the objects that are actually created when the nib file is loaded and typically comprise
the bulk of the objects. Placeholder objects refer to files that live outside of the nib file but which are intimately
tied to the contents of the nib file. There are normally three placeholder objects in a nib file:
●

File’s Owner

●

First responder

●

Application

File’s Owner
File’s Owner Represents the nib file’s controller object. File’s Owner is the most commonly used placeholder
object in nib files and is supported by both Mac OS X and iOS nib files. The File’s Owner placeholder is the
main bridge between your application and the contents of the nib file.
When you build and run your application, the nib-loading code substitutes the object that is the file’s owner
for any references to the File’s Owner placeholder in the nib file. This substitution results in the outlets and
actions connected to the File’s Owner placeholder being connected to the object that is the file’s owner.
You can designate any object in your application as the File’s Owner of a nib file. You tell Interface Builder the
class of the File’s Owner so it knows what connections to make available. Typically, the file’s owner is a controller
class that manages the interactions with the views and other controller objects inside the nib file.


79


To configure the File’s Owner placeholder
1.

Select the File’s Owner placeholder object in the Interface Builder dock

2.

Open the Identity inspector.

3.

In the Class field of the Custom Class section, set the class of the File’s Owner to the corresponding
class in your application.
The following table lists some of the standard classes that are commonly used to represent File’s Owner
in applications:
Subclass of

Description

NSDocument

Mac OS X

Document-based applications store the document
window and other required interface objects in a
nib file. The File’s Owner of this nib file is
traditionally the document object itself.

NSWindowController

Mac OS X

Window controllers provide a great deal of
automatic management for nib files and are
especially useful when your nib file contains only
one window.

NSViewController

Mac OS X

A view controller manages custom accessory views
and other view-based content.

UIViewController

iOS

A custom UIViewController object is often used
to manage the content view for a distinct screen’s
worth of content. A UI view controller provides
automatic nib-loading and purging support.

Any custom NSObject
subclass

4.

Operating
System

Mac OS X
or iOS

You can use practically any object you like for
manual control of a nib file. It is up to you to define
the relationships between this class and the objects
in your nib file.

Control-click the File’s Owner object to see the outlets and actions defined by that class.

To learn about outlets and actions, see "Manage Connections Between User Interface Objects" (page 106).
You can use these outlets and actions to connect other objects to File’s Owner. You can use File’s Owner
as a target for your bindings. For information about connecting to File’s Owner, see "Make Connections
Directly Between IB Objects and Your Code Files" (page 107).


80


First Responder
The First Responder placeholder object represents the first object in the responder chain, which is determined
dynamically at runtime by the AppKit and UIKit frameworks.

To add new action messages to the first responder’s supported list
1.

Select the First Responder placeholder object in your Interface Builder document.

2.

Open the Attributes inspector.

3.

Click the Add (+) button at the bottom of the User Defined section to create a new action method
entry.

4.

Double-click the method name in the Action column and type the name of the method.

5.

Select the class in which the method will be defined from the pop-up list in the Type column.

6.

After you are done making connections in Interface Builder, add the code for the method to the header
and implementation class files in your project that you specified in step 5.
The name of the method must match the name specified in step 4.

Adding action methods to the First Responder placeholder object does not add the corresponding method
definition to your Xcode source files. All it does is let Xcode know that such a method exists in one of the
objects in the responder chain of your project. It is up to you to ensure the method names you add to the
First Responder placeholder match the names of the methods in your code. Xcode does not validate these
method names for you. At runtime, if a method name is misspelled or does not exist in an object, the
corresponding action message is never received by the target object.
Interface Builder does not prevent you from deleting the standard system messages associated with the
First Responder placeholder. Doing so removes the message name from the current nib file only.
When Mac OS X or iOS sends a message to your application, the message is sent to your application’s first
responder. The first responder is typically the currently selected object or the object with the current focus in
the frontmost window. You use the First Responder object to make connections to any messages that operate
on the current selection or need to be handled by your frontmost window or document. For example, if you
wanted a menu command to be handled by your frontmost window, you would dispatch that command to
your First Responder object.
The First Responder placeholder displays all of the actions that are either supported natively by the operating
system or defined in your Xcode source files.


81

Xcode4 userguide Apple

Recommandé

Recommandé

Contenu connexe

Similaire à Xcode4 userguide Apple

Similaire à Xcode4 userguide Apple (20)

Plus de Pragati Singh

Plus de Pragati Singh (20)

Dernier

Dernier (20)

Xcode4 userguide Apple