Xcode 4 Transition Guide

Tools & Languages: IDEs

2011-02-08
 any modification, extension, or addition to this
warranty.
Apple Inc.
Some states do not allow the exclusion or limitation
© 2011 Apple Inc. of implied warranties or liability for incidental or
All rights reserved. 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
No part of this publication may be reproduced, other rights which vary from state to state.
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

App Store is a service mark of Apple Inc.

Apple, the Apple logo, Cocoa, Finder,
Instruments, iPhone, iTunes, Mac, Mac OS,
Objective-C, Safari, 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
 Contents

Introduction About the Transition to Xcode 4 11

Xcode 4 Provides Many Advantages 11

Use Xcode 4 for Development on Recent OS Versions 12
The Xcode 4 Transition Guide At a Glance 12
Open Your Project in Xcode 4 12
Get Oriented to Xcode’s Organization and Features 12
Learn How to Use Xcode 4 to Design a User Interface 13
Debug and Refine Your Code In Xcode 4 13
Back Up Your Code and Coordinate the Work of Multiple Programmers With Snapshots and
Source Control 13
Use Archives to Distribute Your Program 13

Chapter 1 Using an Existing Xcode 3 Project 15

Open Your Xcode 3 Project in Xcode 4 15

Working on a Project in Xcode 4 Leaves Your Xcode 3 Preferences Untouched 17
Check Out a Working Copy from Your Source Control Repository 17
Create a Workspace to Work with Multiple Related Projects 19

Chapter 2 Creating a New Xcode 4 Project 23

Click New Project in the Xcode 4 Startup Screen to Create a Standalone Project 23
Create a New Workspace If You Have More Than One Related Project 23

Chapter 3 Orientation to Xcode 4 25

Much of Your Project’s Content Is in New Locations in Xcode 4 25

Targets and Build Settings Are in the Project Editor 25
Set the Basic Build Settings for Each Target in the Summary Pane of the Project Editor 26
Select Any File to Open an Editor for That File Type 27
The Source Code Editor Is Similar to the One in Xcode 3 27
Code Completion Is Easier to Use 27
Use Fix-it to Flag Errors and Warnings as You Type 29
Option-Click to Open a File in the Assistant Editor Pane 30
Use the Hex Editor to View Files in Hexadecimal Format 30
View Either Descriptive Key Names or Raw Keys in the Property List Editor 30
Select a Scheme Instead of Setting an Active Target, Build Configuration, and Executable 30
The Scheme Editor Build Pane Specifies Which Targets are Built for Each Type of Action 31
Customize Executables in the Scheme Editor 32
Rename or Reorganize Your Schemes in the Manage Schemes Dialog 33
Use the Find Navigator to Search Your Workspace and List Search Results 33

3
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CONTENTS

Browse to Project Symbols in the Symbol Navigator and the Jump Bar 34
Use Navigators and Filters Instead of Smart Groups 37
The Detail View Isn’t Needed Any More 38
Customize the Build and Run Workflow with the Scheme Editor and Behaviors Preferences 39
Check on the Progress of Xcode Tasks in the Activity Viewer 41
View Projects, Devices, and Documentation in the Organizer Window 41
Browse and Bookmark Documents in the Documentation Organizer 42
Browse for Task-Based Help in the Documentation Organizer 43
Work with Your Source Control Repositories in the Repositories Organizer 44
Organize Your Projects and Devices in the Projects and iOS Organizers 44
Archive Your Product for Distribution 45
Control-Click for Contextual Help 45
Xcode 4 Saves Your Changes Automatically 46
Split the Editor Area to Display Related Content 46
Assistant Finds Related Content for You 47
Use Assistant with Interface Builder 47
Use the Manual Editor to Display Content of Your Choosing 48
The Version Editor Compares Two Versions of Your File 48
Open a New Tab or a New Window to Display More Content 48
Select Keyboard Shortcuts For Opening Files in Assistant Editors, Tabs, or New Windows 48
The Utility Area Supplements the Information in the Editor 50
View Quick Help in the Utility Area 50
Use Inspectors to View and Enter File and Interface Builder Data 53
Drag Files and Code from the Library into Your Project 54

Chapter 4 Designing User Interfaces in Xcode 4 57

Interface Builder Is Fully Integrated with Xcode 4 57

Create a New Nib File with the File Menu or the Library 58
New Classes are Created by Xcode, Not Interface Builder 58
Add Source Files For A New Nib FIle, Then Add the Nib FIle 59
To Add a Custom View, Start With the View’s Subclass, Then Add the View To Your Nib 61
Create Your Interface Controller in Xcode, Then Add a Controller Object to the Nib File 62
Use Assistant to Work on Your Interface Source Code 63
Make Connections Directly Between IB Objects and Source Code 65
Control-click the Canvas to Get Online Help 67
The Document Window Is Replaced by a Dock or List 68
See the User Guide and Xcode Quick Start Guide for More 69

Chapter 5 Debugging and Analyzing Your Code 71

Select a Debugger in the Scheme Editor 71

Use Static Analysis to Find Potential Problems Before Building 72
Use the Issue Navigator or Issues Pop-up Menu to Locate Build Errors 73
Use the Log Navigator to View Build Results 74
Use the Source Editor and Breakpoint Navigator to Manage Breakpoints 75

4
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CONTENTS

Use the Debug Navigator to Examine Threads and Stacks 77

Control Program Execution in the Debug Area and Source Editor 78

Chapter 6 Replacing Text and Refactoring 81

Replace Text Using the Search Navigator 81

Preview Changes Before Replacing Text 83
Refactor Your Code to Make It Easier to Maintain 83

Chapter 7 Repositories, Snapshots, and Archives 87

A Snapshot Saves a Copy of the Current Version of Your Workspace 87

Source Control Repositories Help You Keep Track of Changes and Coordinate Work Groups 88
Set Up Git Version Control When You Create a New Project 90
Commit Files to Add Them to a Repository 91
The Merge Facility Helps You Reconcile Different Branches 91
Use the Version Editor to Compare Revisions 92
The Timeline Provides a Convenient Way to Select Revisions to Compare 93
Use Blame Mode to Review Individual Changes 94
Log Mode Lists All Revisions Chronologically 95
Use Archives to Distribute Your Program or Submit an Application to the App Store 96

Document Revision History 97

5
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CONTENTS

6
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 Figures

Introduction About the Transition to Xcode 4 11

Figure I-1 The Xcode 4 workspace window 11

Chapter 1 Using an Existing Xcode 3 Project 15

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

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

Chapter 3 Orientation to Xcode 4 25

Figure 3-1 Target information in the project editor 25

Figure 3-2 Build settings 26
Figure 3-3 The Mac OS X summary pane 27
Figure 3-4 Code completion 28
Figure 3-5 Quick help for code completion 28
Figure 3-6 Code completion underlining 29
Figure 3-7 Fix-it in action 29
Figure 3-8 The Scheme pop-up menu 31
Figure 3-9 The scheme editor Build pane 32
Figure 3-10 Customizing an executable environment for a product 33
Figure 3-11 The find navigator 34
Figure 3-12 The Find Options dialog 34
Figure 3-13 The symbol navigator 35
Figure 3-14 The symbol navigator, filtered 36
Figure 3-15 A symbol displayed in the source editor 36
Figure 3-16 Using the jump bar to find a symbol 37
Figure 3-17 The related-items pop-up menu 37
Figure 3-18 The project navigator filtered to show only .m files 38
Figure 3-19 Run diagnostic options 39
Figure 3-20 Behaviors preferences 40
Figure 3-21 Naming a tab 41
Figure 3-22 The activity viewer 41
Figure 3-23 The activity pop-up window 41
Figure 3-24 The Organizer button 42
Figure 3-25 The documentation navigator 42
Figure 3-26 The bookmarks navigator 43
Figure 3-27 Finding Xcode 4 help articles 44
Figure 3-28 Contextual help 46
Figure 3-29 The Assistant button 47
Figure 3-30 Setting the behavior for Assistant 47
Figure 3-31 The Single Assistant navigation chooser dialog 49

7
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 FIGURES

Figure 3-32 The navigation chooser dialog 50

Figure 3-33 The Utility button 50
Figure 3-34 The Quick Help window 51
Figure 3-35 The Symbol inspector 51
Figure 3-36 Quick Help for Interface Builder objects 52
Figure 3-37 Quick Help for build settings 53
Figure 3-38 A file inspector 54
Figure 3-39 A file template information pop-up window 54
Figure 3-40 Dragging a piece of a code snippet into your file 55
Figure 3-41 A user-customized code snippet 55

Chapter 4 Designing User Interfaces in Xcode 4 57

Figure 4-1 Interface Builder in the workspace window 57

Figure 4-2 Dropping a nib file in the Resources group 58
Figure 4-3 Creating new class files 59
Figure 4-4 Adding a new Window nib file 60
Figure 4-5 Assigning a class to an Interface Builder object 61
Figure 4-6 Adding a custom view 62
Figure 4-7 Adding a controller object to a nib file 63
Figure 4-8 Selecting a counterpart to a nib file in assistant 64
Figure 4-9 Interface Builder with the Assistant editor open 65
Figure 4-10 Making a connection to source code from Interface Builder 66
Figure 4-11 Inserting an action or outlet statement in your header file 67
Figure 4-12 Connection insertion dialog 67
Figure 4-13 Help articles in Interface Builder 68
Figure 4-14 Outline view for placeholders and objects in Interface Builder 69

Chapter 5 Debugging and Analyzing Your Code 71

Figure 5-1 Selecting a debugger in the scheme editor 71

Figure 5-2 Static analysis results 72
Figure 5-3 The issue navigator 73
Figure 5-4 The issues pop-up menu 74
Figure 5-5 The build log 74
Figure 5-6 The build log with a verbose build command 75
Figure 5-7 Setting breakpoint options 76
Figure 5-8 Scopes of breakpoints in the breakpoint navigator 76
Figure 5-9 The debug navigator stopped at a breakpoint 77
Figure 5-10 The debug area 79
Figure 5-11 Navigating through threads and stacks in the debug bar 80
Figure 5-12 Activating the continue-to-here command 80
Figure 5-13 Reading the value of a variable in the source editor 80

8
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 FIGURES

Chapter 6 Replacing Text and Refactoring 81

Figure 6-1 Find/Replace pop-up menu 81

Figure 6-2 Find/Replace results 82
Figure 6-3 Activity viewer during a Find operation 82
Figure 6-4 Replacement preview 83
Figure 6-5 Refactor preview dialog 84

Chapter 7 Repositories, Snapshots, and Archives 87

Figure 7-1 Snapshots listed in the Organizer window 88

Figure 7-2 Repositories Organizer 89
Figure 7-3 Source control badges in the project navigator 90
Figure 7-4 The Source Control submenu 90
Figure 7-5 Commit confirmation 91
Figure 7-6 The Merge dialog 92
Figure 7-7 Comparing two revisions of a file with the Version editor 93
Figure 7-8 Using the Version editor timeline 94
Figure 7-9 Version editor Blame mode 95
Figure 7-10 Version editor Log mode 95
Figure 7-11 Archives organizer 96

9
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 FIGURES

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

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.

Xcode 4 Provides Many Advantages

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.

● 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.

Xcode 4 Provides Many Advantages 11

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 INTRODUCTION
About the Transition to Xcode 4

● 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).

The Xcode 4 Transition Guide At a Glance

This document first introduces you to the layout and features of Xcode 4 and then describes the most common
workflows in more detail.

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 15)

● “Creating a New Xcode 4 Project” (page 23)

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 Chapters:
● “Orientation to Xcode 4” (page 25)

12 Use Xcode 4 for Development on Recent OS Versions

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
INTRODUCTION
About the Transition to Xcode 4

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 Chapters:
● “Designing User Interfaces in Xcode 4” (page 57)

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 25)

● “Debugging and Analyzing Your Code” (page 71)

● “Replacing Text and Refactoring” (page 81)

Back Up Your Code and Coordinate the Work of Multiple

Programmers With Snapshots and 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 87)

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 87)

The Xcode 4 Transition Guide At a Glance 13

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 INTRODUCTION
About the Transition to Xcode 4

14 The Xcode 4 Transition Guide At a Glance

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 1

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. Once you’ve got your projects open, go to
“Orientation to Xcode 4” (page 25) 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. Opening and building a project in Xcode 4 does not upgrade or alter it. Changes
you make to a project in Xcode 4 remain compatible with earlier versions of Xcode.

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.

Open Your Xcode 3 Project in Xcode 4 15

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 1
Using an Existing Xcode 3 Project

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

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

16 Open Your Xcode 3 Project in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 1
Using an Existing Xcode 3 Project

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 25).

Working on a Project in Xcode 4 Leaves Your Xcode 3 Preferences

Untouched

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.

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.

Check Out a Working Copy from Your Source Control Repository

If your Xcode project is in a Git or Subversion repository, you can check out your project from the repository
and open it in Xcode. 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.

Working on a Project in Xcode 4 Leaves Your Xcode 3 Preferences Untouched 17

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 1
Using an Existing Xcode 3 Project

2. In the Checkout or Clone dialog, enter the path to the repository you want to clone or check out.

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).

18 Check Out a Working Copy from Your Source Control Repository

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 1
Using an Existing Xcode 3 Project

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).

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 87) for more information about source control in Xcode
4.

Create a Workspace to Work with Multiple Related Projects

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, including:

● One project can use the products of another project while building.

● If one project depends on the products of another in the same workspace, Xcode can detect this and
automatically build the projects in the correct sequence.

Create a Workspace to Work with Multiple Related Projects 19

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 1
Using an Existing Xcode 3 Project

● 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.

● 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 (“Select a Scheme Instead
of Setting an Active Target, Build Configuration, and Executable” (page 30)). 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.

20 Create a Workspace to Work with Multiple Related Projects

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 1
Using an Existing Xcode 3 Project

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 “Targets and Build Settings Are in the Project Editor” (page 25) 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 Instead of
Setting an Active Target, Build Configuration, and Executable” (page 30) and “Customize Executables in the
Scheme Editor” (page 32).

Create a Workspace to Work with Multiple Related Projects 21

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 1
Using an Existing Xcode 3 Project

22 Create a Workspace to Work with Multiple Related Projects

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 2

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 If You Have More Than One
Related Project” (page 23).

Click New Project in the Xcode 4 Startup Screen to 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 15).

Create a New Workspace If You Have More Than One Related Project

If you decide you want more than one project, then you should create an Xcode workspace to hold the
related projects. 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.

Click New Project in the Xcode 4 Startup Screen to Create a Standalone Project 23
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 2
Creating a New Xcode 4 Project

24 Create a New Workspace If You Have More Than One Related Project
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3

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 71). 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 57).

Much of Your Project’s Content Is in New Locations in Xcode 4

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 Your Projects and Devices in the Projects and iOS Panes” (page 44)
for more information about the Organizer window.

Targets and Build Settings Are in the Project Editor

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

Much of Your Project’s Content Is in New Locations in Xcode 4 25

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

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 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.

Set the Basic Build Settings for Each Target in the Summary Pane of
the Project Editor
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.

26 Much of Your Project’s Content Is in New Locations in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

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.

Select Any File to Open an Editor for That File Type

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 as 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.

The Source Code Editor Is Similar to the One in Xcode 3

The features you’re used to in Xcode 3 are also present in Xcode 4: Code folding, code completion, Quick
Help, automatic indentation, syntax coloring, edit all in scope, automatic balancing of delimiters, and so forth
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.

Code Completion Is Easier to Use

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-4). 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

Much of Your Project’s Content Is in New Locations in Xcode 4 27

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

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-4 Code completion

A Quick Help popup is also available from code completion, even when the Quick Help inspector is not open.
Hover over the code completion option you’re interested in until a question mark icon appears. Click the
question mark or use the Command-Shift-Control-? Keyboard shortcut 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 popup to cancel the operation.

Figure 3-5 Quick help for code completion

If all of the possible completions have a common prefix (NSString in Figure 3-4), 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-4). Again, press Tab to accept only the subword or Return
to accept the entire suggestion.

28 Much of Your Project’s Content Is in New Locations in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Figure 3-6 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 key cancels the operation and pressing the Delete key always deletes
the preceding character.

Use Fix-it to Flag Errors and Warnings 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 underbar 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-7).

Figure 3-7 Fix-it in action

Much of Your Project’s Content Is in New Locations in Xcode 4 29

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Option-Click to 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 to Display Related
Content” (page 46)). To change this behavior and to set other keyboard shortcuts for opening files, open
the General pane of Xcode preferences.

Use the Hex Editor to 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.

When the hex editor has focus, you can use the Editor menu to customize its display.

View Either Descriptive Key Names or Raw Keys in the Property List
Editor
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 Instead of Setting an Active Target, Build

Configuration, and Executable
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

30 Much of Your Project’s Content Is in New Locations in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

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-8). 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-8 The Scheme pop-up menu

You can have as many schemes as you want, but only one can be active at a time.

The Scheme Editor Build Pane Specifies Which Targets are Built for
Each Type of Action
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-9) 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 automater
plug-in to be provided with the application, and a command-line tool that can be used with the application.
In the 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.

Much of Your Project’s Content Is in New Locations in Xcode 4 31

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-9 The scheme editor Build pane

Customize Executables in the Scheme Editor

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-10). Note that you can choose to display the
running product at a higher UI resolution to simulate running at a different display resolution.

32 Much of Your Project’s Content Is in New Locations in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Figure 3-10 Customizing an executable environment for a product

Rename or Reorganize Your Schemes in the Manage Schemes Dialog

Choose Product > Manage Schemes or choose Manage Schemes from the Scheme pop-up menu (Figure
3-8 (page 31)) 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.

Use the Find Navigator to Search Your Workspace and List Search
Results
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 “Create a Workspace to Work with
Multiple Related Projects” (page 19)). The results are displayed in the find navigator (Figure 3-11). Just as in
Xcode 3, click a find result to see the instance of the term in the source editor.

Much of Your Project’s Content Is in New Locations in Xcode 4 33

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-11 The find navigator

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-12).

Figure 3-12 The Find Options dialog

Browse to Project Symbols in the Symbol Navigator and the Jump

Bar
Click the second button from the left in the navigator selector bar to browse through the symbols in your
project (Figure 3-13). Note that you need to wait until Xcode finishes indexing your project before you can
use this feature.

34 Much of Your Project’s Content Is in New Locations in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Figure 3-13 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

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-14,
only those symbols that include the string KTg are displayed. This filter is not case sensitive.

Much of Your Project’s Content Is in New Locations in Xcode 4 35

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-14 The symbol navigator, filtered

Click a symbol to see it displayed in the source editor (Figure 3-15). 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 to Display Related
Content” (page 46)).

Figure 3-15 A symbol displayed in the source editor

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-16). 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 to Display Related
Content” (page 46)).

36 Much of Your Project’s Content Is in New Locations in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Figure 3-16 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-17.

Figure 3-17 The related-items pop-up menu

Use Navigators and Filters Instead of Smart Groups

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 16)), for example, has filters for recently edited
files, files with source control status, unsaved files, and filename strings. Figure 3-18, 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.

Much of Your Project’s Content Is in New Locations in Xcode 4 37

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-18 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 71).

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.

The Detail View Isn’t Needed Any More

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 (“Open Your Xcode 3 Project in Xcode 4” (page 15))

● Find results: use the find navigator (“Use the Find Navigator to Search Your Workspace and List Search
Results” (page 33))

● Executables: use the scheme editor (“Customize Executables in the Scheme Editor” (page 32))

38 Much of Your Project’s Content Is in New Locations in Xcode 4

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

● Targets: use the project editor (“Targets and Build Settings Are in the Project Editor” (page 25))

● Bookmarks: use the bookmarks navigator in the Organizer window for documentation bookmarks
(“Browse and Bookmark Documents in the Documentation Pane” (page 42))

● 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
(“Work with Your Source Control Repositories in the Repositories Pane” (page 44))

● Project symbols: use the symbol navigator and the jump bar (“Browse to Project Symbols in the Symbol
Navigator and the Jump Bar” (page 34))

Customize the Build and Run Workflow with the Scheme Editor and
Behaviors Preferences

As pointed out in “Select a Scheme Instead of Setting an Active Target, Build Configuration, and
Executable” (page 30), 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; 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-19); and what unit tests to run.

Figure 3-19 Run diagnostic options

Customize the Build and Run Workflow with the Scheme Editor and Behaviors Preferences 39
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

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-20).

Figure 3-20 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 “A Snapshot Saves a Copy of the Current Version of Your Workspace” (page 87).)

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-21). Tab names are case sensitive in the Show Tab field
of Alerts preferences.

40 Customize the Build and Run Workflow with the Scheme Editor and Behaviors Preferences
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-21 Naming a tab

Check on the Progress of Xcode Tasks in the Activity Viewer

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-22). Click the number to open a pop-up window that shows the individual status of each
current task (Figure 3-23).

Figure 3-22 The activity viewer

Figure 3-23 The activity pop-up window

View Projects, Devices, and Documentation in the Organizer Window

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

Check on the Progress of Xcode Tasks in the Activity Viewer 41

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-24 The Organizer button

Browse and Bookmark Documents in the Documentation Organizer

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-25).

Figure 3-25 The documentation navigator

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-26).

42 View Projects, Devices, and Documentation in the Organizer Window

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Figure 3-26 The bookmarks navigator

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

Browse for Task-Based Help in the Documentation Organizer

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-25 (page 42)) or choose
Help > Xcode Help (Figure 3-27).

View Projects, Devices, and Documentation in the Organizer Window 43

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-27 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 “Control-Click for Contextual Help” (page 45) for details.

Work with Your Source Control Repositories in the Repositories

Organizer
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 “Use Repositories for Source Control” (page 88).

Organize Your Projects and Devices in the Projects and iOS Organizers
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.

44 View Projects, Devices, and Documentation in the Organizer Window

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Click the Projects button in the toolbar to display all your projects and their snapshots. See “A Snapshot Saves
a Copy of the Current Version of Your Workspace” (page 87) 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.

Control-Click for Contextual Help

In addition to being listed in the documentation browser in Xcode 4 (“Browse for Task-Based Help in the
Documentation Pane” (page 43)), 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-28). If there are more articles than can be listed
in the shortcut menu, then choose Show 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.

Control-Click for Contextual Help 45

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-28 Contextual help

Xcode 4 Saves Your 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 “A Snapshot Saves a Copy of the
Current Version of Your Workspace” (page 87)).

Split the Editor Area to Display Related Content

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.

46 Xcode 4 Saves Your Changes Automatically

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Assistant Finds Related Content for You

To enable Assistant, click the Assistant button in the workspace toolbar (Figure 3-29).

Figure 3-29 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-30. The choices offered
depend on the type of file being edited.

Figure 3-30 Setting the behavior for Assistant

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 (“Use the Manual Editor to Display Content of Your Choosing” (page 48)), 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
Interface Source Code” (page 63) for details.

Split the Editor Area to Display Related Content 47

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Use the Manual Editor to Display Content of Your Choosing

Choose Manual from the Assistant pop-up menu (Figure 3-30 (page 47)) 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-16 (page 37)). 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.

The Version Editor Compares 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 “Use the Version Editor to Compare Revisions
” (page 92) for more information.

Open a New Tab or a New Window to Display More Content

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.

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.

Select Keyboard Shortcuts For Opening Files in Assistant Editors,

Tabs, or New Windows

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.

48 Open a New Tab or a New Window to Display More Content

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

● 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-31 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.

● 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 (“The navigation chooser
dialog” (page ?)) 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.

Select Keyboard Shortcuts For Opening Files in Assistant Editors, Tabs, or New Windows 49
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-32 The navigation chooser dialog

The Utility Area Supplements the Information in the Editor

There are several types of information located in the utility area of the workspace window, including Quick
Help, the File inspector, Interface Builder inspectors, and libraries of file templates, code snippets, interface
builder objects, and media files.

To open the utility area, choose View > Utilities, or click the Utility button in the toolbar (Figure 3-33).

Figure 3-33 The Utility button

View Quick Help in the Utility Area

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-34).

50 The Utility Area Supplements the Information in the Editor

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Figure 3-34 The Quick Help window

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-35). Just click
any symbol while the Symbol inspector is open to see its Quick Help information.

Figure 3-35 The Symbol inspector

Quick Help is also available for user interface objects in Interface Builder (Figure 3-36) and for build settings
(Figure 3-37).

The Utility Area Supplements the Information in the Editor 51

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-36 Quick Help for Interface Builder objects

52 The Utility Area Supplements the Information in the Editor

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

Figure 3-37 Quick Help for build settings

Use Inspectors to View and Enter 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-38 shows a file inspector. For more information about Interface Builder, see “Designing User
Interfaces in Xcode 4” (page 57).

The Utility Area Supplements the Information in the Editor 53

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

Figure 3-38 A file inspector

Drag Files and Code from the Library into Your Project
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 11)). Each of the buttons at the top of this pane selects
a category of library objects, as follows:

● 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-39).

Figure 3-39 A file template information pop-up window

54 The Utility Area Supplements the Information in the Editor

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 3
Orientation to Xcode 4

● 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-40) and drag that into your file.

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-41).

Figure 3-40 Dragging a piece of a code snippet into your file

Figure 3-41 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 Figure 3-36 (page 52), for example, only the Interface Builder objects whose name or
description contains the word “window” are displayed.

The Utility Area Supplements the Information in the Editor 55

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 3
Orientation to Xcode 4

56 The Utility Area Supplements the Information in the Editor

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4

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.

Interface Builder Is Fully Integrated with Xcode 4

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 47)), 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

Interface Builder Is Fully Integrated with Xcode 4 57

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

Create a New Nib File with the File Menu or the Library

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.

New Classes are Created by Xcode, Not Interface Builder

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.

58 Create a New Nib File with the File Menu or the Library
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 4
Designing User Interfaces in Xcode 4

Add Source Files For A New Nib FIle, Then Add the Nib FIle
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

Next, add the nib file by selecting a User Interface template of type Window in the New File dialog (Figure
4-4).

New Classes are Created by Xcode, Not Interface Builder 59

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

Figure 4-4 Adding a new Window nib file

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).

60 New Classes are Created by Xcode, Not Interface Builder

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 4
Designing User Interfaces in Xcode 4

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 Between IB Objects and Source Code” (page 65).

To Add a Custom View, Start With the View’s Subclass, Then Add the
View To Your Nib
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” popup menu.

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.

New Classes are Created by Xcode, Not Interface Builder 61

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

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 61)).

Create Your Interface Controller in Xcode, Then Add a Controller

Object to the Nib File
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). (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 61)) to assign
the class of your controller to the object. Then use the Label field in that same inspector to change its display
name.

62 New Classes are Created by Xcode, Not Interface Builder

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

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
Between IB Objects and Source Code” (page 65).

Use Assistant to Work on Your Interface Source Code

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 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.

Use Assistant to Work on Your Interface Source Code 63

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

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 numerals 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.

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 Between IB Objects and Source Code” (page 65).

64 Use Assistant to Work on Your Interface Source Code

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

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.

Make Connections Directly Between IB Objects and 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.

Make Connections Directly Between IB Objects and Source Code 65

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

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

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.

66 Make Connections Directly Between IB Objects and Source Code

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

Figure 4-11 Inserting an action or outlet statement in your header file

Figure 4-12 Connection insertion dialog

Control-click the Canvas to Get Online Help

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).

Control-click the Canvas to Get Online Help 67

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

Figure 4-13 Help articles in Interface Builder

The Document Window Is Replaced by a Dock or List

The dock on the left side of the Interface Builder pane (see Figure 4-9 (page 65)) 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
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.

68 The Document Window Is Replaced by a Dock or List

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

Figure 4-14 Outline view for placeholders and objects in Interface Builder

See the User Guide and Xcode Quick Start Guide for More

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 Between IB Objects and Source Code” (page
65)), 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.

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.

See the User Guide and Xcode Quick Start Guide for More 69
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 4
Designing User Interfaces in Xcode 4

70 See the User Guide and Xcode Quick Start Guide for More
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5

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 in the Scheme Editor

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-8 (page 31)) 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.

Select a Debugger in the Scheme Editor 71

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

Use Static Analysis to Find Potential Problems Before Building

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

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, “Use the Issue Navigator or Issues Pop-up Menu to Locate Build Errors”), or cycle through the issues
by clicking the arrows that bracket the issues button.

72 Use Static Analysis to Find Potential Problems Before Building

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

Use the Issue Navigator or Issues Pop-up Menu to 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 Instead of Setting an Active Target,
Build Configuration, and Executable” (page 30). See “Customize Executables in the Scheme Editor” (page
32) 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
( ). 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.

Use the Issue Navigator or Issues Pop-up Menu to Locate Build Errors 73
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

Figure 5-4 The issues pop-up menu

Use the Log Navigator to 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.

Click the list icon ( ) at the end of a build command line to see the full build command and results (Figure
5-6).

74 Use the Log Navigator to View Build Results

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

Figure 5-6 The build log with a verbose build command

Use the Source Editor and Breakpoint Navigator to 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 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.

Use the Source Editor and Breakpoint Navigator to Manage Breakpoints 75

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

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 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

76 Use the Source Editor and Breakpoint Navigator to Manage Breakpoints

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

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.

Use the Debug Navigator to Examine Threads and Stacks

When you pause execution of your code (see “Control Program Execution in the Debugger Area and Source
Editor” (page 78)) 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.

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

Use the Debug Navigator to Examine Threads and Stacks 77

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

Control Program Execution in the Debug Area and Source Editor

When you execute a program from Xcode 4, the debug bar appears at the bottom of the editor pane (see
Figure 5-9 (page 77)). 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

● 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.

78 Control Program Execution in the Debug Area and Source Editor

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 5
Debugging and Analyzing Your Code

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.

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.

Control Program Execution in the Debug Area and Source Editor 79

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 5
Debugging and Analyzing Your Code

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). To see the values of variables, click the variable name in the editor (Figure
5-13 (page 80)). Hover over and click variable components to open the disclosure triangles to see the fields
of structures.

Figure 5-12 Activating the continue-to-here command

Figure 5-13 Reading the value of a variable in the source editor

80 Control Program Execution in the Debug Area and Source Editor

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 6

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.

Replace Text Using the Search Navigator

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 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

Replace Text Using the Search Navigator 81

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 6
Replacing Text and Refactoring

Figure 6-2 Find/Replace results

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 “A Snapshot Saves a
Copy of the Current Version of Your Workspace” (page 87)). 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).

82 Replace Text Using the Search Navigator

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 6
Replacing Text and Refactoring

Preview Changes Before Replacing Text

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 82)). The preview dialog is shown in
Figure 6-4.

Figure 6-4 Replacement preview

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 to Make It Easier to Maintain

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.

Preview Changes Before Replacing Text 83

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 6
Replacing Text and Refactoring

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.

● 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.

84 Refactor Your Code to Make It Easier to Maintain

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 6
Replacing Text and Refactoring

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.

Refactor Your Code to Make It Easier to Maintain 85

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 6
Replacing Text and Refactoring

86 Refactor Your Code to Make It Easier to Maintain

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 7

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.

A Snapshot Saves a Copy of the Current Version 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
(Figure 7-1). To restore from a snapshot, select that snapshot and click the Restore Snapshot button at the
bottom of the window.

A Snapshot Saves a Copy of the Current Version of Your Workspace 87

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 7
Repositories, Snapshots, and Archives

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.

Source Control Repositories Help You 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.

88 Source Control Repositories Help You Keep Track of Changes and Coordinate Work Groups
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 7
Repositories, Snapshots, and Archives

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

R Replaced in the repository

– The contents of the folder have mixed status; display the contents to see individual status

Source Control Repositories Help You Keep Track of Changes and Coordinate Work Groups 89
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 7
Repositories, Snapshots, and Archives

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.

Set Up Git Version Control When You Create a New Project

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 91)).

90 Source Control Repositories Help You Keep Track of Changes and Coordinate Work Groups
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 7
Repositories, Snapshots, and Archives

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 confirmation”). 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 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

The Merge Facility Helps You 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 92)), 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

Source Control Repositories Help You Keep Track of Changes and Coordinate Work Groups 91
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 7
Repositories, Snapshots, and Archives

or conflict between the files, an arrow in the center points to the file taking precedence. For example, if the
file on the 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.

Use the Version Editor to 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-7 (page 93)).

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.

92 Use the Version Editor to Compare Revisions

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 7
Repositories, Snapshots, and Archives

Figure 7-7 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.

The Timeline Provides a Convenient Way to Select Revisions to

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

Use the Version Editor to Compare Revisions 93

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 7
Repositories, Snapshots, and Archives

Figure 7-8 Using the Version editor timeline

Use Blame Mode to 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.

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-9 shows Blame mode in use.

94 Use the Version Editor to Compare Revisions

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
CHAPTER 7
Repositories, Snapshots, and Archives

Figure 7-9 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.

Log Mode Lists All Revisions Chronologically

To review all revisions to a file listed in chronological order, use Log mode (Figure 7-10). 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-10 Version editor Log mode

Use the Version Editor to Compare Revisions 95

2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 CHAPTER 7
Repositories, Snapshots, and Archives

Use Archives to Distribute Your Program or Submit an Application

to the App Store

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 (“Select a Scheme Instead of Setting an Active
Target, Build Configuration, and Executable” (page 30)) and saves the archive in the location specified in the
Locations pane of Xcode preferences.

To see the archives for your project, open the Archives Organizer window (Figure 7-9). 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-11 Archives organizer

96 Use Archives to Distribute Your Program or Submit an Application to the App Store
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
REVISION HISTORY

Document Revision History

This table describes the changes to Xcode 4 Transition Guide.

Date Notes

2011-02-08 New document that explains how to get started using Xcode 4 if you're already
familiar with Xcode 3.

97
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.
 REVISION HISTORY
Document Revision History

98
2011-02-08 | © 2011 Apple Inc. All Rights Reserved.