Xcode 4 Transition Guide by Leung Man Chan

Xcode 4 Transition Guide Tools & Languages: IDEs

2011-01-14

Apple Inc. © 2011 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. The Apple logo is a trademark of Apple Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. 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. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 App Store is a service mark of Apple Inc. Apple, the Apple logo, Cocoa, Finder, Instruments, iPhone, iTunes, Mac, Mac OS, Objective-C, Safari, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. iPad is a trademark of Apple Inc. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Simultaneously published in the United States and Canada. 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 Xcode 4 Provides Many Advantages 12 Use Xcode 4 for Development on Recent OS Versions 12 The Xcode 4 Transition Guide At a Glance 12 Open Your Project in Xcode 4 12 Get Oriented to Xcode’s Organization and Features 13 Learn How to Use Xcode 4 to Design a User Interface 13 Debug and Refine Your Code In Xcode 4 13 Back Up Your Code and Coordinate the Work of Multiple Programmers With Snapshots and Source Control 13 Use Archives to Distribute Your Program 14

Chapter 1

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

Chapter 2

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

Chapter 3

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

CONTENTS

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

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

Chapter 5

Debugging and Analyzing Your Code 71 Select a Debugger in the Scheme Editor 71 Use Static Analysis to Find Potential Problems Before Building 72 Use the Issue Navigator or Issues Pop-up Menu to Locate Build Errors 73 Use the Log Navigator to View Build Results 74 Use the Source Editor and Breakpoint Navigator to Manage Breakpoints 75

CONTENTS

Use the Debug Navigator to Examine Threads and Stacks 77 Control Program Execution in the Debugger Area and Source Editor 77 Chapter 6

Replacing Text and Refactoring 81 Replace Text Using the Search Navigator 81 Preview Changes Before Replacing Text 83 Refactor Your Code to Make It Easier to Maintain 83

Chapter 7

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

Document Revision History 99

CONTENTS

Figures Introduction

About the Transition to Xcode 4 11 Figure I-1

Chapter 1

Using an Existing Xcode 3 Project 15 Figure 1-1 Figure 1-2

Chapter 3

The Xcode 4 workspace window 11

A newly opened Xcode 4 window with an Xcode 3 project 16 The project contents in the Xcode 4 project navigator 16

Orientation to Xcode 4 25 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 Figure 3-29 Figure 3-30 Figure 3-31

Target information in the project editor 25 Build settings 26 Code completion 27 Quick help for code completion 28 Code completion underlining 28 Fix-it in action 29 The Scheme pop-up menu 30 The scheme editor Build pane 31 Customizing an executable environment for a product 32 The find navigator 33 The Find Options dialog 33 The symbol navigator 34 The symbol navigator, filtered 35 A symbol displayed in the source editor 36 Using the jump bar to find a symbol 36 The related-items pop-up menu 37 The project navigator filtered to show only .m files 37 Run diagnostic options 39 Alerts preferences 40 Naming a tab 40 The activity viewer 41 The activity pop-up window 41 The Organizer button 41 The documentation navigator 42 The bookmarks navigator 43 Finding Xcode 4 help articles 44 Contextual help 46 The Assistant button 47 Setting the behavior for Assistant 47 The Utility button 50 The Quick Help window 51

FIGURES

Figure 3-32 Figure 3-33 Figure 3-34 Figure 3-35 Figure 3-36 Figure 3-37 Figure 3-38 Chapter 4

Designing User Interfaces in Xcode 4 57 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

Chapter 5

Interface Builder in the workspace window 57 Dropping a nib file in the Resources group 58 Creating new class files 59 Adding a new Window nib file 60 Assigning a class to an Interface Builder object 61 Adding a custom view 62 Adding a controller object to a nib file 63 Selecting a counterpart to a nib file in assistant 64 Interface Builder with the Assistant editor open 65 Making a connection to source code from Interface Builder 66 Inserting an action or outlet statement in your header file 67 Connection insertion dialog 67 Help articles in Interface Builder 68 Outline view for placeholders and objects in Interface Builder 69

Debugging and Analyzing Your Code 71 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 Figure 5-11 Figure 5-12 Figure 5-13

Chapter 6

The Quick Help inspector 51 Quick Help for Interface Builder objects 52 Quick Help for build settings 53 A file inspector 54 A file template information pop-up window 54 Dragging a piece of a code snippet into your file 55 A user-customized code snippet 55

Selecting a debugger in the scheme editor 71 Static analysis results 72 The issue navigator 73 The issues pop-up menu 74 The build log 74 The build log with a verbose build command 75 Setting breakpoint options 76 Scopes of breakpoints in the breakpoint navigator 76 The debug navigator stopped at a breakpoint 77 The debugger area 78 Navigating through threads and stacks in the debugger 79 Activating the continue-to-here command 79 Reading the value of a variable in the source editor 80

Replacing Text and Refactoring 81 Figure 6-1 Figure 6-2

Find/Replace pop-up menu 81 Find/Replace results 82

FIGURES

Figure 6-3 Figure 6-4 Figure 6-5 Chapter 7

Activity viewer during a Find operation 82 Replacement preview 83 Refactor preview dialog 84

Repositories, Snapshots, and Archives 87 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

Snapshots listed in the Organizer window 88 Repositories Organizer 89 Source control badges in the project navigator 89 The Source Control submenu 90 Commit confirmation 91 The Merge dialog 92 Comparing two revisions of a file with the Version editor 93 Using the Version editor timeline 94 Version editor Blame mode 95 Version editor Log mode 96 Archives organizer 97

FIGURES

INTRODUCTION

About the Transition to Xcode 4

Important: This is a preliminary document for a technology in development. Although this document has been reviewed for technical accuracy, it is not final. Apple is supplying this information to help you plan for the adoption of the technologies described herein. This information is subject to change, and you should always use the latest version of the document available. To get the latest version of this document, open Xcode Preferences, select the Documentation pane, and choose the Xcode 4 Developer Tools Library item in the list. Then click Check and Install Now. Xcode 4 is the latest iteration of Appleâ&#x20AC;&#x2122;s integrated development environment (IDE). This document is intended for developers who are familiar with Xcode 3 and want to get started quickly using Xcode 4. If you want a short tutorial that introduces you to the major features of Xcode 4, see Xcode Quick Start Guide. If you want a more complete introduction to the features and workflows of Xcode 4, see Xcode 4 User Guide. Figure I-1 shows the main user interface elements described in this document. Figure I-1

The Xcode 4 workspace window

Toolbar Navigator selector bar

Inspector selector bar

Jump bars

Breakpoint gutter

Inspector pane

Focus ribbon Navigator area

Editor area

Utility area

Library selector bar Library pane

Debugger area Filter bar

Debugger bar

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.

INTRODUCTION

About the Transition to Xcode 4

Xcode 4 Provides Many Advantages There are many improvements and new features in Xcode 4. A very partial list includes: ●

Xcode 4 has a new, single-window interface for all major workflows (you can have multiple workspace windows and multiple tabs per window).

●

Interface Builder is fully integrated with the main Xcode application.

●

Assistant provides a second editor pane that complements the file you’re working on—for example, if you’re working on an implementation file, it can automatically find and open the corresponding header file.

●

Fix-it checks your symbol names and code syntax as you type, highlights any errors it detects, and in some cases can even fix them for you.

●

The Version editor works with Git or Subversion to show a file’s entire SCM history and compare any two versions of a file.

●

The LLVM 2.0 compiler includes full support for C, Objective-C, and C++.

●

The LLDB debugger is faster and uses less memory than the GDB debugging engine.

●

Xcode 4 lets you work on several interdependent projects in the same window, automatically determining dependencies so that it builds the projects in the right order.

Use Xcode 4 for Development on Recent OS Versions Xcode 4 runs on Mac OS X 10.6.6 and later. It does not install or run on earlier versions of Mac OS X. Xcode 4 supports universal development for iOS 4, iOS 3.2, and Mac OS X 10.5 and later. It does not support development for Mac OS X 10.4 or earlier or iOS 3.1 or earlier.

The Xcode 4 Transition Guide At a Glance This document first introduces you to the layout and features of Xcode 4 and then describes the most common workflows in more detail.

Open Your Project in Xcode 4 You can start a new project or open your Xcode 3 project in Xcode 4. Following this introduction, the first couple of chapters help you get started.

INTRODUCTION

About the Transition to Xcode 4

Relevant Chapters: ● “Using an Existing Xcode 3 Project” (page 15) ●

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

Get Oriented to Xcode’s Organization and Features Xcode 4 is fundamentally different than Xcode 3, so whether you’re new to Apple platforms or an experienced Apple developer, you should read the next chapter to learn about Xcode 4. Relevant Chapters: ● “Orientation to Xcode 4” (page 25)

Learn How to Use Xcode 4 to Design a User Interface One of the most obvious differences between Xcode 3 and Xcode 4 is that Interface Builder is now fully integrated into the Xcode application. The chapter on the Interface Builder highlights the advantages that ensue from this change. Relevant Chapters: ● “Designing User Interfaces in Xcode 4” (page 57)

Debug and Refine Your Code In Xcode 4 Xcode 4 provides a consistent interface for debugging regardless of which supported debugger you use. Relevant Chapters: ● “Orientation to Xcode 4” (page 25) ●

“Debugging and Analyzing Your Code” (page 71)

●

“Replacing Text and Refactoring” (page 81)

Back Up Your Code and Coordinate the Work of Multiple Programmers With Snapshots and Source Control Xcode provides easy backups with snapshots and provides access to the most commonly used features of source control repositories.

INTRODUCTION

About the Transition to Xcode 4

Relevant Chapter: ● “Repositories, Snapshots, and Archives” (page 87)

Use Archives to Distribute Your Program When you’re ready to share your program with others, create an archive to distribute or to submit to iTunes Connect. Relevant Chapter: ● “Repositories, Snapshots, and Archives” (page 87)

CHAPTER 1

Using an Existing Xcode 3 Project

If you’ve been working in Xcode 3 and have one or more Xcode 3 projects that you’d like to use in Xcode 4, this chapter tells you what you need to know to get started. Once you’ve got your projects open, go to “Orientation to Xcode 4” (page 25) to learn more about using Xcode 4.

Open Your Xcode 3 Project in Xcode 4 Xcode 4 can open an Xcode 3 project without difficulty. You can open the project in any of the usual ways: Control-click the project and choose Open With Xcode.app (being sure you pick Xcode 4), drag the project onto the Xcode 4 icon, or choose File > Open to open the project. You can have both Xcode 3 and Xcode 4 installed on your system at the same time without conflict. Xcode 4 reads and builds projects created in Xcode 2.1 through 3.2.3. Projects created with Xcode 4 can be opened and built on Xcode 3.2 through 3.2.3. You can open a project in either application, save it, then open it in the other application without invalidating the project or losing any data. Opening and building a project in Xcode 4 does not upgrade or alter it. Changes you make to a project in Xcode 4 remain compatible with earlier versions of Xcode. Before going any further, you need to get oriented to the Xcode 4 workspace window. Figure 1-1 shows the Xcode 4 window newly opened with an Xcode 3 project.

CHAPTER 1

Using an Existing Xcode 3 Project

Figure 1-1

A newly opened Xcode 4 window with an Xcode 3 project

The left side of the window is the navigation area, opened to the project navigator, which is similar to the Groups & Files list in the Xcode 3 project window. Figure 1-2 shows the contents of an Xcode 3 project as seen in Xcode 4. Figure 1-2

The project contents in the Xcode 4 project navigator

What you see in this list is probably less surprising than what you don’t see. Missing from the Xcode 4 project navigator are these groups: ●

Targets

CHAPTER 1

Using an Existing Xcode 3 Project

●

Executables

●

Find Results

●

Project Symbols

●

Bookmarks

●

SCM (source control repositories)

●

Smart groups

You’ll also notice that the detail view is missing from Xcode 4. The Xcode 4 equivalents to these groups and user interface elements are described in “Orientation to Xcode 4” (page 25).

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

Check Out a Working Copy from Your Source Control Repository If your Xcode project is in a Git or Subversion repository, you can open your project directly from the repository. 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.

CHAPTER 1

Using an Existing Xcode 3 Project

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

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

CHAPTER 1

Using an Existing Xcode 3 Project

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, you’re done. For Subversion, click on the name of the new repository in the repositories organizer and fill in the paths to the trunk, branches, and tags directores. If your Subversion server requires authentication, fill in the user name and password as well.

See “Repositories, Snapshots, and Archives” (page 87) for more information about source control in Xcode 4.

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

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

●

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

CHAPTER 1

Using an Existing Xcode 3 Project

●

Because all the files in one project are visible to all the other projects in the workspace, you don’t need to copy shared libraries into each project folder separately.

●

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

A project can be included in more than one workspace or removed from a workspace without affecting the project. The workspace file itself merely contains pointers to the projects and other files that the workspace includes, plus a minimal amount of data such as schemes stored in the workspace (“Select a Scheme Instead of Setting an Active Target, Build Configuration, and Executable” (page 30)). The pointers to the source files, included libraries, build configurations, and other data are stored in the project files. If you have two or more related projects, use the following procedure to create a workspace and add the projects to it:

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.

CHAPTER 1

Using an Existing Xcode 3 Project

Drag projects from the project navigator of other Xcode 4 windows or from the Finder to the project navigator of the new workspace. When dragging from the Finder, be sure to drag the project file (<ProjectName>.xcodeproj), not the entire project folder. Be careful to drop each new project below the last project, not in another project.

If you’ve set up your build configuration with explicit references between your projects, the build will continue to behave as it did before. If you used to build one project and then import the product into the other project before you built it, you can remove the product from the project that imports it, because Xcode 4 discovers such implicit dependencies and builds in the correct sequence. If you don’t want one project to use the product or files in another project that’s in the same workspace, you need to adjust your build settings accordingly. See “Targets and Build Settings Are in the Project Editor” (page 25) for help in finding and understanding the build settings interface in Xcode 4. Before you build, be sure you’ve created the scheme or schemes you need. See “Select a Scheme Instead of Setting an Active Target, Build Configuration, and Executable” (page 30) and “Customize Executables in the Scheme Editor” (page 31).

CHAPTER 1

Using an Existing Xcode 3 Project

CHAPTER 2

Creating a New Xcode 4 Project

If you want to start a new software development undertaking using Xcode 4, you need to first decide whether you need a single Xcode project or multiple related projects. For a simple application or utility, a single project should suffice. However, if you have several related executables that need to link against a custom library, you probably want at least a separate project for the library and another for the executables, and possibly a separate project for each executable. In that case, see “Create a New Workspace If You Have More Than One Related Project” (page 23).

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

Create a New Workspace If You Have More Than One Related Project If you decide you want more than one project, then you should create an Xcode workspace to hold the related projects. To do so, use the following procedure: 1.

When Xcode 4 opens, ignore the startup screen and choose File > New > New Workspace.

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.

CHAPTER 2

Creating a New Xcode 4 Project

CHAPTER 3

Orientation to Xcode 4

Once you’ve got your projects open in Xcode 4, you can start writing code. This chapter describes many of the features of Xcode 4 that are located in different places, or used somewhat differently, from the same features in Xcode 3. It also describes a couple of features that are new in Xcode 4. For information in the debugging features of Xcode 4, see “Debugging and Analyzing Your Code” (page 71). For changes in the workflow of designing user interfaces using Xcode 4, which has a fully integrated Interface Builder, see “Designing User Interfaces in Xcode 4” (page 57).

Much of Your Project’s Content Is in New Locations in Xcode 4 The following sections tell you where in the Xcode 4 workspace window to find information that was in your Xcode 3 Groups & Files list. Bookmarks and source control repositories, along with other information, are in the Organizer window. See “Organize Your Projects and Devices in the Projects and iOS Panes” (page 44) for more information about the Organizer window.

Targets and Build Settings Are in the Project Editor Click the project in the project navigator. The project editor appears to the right of the project navigator, displaying project and target information. Figure 3-1 shows some of the target information in the project editor. Figure 3-1

Target information in the project editor

CHAPTER 3

Orientation to Xcode 4

Click the various buttons and icons in the project editor to see the information that’s in there. Note that some of this information is in the Targets group in Xcode 3, but much of it, although actually related to the target, is found in other places in Xcode 3. Xcode 4 brings all this information together and makes some of the relationships clearer. In particular, in Xcode 3, if you need to alter any build settings or create any custom settings, you need to select the target in the Groups & Files list and then open the Info window. To change the list of what files were included in the build or in what order they were used, you need to open all levels of disclosure triangles under the target in the Groups & Files list. Although some build settings are specified at the project level, some are specified at the target level, and some use defaults, these relationships are not obvious in Xcode 3. In Xcode 4, on the other hand, you can view all the levels of build settings simultaneously, as seen in Figure 3-2. Figure 3-2

Build settings

You can edit a build setting at any level. The level at which the build setting is actually set is highlighted in green. The value to which the build setting is set is listed in the Resolved column. If you have changed or customized a setting, it’s shown in boldface.

Set the Basic Build Settings for Each Target in the Summary Pane of the Project Editor Most developers never need to change the default of the vast majority of the build settings. However, there are a few basic settings that you must check, and possibly edit, for each target. These settings are gathered into one pane in the Project editor—labeled the Summary pane—and are somewhat different for Mac OS X and iOS projects. 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.

CHAPTER 3

Orientation to Xcode 4

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

The Source Code Editor Is Similar to the One in Xcode 3 The features you’re used to in Xcode 3 are also present in Xcode 4: Code folding, code completion, Quick Help, automatic indentation, syntax coloring, edit all in scope, automatic balancing of delimiters, and so forth are all available and similar to the same features in Xcode 3. Look through the Edit menu, the shortcut menu, and Xcode preferences to find these features. Many of the keyboard shortcuts are unchanged. Use the Key Bindings pane in Xcode preferences to see and edit the keyboard shortcuts.

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

Code completion

CHAPTER 3

Orientation to Xcode 4

A Quick Help popup is also available from code completion, even when the Quick Help inspector is not open. Hover over the code completion option you’re interested in until a question mark icon appears. Click the question mark or use the Command-Shift-Control-? Keyboard shortcut to open Quick Help. As before, press the Tab key to accept the prefix or Return to accept the entire suggestion. Click the Done button in the Quick Help popup to cancel the operation. Figure 3-4

Quick help for code completion

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

Code completion underlining

Press Control–Space bar to toggle the completion suggestion on or off. That is, if the inline suggestion and list are being displayed, pressing Control–Space bar cancels the code completion operation. If there is no suggestion displayed, place the cursor at the end of a partially typed symbol and press Control–Space bar to get completion suggestions. Note that in Xcode 4, pressing the Esc key cancels the operation and pressing the Delete key always deletes the preceding character.

CHAPTER 3

Orientation to Xcode 4

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

Fix-it in action

Option-Click to Open a File in the Assistant Editor Pane By default, when you Option-click a file in one of the navigators or jump bars, an Assistant editor opens in manual mode and displays the file in the Assistant editor pane (see “Split the Editor Area to Display Related Content” (page 46)). To change this behavior and to set other keyboard shortcuts for opening files, open the General pane of Xcode preferences.

Use the Hex Editor to View Files in Hexadecimal Format You can view and edit many types of files in hexadecimal format, including some (such as graphics files) that you can’t edit otherwise. To do so, Control-click the file in the project navigator and choose Open As > Hex from the shortcut menu. You can edit the hexadecimal code directly, or you can edit in the plain text column. Editing either updates the other.

CHAPTER 3

Orientation to Xcode 4

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

View Either Descriptive Key Names or Raw Keys in the Property List Editor For known property list types, the Key column in the property list editor shows a descriptive name of the key instead of the key’s literal text. Choose Editor > Show Raw Keys & Values to display the literal text instead. You can also see the raw key value in Quick Help in the Quick Help.

Select a Scheme Instead of Setting an Active Target, Build Configuration, and Executable In Xcode 3 you have to set an active target, a build configuration, and an executable as separate items. The problem with this approach is that targets, configurations, and executables are intimately linked. At its simplest, for example, a target contains one product, which is executed without any special options or environmental settings. However, sometimes the product requires values for input parameters or other customization before it can be executed. In Xcode 4, you select a scheme, which specifies which targets to build, what build configuration to use, which debugger to use and which executable to launch when you choose Run from the Product menu or click the Run button at the left end of the toolbar. Each scheme also specifies a set of options for several possible actions: ●

running a product for debugging

●

running unit tests

●

profiling your application with Instruments

●

performing a static analysis of your code

●

archiving your product for distribution or submission to iTunes Connect

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-7). To create a new scheme, choose New Scheme from that menu. To edit existing schemes, choose the scheme you want to edit and then choose Edit Active Scheme from that menu. To change the list of schemes, where they’re stored, and whether they’re shared, choose Manage Schemes. Figure 3-7

The Scheme pop-up menu

CHAPTER 3

Orientation to Xcode 4

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

The Scheme Editor Build Pane Specifies Which Targets are Built for Each Type of Action By default, Xcode creates one scheme per target in your project or workspace. For each target, you use the build pane of the scheme editor (Figure 3-8) to specify which targets are built for each type of action. You can add as many targets from your project or workspace to a single scheme as you wish. The figure shows four targets: the SurfWriter application, a custom framework needed to build the application, an automater plug-in to be provided with the application, and a command-line tool that can be used with the application. In the figure, the SurfWriter application and framework are set to be built for every action, but the plug-in is set to be built only when the application is built for running (that is, for debugging) and for archiving (that is, for distribution). Each of these actions has associated options that you can customize with the scheme editor. Figure 3-8

The scheme editor Build pane

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

CHAPTER 3

Orientation to Xcode 4

Figure 3-9

Customizing an executable environment for a product

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

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

CHAPTER 3

Orientation to Xcode 4

Figure 3-10

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

The Find Options dialog

CHAPTER 3

Orientation to Xcode 4

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

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

●

—displays all types of symbols defined in the project or workspace including functions, structs, and enums —displays only symbols defined in the workspace —displays 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.

CHAPTER 3

Orientation to Xcode 4

Use the search field at the bottom of the symbol navigator to filter the results. For example, in Figure 3-13, only those symbols that include the string KTg are displayed. This filter is not case sensitive. Figure 3-13

The symbol navigator, filtered

Click a symbol to see it displayed in the source editor (Figure 3-14). Option-click the file in the symbol navigator to open Assistant and display the file in the Assistant editor pane (see “Split the Editor Area to Display Related Content” (page 46)).

CHAPTER 3

Orientation to Xcode 4

Figure 3-14

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-15). Hold down the Option key when selecting a file in the jump bar to display the file in the Assistant editor pane (see “Split the Editor Area to Display Related Content” (page 46)). Figure 3-15

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

CHAPTER 3

Orientation to Xcode 4

Figure 3-16

The related-items pop-up menu

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

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

CHAPTER 3

Orientation to Xcode 4

●

Build logs

For more information on using these navigators to analyze and debug your code, see “Debugging and Analyzing Your Code” (page 71). Note: Although Xcode 4 does not allow you to create smart groups and does not display any smart groups that you created for your project in Xcode 3, it does preserve your Xcode 3 smart groups. If you open your project in Xcode 4 and work with your code, then later reopen your project in Xcode 3, the smart groups you created earlier are still there.

The Detail View Isn’t Needed Any More All of the information in the detail view has been replaced in Xcode 4 with navigators or editors. Here are some of the main equivalents: ●

Files in your project: use the project navigator (“Open Your Xcode 3 Project in Xcode 4” (page 15))

●

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

●

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

●

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

●

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

●

Source control: use the source control editor in the Organizer window to work with repositories and the Version editor and project navigator to view source control status of files and to commit or update files (“Work with Your Source Control Repositories in the Repositories Pane” (page 44))

●

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

Customize the Build and Run Workflow with the Scheme Editor and Alerts Preferences As pointed out in “Select a Scheme Instead of Setting an Active Target, Build Configuration, and Executable” (page 30), Xcode 4 schemes replace several settings in Xcode 3 that affect how your project is built and run. The Xcode 4 scheme editor enables you to specify many settings that affect your workflow, including build, test, and launch settings. For example, you can specify what targets to build; whether to build with debug symbols; which targets are built for each type of action; what debugger to use; what scripts to run before and after each type of action; arguments to pass to the application on launch; a variety of diagnostic options (Figure 3-18); and what unit tests to run.

CHAPTER 3

Orientation to Xcode 4

Figure 3-18

Run diagnostic options

Once youâ&#x20AC;&#x2122;ve got one or more schemes set up exactly as you want them, the next thing you may do when setting up your build and run workflow is to open Xcode preferences and click Alerts. This preferences pane lets you specify what should happen when a variety of events occur (Figure 3-19).

CHAPTER 3

Orientation to Xcode 4

Figure 3-19

Alerts 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 Alerts preferences setting to create a snapshot, you can specify that Xcode create a snapshot before a mass-editing operation such as a refactoring transformation. To do so, select the Snapshots pane in the File > Project Settings dialog. (Snapshots are discussed in “A Snapshot Saves a Copy of the Current Version of Your Workspace” (page 87).) You can name a tab and specify that tab as the display to use when an event occurs. Then you can set up the display in that tab exactly as you want it; for instance, with a specific source-code file open in the editor, the debug area open, the Utility area closed, and the issues navigator open. To name a tab, double-click the title of the tab and type in the new name (Figure 3-20). Tab names are case sensitive in the Show Tab field of Alerts preferences. Figure 3-20

Naming a tab

CHAPTER 3

Orientation to Xcode 4

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

The activity viewer

Figure 3-22

The activity pop-up window

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

The Organizer button

CHAPTER 3

Orientation to Xcode 4

Browse and Bookmark Documents in the Documentation Organizer To browse documentation, open the Organizer window, click the Documentation button in the toolbar, and click the Browse button in the jump bar (Figure 3-24). Figure 3-24

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

CHAPTER 3

Orientation to Xcode 4

Figure 3-25

The bookmarks navigator

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

Browse for Task-Based Help in the Documentation Organizer New in Xcode 4, online help is available for the Xcode IDE. To browse the Xcode 4 online help, click the disclosure triangle next to Xcode Help in the documentation navigator (Figure 3-24 (page 42)) or choose Help > Xcode Help (Figure 3-26).

CHAPTER 3

Orientation to Xcode 4

Figure 3-26

Finding Xcode 4 help articles

Many of the articles in Xcode 4 help include a short video that illustrates the described procedure. Click the video thumbnail to play the video. To help you discover and understand the many user interface features of Xcode 4, many of the help articles are also available as contextual help. See “Control-Click for Contextual Help” (page 45) for details.

Work with Your Source Control Repositories in the Repositories Organizer Click the Repositories button in the Organizer window toolbar to work with your source control repositories. You can create local repositories, connect to and manage repositories on servers, and so forth. You can also perform many common SCM operations, such as submitting files, from the workspace window. To do so, select the file or files in the project navigator, Control-click, and choose Source Control from the menu. For more information on repositories, see “Use Repositories for Source Control” (page 88).

Organize Your Projects and Devices in the Projects and iOS Organizers Whereas Xcode 4 allows you to have several workspace windows open simultaneously, there is only one Organizer window. The Organizer window displays information for all your workspaces, projects, repositories, devices, and documentation, regardless of how many projects you have and how many are open.

CHAPTER 3

Orientation to Xcode 4

Click the Projects button in the toolbar to display all your projects and their snapshots. See “A Snapshot Saves a Copy of the Current Version of Your Workspace” (page 87) for more information on snapshots. If you’re working with iOS, the Xcode Organizer window also can display the devices that you have connected to your computer. It indicates which of these devices are currently available and lets you select the one to use. The iOS organizer in Xcode 4 provides the same information and capabilities as the Xcode 3 Organizer window.

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

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

CHAPTER 3

Orientation to Xcode 4

Figure 3-27

Contextual help

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

Split the Editor Area to Display Related Content Xcode 3 lets you split the editor window to look at two locations in a source code file, or two different files, at the same time. Although this ability is also present in Xcode 4, the new user interface provides a much more powerful use of split editor windows, called Assistant.

CHAPTER 3

Orientation to Xcode 4

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.

Assistant Finds Related Content for You To enable Assistant, click the Assistant button in the workspace toolbar (Figure 3-28). Figure 3-28

The Assistant button

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

Setting the behavior for Assistant

Selecting a file in the project navigator causes that file to be shown in the normal editor pane. Unless Assistant is set to manual mode (“Use the Manual Editor to Display Content of Your Choosing” (page 48)), it tracks the change. Option-click when selecting a file in the project navigator or hold down the Option key when selecting a file in the jump bar to display that file in the Assistant pane rather than the standard pane. Doing so switches Assistant to manual mode.

CHAPTER 3

Orientation to Xcode 4

The Assistant editor pane can be displayed to the right of the standard editor pane or below it. Choose View > Assistant Layout to switch between a vertical or horizontal split for the editor panes.

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

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

The Version Editor Compares Two Versions of Your File Use the Version editor to compare different revisions from your source control repository. It can also show the difference between the saved file and what's in memory. In addition, the Version editor lets you see source control logs and blame/annotation information. See “Use the Version Editor to Compare Revisions ” (page 92) for more information.

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

CHAPTER 3

Orientation to Xcode 4

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

Adjacent editor: Opens the file in the regular editor pane in the window and tab already open.

●

Focused editor: Opens the file in whichever editor pane currently has focus.

●

Smart splits: If the Assistant editor is not split, opens the file in the Assistant editor. If the Assistant editor is split, displays a 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. Make your selection and press Return, or press Esc to cancel.

●

Separate editor: If the Assistant editor is split but closed, opens the file in the last-created pane of the Assistant editor. If the Assistant editor is open, opens the file in a new Assistant editor pane regardless of whether the Assistant editor is already split.

●

Separate tab: Opens the file in a new tab.

●

Separate window: Opens the file in a new window.

●

Ask: A dialog opens 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. Make your selection and press Return, or press Esc to cancel.

CHAPTER 3

Orientation to Xcode 4

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

The Utility button

View Quick Help in the Utility Area In Xcode 3, you can open a Quick Help window with information about an API symbol by Option窶電ouble-clicking the symbol. In Xcode 4, you can use an Option-single-click to open Quick Help (Figure 3-31).

CHAPTER 3

Orientation to Xcode 4

Figure 3-31

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 Quick Help inspector in the utility area (Figure 3-32). Just click any symbol while the Quick Help inspector is open to see its Quick Help information. Figure 3-32

The Quick Help inspector

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

CHAPTER 3

Orientation to Xcode 4

Figure 3-33

Quick Help for Interface Builder objects

CHAPTER 3

Orientation to Xcode 4

Figure 3-34

Quick Help for build settings

Use Inspectors to View and Enter File and Interface Builder Data Inspectors are panes in the utility area that you can use to read or enter data about files and Interface Builder objects. Figure 3-35 shows a file inspector. For more information about Interface Builder, see “Designing User Interfaces in Xcode 4” (page 57).

CHAPTER 3

Orientation to Xcode 4

Figure 3-35

A file inspector

Drag Files and Code from the Library into Your Project Xcode provides libraries of file templates and code snippets that you can use in your program. It also has libraries of Interface Builder objects and media files that you can use in your nib files. The libraries pane is in the lower part of the utility area (see Figure I-1 (page 11)). Each of the buttons at the top of this pane selects a category of library objects, as follows: â&#x2014;?

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

A file template information pop-up window

CHAPTER 3

Orientation to Xcode 4

●

Code snippets are short pieces of source code that you can use in your software. To use one, you can drag it directly into your source code file. Alternatively, you can copy a portion of the code from the code information pop-up window (Figure 3-37) and drag that into your file. To create your own code snippet, highlight the code for the snippet in a source file and drag it into the Code Snippet library pane. You’ll need to edit the snippet to give it a meaningful name and, optionally, a completion shortcut. You can use a completion shortcut to add a snippet when editing source code. Type the shortcut in your source code file and select the snippet from the code completion list to add the code to your file. Note that a new or edited code snippet is flagged with the word “User” (Figure 3-38). Figure 3-37

Dragging a piece of a code snippet into your file

Figure 3-38

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

CHAPTER 3

Orientation to Xcode 4

CHAPTER 4

Designing User Interfaces in Xcode 4

In the Xcode 3 development environment, Xcode and Interface Builder are separate applications. In Xcode 4, Interface Builder is an editor within the Xcode application. Although most of the features of the Xcode 3 Interface Builder application work identically in Xcode 4, there are some differences—most notably, the ability to make connections from Interface Builder objects directly into source code. This chapter describes the main differences between the two implementations of Interface Builder.

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

Interface Builder in the workspace window Inspector selector bar

Interface Builder objects

Inspector pane

Dock

Library selector bar

Editor area

Canvas

Utility area

Library pane

CHAPTER 4

Designing User Interfaces in Xcode 4

Create a New Nib File with the File Menu or the Library When you create a new Cocoa application or iOS view-based project, Xcode includes a nib file for your main view and a view controller class. The view controller is represented in the nib file as the “file’s owner” object. When you need a new nib file for a project, you should create the interface and implementation files for the controller first. In many cases, Xcode creates a nib file as well. As nib files usually have controllers already assigned to them, it is rarely necessary to add a separate view controller to a nib file. You can add a new nib file to your project either by choosing File > New > New File and selecting a User Interface template, or by dragging an interface file from the File Template library into the project navigator. When dragging into the project navigator, be sure the group into which you want to drop the file is highlighted before you drop (Figure 4-2); you won’t get the results you want if you accidentally drop the file inside another file. Figure 4-2

Dropping a nib file in the Resources group

Whether you choose New File or drag the nib file from the File Template library, be sure you select the appropriate file type for the correct platform. For example, there are two nib templates named Application: one for iPhone and iPad, and one for Cocoa.

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

CHAPTER 4

Designing User Interfaces in Xcode 4

Add Source Files For A New Nib FIle, Then Add the Nib FIle To add a new nib file to a project, first choose File > New > New File and add interface and implementation file templates for a controller class for the nib file. For example, if your new nib file is going to start with a Cocoa window, add a Cocoa Objective-C class thatâ&#x20AC;&#x2122;s a subclass of NSWindowController. Xcode creates both a header file and an implementation file and adds them to your project. In Figure 4-3, for example, the new class will be a subclass of NSWindowController. Figure 4-3

Creating new class files

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

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-4

Adding a new Window nib file

Open the new nib file by selecting it in the project navigator so that it appears in the Interface Builder editor. Then select the Fileâ&#x20AC;&#x2122;s Owner object in the Interface Builder dock and choose your controller in the class field under Custom Class in the Identity inspector (Figure 4-5).

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-5

Assigning a class to an Interface Builder object

To see the outlets and actions provided by the parent class of the file’s owner, click the File’s Owner object in the dock and open the Connections inspector. To add new actions or outlets to the nib file’s controller, see “Make Connections Directly Between IB Objects and Source Code” (page 65).

To Add a Custom View, Start With the View’s Subclass, Then Add the View To Your Nib If you need to add a new custom view to your nib file, first create header and implementation files for the view by choosing File > New > New File and selecting the Objective-C class template. Be sure to choose the appropriate parent class in the “Subclass of” popup menu. After adding the source file templates to your project, drag a custom view object from the library into the nib file, as shown in Figure 4-6.

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-6

Adding a custom view

After adding the custom view to your nib, select the custom view and assign the correct class to it in the class field under Custom Class in the Identity inspector (Figure 4-5 (page 61)).

Create Your Interface Controller in Xcode, Then Add a Controller Object to the Nib File To create a new controller for a nib file, first use the New File dialog to create interface and implementation files for the new class. Use the Objective-C class template and make the templates a subclass of NSObject. If you want to make connections in Interface Builder to the outlets and actions of the controller, drag the Object object from the Object library in the Utilities pane into the dock of your Interface Builder nib file (Figure 4-7). (Tip: Type nsobject into the search field to find the object quickly.) Select the new object in the dock and use the class field under Custom Class in the Identity inspector (Figure 4-5 (page 61)) to assign the class of your controller to the object. Then use the Label field in that same inspector to change its display name.

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-7

Adding a controller object to a nib file

To see the outlets and actions provided by the controller, click the controller object in the dock and open the Connections inspector. To add new actions or outlets to the controller, see “Make Connections Directly Between IB Objects and Source Code” (page 65).

Use Assistant to Work on Your Interface Source Code When you use custom subclasses in your interface, or add outlets and actions to a controller, you can use Assistant to work on your interface design and your interface code at the same time. To do so, select your nib file in the project navigator to open Interface Builder and click the Assistant button to open the Assistant editor pane. If the Assistant editor does not automatically display the header file you want, use the Assistant editor pane jump bar to select the source file containing the controller code for the object. Figure 4-8 shows a window with a graphic view selected in Interface Builder and the header file for the graphic view being chosen from the Automatic mode of Assistant. By default, the Assistant editor pane is displayed below the Interface Builder editor. Choose View > Assistant Layout to switch between a vertical or horizontal split for the two editor panes.

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-8

Selecting a counterpart to a nib file in assistant

In Figure 4-9 you can see that, with a window object selected in the Interface Builder pane, the Assistant editor pane displays the file SKTWindowController.m. The oval containing the numerals 4/5 at the right end of the editor jump bar indicates that the fourth of five counterpart files is being displayed (in this case the others are SKTWindowController.h, SKTGraphicView.h, SKTGraphicView.m, and NSWindow.h). Click the right or left arrows to display the others in turn. You can therefore write code for the window controller at the same time you are designing your window, and you can make connections directly between Interface Builder objects and lines in your code (see “Make Connections Directly Between IB Objects and Source Code” (page 65).

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-9

Interface Builder with the Assistant editor open

Because Interface Builder is now a fully integrated part of Xcode, it is no longer necessary to switch back and forth between two applications to create custom subclasses and define actions and outlets. Therefore, Xcode 4 does not provide the special Interface Builder commands used with Xcode 3 to create new subclasses and copy them into Xcode.

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

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-10 shows a connection being made to an existing IBAction statement. Figure 4-10

Making a connection to source code from Interface Builder

If you need to add a new IBAction or IBOutlet statement, Control-drag to the location in the header file where you want to add the new statement. If the location is a valid connection destination, Xcode displays an insertion indicator (Figure 4-11). When you release the mouse button, Xcode displays a small dialog where you specify the nature of the connection (Figure 4-12). Click Connect to insert the code in your header file.

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-11

Inserting an action or outlet statement in your header file

Figure 4-12

Connection insertion dialog

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

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-13

Help articles in Interface Builder

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

CHAPTER 4

Designing User Interfaces in Xcode 4

Figure 4-14

Outline view for placeholders and objects in Interface Builder

See the User Guide for More For more information on Interface Builder in Xcode 4, including information on making binding connections and a short tutorial illustrating the use of Interface Builder, see “Designing User Interfaces in Xcode” in Xcode 4 User Guide. It’s important to note the differences between the work flow in the User Guide tutorial 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. It’s important to keep Interface Builder and Xcode synchronized. By contrast, in Xcode 4, once you’ve created the class, you can connect to the code directly from Interface Builder (see “Make Connections Directly Between IB Objects and Source Code” (page 65)), and Xcode adds outlet and action code for you. You only need to add the implementation for the actions. If you need to see your new class in Interface Builder, you can add an object to the Interface Builder editor representing that class, but you never create a class in Interface Builder. If you have worked through the tutorial in the Xcode 3 Interface Builder User Guide, you are already familiar with the application created in the User Guide tutorial. However, the workflow is quite different.

CHAPTER 4

Designing User Interfaces in Xcode 4

CHAPTER 5

Debugging and Analyzing Your Code

Xcode 4 provides all the facilities you need to analyze and debug your code in the workspace window. This chapter summarizes those facilities, with an emphasis on differences between Xcode 4 and Xcode 3.

Select a Debugger in the Scheme Editor Xcode 4 comes with GDB and LLDB debuggers. To select which one to use, choose Edit Active Scheme from the Scheme pop-up menu (Figure 3-7 (page 30)) 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.

CHAPTER 5

Debugging and Analyzing Your Code

Use Static Analysis to Find Potential Problems Before Building Use static analysis to examine the syntax of your code for bugs. The static analyzer in Xcode 4 is similar to the one in Xcode 3. Whereas by default, Xcode 3 opens a separate Build Results window to display the results of the analysis, Xcode 4 lets you perform the analysis, examine the results, and edit your source files all within the workspace window. To run the static analyzer, select the project you want to analyze in the project navigator and then choose Product > Analyze. (If you want to open the scheme editor to set options first, hold down the Option key while choosing Product > Analyze.) When the analyzer finishes, the issue navigator opens automatically with a list of the issues found. You can click an issue in the issue navigator to open the file in question. The problem is labeled in a blue rectangle marked with an arrow. Click the blue rectangle to see the faulty logic flow found by the analyzer (Figure 5-2). Figure 5-2

Static analysis results

As you can see in the figure, an analysis results bar opens below the jump bar. You can open the analysis pop-up menu ( ) on the left to see the various issues found, or cycle through them by clicking the arrows at the right end of the analysis results bar. You can open an issues pop-up menu showing the various files in which problems were found by clicking the issues button at the right end of the jump bar (see the following section, “Use the Issue Navigator or Issues Pop-up Menu to Locate Build Errors”), or cycle through the issues by clicking the arrows that bracket the issues button.

CHAPTER 5

Debugging and Analyzing Your Code

Use the Issue Navigator or Issues Pop-up Menu to Locate Build Errors To build and run the executable specified by the active scheme, click the Run button at the left end of the toolbar. Other options, such as running without building or building without running, are available in the Product menu. To open the scheme editor before building or running, hold down the Option key while opening the Product menu. Schemes are described in “Select a Scheme Instead of Setting an Active Target, Build Configuration, and Executable” (page 30). See “Customize Executables in the Scheme Editor” (page 31) for information on the scheme editor. If the compiler finds any problems while building, the issue navigator opens. Select any of the errors or warnings in the list to display in the source editor the line of code where the problem was discovered. You can display problems by file or by type (Figure 5-3). Figure 5-3

The issue navigator

You can also use the issues pop-up menu to navigate through the build issues—for example, if you have the navigator pane closed to maximize the size of the source editor (Figure 5-4). The issues menu appears as a yellow triangle if the most serious issue listed is a warning ( ) or as a red octagon if any errors are listed ( ). Choose an error from the menu or use the arrows to cycle through the errors. If there’s more than one error associated with a line of code, a number appears at the right end of the error description in the source editor. Click the number to display a list of all the errors associated with that line of code.

CHAPTER 5

Debugging and Analyzing Your Code

Figure 5-4

The issues pop-up menu

Use the Log Navigator to View Build Results The log navigator in Xcode 4 replaces the Xcode 3 build log window and also shows you the history of your console run and debug sessions. When you select one of the builds in the build log, the results are displayed in the editor area (Figure 5-5). Figure 5-5

The build log

Double-click a warning or error to open the source editor to that error, or open an Assistant editor, set it to Referenced Files, and select an issue in the log to see it displayed in the Assistant editor. Click the list icon ( ) at the end of a build command line to see the full build command and results (Figure 5-6).

CHAPTER 5

Debugging and Analyzing Your Code

Figure 5-6

The build log with a verbose build command

Use the Source Editor and Breakpoint Navigator to Manage Breakpoints Although you can use the debugger to pause execution of your program at any time and view the state of the running code, it's usually helpful to set breakpoints before running your executable so you can stop at known points and view the values of variables in your source code. To set breakpoints, open a source-code file and click in the gutter next to the spot where you want execution to stop. When you add a breakpoint to the code, Xcode automatically enables breakpoints, as indicated by the breakpoint-state button in the toolbar (enabled: disabled: ). You can toggle the enabled state of breakpoints at any time by clicking the breakpoint-state button. You can also disable an individual breakpoint by clicking its icon. To remove a breakpoint completely, drag it out of the gutter. You can set several options for each breakpoint, such as a condition, the number of times to pass the breakpoint before itâ&#x20AC;&#x2122;s triggered, or an action to perform when the breakpoint is triggered. To set breakpoint options, open the breakpoint navigator and Control-click the breakpoint for which you want options (Figure 5-7), then choose Edit Breakpoint from the shortcut menu. The Condition field lets you specify an execute condition for the breakpoint. When you specify a condition, the breakpoint is triggered only if the condition (for example, i == 24) is true. You can use any variables that are in the current scope for that breakpoint. Note that you must cast any function calls to the appropriate return type.

CHAPTER 5

Debugging and Analyzing Your Code

Figure 5-7

Setting breakpoint options

In addition to conditional breakpoints, which are triggered when a specific condition is met, you can create exception breakpoints, which are triggered when a specific type of exception is thrown or caught, and symbolic breakpoints, which are triggered when a specific method or function begins execution. To do so, click the Add (+) button at the bottom of the breakpoint navigator and choose Add Exception Breakpoint or Add Symbolic Breakpoint from the pop-up menu. By default, a new breakpoint is local to the workspace you have open. If you add the project containing that breakpoint to another workspace, the breakpoint is not copied to the new workspace. You can assign breakpoints to other scopes, however. If you move a breakpoint to User scope, it appears in all of your projects and workspaces. If you move a breakpoint to a specific project, then you see this breakpoint whenever you open that project, regardless of which workspace the project is in. To change the scope of a breakpoint, Control-click the breakpoint and choose the scope from the Move Breakpoint To menu item. The scopes of breakpoints are shown in the breakpoint navigator (Figure 5-8). Figure 5-8

Scopes of breakpoints in the breakpoint navigator

CHAPTER 5

Debugging and Analyzing Your Code

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

The debug navigator stopped at a breakpoint

Control Program Execution in the Debugger Area and Source Editor When you execute a program from Xcode 4, the debugger bar appears at the bottom of the editor pane (see Figure 5-9 (page 77)). The debugger bar includes buttons to: ●

Open or close the debugger area

CHAPTER 5

Debugging and Analyzing Your Code

●

Pause or resume execution of your code

●

Step over; that is, execute the current line of code and, if the current line is a routine, return to the next line in the current file

●

Step in; that is, execute the current line of code and, if the current line is a routine, jump to the first line of that routine

●

Step out of a jumped-to routine; that is, complete the current routine and step to the next routine or back to the calling routine.

Press Control to step by assembly language instruction instead of by statement (the step icons change to show a dot rather than a line under the arrow) or Control-Shift to step only into or over the active thread while holding other threads stopped (the step icons show a dashed rather than solid line under the arrow). If you pause execution or a breakpoint is triggered, the debugger 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 debugger area toolbar to display both the variables and console panes or to hide either one. Figure 5-10

The debugger 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 recently accessed variables.

CHAPTER 5

Debugging and Analyzing Your Code

●

Local displays local variables.

●

All displays all variables and registers.

Use the search field to filter the items displayed in the variables pane. The console pane displays program output and lets you enter commands to the debugger tool. You specify the type of output the console displays with the pop-up menu in the top-left corner of the console pane: ●

All Output displays target and debugger output.

●

Debugger Output displays debugger output only.

●

Target Output displays target output only.

You can use the navigation pop-up menus in the debugger 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 debugger

While execution is stopped at a breakpoint, you can view variables and step through code in the source editor in much the same way as you can in Xcode 3. For example, to continue execution to a specific line of code, hold the pointer over the gutter next to the target code line until the continue-to-here icon appears, then click the icon (Figure 5-12). To see the values of variables, click the variable name in the editor (Figure 5-13 (page 80)). Hover over and click variable components to open the disclosure triangles to see the fields of structures. Figure 5-12

Activating the continue-to-here command

CHAPTER 5

Debugging and Analyzing Your Code

Figure 5-13

Reading the value of a variable in the source editor

CHAPTER 6

Replacing Text and Refactoring

Like Xcode 3, Xcode 4 enables you to replace text throughout your project and to make other global changes to your code, such as converting the code to Objective C 2.0 or creating a superclass from a class. These facilities are referred to as search and replace and factoring.

Replace Text Using the Search Navigator To replace text in your source files, choose Replace from the pop-up menu in the search navigator (Figure 6-1). Type the text you want to find in the top text field and press Return, then type the replacement text in the lower text field (Figure 6-2). Note that Xcode does not search for the text if you donâ&#x20AC;&#x2122;t press Return while the cursor is in the upper text field, so if you get no results after typing your replacement text, put your cursor in the upper text field and press Return. The activity viewer in the workspace toolbar indicates the find operation is in progress (Figure 6-3). Figure 6-1

Find/Replace pop-up menu

CHAPTER 6

Replacing Text and Refactoring

Figure 6-2

Find/Replace results

Figure 6-3

Activity viewer during a Find operation

Click Replace All to replace every occurrence of the searched-for text with the replacement text. To replace a single result, click that result to select it and press Replace. To replace a subset of the occurrences found, use Shift-click or Command-click to make your selection and press Replace. By default, Xcode creates a snapshot of your project before making the changes; see “A Snapshot Saves a Copy of the Current Version of Your Workspace” (page 87)). To change this preference, select the Snapshots pane in the File > Project Settings dialog. You can also make a manual snapshot before clicking the Replace button (choose File > Manual Snapshot).

CHAPTER 6

Replacing Text and Refactoring

Preview Changes Before Replacing Text To see what your changes will look like in your source code before deciding which occurrences to replace, click the Preview button below the Replace text box (Figure 6-2 (page 82)). The preview dialog is shown in Figure 6-4. Figure 6-4

Replacement preview

To select an individual occurrence of the Find text for replacement, click the checkbox for that occurrence in the left pane of the dialog, or click the sliding switch in the center of the right pane. Alternatively, you can select as many occurrences as you wish in the left pane using Shift-click or Command-click, and then press the Space bar to select them. If you decide to replace all the occurrences, click Cancel and then click the Replace All button.

Refactor Your Code to Make It Easier to Maintain A refactoring operation is one that improves the structure of source code without changing its behavior. You might do this to make it easier to maintain, or as a first step in making further changes to the code. Refactoring in Xcode 4 works much as it does in Xcode 3. Before you can choose a refactoring operation from Edit > Refactor or from the shortcut menu in the source editor, you have to select the source code that you want to refactor. Only the refactoring operations appropriate for the selected text are available in the menu. Once youâ&#x20AC;&#x2122;ve selected the text and the refactoring operation, Xcode presents a dialog to let you select options and specify symbol names where necessary.

CHAPTER 6

Replacing Text and Refactoring

You also have the opportunity to preview the changes and decide which files to include before applying the changes (Figure 6-5). Uncheck a file in the navigator pane to leave it out of the transformation. You can edit your source code directly in the Preview dialog. Any such edits are shown in the preview and included in the transformation. Figure 6-5

Refactor preview dialog

Possible refactoring operations include:

●

Rename changes the name of the selected item throughout your project files; select any symbol except except the declaration of a method inside a protocol interface. If you’re renaming a class and you have files that use that class in the file name, check the Rename related files checkbox to rename the files as part of the refactor transformation.

●

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

CHAPTER 6

Replacing Text and Refactoring

Refactoring works only with C and Objective C files. Before youâ&#x20AC;&#x2122;ve saved your updated files, you can use the Edit > Undo operation on a per-file basis to back out changes, or you can close the project without saving changes to revert to your original files.

CHAPTER 6

Replacing Text and Refactoring

CHAPTER 7

Repositories, Snapshots, and Archives

Xcode 4 supports source control repositories for Subversion and Git. It also provides a new snapshot facility that is much faster than the one in Xcode 3. In addition, whenever you build a target for distribution, Xcode 4 saves an archive of the build products.

A Snapshot Saves a Copy of the Current Version of Your Workspace Compared with Xcode 3, the Xcode 4 snapshot feature is much faster and more reliable. Xcode 4 snapshots are not compatible with Xcode 3 snapshots, however. To restore to a snapshot you took in Xcode 3, you have to be running Xcode 3, and vice versa. Note that you must have installed the Git tool by selecting System Tools in the Xcode 4 installer in order to use snapshots. To create a snapshot manually, choose File > Create Snapshot. In addition, by default Xcode 4 creates a snapshot automatically before a major change such as refactoring your code or executing a find-and-replace operation. Choose File > Project Settings (or Workspace Settings) to change this option. To see the snapshots for a project or workspace, click the project in the Projects pane of the Organizer window (Figure 7-1). To restore from a snapshot, select that snapshot and click the Restore Snapshot button at the bottom of the window.

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-1

Snapshots listed in the Organizer window

Note that, because Xcode 4 keeps track of all your projects and displays them in the Projects pane of the Organizer even if they no longer exist, you can restore a deleted project from a snapshot.

Source Control Repositories Help You Keep Track of Changes and Coordinate Work Groups In Xcode 4, you configure SCM repositories in the Organizer (Figure 7-2) instead of a preference pane, as is done in Xcode 3. If you check a project or workspace out of Subversion or Git using the command line or another tool, you can add it to your Xcode SCM repository support. To do so, click the plus sign (+) at the bottom of the navigation pane in the repository organizer and choose Add Working Copy.

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-2

Repositories Organizer

Xcode 4 provides a consistent user interface for both Subversion and Git. For example, the Subversion UI now supports annotations. The Xcode 4 installer installs the Git and Subversion tools when you select System Tools. SCM status is shown as a badge in the project navigator (Figure 7-3), as follows: M Locally modified U Updated in repository A

Locally added

D Locally deleted I

Ignored

Replaced in the repository

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

Figure 7-3

Source control badges in the project navigator

CHAPTER 7

Repositories, Snapshots, and Archives

Badges propagate up to the highest container so you can see the source control status of the whole workspace regardless of the disclosure level. Detailed SCM status is shown in the Source Control area of the File inspector in the utility area. Source control commands are now in the Source Control submenu of the File menu, rather than in a separate SCM menu. When you’ve made changes to files and saved them locally, use the project navigator to select the individual files for which you want to perform a source control operation, and choose the action you wish to perform from the File > Source Control menu (Figure 7-4). Saving a file is not the same as committing it to source control; you must explicitly commit the file. To see which files have been modified locally but not committed, look for the M badge next to the filename in the project navigator. You can use the SCM status filter at the bottom of the project navigator to display only files with SCM status. Figure 7-4

The Source Control submenu

Update and commit operations are recorded in the log navigator. Select a log to see the individual steps of that operation in the editor pane.

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

Commit Files to Add Them to a Repository When you edit a file, it is changed locally but the changes are not included in the source control repository. To add the changes to the repository, you must commit the file. You must save the file before you can commit it, but note that saving a file is not the same as committing it to source control—you must explicitly commit the file. To see which files have been modified locally but not committed, look for the M badge next to the

CHAPTER 7

Repositories, Snapshots, and Archives

file name in the Project navigator. (New files that have never been committed to source control have the A badge.) You can use the SCM status filter at the bottom of the Project navigator to display only files with SCM status. When you choose Commit, a confirmation dialog opens that you can use to make sure the changes you are committing are what you intended (“Commit confirmation”). You can compare your new version with any past version in the confirmation dialog. When you choose File > Source Control > Commit, the confirmation dialog shows all the files with pending changes. Uncheck the checkboxes next to any files that you do not wish to commit. When you choose Source Control > Commit Selected Files from the shortcut menu in the project navigator, only the files you’ve selected in the project navigator are included in the confirmation dialog. In either case, you must enter a comment before committing. You can edit the file in the confirmation dialog before committing. Any changes you make this way are included in the committed file and saved in your project. Figure 7-5

Commit confirmation

The Merge Facility Helps You Reconcile Different Branches When you’re ready to merge the code in a separate branch back into the main branch, or when you want to combine the code in any two branches, you can use the merge facility of your source control system to reconcile differences between the branches. To do so, save and commit any changes, switch to the branch into which you want to merge code, and choose File > Source Control > Merge. In the Merge dialog (Figure 7-6 (page 92)), the left pane shows what the merged file will look like. The right pane shows the file with which you’re merging. For each difference or conflict between the files, an arrow in the center points to the file taking precedence. For example, if the file on the right (the one with which you’re merging) has a line of code missing from the file on the left (your working copy) and the arrow is pointing toward the file on the right, then the line of code will be included in the working copy after the merge operation is complete.

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-6

The Merge dialog

For each difference or conflict, you can use the left and right arrow buttons at the bottom of the dialog to specify which file’s contents should be used. Therefore, to use the contents of the working copy to resolve the top difference in the figure, click on the arrow for that difference and then click on the left arrow button at the bottom of the dialog. Because this line is missing from the current working copy, it is no longer shown in the left pane. In the case of a conflict, there are two additional options for reconciling differences: you can take the code lines from both files, either listing the ones in the left (working copy) file first and those in the right (root copy) file second, or vice versa. If you wish, you can edit the current branch in the dialog to reconcile any differences not handled by the four choices. Click Merge and commit the changes to the updated files to complete the operation.

Use the Version Editor to Compare Revisions Select any file under source control and click the Version Editor button ( ) to display two versions of that file in a side-by-side view. Use the jump bar underneath either editor pane to select the version of the file to compare with the one in the other pane (Figure 7-7 (page 93)). Buttons under the Version editor allow you to show a file comparison and timeline, change logs for the file, or individual change annotations (“blame”) for each line of the file.

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-7

Comparing two revisions of a file with the Version editor

You can edit the current working copy of the file in the Version editor and you can copy code from an older version and paste it into the current version. In Xcode 4, the working copy of a file is on the left.

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

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-8

Using the Version editor timeline

Use Blame Mode to Review Individual Changes In Blame mode, the current revision of the file is displayed along with the last revision that modified each line of the file. If you wish, you can use the jump bar at the bottom of the window to select a different revision to examine. Each log entry is aligned with the line in the file where the change was made. The log entry includes the name of the person who committed the change, the date, and the ID of the commit. Next to the entry is an arrow button. Figure 7-9 shows Blame mode in use.

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-9

Version editor Blame mode

Click the arrow next to any change that interests you to see that change displayed in Comparison mode. Use the Up Arrow and Down Arrow keys on the keyboard to highlight the change associated with this Blame-mode entry.

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

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-10

Version editor Log mode

Use Archives to Distribute Your Program or Submit an Application to the App Store To build your project and save the resulting application or a disk image of the set of build products, choose Archive from the Product menu. Xcode creates an archive of your project using the build configuration and name you specified in the Archive pane of the scheme editor (“Select a Scheme Instead of Setting an Active Target, Build Configuration, and Executable” (page 30)) and saves the archive in the location specified in the Locations pane of Xcode preferences. To see the archives for your project, open the Archives Organizer window (Figure 7-9). To submit your application to the app store, you must have an iTunes Connect account. Click Submit to submit the application. Click Validate to run the same validation used by iTunes Connect to make sure your application is ready for submittal. To get a copy of your application that you can package for distribution or share with others, click Share. You can add a comment by clicking on the text field in the Comment column.

CHAPTER 7

Repositories, Snapshots, and Archives

Figure 7-11

Archives organizer

CHAPTER 7

Repositories, Snapshots, and Archives

REVISION HISTORY

Document Revision History

This table describes the changes to Xcode 4 Transition Guide. Date

Notes

2011-01-14

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

REVISION HISTORY

Document Revision History