Xcode 4 Transition Guide

Xcode 4 Transition
Guide
Contents
About the Transition to Xcode 4 8

At a Glance 8
Use Xcode 4 for Development on Recent OS Versions 9
Open Your Project in Xcode 4 9
Get Oriented to Xcode’s Organization and Features 9
Learn How to Use Xcode 4 to Design a User Interface 9
Debug and Refine Your Code In Xcode 4 10
Back Up Your Code and Use Source Control 10
Use Archives to Distribute Your Program 10
Using an Existing Xcode 3 Project 11

Open Your Xcode 3 Project in Xcode 4 11
See Your Groups and Files 12
Replace Your Interface Builder Plug-ins 14
Keep Your Xcode 3 Preferences 14
Check Out a Working Copy 15
Modernize Your Project 17
Work with Multiple Related Projects 18
Creating a New Xcode 4 Project 21

Create a Standalone Project 21
Create a New Workspace 21
Orientation to Xcode 4 22
Much of Your Project’s Content Is in New Locations 22
Set Build Settings for Each Target 23
Set Basic Build Settings 25
Set Up a Sandbox for Each Target 25
Select Any File to Open an Editor 27
Write and Edit Source Code 27
Speed Up Typing with Code Completion 28
Have Fix-it Flag Errors as You Type 30
Open a File in the Assistant Editor Pane 30
View Files in Hexadecimal Format 30
2011-08-10 | © 2011 Apple Inc. All Rights Reserved.
2
Contents
View Preprocessor or Assembly Output 31

View Key Names or Raw Keys 31
Select a Scheme 31
Specify Which Targets Are Built 32
Customize Executables 34
Rename or Reorganize Your Schemes 34
Search Your Workspace 35
Browse to Project Symbols 37
Filter to FInd Related Content 40
View Details 41
Customize the Build and Run Workflow 41
Check on the Progress of Xcode Tasks 45
View Projects, Devices, and Documentation 45
Browse and Bookmark Documents 46
Browse for Task-Based Help 48
Work with Source Control Repositories 48
Organize Projects and Devices 49
Archive Your Product for Distribution 49
Find Answers with Contextual Help 49
Save Changes Automatically 50
Split the Editor Area 51
Find Related Content 51
Use Assistant with Interface Builder 52
Display Content of Your Choosing 52
Compare Two Versions of Your File 52
Open a New Tab or a New Window 52
Open Files with Keyboard Shortcuts 53
Open the Utility Area 54
View Quick Help 55
View and Edit File and Interface Builder Data 59
Drag Files and Code from the Library 59
Close a Project or a Workspace 62
Designing User Interfaces in Xcode 4 63

Design Your UI in Xcode 63
Create a New Nib File 64
Create New UI Classes in Xcode 64
Add Source Files First 65
Add a Custom View 67
3
Contents
Create an Interface Controller 68

Use Assistant to Work on Your UI Code 69
Make Connections Directly with Source Code 72
Get Online Help in IB 74
Find UI Objects in the Dock 74
Get More Information on IB 75
Debugging and Analyzing Your Code 77

Select a Debugger 77
Find Potential Problems with Static Analysis 78
Locate Build Errors 79
View Build Results 81
Manage Breakpoints 82
Examine Threads and Stacks 84
Control Program Execution 85
Replacing Text and Refactoring 89

FInd and Replace Text 89
Preview Changes 91
Refactor Your Code 92
Repositories, Snapshots, and Archives 95

Take a Snapshot of Your Workspace 95
Keep Track of Changes and Coordinate Work Groups 97
Set Up Git Version Control 99
Commit Files to Add Them to a Repository 99
Reconcile Different Branches 100
Save Internal Project Files in Repositories 102
Compare Revisions 102
Select Revisions to Compare 104
Review Individual Changes 104
List All Revisions Chronologically 106
Distribute Your Program or Submit an Application 106
Document Revision History 108
4
Figures
About the Transition to Xcode 4 8

Figure I-1 The Xcode 4 workspace window 8
Using an Existing Xcode 3 Project 11

Figure 1-1 A newly opened Xcode 4 window with an Xcode 3 project 12
Figure 1-2 The project contents in the Xcode 4 project navigator 13
Figure 1-3 IB plug-in upgrade dialog 14
Figure 1-4 Modernization in the issue navigator 17
Figure 1-5 Updates dialog 18
Orientation to Xcode 4 22
Figure 3-1 Target information in the project editor 23
Figure 3-2 Build settings 24
Figure 3-3 The Mac OS X summary pane 25
Figure 3-4 Mac OS X entitlements editor 26
Figure 3-5 Entitlements property list 27
Figure 3-6 Code completion 28
Figure 3-7 Quick help for code completion 29
Figure 3-8 Code completion underlining 29
Figure 3-9 Fix-it in action 30
Figure 3-10 The Scheme pop-up menu 32
Figure 3-11 The scheme editor Build pane 33
Figure 3-12 Customizing an executable environment for a product 34
Figure 3-13 The find navigator 35
Figure 3-14 The Find Options dialog 36
Figure 3-15 The symbol navigator 37
Figure 3-16 The symbol navigator, filtered 38
Figure 3-17 A symbol displayed in the source editor 38
Figure 3-18 Using the jump bar to find a symbol 39
Figure 3-19 The related-items pop-up menu 39
Figure 3-20 The project navigator filtered to show only .m files 40
Figure 3-21 Run diagnostic options 42
Figure 3-22 Behaviors preferences 43
Figure 3-23 Naming a tab 44
5
Figures
Figure 3-24 The activity viewer 45

Figure 3-25 The activity pop-up window 45
Figure 3-26 The Organizer button 45
Figure 3-27 The documentation navigator 46
Figure 3-28 The bookmarks navigator 47
Figure 3-29 Finding Xcode 4 help articles 48
Figure 3-30 Contextual help 50
Figure 3-31 The Assistant button 51
Figure 3-32 Setting the behavior for Assistant 51
Figure 3-33 The Single Assistant navigation chooser dialog 53
Figure 3-34 The navigation chooser dialog 54
Figure 3-35 The Utility button 55
Figure 3-36 The Quick Help window 55
Figure 3-37 The Symbol inspector 56
Figure 3-38 Quick Help for Interface Builder objects 57
Figure 3-39 Quick Help for build settings 58
Figure 3-40 A file inspector 59
Figure 3-41 A file template information pop-up window 60
Figure 3-42 Dragging a piece of a code snippet into your file 61
Figure 3-43 A user-customized code snippet 61
Designing User Interfaces in Xcode 4 63

Figure 4-1 Interface Builder in the workspace window 63
Figure 4-2 Dropping a nib file in the Resources group 64
Figure 4-3 Creating new class files 65
Figure 4-4 Adding a new Window nib file 66
Figure 4-5 Assigning a class to an Interface Builder object 67
Figure 4-6 Adding a custom view 68
Figure 4-7 Adding a controller object to a nib file 69
Figure 4-8 Selecting a counterpart to a nib file in assistant 70
Figure 4-9 Interface Builder with the assistant editor open 71
Figure 4-10 Making a connection to source code from Interface Builder 72
Figure 4-11 Inserting an action or outlet statement in your header file 73
Figure 4-12 Connection insertion dialog 73
Figure 4-13 Help articles in Interface Builder 74
Figure 4-14 Outline view for placeholders and objects in Interface Builder 75
Debugging and Analyzing Your Code 77

Figure 5-1 Selecting a debugger in the scheme editor 77
Figure 5-2 Static analysis results 78
6
Figures
Figure 5-3 The issue navigator 79

Figure 5-4 The issues pop-up menu 80
Figure 5-5 The build log 81
Figure 5-6 The build log with a verbose build command 82
Figure 5-7 Setting breakpoint options 83
Figure 5-8 Scopes of breakpoints in the breakpoint navigator 84
Figure 5-9 The debug navigator stopped at a breakpoint 85
Figure 5-10 The debug area 86
Figure 5-11 Navigating through threads and stacks in the debug bar 87
Figure 5-12 Activating the continue-to-here command 87
Figure 5-13 Reading the value of a variable in the source editor 88
Replacing Text and Refactoring 89

Figure 6-1 Find/Replace pop-up menu 90
Figure 6-2 Find/Replace results 90
Figure 6-3 Activity viewer during a Find operation 91
Figure 6-4 Replacement preview 91
Figure 6-5 Refactor preview dialog 93
Repositories, Snapshots, and Archives 95

Figure 7-1 Snapshots listed in the Organizer window 96
Figure 7-2 Repositories Organizer 97
Figure 7-3 Source control badges in the project navigator 98
Figure 7-4 The Source Control submenu 98
Figure 7-5 Commit confirmation 100
Figure 7-6 The Merge dialog 101
Figure 7-7 A scheme in the commit dialog 102
Figure 7-8 Comparing two revisions of a file with the version editor 103
Figure 7-9 Using the version editor timeline 104
Figure 7-10 Version editor Blame mode 105
Figure 7-11 Version editor Log mode 106
Figure 7-12 Archives organizer 107
7
About the Transition to Xcode 4
Xcode 4 is the latest iteration of Apple’s integrated development environment (IDE). This document is intended
for developers who are familiar with Xcode 3 and want to get started quickly using Xcode 4. If you want a short
tutorial that introduces you to the major features of Xcode 4, see Xcode Quick Start Guide . If you want a more
complete introduction to the features and workflows of Xcode 4, see Xcode 4 User Guide .
Figure I-1 shows the main user interface elements described in this document.
Figure I-1 The Xcode 4 workspace window
Xcode 4 uses one type of main window, called the workspace window , to hold most of the data you need. You
can have as many workspace windows open as you need. A second window, called the Organizer window, is
used for organizing your projects and reading documentation. For iOS projects, the Organizer window is also
used for managing devices.
At a Glance
There are many improvements and new features in Xcode 4. A very partial list includes:
● Xcode 4 has a new, single-window interface for all major workflows (you can have multiple workspace
windows and multiple tabs per window).
● Interface Builder is fully integrated with the main Xcode application.
8
At a Glance
● Assistant provides a second editor pane that complements the file you’re working on—for example, if
you’re working on an implementation file, it can automatically find and open the corresponding header
file.
● Fix-it checks your symbol names and code syntax as you type, highlights any errors it detects, and in some
cases can even fix them for you.
● The version editor works with Git or Subversion to show a file’s entire SCM history and compare any two
versions of a file.
● The LLVM 2.0 compiler includes full support for C, Objective-C, and C++.
● The LLDB debugger is faster and uses less memory than the GDB debugging engine.
● Xcode 4 lets you work on several interdependent projects in the same window, automatically determining
dependencies so that it builds the projects in the right order.
Use Xcode 4 for Development on Recent OS Versions

Xcode 4 runs on the current release of Mac OS X and comes with current releases of Mac OS X and iOS software
development kits (SDKs).
Open Your Project in Xcode 4

You can start a new project or open your Xcode 3 project in Xcode 4. Following this introduction, the first
couple of chapters help you get started.
Relevant Chapters: “Using an Existing Xcode 3 Project” (page 11), “Creating a New Xcode 4 Project” (page 21).
Get Oriented to Xcode’s Organization and Features

Xcode 4 is fundamentally different than Xcode 3, so whether you’re new to Apple platforms or an experienced
Apple developer, you should read the next chapter to learn about Xcode 4.
Relevant Chapter: “Orientation to Xcode 4” (page 22).
Learn How to Use Xcode 4 to Design a User Interface

One of the most obvious differences between Xcode 3 and Xcode 4 is that Interface Builder is now fully
integrated into the Xcode application. The chapter on the Interface Builder highlights the advantages that
ensue from this change.
Relevant Chapter: “Designing User Interfaces in Xcode 4” (page 63).
9
At a Glance
Debug and Refine Your Code In Xcode 4

Xcode 4 provides a consistent interface for debugging regardless of which supported debugger you use.
Relevant Chapters: “Orientation to Xcode 4” (page 22), “Debugging and Analyzing Your Code” (page 77),
“Replacing Text and Refactoring” (page 89).
Back Up Your Code and Use Source Control

Xcode provides easy backups with snapshots and provides access to the most commonly used features of
source control repositories.
Relevant Chapter: “Repositories, Snapshots, and Archives” (page 95).
Use Archives to Distribute Your Program

When you’re ready to share your program with others, create an archive to distribute or to submit to iTunes
Connect.
Relevant Chapter: “Repositories, Snapshots, and Archives” (page 95).
10
Using an Existing Xcode 3 Project
If you’ve been working in Xcode 3 and have one or more Xcode 3 projects that you’d like to use in Xcode 4,
this chapter tells you what you need to know to get started. After you’ve opened your projects, go to “Orientation
to Xcode 4” (page 22) to learn more about using Xcode 4.
Open Your Xcode 3 Project in Xcode 4

Xcode 4 can open an Xcode 3 project without difficulty. You can open the project in any of the usual ways:
Control-click the project and choose Open With Xcode.app (being sure you pick Xcode 4), drag the project
onto the Xcode 4 icon, or choose File > Open to open the project. You can have both Xcode 3 and Xcode 4
installed on your system at the same time without conflict.
Xcode 4 reads and builds projects created in Xcode 2.1 through the latest release of Xcode 3. Projects created
with Xcode 4 can be opened and built on Xcode 3.2 and later.
You can open a project in either application, save it, then open it in the other application without invalidating
the project or losing any data. Changes you make to a project in Xcode 4 remain compatible with earlier
versions of Xcode.
11
See Your Groups and Files

Before going any further, you need to get oriented to the Xcode 4 workspace window. Figure 1-1 shows the
Xcode 4 window newly opened with an Xcode 3 project.
Figure 1-1 A newly opened Xcode 4 window with an Xcode 3 project
12
The left side of the window is the navigation area, opened to the project navigator, which is similar to the
Groups & Files list in the Xcode 3 project window. Figure 1-2 shows the contents of an Xcode 3 project as seen
in Xcode 4.
Figure 1-2 The project contents in the Xcode 4 project navigator
What you see in this list is probably less surprising than what you don’t see. Missing from the Xcode 4 project
navigator are these groups:
● Targets
● Executables
● Find Results
● Project Symbols
● Bookmarks
● SCM (source control repositories)
● Smart groups
You’ll also notice that the detail view is missing from Xcode 4.
The Xcode 4 equivalents to these groups and user interface elements are described in “Orientation to Xcode
4” (page 22).
13
Replace Your Interface Builder Plug-ins
Replace Your Interface Builder Plug-ins

Xcode 4 provides limited support for Interface Builder 3 plug-ins. Specifically, you can build a project with
Interface Builder plug-in dependencies, but you can’t edit the nib files. When you try to open a nib file with
plug-in dependencies, Xcode 4 displays a dialog suggesting that you update the file (Figure 1-3). If you agree,
Xcode converts the class of custom objects built with plug-ins to the nearest AppKit class. If the conversion
isn’t possible, Xcode 4 provides a detailed error message. In that case, you must remove the plug-in dependency
using Interface Builder 3 before you can edit the nib file in Xcode 4.
Figure 1-3 IB plug-in upgrade dialog
Keep Your Xcode 3 Preferences

Xcode 4 copies your Xcode 3 settings for the Text Editing, Fonts and Colors, Indentation, and SCM preferences.
However, changes you make to these preferences in Xcode 4 are not copied back to Xcode 3.
Xcode 4 ignores your Xcode 3 General, Code Sense, Building, Distributed Builds, Debugging, Key Bindings, File
Types, Source Trees, and Documentation preferences. Similar Xcode 4 features start with Xcode 4 defaults.
Changing settings in Xcode 4 does not affect your settings for these preferences in Xcode 3.
14
Check Out a Working Copy

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. Use the following procedure to connect to a repository:
1. In the Welcome to Xcode window you see on startup (or when you choose Window > Welcome to Xcode),
click Connect to a repository. Alternately, in the Repositories pane of the Organizer window (referred to
hereafter as the repositories organizer), click the plus sign (+) at the bottom of the navigator pane and
choose Checkout or Clone Repository.
2. In the Checkout or Clone dialog, enter the path to the repository you want to clone or check out.
15
3. Fill in the name you want to use for the repository as displayed in the Organizer window and click Clone
(for Git) or Checkout (for Subversion).
4. In the Save As dialog, specify the name and location you want to use for the working copy and click Clone
(for Git) or Checkout (for Subversion).
5. In the confirmation dialog, click Open to open the new working copy in an Xcode workspace window (for
Git) or Show in Finder to see the new working copy in the Finder (Subversion).
16
Modernize Your Project
6. For Git, you’re done. For Subversion, click on the name of the new repository in the repositories organizer
and fill in the paths to the trunk, branches, and tags directores. If your Subversion server requires
authentication, fill in the user name and password as well.
See “Repositories, Snapshots, and Archives” (page 95) for more information about source control in Xcode 4.
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 that your projects conform to the latest SDKs and best practices.
Open the issue navigator (Figure 1-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 1-4 Modernization in the issue navigator
17
Work with Multiple Related Projects
If the issue navigator lists modernization issues, click the issue to see a dialog that explains the updates that
should be made (Figure 1-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 1-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.

A major new feature of Xcode 4 is the addition of 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. For example:
● 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.
18
● Indexing is done across the entire workspace, extending the scope of content-aware features such as code
completion and refactoring.
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 (see “Select a Scheme” (page
31)). The pointers to the source files, included libraries, build configurations, and other data are stored in the
project files.
If you have two or more related projects, use the following procedure to create a workspace and add the
projects to it:
1. If Xcode 4 is not open, start it. You can ignore or cancel the startup screen.
2. Choose File > New > New Workspace and name the 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.
To avoid possible confusion with your projects, give the workspace a unique name. Click Save.
19
4. Drag projects from the project navigator of other Xcode 4 windows or from the Finder to the project
navigator of the new workspace. When dragging from the Finder, be sure to drag the project file
(<ProjectName>.xcodeproj), not the entire project folder. Be careful to drop each new project below
the last project, not in another project.
If you’ve set up your build configuration with explicit references between your projects, the build will continue
to behave as it did before. If you used to build one project and then import the product into the other project
before you built it, you can remove the product from the project that imports it, because Xcode 4 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 “Set Build Settings for Each Target” (page 23) for help in finding and understanding the build settings
interface in Xcode 4.
Before you build, be sure you’ve created the scheme or schemes you need. See “Select a Scheme” (page 31)
and “Customize Executables” (page 34).
20
Creating a New Xcode 4 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. In that case, see “Create a New Workspace” (page 21).
Create a Standalone Project

If you decide that you don’t need a workspace, open Xcode 4 and click “Create a new Xcode project” in the
startup screen. If Xcode 4 is already open, choose File > New > New Project. In the dialog that appears, be
careful to select the type of project you want to create for the correct platform.
If you decide later that you want to create a workspace and add your project to it after all, see the instructions
in “Using an Existing Xcode 3 Project” (page 11).
Create a New Workspace

If you decide you want to work with two or more related projects, create an Xcode workspace. To do so, use the
following procedure:
1. When Xcode 4 opens, ignore the startup screen and choose File > New > New Workspace.
2. 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 create a new folder and put the
workspace file in there as well. To avoid possible confusion with your projects, give the workspace a unique
name. Click Save.
3. Choose File > New > New Project and follow the directions for each project you want to add. Be careful
to select the correct platform and project type for your purposes.
21
Orientation to Xcode 4
Once you’ve got your projects open in Xcode 4, you can start writing code. This chapter describes many of the
features of Xcode 4 that are located in different places, or used somewhat differently, from the same features
in Xcode 3. It also describes a couple of features that are new in Xcode 4. For information in the debugging
features of Xcode 4, see “Debugging and Analyzing Your Code” (page 77). For changes in the workflow of
designing user interfaces using Xcode 4, which has a fully integrated Interface Builder, see “Designing User
Interfaces in Xcode 4” (page 63).
Much of Your Project’s Content Is in New Locations

The following sections tell you where in the Xcode 4 workspace window to find information that was in your
Xcode 3 Groups & Files list. Bookmarks and source control repositories, along with other information, are in
the Organizer window. See “Organize Projects and Devices” (page 49) for more information about the Organizer
window.
22
Set Build Settings for Each Target

Click the project in the project navigator. The project editor appears to the right of the project navigator,
displaying project and target information. Figure 3-1 shows some of the target information in the project
editor.
Figure 3-1 Target information in the project editor
Click the various buttons and icons in the project editor to see the information that’s in there. Note that some
of this information is in the Targets group in Xcode 3, but much of it, although actually related to the target,
is found in other places in Xcode 3. Xcode 4 brings all this information together and makes some of the
relationships clearer.
In particular, in Xcode 3, if you need to alter any build settings or create any custom settings, you need to
select the target in the Groups & Files list and then open the Info window. To change the list of what files were
included in the build or in what order they were used, you need to open all levels of disclosure triangles under
23
the target in the Groups & Files list. Although some build settings are specified at the project level, some are
specified at the target level, and some use defaults, these relationships are not obvious in Xcode 3. In Xcode
4, on the other hand, you can view all the levels of build settings simultaneously, as seen in Figure 3-2.
Figure 3-2 Build settings
You can edit a build setting at any level. The level at which the build setting is actually set is highlighted in
green. The value to which the build setting is set is listed in the Resolved column. If you have changed or
customized a setting, it’s shown in boldface.
24
Set Basic Build Settings

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. Figure 3-3 shows the build settings summary pane for a Mac OS X project.
Figure 3-3 The Mac OS X summary pane
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.
Set Up a Sandbox for Each Target

An application sandbox enforces restrictions, known as entitlements , on how an application can interact with
the rest of the system. A sandboxed application is harder to compromise and therefore enhances security for
users. For example, if your application has no need to have access to the network, you can specify that the
application’s sandbox should prohibit network access. Then, if a hostile hacker manages to take over control
of your application on a user’s computer, the hacker won’t be able to use the application to send email or
connect to the internet.
In Xcode 4.1 and later, the project editor provides a UI for setting up entitlements for Mac OS X applications.
You can set entitlements for each target in the project editor (Figure 3-4). There is also a default code-signing
entitlements file available in the file templates in the utilities pane.
25
Note Although the Mac OS X sandboxing UI is available in Xcode on v10.6 Snow Leopard, only Mac
OS X v10.7 Lion and later versions of the operating system enforce the entitlements.
Figure 3-4 Mac OS X entitlements editor
26
When you enable application sandboxing, you can select an entitlements file if you already have one. If you
do not, Xcode creates one with the name of your project and the extension entitlements. You can view and
edit this file with the property list editor in Xcode (Figure 3-5).
Figure 3-5 Entitlements property list
Select Any File to Open an Editor

Xcode 4 includes editors for source code, property list (.plist) files, rich text (.rtf) files, Core Data model
files, nib files, and others. To open or display any of these editors, select a file of that type in the project navigator.
The editor opens automatically in the editor area of the workspace window. Any file for which Xcode does not
have an editor is displayed using the same Quick Look facility used by the Finder.
Each document-type editor has custom commands in the Navigate and Editor menus to act on the information
in that document type.
Write and Edit Source Code

The features you’re used to in Xcode 3 are also present in Xcode 4. For example, code folding, code completion,
Quick Help, automatic indentation, syntax coloring, edit all in scope, and automatic balancing of delimiters
are all available and similar to the same features in Xcode 3. Look through the Edit menu, the shortcut menu,
and Xcode preferences to find these features. Many of the keyboard shortcuts are unchanged. Use the Key
Bindings pane in Xcode preferences to see and edit the keyboard shortcuts.
27
Speed Up Typing with Code Completion

The user interface for code completion is similar to that in Xcode 3, but there are some important differences.
One of the first changes that you’ll notice is that you always get both an inline suggestion for completing the
symbol name plus a list of possibilities (Figure 3-6). Click an item in the suggestion list or use the up and down
arrows to select one. As you do so, the inline suggestion changes as well. Furthermore, as you can see in the
figure, if you open the Quick Help inspector, you can read documentation about each selection. You can disable
automatic code completion in the Text Editing pane of Xcode preferences, but you can always invoke code
completion by pressing Control-Spacebar.
Figure 3-6 Code completion
28
A Quick Help pop-up dialog is also available from code completion, even when the Quick Help inspector is not
open. Hold the pointer over the code completion option you’re interested in until a question mark icon appears.
Click the question mark or press Command-Shift-Control-Question Mark to open Quick Help. As before, press
the Tab key to accept the prefix or Return to accept the entire suggestion. Click the Done button in the Quick
Help pop-up dialog to cancel the operation.
Figure 3-7 Quick help for code completion
If all of the possible completions have a common prefix (NSString in Figure 3-6), the prefix is indicated with
a dotted underline. Press the Tab key to accept only the prefix. Press Return to accept the entire autocompletion
suggestion. If there is no common prefix, code completion shows the dotted underline up to the next uppercase
letter in the symbol (Figure 3-6). Again, press Tab to accept only the subword, or press Return to accept the
entire suggestion.
Figure 3-8 Code completion underlining
Press Control–Space bar to toggle the completion suggestion on or off. That is, if the inline suggestion and
list are being displayed, pressing Control–Space bar cancels the code completion operation. If there is no
suggestion displayed, place the cursor at the end of a partially typed symbol and press Control–Space bar to
get completion suggestions.
Note that in Xcode 4, pressing the Esc (Escape) key cancels the operation and pressing the Delete key always
deletes the preceding character.
29
Have Fix-it Flag Errors as You Type

When your target is set to use the LLVM compiler, a new feature called Fix-it scans your source text as you
type. Fix-it marks syntax errors with a red underscore or a caret at the position of the error, and a symbol in
the gutter. Clicking the symbol displays a message describing the possible syntax error and in many cases
offers to repair it automatically (Figure 3-9).
Figure 3-9 Fix-it in action
Open a File in the Assistant Editor Pane

By default, when you Option-click a file in one of the navigators or jump bars, an assistant editor opens in
manual mode and displays the file in the assistant editor pane (see “Split the Editor Area” (page 51)). To change
this behavior and to set other keyboard shortcuts for opening files, open the General pane of Xcode preferences.
View Files in Hexadecimal Format

You can view and edit many types of files in hexadecimal format, including some (such as graphics files) that
you can’t edit otherwise. To do so, Control-click the file in the project navigator and choose Open As > Hex
from the shortcut menu.
You can edit the hexadecimal code directly, or you can edit in the plain text column. Editing either updates
the other.
30
When the hex editor has focus, you can use the Editor menu to customize its display.
View Preprocessor or Assembly Output

You can use commands in the Product > Generate Output menu to process source files and generate the
preprocessed output or assembly output.
The preprocessor evaluates directives in your source code (for example, instructions starting with the number
sign (#), such as includes, defines, and conditional logic) and converts them into C code to be sent to the
compiler. You can examine the preprocessed output to make sure that the logic in your source code is being
interpreted by the preprocessor as you expect in order to debug compilation problems.
The assembly output is the set of instructions that the compiler generated from the preprocessed output. You
can study the assembly output to see how the instructions were formed or ordered, to seek out better
optimization patterns, or to look for compiler bugs.
The output type is also a new category in the assistant editor for a selected primary file.
View Key Names or Raw Keys

For known property list 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 the raw key value in Quick Help in the Quick Help.
Select a Scheme
In Xcode 3 you have to set an active target, a build configuration, and an executable as separate items. The
problem with this approach is that targets, configurations, and executables are intimately linked. At its simplest,
for example, a target contains one product, which is executed without any special options or environmental
settings. However, sometimes the product requires values for input parameters or other customization before
it can be executed. In Xcode 4, you select a scheme, which specifies which targets to build, what build
configuration to use, which debugger to use, and which executable to launch when you choose Run from the
Product menu or click the Run button at the left end of the toolbar. Each scheme also specifies a set of options
for several possible actions:
● Running a product for debugging
● Running unit tests
● Profiling your application with Instruments
● Performing a static analysis of your code
● Archiving your product for distribution or submission to iTunes Connect
31
You can set each action to do either a debug or release build.
When you open an existing Xcode project (or create a new one), Xcode 4 automatically creates a scheme for
you. To select a scheme, you use the Scheme pop-up menu in the upper-left corner of the Xcode window
(Figure 3-10). To create a new scheme, choose New Scheme from that menu. To edit existing schemes, choose
the scheme you want to edit and then choose Edit Active Scheme from that menu. To change the list of
schemes, where they’re stored, and whether they’re shared, choose Manage Schemes.
Figure 3-10 The Scheme pop-up menu
You can have as many schemes as you want, but only one can be active at a time.
Specify Which Targets Are Built

By default, Xcode creates one scheme per target in your project or workspace. For each target, you use the
build pane of the scheme editor (Figure 3-11) to specify which targets are built for each type of action. You
can add as many targets from your project or workspace to a single scheme as you wish. The figure shows four
targets: the SurfWriter application, a custom framework needed to build the application, an Automator plug-in
to be provided with the application, and a command-line tool that can be used with the application. In the
32
figure, the SurfWriter application and framework are set to be built for every action, but the plug-in is set to
be built only when the application is built for running (that is, for debugging) and for archiving (that is, for
distribution). Each of these actions has associated options that you can customize with the scheme editor.
Figure 3-11 The scheme editor Build pane
33
Customize Executables
To customize the environment in which a product is launched in Xcode 3, you click the executable in the
Groups & Files list and then open the Info window. In Xcode 4, choose Edit Active Scheme from the Scheme
pop-up and choose the product you want to run (Figure 3-12). Note that you can choose to display the running
product at a higher UI resolution to simulate running at a different display resolution.
Figure 3-12 Customizing an executable environment for a product
Rename or Reorganize Your Schemes

Choose Product > Manage Schemes or choose Manage Schemes from the Scheme pop-up menu (Figure
3-10 (page 32)) to see a list of all the schemes in the project and to rename or reorganize the schemes in the
menu. You can also specify whether each scheme should be displayed in the pop-up menu, where the scheme
is stored (in the project or workspace) and whether the scheme should be shared with others using the project
or workspace.
34
Search Your Workspace

Rather than a Find group and batch find panel, Xcode 4 has a find navigator. Click the magnifying glass icon
in the navigation pane, type a term in the search field, and press Return to search through the entire project
or all the projects in the Xcode workspace (workspaces are discussed in “Work with Multiple Related
Projects” (page 18)). The results are displayed in the find navigator (Figure 3-13). Just as in Xcode 3, click a find
result to see the instance of the term in the source editor.
Figure 3-13 The find navigator
35
To customize the search, click the magnifying glass in the search field and choose Show Find Options to get
the Find Options dialog (Figure 3-14).
Figure 3-14 The Find Options dialog
36
Browse to Project Symbols

Click the second button from the left in the navigator selector bar to browse through the symbols in your
project (Figure 3-15). Note that you need to wait until Xcode finishes indexing your project before you can use
this feature.
Figure 3-15 The symbol navigator
Use the search field and scope buttons at the bottom of the navigator to specify exactly what is listed. The
scope 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
37
When you select the Flat button at the top of the symbol navigator, the navigator displays all classes arranged
alphabetically. When you select the Hierarchical button, the navigator displays the class hierarchy.
Use the search field at the bottom of the symbol navigator to filter the results. For example, in Figure 3-16,
only those symbols that include the string KTg are displayed. This filter is not case sensitive.
Figure 3-16 The symbol navigator, filtered
Click a symbol to see it displayed in the source editor (Figure 3-17). Option-click the file in the symbol navigator
to open Assistant and display the file in the assistant editor pane (see “Split the Editor Area” (page 51)).
Figure 3-17 A symbol displayed in the source editor
38
Each of the navigation elements in the jump bar is also a pop-up menu with a list of symbols at that level in
the project hierarchy. The jump bar shows the same structure as seen in the project navigator down to individual
files, and then the symbols in the files. Click one of the navigation elements in the jump bar to see the list and
to select a symbol to display (Figure 3-18). Hold down the Option key when selecting a file in the jump bar to
display the file in the assistant editor pane (see “Split the Editor Area” (page 51)).
Figure 3-18 Using the jump bar to find a symbol
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 you can see in Figure 3-19.
Figure 3-19 The related-items pop-up menu
39
Filter to FInd Related Content

Rather than providing smart groups to gather together related information, Xcode 4 provides a variety of
navigators and filters. The project navigator (Figure 1-2 (page 13)), for example, has filters for recently edited
files, files with source control status, unsaved files, and filename strings. Figure 3-20, 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 3-20 The project navigator filtered to show only .m files
In addition to the structure, symbol, and find navigators already discussed, there are navigators that display:
● Warnings, errors, and other issues found when analyzing or building your project
● Threads and stacks in a debugging session
● Breakpoints
● Build logs
For more information on using these navigators to analyze and debug your code, see “Debugging and Analyzing
Your Code” (page 77).
40
Customize the Build and Run Workflow
Note Although Xcode 4 does not allow you to create smart groups and does not display any smart
groups that you created for your project in Xcode 3, it does preserve your Xcode 3 smart groups. If
you open your project in Xcode 4 and work with your code, then later reopen your project in Xcode
3, the smart groups you created earlier are still there.
View Details
All of the information in the detail view has been replaced in Xcode 4 with navigators or editors. Here are some
of the main equivalents:
● Files in your project: use the project navigator (see “Open Your Xcode 3 Project in Xcode 4” (page 11))
● Find results: use the find navigator (see “Search Your Workspace” (page 35))
● Executables: use the scheme editor (see “Customize Executables” (page 34))
● Targets: use the project editor (see “Set Build Settings for Each Target” (page 23))
● Bookmarks: use the bookmarks navigator in the Organizer window for documentation bookmarks (see
“Browse and Bookmark Documents” (page 46))
● Source control: use the source control editor in the Organizer window to work with repositories and the
version editor and project navigator to view source control status of files and to commit or update files
(see “Work with Source Control Repositories” (page 48))
● Project symbols: use the symbol navigator and the jump bar (see “Browse to Project Symbols” (page 37))

As pointed out in “Select a Scheme” (page 31), Xcode 4 schemes replace several settings in Xcode 3 that affect
how your project is built and run. The Xcode 4 scheme editor enables you to specify many settings that affect
your workflow, including build, test, and launch settings. For example, you can specify what targets to build;
41
whether to build with debug symbols; which targets are built for each type of action; what debugger to use;
what scripts to run before and after each type of action; arguments to pass to the application on launch; a
variety of diagnostic options (Figure 3-21); and what unit tests to run.
Figure 3-21 Run diagnostic options
42
Once you’ve got one or more schemes set up exactly as you want them, the next thing you may do when
setting up your build and run workflow is to open Xcode preferences and click Behaviors. This preferences
pane lets you specify what should happen when a variety of events occur (Figure 3-22).
Figure 3-22 Behaviors preferences
For example, you can have Xcode display the debug area when your code pauses at a breakpoint, or it can
display the issues navigator when a build fails. Note that, in addition to the Behaviors preferences setting to
create a snapshot, you can specify that Xcode create a snapshot before a mass-editing operation such as a
refactoring transformation. To do so, select the Snapshots pane in the File > Project Settings dialog. (Snapshots
are discussed in “Take a Snapshot of Your Workspace” (page 95).)
43
You can name a tab and specify that tab as the display to use when an event occurs. Then you can set up the
display in that tab exactly as you want it; for instance, with a specific source-code file open in the editor, the
debug area open, the Utility area closed, and the issues navigator open. To name a tab, double-click the title
of the tab and type in the new name (Figure 3-23). Tab names are case sensitive in the Show Tab field of Alerts
preferences.
Figure 3-23 Naming a tab
When Xcode reopens the named tab, it remembers the tab’s state—including which window it was in. By
naming a tab in a separate window, you can use the Show tab option in Behaviors preferences to automatically
open a new window. To do so, create a named tab, set it up exactly as you want it, and drag the tab out of the
window to create a new window. Now, each time Xcode recreates the tab, it opens a new window to hold the
tab.
You can also can design custom behaviors that are triggered by menu items or their key equivalents. This
feature allows you to create behaviors that you can invoke at any time. For example, you can create a "Unit
Testing" behavior that creates a snapshot and runs your unit tests (Figure 3-22 (page 43)). After you’ve created
a behavior, it appears in the Xcode > Behaviors menu. To assign key equivalents to custom behaviors, find the
behavior in the Customized tab of the Key Bindings preferences pane.
44
Check on the Progress of Xcode Tasks
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 3-24).
Figure 3-24 The activity viewer
Click the number to open a pop-up window that shows the individual status of each current task (Figure 3-25).
Figure 3-25 The activity pop-up window
View Projects, Devices, and Documentation

Xcode 4 has two main windows. You’ve seen the workspace window (Figure 1-1 (page 12)), 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 3-26).
Figure 3-26 The Organizer button
45
Browse and Bookmark Documents

To browse documentation, open the Organizer window, click the Documentation button in the toolbar, and
click the Browse button in the jump bar (Figure 3-27).
Figure 3-27 The documentation navigator
46
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 3-28).
Figure 3-28 The bookmarks navigator
To select which documentation sets to download, use the Documentation pane in Xcode preferences.
47
Browse for Task-Based Help

New in Xcode 4, online help is available for the Xcode IDE. To browse the Xcode 4 online help, click the disclosure
triangle next to Xcode Help in the documentation navigator (Figure 3-27 (page 46)) or choose Help > Xcode
Help (Figure 3-29).
Figure 3-29 Finding Xcode 4 help articles
Many of the articles in Xcode 4 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 4, many of the help articles
are also available as contextual help. See “FInd Answers with Contextual Help” (page 49) for details.
Work with 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. For more
information on repositories, see “Keep Track of Changes and Coordinate Work Groups ” (page 97).
48
Find Answers with Contextual Help
Organize Projects and Devices

Whereas Xcode 4 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 and their snapshots. See “Take a Snapshot
of Your Workspace” (page 95) for more information on snapshots.
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.
The iOS organizer in Xcode 4 provides the same information and capabilities as the Xcode 3 Organizer window.
Archive Your Product for Distribution

In Xcode 3, to distribute your product, you need to configure build settings for a release. It’s often easier to
use the command line than to create an installable application in Xcode. In Xcode 4, when you’re ready to
share your program with others, you choose Archive from the Product menu. In the Archives pane of the
Organizer window, you can then share the application with others or submit to iTunes Connect.
Find Answers with Contextual Help

In addition to being listed in the documentation browser in Xcode 4 (see “Browse for Task-Based Help” (page
48)), many of the 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 3-30). If there are more articles than can be listed in the shortcut menu, then choose Show
49
Save Changes Automatically
All Help Topics and the help opens in the Organizer window. 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 4.
Figure 3-30 Contextual help
Save Changes Automatically

When you edit a file in Xcode 4, the file’s icon is shaded in the project navigator to indicate that there are
unsaved changes. By default, if you build the project or quit Xcode, Xcode 4 automatically saves all changed
files for you. 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 or perform another operation that affects many files in your
project and that might be difficult to undo, create a snapshot (see “Take a Snapshot of Your Workspace” (page
95)).
50
Split the Editor Area
Split the Editor Area

Xcode 3 lets you split the editor window to look at two locations in a source code file, or two different files, at
the same time. Although this ability is also present in Xcode 4, the new user interface provides a much more
powerful use of split editor windows, called Assistant.
Assistant has two modes: tracking (or automatic) mode and manual mode. Tracking mode has several criteria
from which you can choose, such as counterparts, superclasses, subclasses, or siblings. Assistant selects the
file or files that best meet the selected criterion and opens those files in the Assistant pane of the source editor.
In manual mode, you select the file to display in the Assistant pane. You can also split the assistant editor pane
to create multiple assistant editors.
Find Related Content

To enable Assistant, click the Assistant button in the workspace toolbar (Figure 3-31).
Figure 3-31 The Assistant button
Assistant opens a second pane in the editor area of the workspace window. For source files, the default behavior
for Assistant is to display the counterpart of the file displayed in the standard editor pane. That is, if you’ve
opened an implementation file, Assistant displays the corresponding header file, and vice versa. You can choose
any of several other possible criteria to be used by Assistant using the Assistant pop-up menu. The Assistant
pop-up menu is the first item in the path shown in the jump bar above the assistant editor. To do so, open the
pop-up menu and choose an item, as shown in Figure 3-32. The choices offered depend on the type of file
being edited.
Figure 3-32 Setting the behavior for Assistant
51
Open a New Tab or a New Window
Selecting a file in the project navigator causes that file to be shown in the normal editor pane. Unless Assistant
is set to manual mode (see “Display Content of Your Choosing” (page 52)), it tracks the change. Option-click
when selecting a file in the project navigator or hold down the Option key when selecting a file in the jump
bar to display that file in the Assistant pane rather than the standard pane. Doing so switches Assistant to
manual mode.
The assistant editor pane can be displayed to the right of the standard editor pane or below it. Choose View
> Assistant Layout to switch between a vertical or horizontal split for the editor panes.
Use Assistant with Interface Builder

When you’re using Interface Builder to design a user interface, you can use Assistant to automatically display
the code file most relevant to the interface element you’re working with. See “Use Assistant to Work on Your
UI Code” (page 69) for details.
Display Content of Your Choosing

Choose Manual from the Assistant pop-up menu (Figure 3-32 (page 51)) to put the editor in manual mode. In
this mode, Assistant acts like the split editor in Xcode 3. You can open any file in the assistant editor pane,
including the same file as one you’re working on in the other editor pane. You can use the pop-up menus in
the jump bar above the assistant editor pane to select the file or symbol to edit in that pane (Figure 3-18 (page
39)). The standard editor pane (the left editor pane, or the top one if you have a horizontal split) is always the
one that’s affected by changing your selection in the project navigator. Option-click a file in the project navigator
to open it in the Assistant pane.
Compare Two Versions of Your File

Use the version editor to compare different revisions from your source control repository. It can also show the
difference between the saved file and what's in memory. In addition, the version editor lets you see source
control logs and blame/annotation information. See “Compare Revisions ” (page 102) for more information.
Open a New Tab or a New Window

For fast switches between different editors or files, you can add tabs to the Xcode 4 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. 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.
52
Open Files with Keyboard Shortcuts
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.
Open Files with Keyboard Shortcuts

Selecting a file in the project navigator or jump bar causes that file to open in the normal editor pane. If Assistant
is set to tracking mode, it tracks the change. By default, if you hold down the Option key when selecting a file
in the project navigator or jump bar, Xcode displays that file in the Assistant pane rather than the standard
pane. Doing so switches Assistant to manual mode.
You can customize the behavior of the single click, Option-click, Option-Shift-click, and double-click keyboard
shortcuts in the General pane of Xcode preferences. Choose one of the following options from each
keyboard-shortcut pop-up menu:
● Primary editor: Opens the file in the primary editor pane in the window and tab already open.
● Focused editor: Opens the file in whichever editor pane currently has focus.
● Single assistant editor: When the navigation originates in a navigator pane or the primary editor (using
the jump bar or the jump to definition command), if the assistant editor is not open or is not split, opens
the file in the assistant editor.
If the assistant editor is split, displays a navigation chooser dialog (“The Single Assistant navigation chooser
dialog”) showing the current layout of editor panes in the window that has focus, with the option of
selecting any open editor pane or adding a new one. Double-click your selected pane, or make your
selection and press Return. Press Esc to cancel.
Figure 3-33 The Single Assistant navigation chooser dialog
If the file is already open in one of the editor panes, the navigation chooser displays a star to indicate the
pane containing the file.
When the navigation originates in an assistant editor pane, Xcode opens the file in the primary editor.
53
Open the Utility Area
● Separate assistant editor: If the assistant editor is closed and is not split, opens the file in the assistant
editor.
If the assistant editor is open, opens the file in a new assistant editor pane.
If the assistant editor is split but closed, opens the file in the most-recently-opened assistant editor pane,
replacing the file that was in that pane.
If the file is already open in an assistant editor pane, switches the focus to that pane.
● Separate tab: If the file is not already open in the current window, opens the file in a new tab.
If the file is already open in another tab in the same window, switches the focus to that tab.
● Separate window: If the file is not already open in a separate window, opens the file in a new window.
If the file is already open in a separate window, switches the focus to that window.
The Option-Shift-Click key combination opens a navigation chooser dialog (Figure 3-34) showing the current
layout with the options of selecting any open editor pane in any window and any tab, or adding a new editor
pane, window, or tab. Double-click your selection, or make your selection and press Return. Press Esc to cancel.
Figure 3-34 The navigation chooser dialog
The Open Quickly command works in Xcode 4 in much the same way that it worked in Xcode 3. In Xcode 4,
however, you can open a file in the assistant editor by holding the Option key when you double-click or click
Open. To open the file in a separate window, hold down Option-Shift. To see the navigation chooser dialog,
hold down Option-Shift-Click. These behaviors follow the preferences you set for navigation in the General
preferences pane.

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.
54
To open the utility area, choose View > Utilities, or click the Utility button in the toolbar (Figure 3-35).
Figure 3-35 The Utility button
View Quick Help

In Xcode 3, you can open a Quick Help window with information about an API symbol by Option–double-clicking
the symbol. In Xcode 4, you can use an Option-single-click to open Quick Help (Figure 3-36).
Figure 3-36 The Quick Help window
55
Whereas in Xcode 3, you can make the Quick Help window permanent by moving it from its original location,
in Xcode 4, Quick Help is always available in the Symbol inspector in the utility area (Figure 3-37). Just click
any symbol while the Symbol inspector is open to see its Quick Help information.
Figure 3-37 The Symbol inspector
56
Quick Help is also available for user interface objects in Interface Builder (Figure 3-38) and for build settings
(Figure 3-39).
Figure 3-38 Quick Help for Interface Builder objects
57
Figure 3-39 Quick Help for build settings
58
View and Edit File and Interface Builder Data

Inspectors are panes in the utility area that you can use to read or enter data about files and Interface Builder
objects. Figure 3-40 shows a file inspector. For more information about Interface Builder, see “Designing User
Interfaces in Xcode 4” (page 63).
Figure 3-40 A file inspector
Drag Files and Code from the Library

Xcode provides libraries of file templates and code snippets that you can use in your program. It also has
libraries of Interface Builder objects and media files that you can use in your nib files. The libraries pane is in
the lower part of the utility area (see Figure I-1 (page 8)). Each of the buttons at the top of this pane selects
a category of library objects, as follows:
59
● File templates range from templates for applications to subclasses of commonly used Cocoa classes. To
use a template, drag it from the library to a folder in the project navigator. File templates have subcategories,
which you can choose from the pop-up menu below the line of buttons. You can display the templates
as icons only or as icons and text. Regardless of which you choose, when you click a template, an information
window pops open with information about the use of the template (Figure 3-41).
Figure 3-41 A file template information pop-up window
● Code snippets are short pieces of source code that you can use in your software. To use one, you can drag
it directly into your source code file. Alternatively, you can copy a portion of the code from the code
information pop-up window (Figure 3-42) and drag that into your file.
60
To create your own code snippet, highlight the code for the snippet in a source file and drag it into the
Code Snippet library pane. You’ll need to edit the snippet to give it a meaningful name and, optionally, a
completion shortcut. You can use a completion shortcut to add a snippet when editing source code. Type
the shortcut in your source code file and select the snippet from the code completion list to add the code
to your file. Note that a new or edited code snippet is flagged with the word “User” (Figure 3-43).
Figure 3-42 Dragging a piece of a code snippet into your file
Figure 3-43 A user-customized code snippet
● Interface Builder objects are used the same way as those in the Xcode 3 Interface Builder. In Xcode 4
they are organized with subcategories and provide information pop-up windows like those for the file
templates and code snippets.
● Media files include a selection of graphics and icons that you can use in your program. All media files in
your workspace or project are listed here.
At the bottom of the library pane is a search field that you can use to filter the library items displayed in the
selected library. In , for example, only the Interface Builder objects whose name or description contains the
word “window” are displayed.Figure 3-38 (page 57)
61
Close a Project or a Workspace
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, press
Command-Option-W—or hold down the Option key and click the close box—to close the project or workspace
without first closing all windows and tabs. In this way, you can ensure that Xcode restores your window
configuration the next time you open the project.
62
Designing User Interfaces in Xcode 4
In the Xcode 3 development environment, Xcode and Interface Builder are separate applications. In Xcode 4,
Interface Builder is an editor within the Xcode application. Although most of the features of the Xcode 3
Interface Builder application work identically in Xcode 4, there are some differences—most notably, the ability
to make connections from Interface Builder objects directly into source code. This chapter describes the main
differences between the two implementations of Interface Builder.
Design Your UI in Xcode

In Xcode 4, Interface Builder appears in the editor area of the workspace window when you select a nib file in
the project navigator. (A nib file is a file created by Interface Builder containing the user interface design
information that you enter. A nib file may have the file name extension nib or xib.) When you open a nib file,
the Interface Builder inspectors appear in the utility area. You can also open an assistant editor (see “Use
Assistant with Interface Builder” (page 52)), which shows a file or files associated with whatever object you’ve
selected in the Interface Builder pane. You can select Interface Builder objects in the library pane and drag
them onto the Interface Builder canvas. Figure 4-1 shows Interface Builder and associated panes open in the
workspace window.
Figure 4-1 Interface Builder in the workspace window
63
Create a New Nib File
Create a New Nib File

When you create a new Cocoa application or iOS view-based project, Xcode includes a nib file for your main
view and a view controller class. The view controller is represented in the nib file as the “file’s owner” object.
When you need a new nib file for a project, you should create the interface and implementation files for the
controller first. In many cases, Xcode creates a nib file as well. As nib files usually have controllers already
assigned to them, it is rarely necessary to add a separate view controller to a nib file.
You can add a new nib file to your project either by choosing File > New > New File and selecting a User
Interface template, or by dragging an interface file from the File Template library into the project navigator.
When dragging into the project navigator, be sure the group into which you want to drop the file is highlighted
before you drop (Figure 4-2); you won’t get the results you want if you accidentally drop the file inside another
file.
Figure 4-2 Dropping a nib file in the Resources group
Whether you choose New File or drag the nib file from the File Template library, be sure you select the
appropriate file type for the correct platform. For example, there are two nib templates named Application:
one for iPhone and iPad, and one for Cocoa.
Create New UI Classes in Xcode

In Xcode 3, you typically add a new class to the class hierarchy in Interface Builder, add outlets and action
methods, and then ask Interface Builder to create the corresponding header and implementation files for you
in Xcode. Keeping your class files synchronized between Interface Builder and Xcode can be a problem with
Xcode 3. In Xcode 4, on the other hand, all class creation is done directly by Xcode. In Interface Builder, you
only need to make your connections to the file’s owner or controller object.
64
Add Source Files First

To add a new nib file to a project, first choose File > New > New File and add interface and implementation
file templates for a controller class for the nib file. For example, if your new nib file is going to start with a
Cocoa window, add a Cocoa Objective-C class that’s a subclass of NSWindowController. Xcode creates both
a header file and an implementation file and adds them to your project. In Figure 4-3, for example, the new
class will be a subclass of NSWindowController.
Figure 4-3 Creating new class files
65
Next, add the nib file by selecting a User Interface template of type Window in the New File dialog (Figure 4-4).
Figure 4-4 Adding a new Window nib file
66
Open the new nib file by selecting it in the project navigator so that it appears in the Interface Builder editor.
Then select the File’s Owner object in the Interface Builder dock and choose your controller in the class field
under Custom Class in the Identity inspector (Figure 4-5).
Figure 4-5 Assigning a class to an Interface Builder object
To see the outlets and actions provided by the parent class of the file’s owner, click the File’s Owner object in
the dock and open the Connections inspector. To add new actions or outlets to the nib file’s controller, see
“Make Connections Directly with Source Code” (page 72).
Add a Custom View

If you need to add a new custom view to your nib file, first create header and implementation files for the view
by choosing File > New > New File and selecting the Objective-C class template. Be sure to choose the
appropriate parent class in the “Subclass of” pop-up menu.
67
After adding the source file templates to your project, drag a custom view object from the library into the nib
file, as shown in Figure 4-6.
Figure 4-6 Adding a custom view
After adding the custom view to your nib, select the custom view and assign the correct class to it in the class
field under Custom Class in the Identity inspector (Figure 4-5 (page 67)).
Create an Interface Controller

To create a new controller for a nib file, first use the New File dialog to create interface and implementation
files for the new class. Use the Objective-C class template and make the templates a subclass of NSObject. If
you want to make connections in Interface Builder to the outlets and actions of the controller, drag the Object
object from the Object library in the Utilities pane into the dock of your Interface Builder nib file (Figure 4-7).
68
Use Assistant to Work on Your UI Code
(Tip: Type nsobject into the search field to find the object quickly.) Select the new object in the dock and
use the class field under Custom Class in the Identity inspector (Figure 4-5 (page 67)) to assign the class of
your controller to the object. Then use the Label field in that same inspector to change its display name.
Figure 4-7 Adding a controller object to a nib file
To see the outlets and actions provided by the controller, click the controller object in the dock and open the
Connections inspector. To add new actions or outlets to the controller, see “Make Connections Directly with
Source Code” (page 72).

When you use custom subclasses in your interface, or add outlets and actions to a controller, you can use
Assistant to work on your interface design and your interface code at the same time. To do so, select your nib
file in the project navigator to open Interface Builder and click the Assistant button to open the assistant editor
69
pane. If the assistant editor does not automatically display the header file you want, use the assistant editor
pane jump bar to select the source file containing the controller code for the object. Figure 4-8 shows a window
with a graphic view selected in Interface Builder and the header file for the graphic view being chosen from
the Automatic mode of Assistant. By default, the assistant editor pane is displayed below the Interface Builder
editor. Choose View > Assistant Layout to switch between a vertical or horizontal split for the two editor panes.
Figure 4-8 Selecting a counterpart to a nib file in assistant
In Figure 4-9 you can see that, with a window object selected in the Interface Builder pane, the assistant editor
pane displays the file SKTWindowController.m. The oval containing the characters 4/5 at the right end of
the editor jump bar indicates that the fourth of five counterpart files is being displayed (in this case the others
are SKTWindowController.h, SKTGraphicView.h, SKTGraphicView.m, and NSWindow.h). Click the right
or left arrows to display the others in turn.
70
You can therefore write code for the window controller at the same time you are designing your window, and
you can make connections directly between Interface Builder objects and lines in your code (see “Make
Connections Directly with Source Code” (page 72).
Figure 4-9 Interface Builder with the assistant editor open
Because Interface Builder is now a fully integrated part of Xcode, it is no longer necessary to switch back and
forth between two applications to create custom subclasses and define actions and outlets. Therefore, Xcode
4 does not provide the special Interface Builder commands used with Xcode 3 to create new subclasses and
copy them into Xcode.
71
Make Connections Directly with Source Code

In Xcode 3, when you want to create a new action or outlet connection, you have to make it between the
Interface Builder Object and a placeholder object representing the controller or other source code file. After
creating and saving the connection in Interface Builder, you then have to open the source code file in Xcode
to add the corresponding IBAction or IBOutlet statement.
In Xcode 4, on the other hand, you can make the connection directly from the Interface Builder object to the
appropriate header file, and, if needed, Xcode inserts the statement directly into your header file.
Figure 4-10 shows a connection being made to an existing IBAction statement.
Figure 4-10 Making a connection to source code from Interface Builder
72
If you need to add a new IBAction or IBOutlet statement, Control-drag to the location in the header file
where you want to add the new statement. If the location is a valid connection destination, Xcode displays an
insertion indicator (Figure 4-11). When you release the mouse button, Xcode displays a small dialog where
you specify the nature of the connection (Figure 4-12). Click Connect to insert the code in your header file.
Figure 4-11 Inserting an action or outlet statement in your header file
Figure 4-12 Connection insertion dialog
73
Get Online Help in IB
Get Online Help in IB

Use the shortcut menu to see online help articles, including some with videos illustrating the procedure to
make connections from Interface Builder objects to source code. Note that, because the Control-click key
combination is used by Interface Builder to make connections, you must Control-click on the canvas (not on
any object in the user interface) to get the shortcut menu (Figure 4-6).
Figure 4-13 Help articles in Interface Builder
Find UI Objects in the Dock

The dock on the left side of the Interface Builder pane (see Figure 4-9 (page 71)) shows the Interface Builder
objects and placeholders in your nib file. These are displayed in the document window in Xcode 3; otherwise,
they work in the same way. To get a list (called the outline view —Figure 4-14) showing all the objects nested
in higher-level objects—for convenience in selecting the object in which you’re interested—click the small
74
Get More Information on IB
triangle below the placeholders. Note that you can also use the Interface Builder jump bar to select objects in
the interface. To return to the icon view, click the small triangle next to the search field at the bottom of the
list.
Figure 4-14 Outline view for placeholders and objects in Interface Builder

For more information on Interface Builder in Xcode 4, including information on making binding connections,
see “Designing User Interfaces in Xcode” in Xcode 4 User Guide . For short tutorials illustrating the use of Interface
Builder, see Xcode Quick Start Guide .
It’s important to note the differences between the work flow in Xcode 4 and the way you do things in Xcode
3. In Xcode 3, if you want to create a new class and use it in an interface file, you have to create the class twice:
once in Xcode, and once in Interface Builder. You need to fully define the class with all outlets and actions,
and connect to those outlets and actions in Interface Builder. You must keep Interface Builder and Xcode
synchronized. By contrast, in Xcode 4, once you’ve created the class, you can connect to the code directly from
Interface Builder (see “Make Connections Directly with Source Code” (page 72)), and Xcode adds outlet and
action code for you. You only need to add the implementation for the actions. If you need to see your new
class in Interface Builder, you can add an object to the Interface Builder editor representing that class, but you
never create a class in Interface Builder.
75
If you have worked through the tutorial in the Xcode 3 Interface Builder User Guide , you are already familiar
with the application created in the User Guide tutorial. However, the workflow is quite different.
76
Debugging and Analyzing Your Code
Xcode 4 provides all the facilities you need to analyze and debug your code in the workspace window. This
chapter summarizes those facilities, with an emphasis on differences between Xcode 4 and Xcode 3.
Select a Debugger
Xcode 4 comes with GDB and LLDB debuggers. To select which one to use, choose Edit Active Scheme from
the Scheme pop-up menu (Figure 3-10 (page 32)) and select the Run item in the left column. In the Info pane,
choose the debugger you want to use from the Debugger pop-up menu. Figure 5-1 shows the scheme editor
open to the Run Info pane.
Figure 5-1 Selecting a debugger in the scheme editor
LLDB is a debugger that is part of the LLVM open-source compiler project (see the LLVM home page at
http://llvm.org/). The LLDB debugger is available with Xcode for the first time with Xcode 4. With few exceptions,
the user interfaces for debugging are identical for the two debuggers.
77
Find Potential Problems with Static Analysis
Find Potential Problems with Static Analysis

Use static analysis to examine the syntax of your code for bugs. The static analyzer in Xcode 4 is similar to the
one in Xcode 3. Whereas by default, Xcode 3 opens a separate Build Results window to display the results of
the analysis, Xcode 4 lets you perform the analysis, examine the results, and edit your source files all within
the workspace window.
To run the static analyzer, select the project you want to analyze in the project navigator and then choose
Product > Analyze. (If you want to open the scheme editor to set options first, hold down the Option key while
choosing Product > Analyze.) When the analyzer finishes, the issue navigator opens automatically with a list
of the issues found. You can click an issue in the issue navigator to open the file in question. The problem is
labeled in a blue rectangle marked with an arrow. Click the blue rectangle to see the faulty logic flow found
by the analyzer (Figure 5-2).
Figure 5-2 Static analysis results
78
Locate Build Errors
As you can see in the figure, an analysis results bar opens below the jump bar. You can open the analysis
pop-up menu ( ) on the left to see the various issues found, or cycle through them by clicking the arrows at
the right end of the analysis results bar. You can open an issues pop-up menu showing the various files in
which problems were found by clicking the issues button at the right end of the jump bar (see the following
section, “Locate Build Errors”), or cycle through the issues by clicking the arrows that bracket the issues button.
Locate Build Errors

To build and run the executable specified by the active scheme, click the Run button at the left end of the
toolbar. Other options, such as running without building or building without running, are available in the
Product menu. To open the scheme editor before building or running, hold down the Option key while opening
the Product menu. Schemes are described in “Select a Scheme” (page 31). See “Customize Executables” (page
34) for information on the scheme editor.
If the compiler finds any problems while building, the issue navigator opens. Select any of the errors or warnings
in the list to display in the source editor the line of code where the problem was discovered. You can display
problems by file or by type (Figure 5-3).
Figure 5-3 The issue navigator
You can also use the issues pop-up menu to navigate through the build issues—for example, if you have the
navigator pane closed to maximize the size of the source editor (Figure 5-4). The issues menu appears as a
yellow triangle if the most serious issue listed is a warning ( ) or as a red octagon if any errors are listed (
79
Locate Build Errors
). Choose an error from the menu or use the arrows to cycle through the errors. If there’s more than one
error associated with a line of code, a number appears at the right end of the error description in the source
editor. Click the number to display a list of all the errors associated with that line of code.
Figure 5-4 The issues pop-up menu
As of Xcode 4.1, you can select what kind of content to view when debugging: source only (when available),
disassembly only, or source and disassembly. The disassembly is the set of assembly-language instructions
seen by the debugger while your program is running. Viewing the disassembly can give you more insight into
what your code is doing when it’s stopped at a breakpoint. By viewing the disassembly and source code
together, you can more easily relate the instruction being executed with the code you wrote.
To view the disassembly while debugging, choose Product > Debug Workflow > Show Disassembly When
Debugging, or open an assistant editor and choose Disassembly from the Assistant pop-up menu in the assistant
editor jump bar.
80
View Build Results
View Build Results

The log navigator in Xcode 4 replaces the Xcode 3 build log window and also shows you the history of your
console run and debug sessions. When you select one of the builds in the build log, the results are displayed
in the editor area (Figure 5-5).
Figure 5-5 The build log
Double-click a warning or error to open the source editor to that error, or open an assistant editor, set it to
Referenced Files, and select an issue in the log to see it displayed in the assistant editor.
81
Manage Breakpoints
Click the list icon ( ) at the end of a build command line to see the full build command and results (Figure
5-6).
Figure 5-6 The build log with a verbose build command
Manage Breakpoints
Although you can use the debugger to pause execution of your program at any time and view the state of the
running code, it's usually helpful to set breakpoints before running your executable so you can stop at known
points and view the values of variables in your source code.
To set breakpoints, open a source-code file and click in the gutter next to the spot where you want execution
to stop. When you add a breakpoint to the code, Xcode automatically enables breakpoints, as indicated by
the breakpoint-state button in the toolbar (enabled: disabled: ). You can toggle the enabled state of
breakpoints at any time by clicking the breakpoint-state button. You can also disable an individual breakpoint
by clicking its icon. To remove a breakpoint completely, drag it out of the gutter.
You can set several options for each breakpoint, such as a condition, the number of times to pass the breakpoint
before it’s triggered, or an action to perform when the breakpoint is triggered. To set breakpoint options, open
the breakpoint navigator and Control-click the breakpoint for which you want options (Figure 5-7), then choose
82
Manage Breakpoints
Edit Breakpoint from the shortcut menu. The Condition field lets you specify an execute condition for the
breakpoint. When you specify a condition, the breakpoint is triggered only if the condition (for example, i ==
24) is true. You can use any variables that are in the current scope for that breakpoint. Note that you must cast
any function calls to the appropriate return type.
Figure 5-7 Setting breakpoint options
In addition to conditional breakpoints, which are triggered when a specific condition is met, you can create
exception breakpoints, which are triggered when a specific type of exception is thrown or caught, and symbolic
breakpoints, which are triggered when a specific method or function begins execution. To do so, click the Add
(+) button at the bottom of the breakpoint navigator and choose Add Exception Breakpoint or Add Symbolic
Breakpoint from the pop-up menu.
By default, a new breakpoint is local to the workspace you have open. If you add the project containing that
breakpoint to another workspace, the breakpoint is not copied to the new workspace. You can assign breakpoints
to other scopes, however. If you move a breakpoint to User scope, it appears in all of your projects and
workspaces. If you move a breakpoint to a specific project, then you see this breakpoint whenever you open
83
Examine Threads and Stacks
that project, regardless of which workspace the project is in. To change the scope of a breakpoint, Control-click
the breakpoint and choose the scope from the Move Breakpoint To menu item. The scopes of breakpoints are
shown in the breakpoint navigator (Figure 5-8).
Figure 5-8 Scopes of breakpoints in the breakpoint navigator
You can share any breakpoints with other users. To share a breakpoint, in the breakpoint navigator, select the
breakpoint you want to share, Control-click the breakpoint, and choose Share Breakpoint from the shortcut
menu. Xcode moves shared breakpoints into their own category in the breakpoint navigator.
Examine Threads and Stacks

When you pause execution of your code (see “Control Program Execution” (page 85)) or the running code
triggers a breakpoint, Xcode opens the debug navigator, displaying the threads that were running when
execution paused. Under each thread is the stack at that point in program execution. Select a stack frame to
see in the source editor the corresponding source file or disassembled object code.
84
Control Program Execution
The slider at the bottom of the debug navigator controls how much stack information the debug navigator
displays. At the left end of the slider, the debug navigator shows only the top frame of each stack. At the right
end, it shows all stack frames. Click the button at the left end of the slider ( ) to toggle between displaying
all the active threads or only threads that have your code in them (as opposed to system library code). Figure
5-9 shows the debug navigator when execution has stopped at a breakpoint.
Figure 5-9 The debug navigator stopped at a breakpoint

When you execute a program from Xcode 4, the debug bar appears at the bottom of the editor pane (see
Figure 5-9 (page 85)). The debug bar includes buttons to:
● Open or close the debug area
● Pause or resume execution of your code
● Step over; that is, execute the current line of code and, if the current line is a routine, return to the next
line in the current file
● Step in; that is, execute the current line of code and, if the current line is a routine, jump to the first line
of that routine
85
● Step out of a jumped-to routine; that is, complete the current routine and step to the next routine or back
to the calling routine.
Press Control to step by assembly language instruction instead of by statement (the step icons change to show
a dot rather than a line under the arrow) or Control-Shift to step only into or over the active thread while
holding other threads stopped (the step icons show a dashed rather than solid line under the arrow).
If you pause execution or a breakpoint is triggered, the debug area opens displaying the values of variables
and registers, plus the debug console (Figure 5-10). You can use the buttons at the right end of the debug
area toolbar to display both the variables and console panes or to hide either one.
Figure 5-10 The debug area
The variables pane displays variables and registers. You specify which items to display using the pop-up menu
in the top-left corner of the variables pane:
● Auto displays only the variables you’re most likely to be interested in, given the current context.
● Local displays local variables.
● All displays all variables and registers.
86
Use the search field to filter the items displayed in the variables pane.
The console pane displays program output and lets you enter commands to the debugger tool. You specify
the type of output the console displays with the pop-up menu in the top-left corner of the console pane:
● All Output displays target and debugger output.
● Debugger Output displays debugger output only.
● Target Output displays target output only.
You can use the navigation pop-up menus in the debug bar to navigate through the threads and stacks (Figure
5-11), or you can use the debug navigator for that purpose.
Figure 5-11 Navigating through threads and stacks in the debug bar
While execution is stopped at a breakpoint, you can view variables and step through code in the source editor
in much the same way as you can in Xcode 3. For example, to continue execution to a specific line of code,
hold the pointer over the gutter next to the target code line until the continue-to-here icon appears, then click
the icon (Figure 5-12).
Figure 5-12 Activating the continue-to-here command
87
To see the values of variables, click the variable name in the editor (Figure 5-13). Hover over and click variable
components to open the disclosure triangles to see the fields of structures.
Figure 5-13 Reading the value of a variable in the source editor
88
Replacing Text and Refactoring
Like Xcode 3, Xcode 4 enables you to replace text throughout your project and to make other global changes
to your code, such as converting the code to Objective-C 2.0 or creating a superclass from a class. These facilities
are referred to as search and replace and factoring .
FInd and Replace Text

To replace text in your source files, choose Replace from the pop-up menu in the search navigator (Figure 6-1).
Type the text you want to find in the top text field and press Return, then type the replacement text in the
lower text field (Figure 6-2). Note that Xcode does not search for the text if you don’t press Return while the
89
FInd and Replace Text
cursor is in the upper text field, so if you get no results after typing your replacement text, put your cursor in
the upper text field and press Return. The activity viewer in the workspace toolbar indicates the find operation
is in progress (Figure 6-3).
Figure 6-1 Find/Replace pop-up menu
Figure 6-2 Find/Replace results
90
Preview Changes
Figure 6-3 Activity viewer during a Find operation
Click Replace All to replace every occurrence of the searched-for text with the replacement text. To replace a
single result, click that result to select it and press Replace. To replace a subset of the occurrences found, use
Shift-click or Command-click to make your selection and press Replace.
By default, Xcode creates a snapshot of your project before making the changes; see “Take a Snapshot of Your
Workspace” (page 95)). To change this preference, select the Snapshots pane in the File > Project Settings
dialog. You can also make a manual snapshot before clicking the Replace button (choose File > Manual
Snapshot).
Preview Changes
To see what your changes will look like in your source code before deciding which occurrences to replace,
click the Preview button below the Replace text box (Figure 6-2 (page 90)). The preview dialog is shown in
Figure 6-4.
Figure 6-4 Replacement preview
91
Refactor Your Code
To select an individual occurrence of the Find text for replacement, click the checkbox for that occurrence in
the left pane of the dialog, or click the sliding switch in the center of the right pane. Alternatively, you can
select as many occurrences as you wish in the left pane using Shift-click or Command-click, and then press the
Space bar to select them. If you decide to replace all the occurrences, click Cancel and then click the Replace
All button.
Refactor Your Code

A refactoring operation is one that improves the structure of source code without changing its behavior. You
might do this to make it easier to maintain, or as a first step in making further changes to the code. Refactoring
in Xcode 4 works much as it does in Xcode 3. Before you can choose a refactoring operation (also called a
transformation ) from Edit > Refactor or from the shortcut menu in the source editor, you have to select the
source code that you want to refactor. Only the refactoring operations appropriate for the selected text are
available in the menu.
Once you’ve selected the text and the refactoring operation, Xcode presents a dialog to let you select options
and specify symbol names where necessary.
92
Refactor Your Code
You also have the opportunity to preview the changes and decide which files to include before applying the
changes (Figure 6-5). Uncheck a file in the navigator pane to leave it out of the refactoring operation. You can
edit your source code directly in the Preview dialog. Any such edits are shown in the preview and included in
the refactoring operation.
Figure 6-5 Refactor preview dialog
Possible refactoring operations include:

● Rename changes the name of the selected item throughout your project files; select any symbol except
except the declaration of a method inside a protocol interface. If you’re renaming a class and you have
files that use that class in the file name, check the Rename related files checkbox to rename the files as
part of the refactoring operation.
● Extract creates a function or method from the selected code; select code or code and comments within
a function or method implementation.
● Encapsulate creates accessors (Get and Set methods) for the selected item and changes code that directly
accesses the item to use the accessor methods instead; select a symbol that is an instance variable (“ivar”)
or a member of a struct or union.
● Create Superclass creates a superclass from the selected class; select a symbol that is a class defined in
your project.
● Move Up Moves the declaration and definition of the selected item into the superclass of the class where
they currently reside, removing them from their former location; select a symbol that is a method or
instance variable in a class, not a category, where the class and superclass are defined in your project.
93
Refactor Your Code
● Move Down moves the declaration and definition of the refactoring item to one or more of the subclasses
of the class that declares and defines the item; select a symbol that is an instance variable in a class, not
a category, where the class is defined in your project and one or more subclasses already exist.
Refactoring works only with C and Objective-C files.
Before you’ve saved your updated files, you can use the Edit > Undo operation on a per-file basis to back out
changes, or you can close the project without saving changes to revert to your original files.
94
Repositories, Snapshots, and Archives
Xcode 4 supports source control repositories for Subversion and Git. It also provides a new snapshot facility
that is much faster than the one in Xcode 3. In addition, whenever you build a target for distribution, Xcode 4
saves an archive of the build products.
Take a Snapshot of Your Workspace

Compared with Xcode 3, the Xcode 4 snapshot feature is much faster and more reliable. Xcode 4 snapshots
are not compatible with Xcode 3 snapshots, however. To restore to a snapshot you took in Xcode 3, you have
to be running Xcode 3, and vice versa.
Note that you must have installed the Git tool by selecting System Tools in the Xcode 4 installer in order to
use snapshots.
To create a snapshot manually, choose File > Create Snapshot. In addition, by default Xcode 4 creates a snapshot
automatically before a major change such as refactoring your code or executing a find-and-replace operation.
Choose File > Project Settings (or Workspace Settings) to change this option.
To see the snapshots for a project or workspace, click the project in the Projects pane of the Organizer window.
In Xcode 4.1 and later, to restore a snapshot, choose Restore Snapshot from the File menu and select the
snapshot to restore. Xcode displays a preview dialog in which you can review the differences between the
current version of the project and the snapshot version. When you click Restore, Xcode replaces the current
version of the project with the version in the snapshot. Xcode makes a snapshot of the current version before
replacing it.
95
Take a Snapshot of Your Workspace
To restore a snapshot in a new location instead of restoring on top of the current project, select the project in
the Projects pane of the Organizer window, choose the snapshot you want to restore, and click the Export
Snapshot button at the bottom of the window (Figure 7-1).
Figure 7-1 Snapshots listed in the Organizer window
Note that, because Xcode 4 keeps track of all your projects and displays them in the Projects pane of the
Organizer even if they no longer exist, you can restore a deleted project from a snapshot.
96
Keep Track of Changes and Coordinate Work Groups

In Xcode 4, you configure SCM repositories in the Organizer (Figure 7-2) instead of a preference pane, as is
done in Xcode 3. If you check a project or workspace out of Subversion or Git using the command line or
another tool, you can add it to your Xcode SCM repository support. To do so, click the plus sign (+) at the
bottom of the navigation pane in the repository organizer and choose Add Working Copy.
Figure 7-2 Repositories Organizer
Xcode 4 provides a consistent user interface for both Subversion and Git. For example, the Subversion UI now
supports annotations. The Xcode 4 installer installs the Git and Subversion tools when you select System Tools.
SCM status is shown as a badge in the project navigator (Figure 7-3), as follows:
M Locally modified
U Updated in repository
A Locally added
D Locally deleted
I Ignored
97
R Replaced in the repository
– The contents of the folder have mixed status; display the contents to see individual status
Figure 7-3 Source control badges in the project navigator
Badges propagate up to the highest container so you can see the source control status of the whole workspace
regardless of the disclosure level. Detailed SCM status is shown in the Source Control area of the File inspector
in the utility area.
Source control commands are now in the Source Control submenu of the File menu, rather than in a separate
SCM menu. When you’ve made changes to files and saved them locally, use the project navigator to select the
individual files for which you want to perform a source control operation, and choose the action you wish to
perform from the File > Source Control menu (Figure 7-4). Saving a file is not the same as committing it to
source control; you must explicitly commit the file. To see which files have been modified locally but not
committed, look for the M badge next to the filename in the project navigator. You can use the SCM status
filter at the bottom of the project navigator to display only files with SCM status.
Figure 7-4 The Source Control submenu
Update and commit operations are recorded in the log navigator. Select a log to see the individual steps of
that operation in the editor pane.
98
Set Up Git Version Control

Xcode creates a Git repository for a new project if you check the Source Control check box in the Save As dialog.
When you do so, Xcode adds a hidden file (named .git) to the folder containing the project. That file contains
all the information Git needs to keep track of the files in the project and the changes made to them. Xcode
also performs an initial commit of the files in the folder. Any time you add files to your project or modify any
of the files in the project, you need to commit them to add them to the repository (see “Commit Files to Add
Them to a Repository” (page 99)).
Note that you must have installed the Git tool by checking the System Tools check box in the Xcode installer
in order to create and use a Git repository. This check box is enabled by default.
Commit Files to Add Them to a Repository

When you edit a file, it is changed locally but the changes are not included in the source control repository.
To add the changes to the repository, you must commit the file. You must save the file before you can commit
it, but note that saving a file is not the same as committing it to source control—you must explicitly commit
the file. To see which files have been modified locally but not committed, look for the M badge next to the file
name in the Project navigator. (New files that have never been committed to source control have the A badge.)
You can use the SCM status filter at the bottom of the Project navigator to display only files with SCM status.
When you choose Commit, a confirmation dialog opens that you can use to make sure the changes you are
committing are what you intended (“Commit Files to Add Them to a Repository”). You can compare your new
version with any past version in the confirmation dialog. When you choose File > Source Control > Commit,
the confirmation dialog shows all the files with pending changes. Uncheck the checkboxes next to any files
that you do not wish to commit. When you choose Source Control > Commit Selected Files from the shortcut
menu in the project navigator, only the files you’ve selected in the project navigator are included in the
99
confirmation dialog. In either case, you must enter a comment before committing. You can edit the file in the
confirmation dialog before committing. Any changes you make this way are included in the committed file
and saved in your project.
Figure 7-5 Commit confirmation
Reconcile Different Branches

When you’re ready to merge the code in a separate branch back into the main branch, or when you want to
combine the code in any two branches, you can use the merge facility of your source control system to reconcile
differences between the branches.
To do so, save and commit any changes, switch to the branch into which you want to merge code, and choose
File > Source Control > Merge. In the Merge dialog (Figure 7-6 (page 101)), the left pane shows what the merged
file will look like. The right pane shows the file with which you’re merging. For each difference or conflict
between the files, an arrow in the center points to the file taking precedence. For example, if the file on the
100
right (the one with which you’re merging) has a line of code missing from the file on the left (your working
copy) and the arrow is pointing toward the file on the right, then the line of code will be included in the working
copy after the merge operation is complete.
Figure 7-6 The Merge dialog
For each difference or conflict, you can use the left and right arrow buttons at the bottom of the dialog to
specify which file’s contents should be used. Therefore, to use the contents of the working copy to resolve the
top difference in the figure, click on the arrow for that difference and then click on the left arrow button at the
bottom of the dialog. Because this line is missing from the current working copy, it is no longer shown in the
left pane. In the case of a conflict, there are two additional options for reconciling differences: you can take
the code lines from both files, either listing the ones in the left (working copy) file first and those in the right
(root copy) file second, or vice versa.
If you wish, you can edit the current branch in the dialog to reconcile any differences not handled by the four
choices. Click Merge and commit the changes to the updated files to complete the operation.
101
Compare Revisions
Save Internal Project Files in Repositories

In Xcode 4.1 and later, you can use repositories to view internal project files (schemes, user interface settings,
and so forth) when looking at SCM details in the SCM commit and update workflows. You can use this facility
to save and keep track of versions of project files in the same way as you save and keep track of source files.
Figure 7-7 shows a commit dialog displaying two versions of a scheme.
Figure 7-7 A scheme in the commit dialog
Compare Revisions
Select any file under source control and click the Version Editor button ( ) to display two versions
of that file in a side-by-side view. Use the jump bar underneath either editor pane to select the version of the
file to compare with the one in the other pane (Figure 7-8 (page 103)).
102
Compare Revisions
Buttons under the version editor allow you to show a file comparison and timeline, change logs for the file, or
individual change annotations (“blame”) for each line of the file.
Figure 7-8 Comparing two revisions of a file with the version editor
You can edit the current working copy of the file in the version editor and you can copy code from an older
version and paste it into the current version. In Xcode 4, the working copy of a file is on the left.
103
Compare Revisions
Select Revisions to Compare

Click the Timeline icon ( ) in the center column to show a visual timeline of all repository versions (Figure
7-9); use the sliders to control which version is displayed on each side.
Figure 7-9 Using the version editor timeline
Review Individual Changes

In Blame mode, the current revision of the file is displayed along with the last revision that modified each line
of the file. If you wish, you can use the jump bar at the bottom of the window to select a different revision to
examine.
104
Compare Revisions
Each log entry is aligned with the line in the file where the change was made. The log entry includes the name
of the person who committed the change, the date, and the ID of the commit. Next to the entry is an arrow
button. Figure 7-10 shows Blame mode in use.
Figure 7-10 Version editor Blame mode
Click the arrow next to any change that interests you to see that change displayed in Comparison mode. Use
the Up Arrow and Down Arrow keys on the keyboard to highlight the change associated with this Blame-mode
entry.
105
Distribute Your Program or Submit an Application
List All Revisions Chronologically

To review all revisions to a file listed in chronological order, use Log mode (Figure 7-11). Each change is listed
individually, and you can click the arrow next to the log entry to see the change displayed in Comparison
mode.
Figure 7-11 Version editor Log mode

To build your project and save the resulting application or a disk image of the set of build products, choose
Archive from the Product menu. Xcode creates an archive of your project using the build configuration and
name you specified in the Archive pane of the scheme editor (see “Select a Scheme” (page 31)) and saves the
archive in the location specified in the Locations pane of Xcode preferences.
106
To see the archives for your project, open the Archives Organizer window (Figure 7-10). To submit your
application to the app store, you must have an iTunes Connect account. Click Submit to submit the application.
Click Validate to run the same validation used by iTunes Connect to make sure your application is ready for
submittal. To get a copy of your application that you can package for distribution or share with others, click
Share. You can add a comment by clicking on the text field in the Comment column.
Figure 7-12 Archives organizer
107
Document Revision History
This table describes the changes to Xcode 4 Transition Guide .
Date Notes
2011-08-10 Added features new with Mac OS X v10.7 Lion.
2011-07-07 Added information about features new in Xcode 4.1, including Interface
Builder plug-ins and automatic project updates.
2011-02-08 New document that explains how to get started using Xcode 4 if you're
already familiar with Xcode 3.
108
Apple Inc.
© 2011 Apple Inc.
All rights reserved.
No part of this publication may be reproduced,

stored in a retrieval system, or transmitted, in any
form or by any means, mechanical, electronic,
photocopying, recording, or otherwise, without
prior written permission of Apple Inc., with the
following exceptions: Any person is hereby
authorized to store documentation on a single
computer for personal use only and to print
copies of documentation for personal use
provided that the documentation contains
Apple’s copyright notice.
The Apple logo is a trademark of Apple Inc.
No licenses, express or implied, are granted with
respect to any of the technology described in this
document. Apple retains all intellectual property
rights associated with the technology described
in this document. This document is intended to
assist application developers to develop
applications only for Apple-labeled computers.
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, Cocoa, Finder, Instruments,

iPhone, iTunes, Leopard, Mac, Mac OS,
Objective-C, Safari, Sand, Snow Leopard, and
Xcode are trademarks of Apple Inc., registered in
the United States and other countries.
iPad is a trademark of Apple Inc.
IOS is a trademark or registered trademark of
Cisco in the U.S. and other countries and is used
under license.
Even though Apple has reviewed this document,
APPLE MAKES NO WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS
DOCUMENT, ITS QUALITY, ACCURACY,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED
“AS IS,” AND YOU, THE READER, ARE ASSUMING THE
ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS DOCUMENT, even if advised of
the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE
ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,
agent, or employee is authorized to make any
modification, extension, or addition to this warranty.
Some states do not allow the exclusion or limitation
of implied warranties or liability for incidental or
consequential damages, so the above limitation or
exclusion may not apply to you. This warranty gives
you specific legal rights, and you may also have other
rights which vary from state to state.

Xcode 4 Transition Guide

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Xcode 4 Transition Guide

Uploaded by

Copyright:

Available Formats

Xcode 4 Transition

About the Transition to Xcode 4 8

Using an Existing Xcode 3 Project 11

Creating a New Xcode 4 Project 21

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

View Preprocessor or Assembly Output 31

Designing User Interfaces in Xcode 4 63

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Create an Interface Controller 68

Debugging and Analyzing Your Code 77

Replacing Text and Refactoring 89

Repositories, Snapshots, and Archives 95

Document Revision History 108

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

About the Transition to Xcode 4 8

Using an Existing Xcode 3 Project 11

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Figure 3-24 The activity viewer 45

Designing User Interfaces in Xcode 4 63

Debugging and Analyzing Your Code 77

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Figure 5-3 The issue navigator 79

Replacing Text and Refactoring 89

Repositories, Snapshots, and Archives 95

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Figure I-1 The Xcode 4 workspace window

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Use Xcode 4 for Development on Recent OS Versions

Open Your Project in Xcode 4

Get Oriented to Xcode’s Organization and Features

Relevant Chapter: “Orientation to Xcode 4” (page 22).

Learn How to Use Xcode 4 to Design a User Interface

Relevant Chapter: “Designing User Interfaces in Xcode 4” (page 63).

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Debug and Refine Your Code In Xcode 4

Back Up Your Code and Use Source Control

Relevant Chapter: “Repositories, Snapshots, and Archives” (page 95).

Use Archives to Distribute Your Program

Relevant Chapter: “Repositories, Snapshots, and Archives” (page 95).

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Open Your Xcode 3 Project in Xcode 4

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

See Your Groups and Files

Figure 1-1 A newly opened Xcode 4 window with an Xcode 3 project

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Figure 1-2 The project contents in the Xcode 4 project navigator

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Replace Your Interface Builder Plug-ins

Figure 1-3 IB plug-in upgrade dialog

Keep Your Xcode 3 Preferences

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Check Out a Working Copy

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Modernize Your Project

Figure 1-4 Modernization in the issue navigator

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

Figure 1-5 Updates dialog

Work with Multiple Related Projects

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.

2011-08-10 | © 2011 Apple Inc. All Rights Reserved.