Xcode 4 Transition Guide: Tools & Languages: Ides

Xcode 4 Transition Guide
Tools & Languages: IDEs
2011-07-07
Apple Inc. 2011 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. The Apple logo is a trademark of Apple Inc. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Cocoa, Finder, Instruments, iPhone, iTunes, Leopard, Mac, Mac OS, Objective-C, Safari, Sand, Snow Leopard, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. iPad is a trademark of Apple Inc. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make
any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.
Contents
Introduction
About the Transition to Xcode 4 11

At a Glance 11 Use Xcode 4 for Development on Recent OS Versions 12 Open Your Project in Xcode 4 12 Get Oriented to Xcodes Organization and Features 12 Learn How to Use Xcode 4 to Design a User Interface 12 Debug and Refine Your Code In Xcode 4 12 Back Up Your Code and Use 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 See Your Groups and Files 15 Replace Your Interface Builder Plug-ins 17 Keep Your Xcode 3 Preferences 18 Check Out a Working Copy 18 Modernize Your Project 20 Work with Multiple Related Projects 21
Chapter 2
Creating a New Xcode 4 Project 25

Create a Standalone Project 25 Create a New Workspace 25
Chapter 3
Orientation to Xcode 4 27
Much of Your Projects Content Is in New Locations 27 Set Build Settings for Each Target 27 Set Basic Build Settings 28 Set Up a Sandbox for Each Target 29 Select Any File to Open an Editor 31 Write and Edit Source Code 31 Speed Up Typing with Code Completion 31 Have Fix-it Flag Errors as You Type 33 Open a File in the Assistant Editor Pane 34 View Files in Hexadecimal Format 34 View Preprocessor or Assembly Output 34 View Key Names or Raw Keys 34 Select a Scheme 34 Specify Which Targets are Built 35
3
2011-07-07 | 2011 Apple Inc. All Rights Reserved.
CONTENTS
Customize Executables 36 Rename or Reorganize Your Schemes 37 Search Your Workspace 37 Browse to Project Symbols 38 Filter to FInd Related Content 41 View Details 42 Customize the Build and Run Workflow 43 Check on the Progress of Xcode Tasks 45 View Projects, Devices, and Documentation 46 Browse and Bookmark Documents 46 Browse for Task-Based Help 47 Work with Source Control Repositories 48 Organize Projects and Devices 48 Archive Your Product for Distribution 49 FInd Answers with Contextual Help 49 Save Changes Automatically 50 Split the Editor Area 50 Find Related Content 50 Use Assistant with Interface Builder 51 Display Content of Your Choosing 51 Compare Two Versions of Your File 51 Open a New Tab or a New Window 52 Open Files with Keyboard Shortcuts 52 Open the Utility Area 53 View Quick Help 54 View and Edit File and Interface Builder Data 56 Drag Files and Code from the Library 57 Close a Project or a Workspace 59 Chapter 4
Designing User Interfaces in Xcode 4 61

Design Your UI in Xcode 61 Create a New Nib File 62 Create New UI Classes in Xcode 62 Add Source Files First 63 Add a Custom View 65 Create an Interface Controller 66 Use Assistant to Work on Your UI Code 67 Make Connections Directly with Source Code 69 Get Online Help in IB 71 Find UI Objects in the Dock 72 Get More Information on IB 73
Chapter 5
Debugging and Analyzing Your Code 75

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

FInd and Replace Text 85 Preview Changes 87 Refactor Your Code 87
Chapter 7
Repositories, Snapshots, and Archives 91

Take a Snapshot of Your Workspace 91 Keep Track of Changes and Coordinate Work Groups 92 Set Up Git Version Control 94 Commit Files to Add Them to a Repository 95 Reconcile Different Branches 95 Save Internal Project Files in Repositories 96 Compare Revisions 97 Select Revisions to Compare 98 Review Individual Changes 99 List All Revisions Chronologically 100 Distribute Your Program or Submit an Application 101
Document Revision History 103
5
CONTENTS
6
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 Figure 1-2 Figure 1-3 Figure 1-4 Figure 1-5 A newly opened Xcode 4 window with an Xcode 3 project 16 The project contents in the Xcode 4 project navigator 16 IB plug-in upgrade dialog 18 Modernization in the issue navigator 21 Updates dialog 21
Chapter 3
Orientation to Xcode 4 27
Figure 3-1 Figure 3-2 Figure 3-3 Figure 3-4 Figure 3-5 Figure 3-6 Figure 3-7 Figure 3-8 Figure 3-9 Figure 3-10 Figure 3-11 Figure 3-12 Figure 3-13 Figure 3-14 Figure 3-15 Figure 3-16 Figure 3-17 Figure 3-18 Figure 3-19 Figure 3-20 Figure 3-21 Figure 3-22 Figure 3-23 Figure 3-24 Figure 3-25 Figure 3-26 Figure 3-27 Figure 3-28 Target information in the project editor 27 Build settings 28 The Mac OS X summary pane 29 Mac OS X entitlements editor 30 Entitlements property list 31 Code completion 32 Quick help for code completion 32 Code completion underlining 33 Fix-it in action 33 The Scheme pop-up menu 35 The scheme editor Build pane 36 Customizing an executable environment for a product 37 The find navigator 38 The Find Options dialog 38 The symbol navigator 39 The symbol navigator, filtered 40 A symbol displayed in the source editor 40 Using the jump bar to find a symbol 41 The related-items pop-up menu 41 The project navigator filtered to show only .m files 42 Run diagnostic options 43 Behaviors preferences 44 Naming a tab 44 The activity viewer 45 The activity pop-up window 45 The Organizer button 46 The documentation navigator 46 The bookmarks navigator 47
7
FIGURES
Figure 3-29 Figure 3-30 Figure 3-31 Figure 3-32 Figure 3-33 Figure 3-34 Figure 3-35 Figure 3-36 Figure 3-37 Figure 3-38 Figure 3-39 Figure 3-40 Figure 3-41 Figure 3-42 Figure 3-43 Chapter 4
Finding Xcode 4 help articles 48 Contextual help 49 The Assistant button 50 Setting the behavior for Assistant 51 The Single Assistant navigation chooser dialog 52 The navigation chooser dialog 53 The Utility button 54 The Quick Help window 54 The Symbol inspector 55 Quick Help for Interface Builder objects 55 Quick Help for build settings 56 A file inspector 57 A file template information pop-up window 57 Dragging a piece of a code snippet into your file 58 A user-customized code snippet 58
Designing User Interfaces in Xcode 4 61

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

Figure 5-1 Figure 5-2 Figure 5-3 Figure 5-4 Figure 5-5 Figure 5-6 Figure 5-7 Figure 5-8 Figure 5-9 Figure 5-10 Selecting a debugger in the scheme editor 75 Static analysis results 76 The issue navigator 77 The issues pop-up menu 78 The build log 78 The build log with a verbose build command 79 Setting breakpoint options 80 Scopes of breakpoints in the breakpoint navigator 81 The debug navigator stopped at a breakpoint 82 The debug area 83
8
FIGURES
Figure 5-11 Figure 5-12 Figure 5-13 Chapter 6
Navigating through threads and stacks in the debug bar 84 Activating the continue-to-here command 84 Reading the value of a variable in the source editor 84
Replacing Text and Refactoring 85

Figure 6-1 Figure 6-2 Figure 6-3 Figure 6-4 Figure 6-5 Find/Replace pop-up menu 85 Find/Replace results 86 Activity viewer during a Find operation 86 Replacement preview 87 Refactor preview dialog 88
Chapter 7
Repositories, Snapshots, and Archives 91

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

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

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

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

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

Xcode 4 provides a consistent interface for debugging regardless of which supported debugger you use.
12
At a Glance
INTRODUCTION
Relevant Chapters: Orientation to Xcode 4 (page 27), Debugging and Analyzing Your Code (page 75), Replacing Text and Refactoring (page 85).
Back Up Your Code and Use Source Control

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

When youre 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 91).
At a Glance
13
INTRODUCTION
14
At a Glance
CHAPTER 1
Using an Existing Xcode 3 Project
If youve been working in Xcode 3 and have one or more Xcode 3 projects that youd like to use in Xcode 4, this chapter tells you what you need to know to get started. After youve opened your projects, go to Orientation to Xcode 4 (page 27) to learn more about using Xcode 4.
Open Your Xcode 3 Project in Xcode 4

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

Before going any further, you need to get oriented to the Xcode 4 workspace window. Figure 1-1 shows the Xcode 4 window newly opened with an Xcode 3 project.
Open Your Xcode 3 Project in Xcode 4

15
CHAPTER 1
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
See Your Groups and Files

CHAPTER 1
What you see in this list is probably less surprising than what you dont see. Missing from the Xcode 4 project navigator are these groups:

Targets Executables Find Results Project Symbols Bookmarks SCM (source control repositories) Smart groups
Youll 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 27).
Replace Your Interface Builder Plug-ins

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

17
CHAPTER 1
Figure 1-3
IB plug-in upgrade dialog
Keep Your Xcode 3 Preferences

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

If your Xcode project is in a Git or Subversion repository, you can check out your project from the repository and open it in Xcode. Use the following procedure to connect to a repository: 1. In the Welcome to Xcode window you see on startup (or when you choose Window > Welcome to Xcode), click Connect to a repository. Alternately, in the Repositories pane of the Organizer window (referred to hereafter as the repositories organizer), click the plus sign (+) at the bottom of the navigator pane and choose Checkout or Clone Repository.
18
Keep Your Xcode 3 Preferences

CHAPTER 1
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).
Check Out a Working Copy

19
CHAPTER 1
4. 5. 6.
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). 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). For Git, youre 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 91) for more information about source control in Xcode 4.
Modernize Your Project

When you open a project, Xcode 4 evaluates it to see whether there are any settings that should be updated. This feature provides an easy way to make sure that your projects conform to the latest SDKs and best practices. Open the issue navigator (Figure 1-4) to see whether anything in your project needs to be updated. You can also select the project in the project navigator and choose Editor > Check for Outdated Settings, or choose the project from the the drop-down issues menu at the right end of the jump bar.
20
Modernize Your Project

CHAPTER 1
Figure 1-4
Modernization in the issue navigator
If the issue navigator lists modernization issues, click the issue to see a dialog that explains the updates that should be made (Figure 1-5). Deselect any checkboxes for settings you dont want to change, then click Perform Changes to update the project to optimize it for Xcode 4. Figure 1-5 Updates dialog
After you have clicked Perform Changes, whether you choose to make all the changes or not, Xcode does not show the warning again. To rerun the check, select your project in the project navigator and choose Check for Outdated Settings from the Editor menu.
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. For example:
One project can use the products of another project while building.

21
CHAPTER 1
If one project depends on the products of another in the same workspace, Xcode can detect this and automatically build the projects in the correct sequence. Because all the files in one project are visible to all the other projects in the workspace, you dont 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 (see Select a Scheme (page 34)). 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. 2. 3. If Xcode 4 is not open, start it. You can ignore or cancel the startup screen. Choose File > New > New Workspace and name the new workspace. 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.
22

CHAPTER 1
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 youve 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 dont want one project to use the product or files in another project thats in the same workspace, you need to adjust your build settings accordingly. See Set Build Settings for Each Target (page 27) for help in finding and understanding the build settings interface in Xcode 4. Before you build, be sure youve created the scheme or schemes you need. See Select a Scheme (page 34) and Customize Executables (page 36).

23
CHAPTER 1
24

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 (page 25).
Create a Standalone Project

If you decide that you dont 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 decide you want to work with two or more related projects, create an Xcode workspace. To do so, use the following procedure: 1. 2. When Xcode 4 opens, ignore the startup screen and choose File > New > New Workspace. 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. 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.
3.
Create a Standalone Project

25
CHAPTER 2
Creating a New Xcode 4 Project
26
Create a New Workspace

CHAPTER 3
Orientation to Xcode 4
Once youve 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 75). 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 61).
Much of Your Projects Content Is in New Locations

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

Click the project in the project navigator. The project editor appears to the right of the project navigator, displaying project and target information. Figure 3-1 shows some of the target information in the project editor. Figure 3-1 Target information in the project editor

27
CHAPTER 3
Click the various buttons and icons in the project editor to see the information thats 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, its shown in boldface.
Set Basic Build Settings

Most developers never need to change the default of the vast majority of the build settings. However, there are a few basic settings that you must check, and possibly edit, for each target. These settings are gathered into one pane in the Project editorlabeled the Summary paneand 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.
28

CHAPTER 3
Figure 3-3
The Mac OS X summary pane
Each setting in the Summary pane is also found in one of the other panes. When you edit a setting, Xcode updates the other pane automatically.
Set Up a Sandbox for Each Target

An application sandbox enforces restrictions, known as entitlements, on how an application can interact with the rest of the system. A sandboxed application is harder to compromise and therefore enhances security for users. For example, if your application has no need to have access to the network, you can specify that the applications sandbox should prohibit network access. Then, if a hostile hacker manages to take over control of your application on a users computer, the hacker wont be able to use the application to send email or connect to the internet. In Xcode 4.1 and later, the project editor provides a UI for setting up entitlements for Mac OS X applications. You can set entitlements for each target in the project editor (Figure 3-4). There is also a default code-signing entitlements file available in the file templates in the utilities pane.

29
CHAPTER 3
Note: Although the Mac OS X sandboxing UI is available in Xcode on v10.6 Snow Leopard, only Mac OS X v10.7 Lion and later versions of the operating system enforce the entitlements. Figure 3-4 Mac OS X entitlements editor
When you enable application sandboxing, you can select an entitlements file if you already have one. If you do not, Xcode creates one with the name of your project and the extension entitlements. You can view and edit this file with the property list editor in Xcode (Figure 3-5).
30

CHAPTER 3
Figure 3-5
Entitlements property list
Select Any File to Open an Editor

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

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

The user interface for code completion is similar to that in Xcode 3, but there are some important differences. One of the first changes that youll notice is that you always get both an inline suggestion for completing the symbol name plus a list of possibilities (Figure 3-6). Click an item in the suggestion list or use the up and down arrows to select one. As you do so, the inline suggestion changes as well. Furthermore, as you can see in the figure, if you open the Quick Help inspector, you can read documentation about each selection. You can disable automatic code completion in the Text Editing pane of Xcode preferences, but you can always invoke code completion by pressing Control-Spacebar.

31
CHAPTER 3
Figure 3-6
Code completion
A Quick Help pop-up dialog is also available from code completion, even when the Quick Help inspector is not open. Hold the pointer over the code completion option youre interested in until a question mark icon appears. Click the question mark or press Command-Shift-Control-Question Mark to open Quick Help. As before, press the Tab key to accept the prefix or Return to accept the entire suggestion. Click the Done button in the Quick Help pop-up dialog to cancel the operation. Figure 3-7 Quick help for code completion
If all of the possible completions have a common prefix (NSString in Figure 3-6), the prefix is indicated with a dotted underline. Press the Tab key to accept only the prefix. Press Return to accept the entire autocompletion suggestion. If there is no common prefix, code completion shows the dotted underline up to the next uppercase letter in the symbol (Figure 3-6). Again, press Tab to accept only the subword, or press Return to accept the entire suggestion.
32

CHAPTER 3
Figure 3-8
Code completion underlining
Press ControlSpace bar to toggle the completion suggestion on or off. That is, if the inline suggestion and list are being displayed, pressing ControlSpace 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 ControlSpace bar to get completion suggestions. Note that in Xcode 4, pressing the Esc (Escape) key cancels the operation and pressing the Delete key always deletes the preceding character.
Have Fix-it Flag Errors as You Type

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

33
CHAPTER 3
Open a File in the Assistant Editor Pane

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

You can view and edit many types of files in hexadecimal format, including some (such as graphics files) that you cant 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 Preprocessor or Assembly Output

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

For known property list types, the Key column in the property list editor shows a descriptive name of the key instead of the keys literal text. Choose Editor > Show Raw Keys & Values to display the literal text instead. You can also see the raw key value in Quick Help in the Quick Help.
Select a Scheme
In Xcode 3 you have to set an active target, a build configuration, and an executable as separate items. The problem with this approach is that targets, configurations, and executables are intimately linked. At its simplest, for example, a target contains one product, which is executed without any special options or environmental settings. However, sometimes the product requires values for input parameters or other customization before it can be executed. In Xcode 4, you select a scheme, which specifies which targets to
34

CHAPTER 3
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
You can set each action to do either a debug or release build. When you open an existing Xcode project (or create a new one), Xcode 4 automatically creates a scheme for you. To select a scheme, you use the Scheme pop-up menu in the upper-left corner of the Xcode window (Figure 3-10). To create a new scheme, choose New Scheme from that menu. To edit existing schemes, choose the scheme you want to edit and then choose Edit Active Scheme from that menu. To change the list of schemes, where theyre stored, and whether theyre shared, choose Manage Schemes. Figure 3-10 The Scheme pop-up menu
You can have as many schemes as you want, but only one can be active at a time.
Specify Which Targets are Built

By default, Xcode creates one scheme per target in your project or workspace. For each target, you use the build pane of the scheme editor (Figure 3-11) to specify which targets are built for each type of action. You can add as many targets from your project or workspace to a single scheme as you wish. The figure shows four targets: the SurfWriter application, a custom framework needed to build the application, an Automator plug-in to be provided with the application, and a command-line tool that can be used with the application. In the 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.

35
CHAPTER 3
Figure 3-11
The scheme editor Build pane
Customize Executables
To customize the environment in which a product is launched in Xcode 3, you click the executable in the Groups & Files list and then open the Info window. In Xcode 4, choose Edit Active Scheme from the Scheme pop-up and choose the product you want to run (Figure 3-12). Note that you can choose to display the running product at a higher UI resolution to simulate running at a different display resolution.
36

CHAPTER 3
Figure 3-12
Customizing an executable environment for a product
Rename or Reorganize Your Schemes

Choose Product > Manage Schemes or choose Manage Schemes from the Scheme pop-up menu (Figure 3-10 (page 35)) 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.
Search Your Workspace

Rather than a Find group and batch find panel, Xcode 4 has a find navigator. Click the magnifying glass icon in the navigation pane, type a term in the search field, and press Return to search through the entire project or all the projects in the Xcode workspace (workspaces are discussed in Work with Multiple Related Projects (page 21)). The results are displayed in the find navigator (Figure 3-13). Just as in Xcode 3, click a find result to see the instance of the term in the source editor.

37
CHAPTER 3
Figure 3-13
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-14). Figure 3-14 The Find Options dialog
Browse to Project Symbols

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

CHAPTER 3
Figure 3-15
The symbol navigator
Use the search field and scope buttons at the bottom of the navigator to specify exactly what is listed. The scope buttons are blue when toggled on and black when off. Use the buttons in any combination:
hides symbols other than classes and their members, including protocols, functions, structs, enums, unions, types, and globals hides symbols defined only in external frameworks, displaying only symbols defined in the project or workspace, hides member symbols defined within the classes such as methods, properties, and variables
When you select the Flat button at the top of the symbol navigator, the navigator displays all classes arranged alphabetically. When you select the Hierarchical button, the navigator displays the class hierarchy. Use the search field at the bottom of the symbol navigator to filter the results. For example, in Figure 3-16, only those symbols that include the string KTg are displayed. This filter is not case sensitive.

39
CHAPTER 3
Figure 3-16
The symbol navigator, filtered
Click a symbol to see it displayed in the source editor (Figure 3-17). Option-click the file in the symbol navigator to open Assistant and display the file in the assistant editor pane (see Split the Editor Area (page 50)). Figure 3-17 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-18). Hold down the Option key when selecting a file in the jump bar to display the file in the assistant editor pane (see Split the Editor Area (page 50)).
40

CHAPTER 3
Figure 3-18
Using the jump bar to find a symbol
The jump bar also has back and forward buttons for moving through previously viewed files, and a pop-up menu ( ) that displays a variety of useful information about related items, as you can see in Figure 3-19. The related-items pop-up menu
Figure 3-19
Filter to FInd Related Content

Rather than providing smart groups to gather together related information, Xcode 4 provides a variety of navigators and filters. The project navigator (Figure 1-2 (page 16)), for example, has filters for recently edited files, files with source control status, unsaved files, and filename strings. Figure 3-20, for example, shows a project filtered to show only implementation (*.m) files. The filter field and buttons are at the bottom of the navigator area.

41
CHAPTER 3
Figure 3-20
The project navigator filtered to show only .m files
In addition to the structure, symbol, and find navigators already discussed, there are navigators that display:

Warnings, errors, and other issues found when analyzing or building your project Threads and stacks in a debugging session Breakpoints Build logs
For more information on using these navigators to analyze and debug your code, see Debugging and Analyzing Your Code (page 75). Note: Although Xcode 4 does not allow you to create smart groups and does not display any smart groups that you created for your project in Xcode 3, it does preserve your Xcode 3 smart groups. If you open your project in Xcode 4 and work with your code, then later reopen your project in Xcode 3, the smart groups you created earlier are still there.
View Details
All of the information in the detail view has been replaced in Xcode 4 with navigators or editors. Here are some of the main equivalents:

Files in your project: use the project navigator (Open Your Xcode 3 Project in Xcode 4 (page 15)) Find results: use the find navigator (Search Your Workspace (page 37)) Executables: use the scheme editor (Customize Executables (page 36))
42

CHAPTER 3
Targets: use the project editor (Set Build Settings for Each Target (page 27)) Bookmarks: use the bookmarks navigator in the Organizer window for documentation bookmarks (Browse and Bookmark Documents (page 46)) Source control: use the source control editor in the Organizer window to work with repositories and the version editor and project navigator to view source control status of files and to commit or update files (Work with Source Control Repositories (page 48)) Project symbols: use the symbol navigator and the jump bar (Browse to Project Symbols (page 38))
Customize the Build and Run Workflow

As pointed out in Select a Scheme (page 34), 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-21); and what unit tests to run. Figure 3-21 Run diagnostic options
Once youve got one or more schemes set up exactly as you want them, the next thing you may do when setting up your build and run workflow is to open Xcode preferences and click Behaviors. This preferences pane lets you specify what should happen when a variety of events occur (Figure 3-22).

43
CHAPTER 3
Figure 3-22
Behaviors preferences
For example, you can have Xcode display the debug area when your code pauses at a breakpoint, or it can display the issues navigator when a build fails. Note that, in addition to the Behaviors preferences setting to create a snapshot, you can specify that Xcode create a snapshot before a mass-editing operation such as a refactoring transformation. To do so, select the Snapshots pane in the File > Project Settings dialog. (Snapshots are discussed in Take a Snapshot of Your Workspace (page 91).) You can name a tab and specify that tab as the display to use when an event occurs. Then you can set up the display in that tab exactly as you want it; for instance, with a specific source-code file open in the editor, the debug area open, the Utility area closed, and the issues navigator open. To name a tab, double-click the title of the tab and type in the new name (Figure 3-23). Tab names are case sensitive in the Show Tab field of Alerts preferences. Figure 3-23 Naming a tab
44

CHAPTER 3
Xcode remembers the state of the named tabincluding which window it was inwhen it reopens the tab. By naming a tab in a separate window, you can use the Show tab option in Behaviors preferences to automatically open a new window. To do so, create a named tab, set it up exactly as you want it, and drag the tab out of the window to create a new window. Now, each time Xcode recreates the tab, it will open a new window to hold the tab. You can also can design custom behaviors that are triggered by menu items or their key equivalents. This feature allows you to create behaviors that you can invoke at any time. For example, you can create a "Unit Testing" behavior that creates a snapshot and runs your unit tests (Figure 3-22 (page 44)). Once youve created a behavior, it appears in the Xcode > Behaviors menu. To assign key equivalents to custom behaviors, find the behavior in the Customized tab of the Key Bindings preferences pane.
Check on the Progress of Xcode Tasks

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

45
CHAPTER 3
View Projects, Devices, and Documentation

Xcode 4 has two main windows. Youve 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-26). Figure 3-26 The Organizer button
Browse and Bookmark Documents

To browse documentation, open the Organizer window, click the Documentation button in the toolbar, and click the Browse button in the jump bar (Figure 3-27). Figure 3-27 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-28).
46

CHAPTER 3
Figure 3-28
The bookmarks navigator
To select which documentation sets to download, use the Documentation pane in Xcode preferences.
Browse for Task-Based Help

New in Xcode 4, online help is available for the Xcode IDE. To browse the Xcode 4 online help, click the disclosure triangle next to Xcode Help in the documentation navigator (Figure 3-27 (page 46)) or choose Help > Xcode Help (Figure 3-29).

47
CHAPTER 3
Figure 3-29
Finding Xcode 4 help articles
Many of the articles in Xcode 4 help include a short video that illustrates the described procedure. Click the video thumbnail to play the video. To help you discover and understand the many user interface features of Xcode 4, many of the help articles are also available as contextual help. See FInd Answers with Contextual Help (page 49) for details.
Work with Source Control Repositories

Click the Repositories button in the Organizer window toolbar to work with your source control repositories. You can create local repositories, connect to and manage repositories on servers, and so forth. You can also perform many common SCM operations, such as submitting files, from the workspace window. To do so, select the file or files in the project navigator, Control-click, and choose Source Control from the menu. For more information on repositories, see Keep Track of Changes and Coordinate Work Groups (page 92).
Organize Projects and Devices

Whereas Xcode 4 allows you to have several workspace windows open simultaneously, there is only one Organizer window. The Organizer window displays information for all your workspaces, projects, repositories, devices, and documentation, regardless of how many projects you have and how many are open. Click the Projects button in the toolbar to display all your projects and their snapshots. See Take a Snapshot of Your Workspace (page 91) for more information on snapshots.
48

CHAPTER 3
If youre 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. Its often easier to use the command line than to create an installable application in Xcode. In Xcode 4, when youre ready to share your program with others, you choose Archive from the Product menu. In the Archives pane of the Organizer window, you can then share the application with others or submit to iTunes Connect.
FInd Answers with Contextual Help

In addition to being listed in the documentation browser in Xcode 4 (Browse for Task-Based Help (page 47)), many of the help articles are available from shortcut menus throughout the application. Control-click in any of the main user-interface areas in the workspace or Organizer window to see a list of help articles available for that area (Figure 3-30). If there are more articles than can be listed in the shortcut menu, then choose Show All Help Topics and the help opens in the Organizer window. You can use this facility to find information about a specific task that youre trying to accomplish, or just to learn what tasks can be performed using that area of Xcode 4. Figure 3-30 Contextual help
FInd Answers with Contextual Help

49
CHAPTER 3
Save Changes Automatically

When you edit a file in Xcode 4, the files icon is shaded in the project navigator to indicate that there are unsaved changes. By default, if you build the project or quit Xcode, Xcode 4 automatically saves all changed files for you. You can change this behavior in the General pane of Xcode preferences . To ensure you can return to a known state before you build your project or perform another operation that affects many files in your project and that might be difficult to undo, create a snapshot (see Take a Snapshot of Your Workspace (page 91)).
Split the Editor Area

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

To enable Assistant, click the Assistant button in the workspace toolbar (Figure 3-31). Figure 3-31 The Assistant button
Assistant opens a second pane in the editor area of the workspace window. For source files, the default behavior for Assistant is to display the counterpart of the file displayed in the standard editor pane. That is, if youve opened an implementation file, Assistant displays the corresponding header file, and vice versa. You can choose any of several other possible criteria to be used by Assistant using the Assistant pop-up menu. The Assistant pop-up menu is the first item in the path shown in the jump bar above the assistant editor. To do so, open the pop-up menu and choose an item, as shown in Figure 3-32. The choices offered depend on the type of file being edited.
50
Save Changes Automatically

CHAPTER 3
Figure 3-32
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 (Display Content of Your Choosing (page 51)), 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 youre using Interface Builder to design a user interface, you can use Assistant to automatically display the code file most relevant to the interface element youre working with. See Use Assistant to Work on Your UI Code (page 67) for details.
Display Content of Your Choosing

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

Use the version editor to compare different revisions from your source control repository. It can also show the difference between the saved file and what's in memory. In addition, the version editor lets you see source control logs and blame/annotation information. See Compare Revisions (page 97) for more information.
Split the Editor Area

51
CHAPTER 3
Open a New Tab or a New Window

For fast switches between different editors or files, you can add tabs to the Xcode 4 workspace window, or you can open additional windows. To activate tabs, choose View > Show Tab Bar, or add a new tab by choosing File > New > New Tab. Choose File > New > New Window to open a new workspace window. If you open the same file in two tabs or two windows, the changes you make in one tab or window are reflected in the other. Tabs can be reordered, closed independently, or dragged out of the tab bar to create a new window, just as they can in Safari. You can use items in the Window menu (or their keyboard equivalents) to move between tabs.
Open Files with Keyboard Shortcuts

Selecting a file in the project navigator or jump bar causes that file to open in the normal editor pane. If Assistant is set to tracking mode, it tracks the change. By default, if you hold down the Option key when selecting a file in the project navigator or jump bar, Xcode displays that file in the Assistant pane rather than the standard pane. Doing so switches Assistant to manual mode. You can customize the behavior of the single click, Option-click, Option-Shift-click, and double-click keyboard shortcuts in the General pane of Xcode preferences. Choose one of the following options from each keyboard-shortcut pop-up menu:

Primary editor: Opens the file in the primary editor pane in the window and tab already open. Focused editor: Opens the file in whichever editor pane currently has focus. Single assistant editor: When the navigation originates in a navigator pane or the primary editor (using the jump bar or the jump to definition command), if the assistant editor is not open or is not split, opens the file in the assistant editor. If the assistant editor is split, displays a navigation chooser dialog (The Single Assistant navigation chooser dialog) showing the current layout of editor panes in the window that has focus, with the option of selecting any open editor pane or adding a new one. Double-click your selected pane, or make your selection and press Return. Press Esc to cancel.
Figure 3-33
The Single Assistant navigation chooser dialog
52
Open a New Tab or a New Window

CHAPTER 3
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. Figure 3-34 The navigation chooser dialog
The Open Quickly command works in Xcode 4 much the same way that it worked in Xcode 3. In Xcode 4, however, you can open a file in the assistant editor by holding the Option key when you double-click or click Open. To open the file in a separate window, hold Option-Shift. To see the navigation chooser dialog, hold Option-Shift-Click. These behaviors follow the preferences you set for navigation in the General preferences pane.
Open the Utility Area

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.

53
CHAPTER 3
To open the utility area, choose View > Utilities, or click the Utility button in the toolbar (Figure 3-35). Figure 3-35 The Utility button
View Quick Help

In Xcode 3, you can open a Quick Help window with information about an API symbol by Optiondouble-clicking the symbol. In Xcode 4, you can use an Option-single-click to open Quick Help (Figure 3-36). Figure 3-36 The Quick Help window
Whereas in Xcode 3, you can make the Quick Help window permanent by moving it from its original location, in Xcode 4, Quick Help is always available in the Symbol inspector in the utility area (Figure 3-37). Just click any symbol while the Symbol inspector is open to see its Quick Help information.
54

CHAPTER 3
Figure 3-37
The Symbol inspector
Quick Help is also available for user interface objects in Interface Builder (Figure 3-38) and for build settings (Figure 3-39). Figure 3-38 Quick Help for Interface Builder objects

55
CHAPTER 3
Figure 3-39
Quick Help for build settings
View and Edit File and Interface Builder Data

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

CHAPTER 3
Figure 3-40
A file inspector
Drag Files and Code from the Library

Xcode provides libraries of file templates and code snippets that you can use in your program. It also has libraries of Interface Builder objects and media files that you can use in your nib files. The libraries pane is in the lower part of the utility area (see Figure I-1 (page 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-41).
Figure 3-41
A file template information pop-up window

57
CHAPTER 3
Code snippets are short pieces of source code that you can use in your software. To use one, you can drag it directly into your source code file. Alternatively, you can copy a portion of the code from the code information pop-up window (Figure 3-42) and drag that into your file. 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. Youll need to edit the snippet to give it a meaningful name and, optionally, a completion shortcut. You can use a completion shortcut to add a snippet when editing source code. Type the shortcut in your source code file and select the snippet from the code completion list to add the code to your file. Note that a new or edited code snippet is flagged with the word User (Figure 3-43).
Figure 3-42
Dragging a piece of a code snippet into your file
Figure 3-43
A user-customized code snippet
Interface Builder objects are used the same way as those in the Xcode 3 Interface Builder. In Xcode 4 they are organized with subcategories and provide information pop-up windows like those for the file templates and code snippets. Media files include a selection of graphics and icons that you can use in your program. All media files in your workspace or project are listed here.
At the bottom of the library pane is a search field that you can use to filter the library items displayed in the selected library. In Figure 3-38 (page 55), for example, only the Interface Builder objects whose name or description contains the word window are displayed.
58

CHAPTER 3
Close a Project or a Workspace

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

59
CHAPTER 3
60

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 differencesmost notably, the ability to make connections from Interface Builder objects directly into source code. This chapter describes the main differences between the two implementations of Interface Builder.
Design Your UI in Xcode

In Xcode 4, Interface Builder appears in the editor area of the workspace window when you select a nib file in the project navigator. (A nib file is a file created by Interface Builder containing the user interface design information that you enter. A nib file may have the file name extension nib or xib.) When you open a nib file, the Interface Builder inspectors appear in the utility area. You can also open an assistant editor (see Use Assistant with Interface Builder (page 51)), which shows a file or files associated with whatever object youve 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
Design Your UI in Xcode

61
CHAPTER 4
Create a New Nib File

When you create a new Cocoa application or iOS view-based project, Xcode includes a nib file for your main view and a view controller class. The view controller is represented in the nib file as the files 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 wont get the results you want if you accidentally drop the file inside another file. Figure 4-2 Dropping a nib file in the Resources group
Whether you choose New File or drag the nib file from the File Template library, be sure you select the appropriate file type for the correct platform. For example, there are two nib templates named Application: one for iPhone and iPad, and one for Cocoa.
Create New UI Classes in Xcode

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

CHAPTER 4
Add Source Files First

To add a new nib file to a project, first choose File > New > New File and add interface and implementation file templates for a controller class for the nib file. For example, if your new nib file is going to start with a Cocoa window, add a Cocoa Objective-C class thats 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).

63
CHAPTER 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 Files 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).
64

CHAPTER 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 files owner, click the Files Owner object in the dock and open the Connections inspector. To add new actions or outlets to the nib files controller, see Make Connections Directly with Source Code (page 69).
Add a Custom View

If you need to add a new custom view to your nib file, first create header and implementation files for the view by choosing File > New > New File and selecting the Objective-C class template. Be sure to choose the appropriate parent class in the Subclass of pop-up menu. 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.

65
CHAPTER 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 65)).
Create an Interface Controller

To create a new controller for a nib file, first use the New File dialog to create interface and implementation files for the new class. Use the Objective-C class template and make the templates a subclass of NSObject. If you want to make connections in Interface Builder to the outlets and actions of the controller, drag the Object object from the Object library in the Utilities pane into the dock of your Interface Builder nib file (Figure 4-7). (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 65)) to assign the class of your controller to the object. Then use the Label field in that same inspector to change its display name.
66

CHAPTER 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 with Source Code (page 69).
Use Assistant to Work on Your UI 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.

67
CHAPTER 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 with Source Code (page 69).
68

CHAPTER 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 with Source Code

In Xcode 3, when you want to create a new action or outlet connection, you have to make it between the Interface Builder Object and a placeholder object representing the controller or other source code file. After creating and saving the connection in Interface Builder, you then have to open the source code file in Xcode to add the corresponding IBAction or IBOutlet statement. In Xcode 4, on the other hand, you can make the connection directly from the Interface Builder object to the appropriate header file, and, if needed, Xcode inserts the statement directly into your header file.

69
CHAPTER 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.
70

CHAPTER 4
Figure 4-11
Inserting an action or outlet statement in your header file
Figure 4-12
Connection insertion dialog
Get Online Help in IB

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

71
CHAPTER 4
Figure 4-13
Help articles in Interface Builder
Find UI Objects in the Dock

The dock on the left side of the Interface Builder pane (see Figure 4-9 (page 69)) 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 viewFigure 4-14) showing all the objects nested in higher-level objectsfor convenience in selecting the object in which youre interestedclick 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.
72
Find UI Objects in the Dock

CHAPTER 4
Figure 4-14
Outline view for placeholders and objects in Interface Builder
Get More Information on IB

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. Its 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 youve created the class, you can connect to the code directly from Interface Builder (see Make Connections Directly with Source Code (page 69)), 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.

73
CHAPTER 4
74

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
Xcode 4 comes with GDB and LLDB debuggers. To select which one to use, choose Edit Active Scheme from the Scheme pop-up menu (Figure 3-10 (page 35)) 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
75
CHAPTER 5
Find Potential Problems with Static Analysis

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

CHAPTER 5
Locate Build Errors

To build and run the executable specified by the active scheme, click the Run button at the left end of the toolbar. Other options, such as running without building or building without running, are available in the Product menu. To open the scheme editor before building or running, hold down the Option key while opening the Product menu. Schemes are described in Select a Scheme (page 34). See Customize Executables (page 36) 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 issuesfor 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 theres 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.
Locate Build Errors

77
CHAPTER 5
Figure 5-4
The issues pop-up menu
As of Xcode 4.1, you can select what kind of content to view when debugging: source only (when available), disassembly only, or source and disassembly. The disassembly is the set of assembly-language instructions seen by the debugger while your program is running. Viewing the disassembly can give you more insight into what your code is doing when its stopped at a breakpoint. By viewing the disassembly and source code together, you can more easily relate the instruction being executed with the code you wrote. To view the disassembly while debugging, choose Product > Debug Workflow > Show Disassembly When Debugging, or open an assistant editor and choose Disassembly from the Assistant pop-up menu in the assistant editor jump bar.
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
78
View Build Results

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

When you pause execution of your code (see Control Program Execution (page 82)) 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.
Examine Threads and Stacks

81
CHAPTER 5
Figure 5-9
The debug navigator stopped at a breakpoint
Control Program Execution

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

CHAPTER 5
If you pause execution or a breakpoint is triggered, the debug area opens displaying the values of variables and registers, plus the debug console (Figure 5-10). You can use the buttons at the right end of the debug area toolbar to display both the variables and console panes or to hide either one. Figure 5-10 The debug area
The variables pane displays variables and registers. You specify which items to display using the pop-up menu in the top-left corner of the variables pane:

Auto displays only the variables youre 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.

83
CHAPTER 5
You can use the navigation pop-up menus in the debug bar to navigate through the threads and stacks (Figure 5-11), or you can use the debug navigator for that purpose. Figure 5-11 Navigating through threads and stacks in the debug bar
While execution is stopped at a breakpoint, you can view variables and step through code in the source editor in much the same way as you can in Xcode 3. For example, to continue execution to a specific line of code, hold the pointer over the gutter next to the target code line until the continue-to-here icon appears, then click the icon (Figure 5-12). To see the values of variables, click the variable name in the editor (Figure 5-13 (page 84)). 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
84

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.
FInd and Replace Text

To replace text in your source files, choose Replace from the pop-up menu in the search navigator (Figure 6-1). Type the text you want to find in the top text field and press Return, then type the replacement text in the lower text field (Figure 6-2). Note that Xcode does not search for the text if you dont 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

85
CHAPTER 6
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 Take a Snapshot of Your Workspace (page 91)). 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).
86

CHAPTER 6
Preview Changes
To see what your changes will look like in your source code before deciding which occurrences to replace, click the Preview button below the Replace text box (Figure 6-2 (page 86)). 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

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 youve selected the text and the refactoring operation, Xcode presents a dialog to let you select options and specify symbol names where necessary.
Preview Changes
87
CHAPTER 6
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 youre 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.
88
Refactor Your Code

CHAPTER 6
Refactoring works only with C and Objective-C files. Before youve 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

89
CHAPTER 6
90
Refactor Your Code

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.
Take a Snapshot of Your Workspace

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

91
CHAPTER 7
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.
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.
92

CHAPTER 7
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 R Ignored Replaced in the repository The contents of the folder have mixed status; display the contents to see individual status

93
CHAPTER 7
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 youve 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

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

CHAPTER 7
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 controlyou must explicitly commit the file. To see which files have been modified locally but not committed, look for the M badge next to the file name in the Project navigator. (New files that have never been committed to source control have the A badge.) You can use the SCM status filter at the bottom of the Project navigator to display only files with SCM status. When you choose Commit, a confirmation dialog opens that you can use to make sure the changes you are committing are what you intended (Commit Files to Add Them to a Repository). You can compare your new version with any past version in the confirmation dialog. When you choose File > Source Control > Commit, the confirmation dialog shows all the files with pending changes. Uncheck the checkboxes next to any files that you do not wish to commit. When you choose Source Control > Commit Selected Files from the shortcut menu in the project navigator, only the files youve 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
Reconcile Different Branches

When youre 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 96)), the left pane shows what the merged file will look like. The right pane shows the file with which youre merging. For each difference

95
CHAPTER 7
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 youre 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 files 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.
Save Internal Project Files in Repositories

In Xcode 4.1 and later, you can use repositories to view internal project files (schemes, user interface settings, and so forth) when looking at SCM details in the SCM commit and update workflows. You can use this facility to save and keep track of versions of project files in the same way as you save and keep track of source files. A scheme in the commit dialog shows a commit dialog displaying two versions of a scheme.
96

CHAPTER 7
Figure 7-7
A scheme in the commit dialog
Compare Revisions
Select any file under source control and click the Version Editor button ( ) to display two versions of that file in a side-by-side view. Use the jump bar underneath either editor pane to select the version of the file to compare with the one in the other pane (Figure 7-8 (page 98)). 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.
Compare Revisions
97
CHAPTER 7
Figure 7-8
Comparing two revisions of a file with the version editor
You can edit the current working copy of the file in the version editor and you can copy code from an older version and paste it into the current version. In Xcode 4, the working copy of a file is on the left.
Select Revisions to Compare

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

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

To review all revisions to a file listed in chronological order, use Log mode (Figure 7-11). Each change is listed individually, and you can click the arrow next to the log entry to see the change displayed in Comparison mode. Figure 7-11 Version editor Log mode
100
Compare Revisions
CHAPTER 7
Distribute Your Program or Submit an Application

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 (page 34)) 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-10). To submit your application to the app store, you must have an iTunes Connect account. Click Submit to submit the application. Click Validate to run the same validation used by iTunes Connect to make sure your application is ready for submittal. To get a copy of your application that you can package for distribution or share with others, click Share. You can add a comment by clicking on the text field in the Comment column. Figure 7-12 Archives organizer

101
CHAPTER 7
102

REVISION HISTORY
Document Revision History
This table describes the changes to Xcode 4 Transition Guide. Date 2011-07-07 Notes Added information about features new in Xcode 4.1, including Interface Builder plug-ins and automatic project updates. New document that explains how to get started using Xcode 4 if you're already familiar with Xcode 3.
2011-02-08
103
REVISION HISTORY
Document Revision History
104

Xcode 4 Transition Guide: Tools & Languages: Ides

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Xcode 4 Transition Guide: Tools & Languages: Ides

Transféré par

Droits d'auteur :

Formats disponibles

Xcode 4 Transition Guide

Tools & Languages: IDEs

About the Transition to Xcode 4 11

Using an Existing Xcode 3 Project 15

Creating a New Xcode 4 Project 25

Designing User Interfaces in Xcode 4 61

Debugging and Analyzing Your Code 75

Replacing Text and Refactoring 85

Repositories, Snapshots, and Archives 91

Document Revision History 103

About the Transition to Xcode 4 11

Using an Existing Xcode 3 Project 15

Designing User Interfaces in Xcode 4 61

Debugging and Analyzing Your Code 75

Figure 5-11 Figure 5-12 Figure 5-13 Chapter 6

Replacing Text and Refactoring 85

Repositories, Snapshots, and Archives 91

About the Transition to Xcode 4

About the Transition to Xcode 4

Use Xcode 4 for Development on Recent OS Versions

Open Your Project in Xcode 4

Get Oriented to Xcodes Organization and Features

Learn How to Use Xcode 4 to Design a User Interface

Debug and Refine Your Code In Xcode 4

About the Transition to Xcode 4

Back Up Your Code and Use Source Control

Use Archives to Distribute Your Program

About the Transition to Xcode 4

Using an Existing Xcode 3 Project

Open Your Xcode 3 Project in Xcode 4

See Your Groups and Files

Open Your Xcode 3 Project in Xcode 4

Using an Existing Xcode 3 Project

A newly opened Xcode 4 window with an Xcode 3 project

See Your Groups and Files

Using an Existing Xcode 3 Project

Replace Your Interface Builder Plug-ins

Replace Your Interface Builder Plug-ins

Using an Existing Xcode 3 Project

IB plug-in upgrade dialog

Keep Your Xcode 3 Preferences

Check Out a Working Copy

Keep Your Xcode 3 Preferences

Using an Existing Xcode 3 Project

Check Out a Working Copy

Using an Existing Xcode 3 Project

Modernize Your Project

Modernize Your Project

Using an Existing Xcode 3 Project

Modernization in the issue navigator

Work with Multiple Related Projects

Work with Multiple Related Projects

Using an Existing Xcode 3 Project

Work with Multiple Related Projects

Using an Existing Xcode 3 Project

Work with Multiple Related Projects

Using an Existing Xcode 3 Project

Work with Multiple Related Projects

Creating a New Xcode 4 Project

Create a Standalone Project

Create a New Workspace

Create a Standalone Project