Mastering Xcode 4 – Read Now and Download Mobi

Mastering Xcode 4: Develop and Design

Joshua Nozzi

Mastering Xcode 4: Develop and Design
Joshua Nozzi

Peachpit Press
1249 Eighth Street
Berkeley, CA 94710
510/524-2178
510/524-2221 (fax)

Find us on the Web at: www.peachpit.com
To report errors, please send a note to [email protected]
Peachpit Press is a division of Pearson Education
Copyright © 2012 by Joshua Nozzi

Editor: Cliff Colby
Production editor: Myrna Vladic
Development editor: Kim Wimpsett and Robyn G. Thomas
Copyeditor: Scout Festa
Technical Editor: Duncan Campbell
Cover design: Aren Howell Straiger
Interior design: Mimi Heft
Compositor: David Van Ness
Indexer: Ann Rogers

Notice of Rights

All rights reserved. No part of this book may be reproduced or transmitted in any form by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of the publisher. For information on getting permission for reprints and excerpts, contact [email protected].

Notice of Liability

The information in this book is distributed on an “As Is” basis, without warranty. While every precaution has been taken in the preparation of the book, neither the author nor Peachpit Press shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the instructions contained in this book or by the computer software and hardware products described in it.

Trademarks

Xcode is a trademark of Apple Inc., registered in the United States and other countries. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and Peachpit Press was aware of a trademark claim, the designations appear as requested by the owner of the trademark. All other product names and services identified throughout this book are used in editorial fashion only and for the benefit of such companies with no intention of infringement of the trademark. No such use, or the use of any trade name, is intended to convey endorsement or other affiliation with this book.

ISBN 13:   978-0-321-76752-3
ISBN 10:          0-321-76752-7

9  8  7  6  5  4  3  2  1

Printed and bound in the United States of America

Thanks to all my peers, friends, and family for their enthusiastic support,
to a great team of professionals for helping me reach this goal,
and to Matt for putting up with yet another of
my time-consuming projects.

Acknowledgments

I wish to thank the following people whose work I used while writing this book.

Cyril Godefroy

Cyril’s masterfully broken code examples demonstrated some nice highlights of the Clang Static Analyzer. You can find them at http://xcodebook.com/cgodefroy.

Colin Wheeler

Colin’s Xcode shortcut cheat sheet saved me loads of tedium when creating Appendix B. You can find the original, downloadable version that Colin maintains at http://xcodebook.com/cwheeler.

Contents

Introduction

Welcome to Xcode

PART I THE BASICS: GETTING STARTED WITH XCODE 4

CHAPTER 1 DISCOVERING XCODE TOOLS

Downloading

Installing

Exploring

Wrapping Up

CHAPTER 2 STARTING A PROJECT

Welcome to Xcode!

Creating a New Project

Project Modernization

Building and Running an Application

Wrapping Up

CHAPTER 3 NAVIGATING A PROJECT

The Workspace Window

The Navigator Area

The Jump Bar

The Editor Area

The Utility Area

The Debug Area

The Activity Viewer

The Tabs

The Organizer Window

Wrapping Up

CHAPTER 4 GETTING HELP

The Help Menu

The Organizer’s Documentation Tab

The Source Editor

Community Help and Feedback

Wrapping Up

PART II WORKING WITH COCOA APPLICATIONS

CHAPTER 5 CREATING USER INTERFACES

Understanding Nibs

Getting Familiar with Interface Builder

Adding User Interface Elements

Layout

Wrapping Up

CHAPTER 6 ADDING FILES TO A PROJECT

Adding Existing Files

Creating New Files

Using the File Template Library

Removing Files from the Project

Wrapping Up

CHAPTER 7 WRITING CODE WITH THE SOURCE EDITOR

Exploring the Source Editor Interface

Navigating Source Code

Using Code Completion

Exploring the Code Snippet Library

The Assistant

Wrapping Up

CHAPTER 8 SEARCHING AND REPLACING

Using the Search Navigator

Searching within Files

Wrapping Up

CHAPTER 9 BASIC DEBUGGING AND ANALYSIS

Compile-Time Debugging

Runtime Debugging

Wrapping Up

CHAPTER 10 USING THE DATA MODEL EDITOR

Introducing Core Data

Using the Data Model Editor

Creating a Basic Data Model

Creating a UI for the Model

Using the Assistant

Wrapping Up

CHAPTER 11 CUSTOMIZING THE APPLICATION ICON

Picking the Ideal Artwork

Creating Icons

Setting the Application Icon

Setting Document Icons

Wrapping Up

CHAPTER 12 DEPLOYING AN APPLICATION

Archiving

Alternatives to Archiving

Wrapping Up

PART III GOING BEYOND THE BASICS

CHAPTER 13 ADVANCED EDITING

Renaming Symbols

Refactoring

Organizing with Macros

Changing Editor Key Bindings

Jump to Definition

My Company Name

Wrapping Up

CHAPTER 14 THE BUILD SYSTEM

An Overview

Working with Targets

Working with Schemes

Entitlements (Sandboxing)

Wrapping Up

CHAPTER 15 LIBRARIES, FRAMEWORKS, AND LOADABLE BUNDLES

What are Libraries, Frameworks, and Bundles?

Using Existing Libraries and Frameworks

Creating a Framework

Wrapping Up

CHAPTER 16 WORKSPACES

What Is a Workspace?

When to Use a Workspace

Creating a Workspace

Another Kind of Workspace

Wrapping Up

CHAPTER 17 DEBUGGING AND ANALYSIS IN DEPTH

Using the Clang Static Analyzer

Exploring Analyzer Results

Threads and Stacks

Inspecting Memory

Conferring with the Console

Viewing Generated Output

Debugging Apps for iOS Devices

Wrapping Up

CHAPTER 18 UNIT TESTING

What is Unit Testing?

Unit Testing in Xcode

Writing a Unit Test

Adding Unit Tests to Existing Projects

Wrapping Up

CHAPTER 19 USING SCRIPTING AND PREPROCESSING

Extending Your Workflow with Custom Scripts

Using the Preprocessor

Wrapping Up

CHAPTER 20 USING INSTRUMENTS

An Overview of DTrace

A Tour of Instruments

Using Instruments for Common Tasks

Wrapping Up

CHAPTER 21 SOURCE CODE MANAGEMENT

Xcode Snapshots

Using an SCM System

Wrapping Up

Index

APPENDIXES

APPENDIX A MANAGING YOUR IOS DEVICES

APPENDIX B GESTURES AND KEYBOARD SHORTCUTS

APPENDIX C DOCUMENTATION UPDATES

APPENDIX D OTHER RESOURCES

Introduction

This book is an intermediate-level introduction to Xcode 4, Apple’s integrated development environment. It assumes you have some development experience and are familiar with the Cocoa API. It won’t teach you how to write code or much at all about Cocoa. There are other books for that. This one is strictly focused on how to use Xcode itself, whatever your development endeavors.

Of course, since Xcode is most often used with the Cocoa API and Objective-C, there are basic introductions to Cocoa concepts and a few trivial code samples sprinkled here and there to illustrate various points. In these cases, I point to the documentation that Apple provides (to save you some trouble looking it up), but I only had a limited number of pages in which to show you Xcode stuff, so please keep this in mind when writing your scathing Amazon reviews.

Also, I’ve formed the opinion that Apple is crafty when it comes to software releases. Not only are they ultra-secretive, but they appear to know my precise schedule and plans (I blame iCloud). They seem to use this knowledge to wait until I’m almost finished and then change a bunch of stuff in a single release, necessitating the tracking down and editing of many fine details. I imagine an Apple overseer watching me through my Mac’s camera, stroking a wrinkly, hairless cat and waiting until I’m almost finished. He then orders his henchmen to release the next set of random changes and leans toward the screen expectantly, muttering “Yeeesssss...” as I shake my fist at the sky and shout his name in dramatic fashion. The cat, of course, is hairless to avoid messing up his black turtleneck.

Whatever the case, I may say things that no longer apply to some future version or mention menus that no longer exist as such. Sorry. Blame Apple. Then buy my next edition.

What You Will Learn

This book is divided into three major parts and includes four appendixes on the book’s companion Web site.

Part I: The Basics: Getting Started with Xcode 4

In very short order, you’ll install Xcode and get down to business building a useless application. Nobody but perhaps your mother would buy it, but it very neatly demonstrates the Xcode 4 project workflow and how to find your way around a project.

Part II: Working with Cocoa Applications

Next, you’ll learn how to build and edit user interfaces, add resources, and customize the application. You’ll explore all major aspects of the Xcode user interface and its primary editors. You’ll learn to refactor code, to use the debugger and the Core Data modeler, and to archive builds for deployment (independently or via the App Store).

Part III: Going Beyond the Basics

Then you’ll dive a little deeper and explore Xcode’s build system (including the new schemes system). You’ll learn how to create and use libraries and frameworks and how to combine multiple projects into a single workspace. You’ll create and run unit tests and use custom scripts with the build process.

Finally, you’ll take a solid tour of Instruments (Apple’s profiling tool) and experience its uncanny ability to point out your mistakes and make you feel stupid. Thoroughly abashed, you’ll wrap up with an overview of Xcode’s integrated source code management support.

Appendixes

You’ll find four appendixes on the book’s companion Web site (http://xcodebook.com/extracontent). Appendix A helps you manage your iOS devices. Appendix B includes tables of gestures and keyboard shortcuts for frequently used tasks. Appendix C shows you how to manage Xcode documentation updates. Appendix D provides you with Apple and third-party resources for additional information.

Welcome to Xcode

Upstart newbies. Always strolling in and making short work of stuff that used to take you hours. In your day, you typed all your build commands and liked it. Uphill. Both ways. In the snow. Then again, why let those newbies outpace you? Xcode puts the same powerful tools you know (and some new ones you may not) in your hands. Despite its shiny, easy-to-use interface, a lot of power lurks just under the surface. Xcode 4 lets you write and manage your code, design and build user interfaces, analyze and debug your apps, and more. So what if it takes you less time?

Interface Builder

Build and edit rich user interfaces with Interface Builder. Drag and drop outlets and actions directly into your code using the Assistant editor.

Clang Static Analyzer

Find subtle errors in your programs with the Clang Static Analyzer. Follow the blue arrows through your code as the problem is broken down step by step.

Instruments

Trace and profile your code with Instruments. Follow your application’s activity through time to find and analyze performance problems and more.

Source Code Management

Manage your source code with the integrated source code management features. Branch, merge, pull, push, and resolve conflicts all from within Xcode.

Part I: The Basics: Getting Started with Xcode 4

1. Discovering Xcode Tools

Xcode 4 is the flagship application of Xcode Tools, Apple’s suite of developer tools. It is aimed squarely at developing, testing, and packaging Mac OS and iOS applications, utilities, and plug-ins written with the Cocoa frameworks in Objective-C, though it’s perfectly suited for C/C++ development.

In this chapter, you’ll learn how to download and install Xcode Tools. You’ll also take a brief tour of some of the powerful tools that accompany Xcode.

Downloading

The latest stable release of Xcode 4 is obtained through the Mac App Store. To download the installer, launch the App Store application from your Applications folder and search the store for Xcode. Click Install and log in if requested.

As with any application purchased through the App Store, the installer (called “Install Xcode”) will appear on your dock with a progress bar tattooed on its icon. Go get some coffee because the installer is several gigabytes in size.

Installing

Once the download is complete, just launch the installer by clicking it in the Dock. If the Dock shortcut has gone away, you can find the installer in your Applications folder (again, it’s called “Install Xcode”). Just follow the on-screen instructions. The installer is very basic as the options you might know of from previous versions have gone away. Xcode 4 overwrites any existing versions in your system’s /Developer folder. This is the default (and now, unchangeable) install location for the Xcode Tools suite. Once the installation is complete, you’ll have a very powerful software development suite at your fingertips. Just look in the /Developer/Applications folder of your system disk. Xcode and its friends live there.

Note

The file you downloaded contains the tools and relevant SDKs. It does not contain the documentation for those SDKs, however. When you launch Xcode, it will check for the latest version of this documentation and download it in the background. These files are large as well. The processor, disk, and network activity this causes can be alarming, given that Xcode seems to be peacefully awaiting orders. You can turn off this automatic updating in the Documentation panel of Xcode’s preferences.

Exploring

Now that you’ve installed Xcode Tools, you can find it on your system disk under the /Developer folder unless you’ve chosen to install elsewhere. You’ll find Xcode and a number of other applications in the /Developer/Applications folder. Although this book concentrates on the Xcode 4 application, there are other important tools with which you should become familiar.

Let’s explore some of the tools included in the suite.

The Big Tools

There are three important applications in which you’ll spend most of your time.

Xcode

The Xcode integrated development environment (IDE) is the star of the suite. With Xcode, you create and manage projects, write and debug your code, design your UI, build your data models, write and run unit tests, and build and package your apps and plug-ins. You’ll spend most of your development time in Xcode. Some of these tools can be launched automatically from within Xcode (Instruments and the iOS Simulator, for example). This will be covered in later chapters.

Instruments

Instruments is Apple’s profiling and analysis tool. We’ll briefly visit Instruments in Part III, but this application could easily justify a book of its own. It could be loosely described as a luxury wrapper around DTrace (a performance measuring tool), but that would be understating its power. We’ll explore its most common uses for application development, which are profiling and memory management debugging.

iOS Simulator

Not all iOS developers can afford every iOS device on the market. Debugging an application directly on the device has some limitations as well. The iOS Simulator (previously named iPhone Simulator) provides a solution to both of these problems. We’ll explore the iOS Simulator in Chapter 17.

Other Helpful Tools

The following are some additional tools you are likely to use in a typical Mac or iOS project. These tools are also installed with the Xcode Tools suite.

Help Indexer

Mac OS users expect applications to come with the customary built-in manual, called a Help Book. This is a simple collection of HTML documents accompanied by a special—and required—index file for the OS X Help Viewer. The Help Indexer application processes your Help Book files and builds this index for you.

Icon Composer

Mac OS and iOS applications use the .icns format. The Icon Composer application allows you to drop your appropriately sized artwork into the image wells and test your icon against various backdrops.

PackageMaker

PackageMaker is used to build Mac OS Installer packages. The Installer packages let you tell OS X where to install your application and other resources, as well as run various pre- and post-flight scripts (scripts that are run before and after the main installation) with administrative privileges if desired.

Quartz Composer

Quartz Composer lets you create stunning visualizations for screen savers, interactive menu screens à la Front Row and Cover Flow, and more. The compositions can be self-contained or accept input from your application to affect various properties. Even non-developers can enjoy Quartz Composer, because it does not require writing a single line of code.

Wrapping Up

Plenty of other helpful utilities (both GUI and command-line) exist in addition to those covered here. Consult the Xcode user guide (found under Xcode’s Help menu) for details.

Note

In the Cocoa developer community, you’ll hear people refer to Interface Builder as a separate application. Prior to Xcode 4, Interface Builder was indeed a separate application. It is now integrated into Xcode.

2. Starting a Project

Xcode comes with a number of template projects to make it easier for developers to get started. Beyond templates for Mac OS and iOS applications, there are templates for command-line tools, AppleScript applications, frameworks, bundles, plug-ins, Spotlight plug-ins, IOKit drivers, and more.

In this chapter, you’ll create a basic Cocoa application, which you’ll use throughout this book to explore Xcode.

Welcome to Xcode!

You can find Xcode in the /Developer/Applications folder (assuming you chose this default location when you installed Xcode Tools). When you launch the application, you’ll be presented with the Welcome to Xcode window, as shown in Figure 2.1.

Figure 2.1 The Welcome to Xcode window

You can use this welcome window to start a new project, check out an existing project from a source code repository (such as Subversion or Git), open the documentation viewer, or visit Apple’s developer site. You can also ask Xcode not to show you this window on startup again.

Creating a New Project

To create a new project, click the “Create a new Xcode project” option on the welcome screen. You can also choose File > New > New Project from the main menu at the top of the screen. You’ll be presented with a sheet from which you can choose a project template, as shown in Figure 2.2.

Figure 2.2 The New Project template sheet

Exploring the Templates

Let’s take a moment to look through the available project templates Xcode offers. The left panel separates the template categories by their types (such as Mac OS, iOS projects, and any third-party template types you may have installed). Beyond the obvious platform categorization, the templates are further subdivided by the type of product (application, plug-in, framework, and so on) you’ll be building.

In most cases, selecting an individual template yields an Options bar, allowing you to choose common subtypes (such as document-based versus non-document-based, static library versus dynamic, and so on) and optional subcomponents (such as Spotlight importers or Cocoa views for plug-ins).

Most projects will be Mac OS or iOS applications.

Creating a Test Project

Let’s create a test project with which to explore. To do this, choose the Application category under the Mac OS X type and then click the Cocoa Application template. Click Next to continue. Xcode will respond by asking you for some additional information to customize your project, as shown in Figure 2.3.

Figure 2.3 The New Project options sheet

The Product Name field is where you would put your application’s name in most cases. Let’s call our product TestApp in the interest of clarity. This not only determines the name of your project file and its enclosing folder but the name of your built product (your application, plug-in, library, and so on).

The Company Identifier field is just as important as your product name. This identifier is used to create your bundle identifier. The bundle identifier, in turn, can be used as a unique identifier for your application’s preferences file, its document files, its associated Spotlight importer, and many other things. Apple encourages developers to use a reverse-ordered ICANN domain name. Assuming your domain is yourcompany.com, your company identifier would be com.yourcompany. Xcode fills in your app’s name (substituting illegal characters as needed) to form your project’s bundle identifier (displayed below the Company Identifier field).

Although only the Product Name field is required, you should always provide a suitable company identifier. The identifier doesn’t necessarily have to correspond to an existing domain, but it should be unique.

The App Store Category pop-up lets you select a general category under which your application would fall if you choose to deploy to the Mac App Store. Since you won’t be submitting TestApp to the App Store, you can leave that set to None, its default.

The next three options (Create Document-Based Application, Document Class, and Document Extension) let you use a document-based application template. A plain Cocoa application (Create Document-Based Application deselected) is intended for applications that do not work with individual files as documents; a document-based Cocoa application uses the Cocoa document architecture to open and manipulate document files. For simplicity, TestApp will not be document-based, so leave that option deselected.

The Use Core Data option adds support for Cocoa’s object graph management and persistence framework, called Core Data. Select this option so you can explore the Data Model Editor in Chapter 10.

The Include Unit Tests option will add support for unit tests to your project. Select this option to include unit tests, which you’ll explore in Chapter 18.

The Include Spotlight Importer option adds a Spotlight importer plug-in as a dependent build target to your project’s application target. When you add the necessary code, Spotlight—the Mac OS X search facility—will use the importer to add the data you provide to its search index automatically. Leave this deselected, and leave Spotlight importer plug-in programming for another book.

Different project and option choices can cause different fields to appear when creating a new project. Consult the Xcode documentation (covered in Chapter 4) for further details about these options.

Once you’ve filled in the requested information, click Next to continue. Xcode will present a Save As dialog box. Select the option to create a local Git repository for this project. You’ll explore Xcode’s Git (and Subversion) support in Chapter 21. Choose a convenient location (such as your desktop), and click Save.

You should now have a basic Xcode project ready to go, as shown in Figure 2.4.

Figure 2.4 A newly created Cocoa application project window

Project Modernization

For those who weren’t born (as Mac or iOS developers) yesterday, Xcode introduces the concept of “project modernization.” As much fun as it is to create brand new projects full of new possibilities, many of us have existing projects that were created in earlier versions of Xcode.

These preexisting projects often contain settings that are not compatible with modern versions of Xcode. Fortunately, Xcode not only finds these problems but offers to fix them as well. It even lets you pick the fixes to apply, since its idea of “fixing” may not necessarily agree with yours.

Modernizing a Project

When opening projects that were created with previous versions of Xcode, you might notice some warnings appear in the Issue navigator (Figure 2.5), informing you of issues that need cleaning up.

Figure 2.5 Warnings of outdated project settings

Notes

Project modernization was introduced in Xcode version 4.1 and is not available in 4.0.

The Issue navigator is explored in Chapter 3.

Selecting the issue (or choosing Editor > Check for Outdated Settings from the main menu) will display a Build Settings sheet (Figure 2.6) summarizing the changes that Xcode thinks you should make. Deselect the check box to the left of any settings you think Xcode ought to ignore.

Figure 2.6 The Build Settings sheet prompting changes

To perform the selected changes, click Perform Changes. To cancel without performing any changes, click Cancel. To ignore the selected issues, select Don’t Perform Changes. The separate Perform Changes and Don’t Perform Changes buttons let you accept some updates and then come back and instruct Xcode to ignore others.

Remember that you can always check for outdated settings at any time by choosing Editor > Check for Outdated Settings from the main menu.

Building and Running an Application

At this point you have a fully functional—if uninteresting—Cocoa application project that is ready to be built and run. To see your application, click the Run button in the project window toolbar (or choose Product > Run “TestApp” from the main menu). Xcode will build the project from scratch (because this is the first time it’s been built) and then launch it. After a short time, you’ll see your application’s empty window (Figure 2.7). It’s not particularly exciting at the moment, but it is a functioning application at this point, even without customization.

Figure 2.7 The new Cocoa application

The Run button doesn’t just trigger a build and run. You can click and hold the button to reveal a menu of other actions similar to those found under the Product menu. These actions include Test, Profile, and Analyze. Each of these will build the project automatically if it needs building before performing the requested action. These other actions are covered in later chapters.

Wrapping Up

TestApp isn’t very interesting in its current state, but it is a fully functional application with a main menu, a window, and even an About panel. You now know how to create, build, and run a basic template application. In the next chapter, you’ll explore Xcode’s user interface using the project you just created.

3. Navigating a Project

In the previous chapter, you created a Cocoa application project called TestApp. In this chapter, you’ll explore the anatomy of this project and familiarize yourself with Xcode’s user interface.

Earlier versions of Xcode allowed users to select a multiple-window interface, but the default was single-window (where most views related to the open project were contained within the same window). Single-window mode wasn’t quite single-window mode, however; a number of auxiliary windows could appear. In Xcode 4, Apple has taken the all-in-one-window design approach much further.

If it’s not open already, open the TestApp project you created in Chapter 2.

The Workspace Window

An Xcode project consists of a collection of source files (such as Objective-C files, Interface Builder nibs, and Core Data managed object models), resources (such as images and rich text files), and the Xcode project file, in which the various settings and build rules are maintained. It is helpful to think of an Xcode project as a collection of sources and resources with a project file to bind them together. Xcode 4 goes a step further and allows you to combine multiple related projects into a single workspace (see Chapter 16). The main window for a given project or workspace is called the workspace window (Figure 3.1).

Figure 3.1 The workspace window

The workspace window is divided into multiple areas, which you’ll examine in detail in this chapter. Almost everything related to your workspace is contained within these areas, whose responsibilities include organization, navigation, editing, inspection, and debugging.

The Navigator Area

The Navigator area consists of a complex set of panes. Found along the left edge of the workspace window, it is the primary interface for organizing and exploring the files, symbols, build issues, run logs, breakpoints, threads and stacks, and search results for the project.

The button bar along the top edge of the Navigator area switches between the various navigation panes. You can toggle the Navigator area on and off using the View button bar in the toolbar near the right side of the workspace window.

Project Navigator

You can use the Project navigator (Figure 3.2) to find your way around the source and resource files of your project (or projects in the case of a multi-project workspace). Clicking any of the resources (except groups, which are merely logical containers within the project) causes Xcode to navigate to that resource, opening it in an appropriate editor in the Editor area immediately to the right of the Navigator area. You’ll explore various editors in Part II.

Figure 3.2 The Project navigator

In addition, this area allows you to organize your project using groups (represented by yellow folders). You can create nested groups and move resources around just as you would with a file system. Groups can also represent real subfolders in your project folder. To create a group, choose File > New > New Group from the main menu.

The Project navigator works much the same way as the Mac OS X Finder in List view mode. You can add to, delete from, and reorganize resources in your project. In Chapter 6, you’ll explore adding files and resources to, and removing them from, a project. Later, in Chapter 21, you’ll explore Xcode’s source code management capabilities.

Symbol Navigator

The Symbol navigator (Figure 3.3) gives you a somewhat different look at your project. Depending upon the filters you select in the filter bar (just above the list of symbols), you can jump to symbols defined within your project or within the Cocoa frameworks.

Figure 3.3 The Symbol navigator

For example, rather than selecting a file from the Project navigator and then looking for your method or instance variable in the editor, you can type the symbol name in the search bar at the bottom of the Symbol navigator and then click the symbol in the list to jump directly to that symbol in your source.

The bar along the bottom edge of the Symbol navigator offers several list-filtering options. The first filter button (starting from the left) lets you choose whether the list shows all symbol types (whether symbols exist for those types or not) as opposed to only showing types for which symbols exist. The second button specifies whether all symbols are shown or only those belonging to the workspace. The third button specifies whether members of a given symbol are shown (for example, the methods of a class). The search field further filters the list by a given search term.

Search Navigator

The Search navigator (Figure 3.4) allows you to search your entire project. The search field at the top of the pane searches the project, while the one at the bottom further filters the search results themselves. The results are arranged first by filename and then by matches within the file. Clicking a result opens the file and selects the match in the editor. Searching and replacing will be covered in more detail in Chapter 8.

Figure 3.4 The Search navigator

Issue Navigator

Upon building your project, the Issue navigator (Figure 3.5) lists any issues it finds. In Xcode, an issue can be an error or a warning. Like the Search navigator, the Issue navigator can organize the issues by the file in which the issues appear. Additionally, Xcode can show you issues organized by type. Clicking to select an issue will cause Xcode to navigate to the issue in the Editor area. Figure 3.5 shows Xcode reporting that the TestAppAppDelegate.m file has, like most people, some issues.

Figure 3.5 The Issue navigator

At the top of the Issue navigator are buttons that let you choose to show issues by the file in which they exist or by their type. The controls at the bottom of the navigator let you filter the list. The first button (starting from the left) lets you choose to show issues only from the last build. The second button lets you choose to show only errors (as opposed to warnings or static analyzer results). The search field lets you filter the list by a given search term.

Note

You can also jump from issue to issue using the arrows just above the scroll bar in the upper-right corner of the Editor area.

Debug Navigator

While execution is paused in an active debugging session (because of encountering a breakpoint or a crashed thread), the Debug navigator (Figure 3.6) allows you to navigate the threads and stacks of your application. You can organize the information by thread or by queue using the selector bar at the top of the navigator.

Figure 3.6 The Debug navigator

The controls along the bottom of the navigator control how much information the navigator displays. The button, when activated, causes the navigator to show only crashed threads or threads for which there are debugging symbols available (typically your own code). The slider controls the amount of stack information that is displayed. Sliding all the way to the right shows the full stack, while sliding to the left shows only the top frame.

The icons to the left of each stack frame indicate to whose code the frame belongs. For example, frames with a blue-and-white icon depicting a person’s head belong to your code, whereas purple-and-white icons depicting a mug belong to the Cocoa frameworks.

Breakpoint Navigator

All the breakpoints associated with your project are collected in the Breakpoint navigator (Figure 3.7). When you set breakpoints in the Source Editor (see Chapter 9), they appear in the Breakpoint navigator list, grouped by file.

Figure 3.7 The Breakpoint navigator

Clicking a breakpoint’s name navigates to its location in the editor. Clicking the blue breakpoint marker toggles the breakpoint on and off. Right-clicking a breakpoint and selecting Edit Breakpoint from the context menu pops up a detailed view that lets you set additional breakpoint properties (also covered in Chapter 9).

The controls along the bottom of the navigator allow you to add and remove breakpoints, as well as further filter the list. The Add (+) button pops up a menu when clicked, offering to add one of two non-workspace-specific breakpoints (to break on exceptions or at a named symbol you supply manually). The Remove (-) button removes any selected breakpoints. The next button to the right of the Remove button can filter the list to show only enabled breakpoints, while the search field can filter the breakpoints by a given search term.

Log Navigator

The Log navigator (Figure 3.8) collects all the various logs (including build, analyze, test, and debug). Clicking a log in the navigator displays it in the Editor area.

Figure 3.8 The Log navigator

When selecting a debug log (also known as a run log), the contents of the Debug area’s console are displayed as plain text for you to browse. When selecting a build log, the Editor area displays a set of controls along the top edge, which let you filter the types of messages you want to see (including all messages, issues only, or errors only). Double-clicking a message navigates to the issue or file. Clicking the list icon at the right edge of a message will expand it to display its associated command and output.

The controls along the bottom of the navigator let you filter the list. The button lets you choose to show only the most recent logs of a given type. The search field lets you filter the list with a given search term.

The Jump Bar

The Jump Bar, found above the Editor area, shows you where you are in the organizational structure in your project (Figure 3.9). It additionally serves as a more compact version of the Project navigator. It is accessible even when the Navigator area is hidden and can be used to navigate your project by clicking any one of the segments and choosing a different path from the pop-up menu.

Figure 3.9 The Jump Bar, TestAppAppDelegate.m selected

The Jump Bar goes beyond the group and file level. It allows you to drill further down into the contents of the file. In the case of a source file, you can further select methods to jump around the file’s contents by clicking any segment after the file’s segment (Figure 3.10). With Interface Builder files, you can navigate the window and view hierarchy of your user interface.

Figure 3.10 The Jump Bar pop-up menu showing members of TestAppAppDelegate.m

The Jump Bar also appears in Assistant windows (covered later in this chapter) and can be used to select various behaviors in addition to individual files.

The Editor Area

The Editor area (Figure 3.11) dynamically switches between editors appropriate to the currently selected file (either through the Project navigator or through the Jump Bar). This means that, for source code files, you’ll see the Source Editor; for Interface Builder files you’ll see the Interface Editor, and so on. Among the other available editor types are the Data Model Editor, the Project Editor, the Version Editor, the Rich Text Editor, and more.

Figure 3.11 The Editor area showing the Source Editor

Although it is called the “Editor” area, this is something of a misnomer where some items are concerned. Some items are not editable, which means the Editor area serves more as a “Viewer” area. For example, the area might display an image resource (such as the application icon) when selected; however, there is currently no image-editing facility in Xcode 4, so you can only view the image.

The other major editors are covered in their related chapters throughout the book.

The Assistant

The Editor area conceals a deceptively powerful feature called the Assistant (Figure 3.12). The Assistant acts as a “split pane” editor with some added intelligence, depending on the behavioral mode you use. You can toggle the Assistant using the middle button of the Editor button bar that sits toward the right side of the toolbar area.

Figure 3.12 The Assistant

The Assistant is a very flexible contextual tool that helps you perform common tasks ancillary to the current editing context. For example, in the Data Model Editor, if you select a Core Data entity with a corresponding managed object subclass, the Assistant can display that subclass for reference or editing. If you select a xib to edit in Interface Builder, the Assistant can show the source file corresponding to the xib’s File’s Owner class (see Chapter 5) or can show the class of the object selected in the Dock to facilitate establishing action and outlet connections.

Opening Files in the Assistant

When you turn on the Assistant using the toolbar, it displays the selected source file’s counterpart in a single pane in Manual behavior mode (where you choose what is displayed in the Assistant pane yourself using its Jump Bar). You can use the Assistant’s Jump Bar to view or edit any file in your workspace. There will always be at least one Assistant pane visible while the Assistant is active.

Adding and Removing Assistant Panes

You can add or remove additional Assistant windows using the Add (+) and Remove (×) buttons in the upper-right corner of the existing Assistant pane (at the right edge of the panel’s Jump Bar).

To add a new pane, click the Add button on any existing pane. The new pane will have its own Jump Bar and will be added after the pane whose Add button you clicked. That is, if you clicked the Add button of the last pane, the new pane will appear after the last one; if you clicked Add for the first of several panes, the new pane will appear after the first one. To remove a pane, click the Remove button on the desired pane.

You can also open assistant panes using keyboard shortcuts. By default, holding down the Option key and clicking an item in the Project navigator will open the item in the Assistant when only one pane is present. If more than one pane is present or you perform an Option-Shift-click, Xcode asks you where you’d like to view the file with an intuitive destination chooser (Figure 3.13).

Figure 3.13 The destination chooser

Changing Layout Behavior

In the previous section, the phrase “after the pane whose Add button you clicked” is intentionally vague. This is because you can customize the Assistant’s layout behavior. To do so, choose View > Assistant Layout to see and select available layout modes (Figure 3.14).

Figure 3.14 The Assistant

Assistant Behavior Modes

You can change the Assistant’s behavior by clicking the segment of the Jump Bar immediately to the right of the navigation buttons. A menu appears (Figure 3.15) listing the available behaviors.

Figure 3.15 The Assistant’s behavior modes in the Jump Bar

When in Manual mode, the Assistant behaves like a glorified—if neatly arranged—split pane editor. Its real power is in its automatic behavioral modes. When you choose any behavior other than Manual, the Assistant becomes contextually aware. Depending on the chosen behavior, the Assistant shows files related to the file (or a subselection within it) currently displayed in the main editor (the selection in the Project navigator).

The power of this feature becomes evident when you’re faced with a scenario where it’s necessary to edit a class’s implementation, header, and associated protocol, or when you select an object in Interface Builder’s Dock and need to add a new outlet or action while connecting it to the interface at the same time.

When there is more than one related file that the Assistant can display, additional controls appear to the left of the Add and Remove buttons. The controls include standard back and forward navigation buttons with the count of available associated files between them. These controls are not visible if there are fewer than two available associated files. The count is shown in the Jump Bar when selecting the behavior mode.

The term selection in this context means “the project member that is currently selected in the Project Navigator, shown in the main editor.”

The available modes are explored in their related chapters.

The Utility Area

The Utility area (Figure 3.16) provides supplementary information and controls for the current editor. Essentially anything you would expect to be in a floating palette for the editor can be found in the Utility area. To toggle the Utility area, click the right button in the View button bar in the toolbar.

Figure 3.16 The Utility area

Like the Editor area and its Assistant, the Utility area is highly contextual. Additional buttons representing various inspectors appear along the top, depending on what you’re editing. For example, while editing a xib, buttons will appear for the Attributes inspector, Size inspector, Connection inspector, and more. With a data model selected, the Data Model inspector button appears. In most situations, two inspectors remain omnipresent: the File inspector and the Quick Help inspector.

The bottom panel contains the File Template library, the Code Snippet library (Chapter 7), the Object library (Chapter 5), and the Media library, which contains available template media (such as standard OS icons) as well as any media included in your workspace.

The Debug Area

The Debug area (Figure 3.17) appears by default when you run your application. You can also toggle it using the middle button of the View button bar in the toolbar.

Figure 3.17 The Debug area

The Debug area is the primary interface for the debugger. It includes a control bar, a console, and a view for inspecting in-scope variables when paused. The Debug area and its controls are covered in more detail in Chapter 9.

Customizing Debugger Behavior

You can customize the Debug area’s behavior in Xcode’s preferences, on the Behaviors tab. There you can choose what actions the debugger takes when certain events occur (including run, pause, unexpected quits, successful quits, and so on).

For example, you could choose to show the Debug navigator when debugging starts or pauses. You could also choose to show the Project navigator and close the Debug area when the application quits normally. If the application quits unexpectedly, you could choose to show the Log navigator, navigate to the most recent run log, and play an alert sound to draw attention to the problem. Custom behaviors are covered in more detail in Chapter 16.

The Activity Viewer

The Activity Viewer (Figure 3.18) isn’t overly complicated and offers little interaction, but its prominent (and immutable) placement in the center of the toolbar makes it worth mentioning. It provides you with visual feedback of all the activities Xcode is performing on the workspace.

Figure 3.18 The Activity Viewer

When more than one activity is underway, the Activity Viewer alternates between them like an ad banner and displays the number of concurrent tasks on its left side. You can click the number to display a pop-up, which lists all the current activities and their progress individually.

In previous versions of Xcode, the right side of each window’s bottom edge had its own status field showing the same information (mostly related to build and debug status). Xcode 4’s all-in-one approach makes it easier to have a single place to see the current status of any actions Xcode is performing.

If there are any issues (errors, warnings, and so on), the number of issues will be displayed in the Activity Viewer as well. Clicking the issue counter will switch to the Issue navigator so you can find and review the issues.

The Tabs

Another new feature in Xcode 4 is the introduction of tabs. Similar to the Safari browser, you can create tabs within the same workspace window for various project members in the workspace. For example, Figure 3.19 shows a source file open in one tab and a user interface file open (in the Interface Editor) in another.

Figure 3.19 Two tabs showing TestAppAppDelegate.m and MainMenu.xib

To create a new tab, choose File > New > New Tab from the main menu. Click any tab to switch to it and navigate to the project member you’d like the tab to represent. You can reorder tabs by dragging and dropping. To rename a tab, double-click the title, type a new name, and then press Return. To close a tab, click the X icon that appears when you mouse over the tab or choose File > Close Tab from the main menu.

Tip

Keyboard shortcuts are handy ways to speed up tab use. Pressing Command+T creates a new tab, while Command+W closes the currently selected tab. Press Command+} and Command+{ to switch between the next and previous tabs.

The Organizer Window

The Organizer window (Figure 3.20) stands apart from workspace windows as a collection point for project and device management, including repositories, archives, snapshots, and more. The various aspects of the Organizer will be explored throughout the book. To open the Organizer, choose Window > Organizer from the main menu.

Figure 3.20 The Organizer window

Wrapping Up

This chapter gave you a taste of the most obvious user interface elements in the workspace window. You’ll explore more of the user interface in later chapters, but there’s far more to Xcode than can fit in a book this size. In the next chapter, you’ll learn how to use Xcode’s built-in documentation browser and help facilities to get help with your coding and with using Xcode itself.

4. Getting Help

You can get help in Xcode 4 for the IDE as well as the Cocoa frameworks in a number of ways. In this chapter, you’ll learn how to find the answers you need.

The Help Menu

You’ll start with the most obvious place first. If you’re familiar with Mac OS X, you should be familiar with the Help menu. Starting with Mac OS X 10.5, the Help menu (Figure 4.1) features a standard Search field, which shows you not only help topics but main menu items that match your search term.

Figure 4.1 The Xcode Help menu

Beneath the Search field are menu choices to open some of the more important help libraries with which you should familiarize yourself. A link to Xcode’s release notes is also listed there. Most of these will open the Organizer window, which you saw in Chapter 3.

Xcode Help

The Xcode User Guide menu item opens a splash page containing video and links about how to find help in Xcode.

Xcode User Guide

The Xcode Help menu item opens the user manual for Xcode. Inside you’ll find in-depth explanations and how-to instructions for all Xcode features.

Documentation and API Reference

The Documentation and API Reference menu item simply opens the Organizer window in Documentation mode so you can browse or search the installed documentation libraries. It will remain on the currently selected page without navigating away and simply show the window.

The Rest

The remaining menu items trigger quick help for the currently selected code in the active workspace window, and open the Organizer window in Documentation mode with the text input cursor in the search bar, respectively.

The Organizer’s Documentation Tab

The Documentation section of the Organizer is Xcode’s main viewer for all SDK and developer tools documentation. Open the Organizer by choosing Window > Organizer from the main menu, and then choose the Documentation tab in the toolbar (Figure 4.2).

Figure 4.2 The Organizer’s Documentation tab

The Organizer responds by showing you a pane on the left (similar to Xcode’s Navigator area) and a main viewing area. Along the top of the main viewing area, you’ll see a Jump Bar similar to the one you explored in Chapter 3. This Jump Bar, however, allows you to navigate the documentation as opposed to your project. The Organizer’s navigation area has three modes: Explore, Search, and Bookmarks. The button bar at the top of the pane switches between the modes.

Explore

In Explore mode, an outline of each of the documentation sets and their sections displays. You can drill down by topic through the guides and API reference documents.

Search

In Search mode, a search field appears, allowing you to search all installed documentation sets. Clicking the magnifying glass icon, then choosing Show Find Options from the context menu reveals a set of filtering options (Figure 4.3) that let you ignore unwanted libraries and more. The results are grouped by type (such as Reference, System Guides, Sample Code, and so on).

Figure 4.3 The Organizer’s search options panel

Bookmarks

In Bookmarks mode, you can jump directly to documentation pages you’ve bookmarked. You can set bookmarks by choosing Editor > Bookmarks from the main menu or by right-clicking anywhere in the page and choosing Add Bookmark for Current Page from the context menu. To delete a bookmark, select it and press the Delete key.

The Source Editor

Although you’ll explore the depths of the Source Editor in Part II, there are a couple of useful ways to find contextual help from within your code.

Quick Help in the Utility Area

As you saw in Chapter 3, Xcode’s Utility area gives you access to various properties, code snippets, user interface elements for Interface Builder, and Quick Help. The Quick Help utility continuously updates its content depending on what you’ve selected in the Source Editor.

To get a feel for this utility, make sure your TestApp project is open and then select the TestAppAppDelegate.m source file from the Classes group in the Project navigator. Open the Utility area, and select the Quick Help utility. In the Source Editor, click window in the @synthesize window; statement. Quick Help responds by showing you the name of the symbol (window) and the header file in which it is declared (the TestApp project’s TestAppAppDelegate.h file).

For a more interesting example, scroll down a bit until you find the – (NSString *) applicationSupportDirectory method, and click the NSString symbol. Quick Help responds by showing a much more detailed description of the NSString class (Figure 4.4), which is part of the Cocoa frameworks and is documented by the built-in document libraries. Any text highlighted in blue is a hyperlink to the corresponding documentation. Clicking a Quick Help hyperlink opens the linked information in the Documentation section of the Organizer.

Figure 4.4 The Quick Help utility

Search Documentation for Selected Text

Another handy way to find the documentation for symbols such as NSString is to select the symbol in the Source Editor and then choose Help > Search Documentation for Selected Text from the main menu. As with hyperlinks in the Quick Help pane, choosing this option will open any corresponding documentation it finds in the Documentation section of the Organizer.

Tip

It’s not necessary to open the Utility pane to see Quick Help content. The same information will appear in a pop-up bubble by holding down the Option key and clicking the symbol you want to locate.

Community Help and Feedback

There are a number of community Web sites for finding more help than is available in the documentation, including Apple’s own developer forums. See Appendix D for more information.

Apple’s Developer Forums

Apple’s developer forums are accessible to ADC members (http://devforums.apple.com). There you can receive help and advice from the Cocoa developer community as well as the occasional Apple engineer. Because this is a public forum, it’s important to keep in mind that most people there are developers like you and are volunteering their time. Take extra care to search for similar questions before posting, ask detailed and clearly written questions, and be civil. As with any community, anything less than civility and courtesy will make the community less likely to help you in the future.

Documentation Errors

If there is anything about Apple’s documentation that is unclear, incorrect, or lacking in any way in Xcode, you are encouraged to submit feedback to Apple. At the bottom of every page of the documentation are hyperlinks that allow you to submit feedback—good, sort-of-good, and bad—to the Apple documentation team. Constructive, detailed feedback helps Apple provide better documentation, and improvements are released often.

Wrapping Up

Xcode offers many ways to find help. Most of those ways point to the same documentation set, but even the documentation pages help you submit suggestions for improvement. In addition, you will find a number of community Web sites (one of which is Apple-hosted) and blogs a quick Google search away. Even if the built-in documentation doesn’t help, the chances are quite good you’ll find your answer on the World Wide Web.

You should now have your bearings in the Xcode IDE. In Part II, you’ll use Xcode to expand on the TestApp project by adding some user interface elements, writing some code, defining a data model, and more. From there, you’ll delve into the debugger and building the application for deployment.

Part II: Working with Cocoa Applications

5. Creating User Interfaces

In previous versions of Xcode Tools, Interface Builder was a separate application. In this chapter, you’ll learn how to use Xcode 4’s newly integrated user interface tools.

The contents of this chapter require some familiarity with Cocoa development, which is beyond the scope of this book. Basic background is given where necessary; however, you are encouraged to read the Cocoa Fundamentals Guide provided by Apple to understand the design concepts behind user interfaces in Cocoa applications.

Understanding Nibs

Cocoa applications load their graphic user interfaces from Interface Builder files (called nibs, or xibs if using XML format, which is the new default). The files are essentially “freeze-dried” object graphs representing the user interface you’ve constructed and the connections between the UI elements and one or more controller objects. Several key concepts are important to grasp when designing and working with a Mac OS or iOS application.

File’s Owner and Controller Objects

A nib and its content always have an owner. Whether it’s an instance of NSWindowController, NSViewController, NSDocument, or any other object, the owner serves as the top-level object that serves as the primary point to which to wire the user interface elements found in the nib.

Generally speaking, File’s Owner is intended to be a controller object (or, in the case of NSDocument, a model-controller). There can be and often are multiple controller objects within a single nib, any of which can provide outlets or actions.

Actions and Outlets

Two types of connections exist between your code and a nib’s contents: actions and outlets. Both types of connection are established by drag and drop.

An action is a method that is called by a control. That is, depending on the type of control, some form of user input has triggered the control to perform its function. In the case of a button, a mouse click would trigger the button’s action. Any given control’s action requires two elements: the action itself and a target. Actions are defined in source code as follows:

- (IBAction)performSomeAction:(id)sender;
- (IBAction)performSomeOtherAction:(id)sender;

Note

The file extension .nib stands for NextStep Interface Builder, which is a holdover from the original creators of these tools—Next, Inc. The newer file extension .xib stands for XML Interface Builder.

An outlet is an instance variable of an object (typically a controller or view object) that serves as a pointer to an element in a nib. Outlets are used to communicate with these objects. An example would be an outlet named tableView that points to an NSTableView instance that exists within a nib. The outlet could be used to ask the table view to refresh after some change to its underlying contents. Outlets are defined in source code as instance variables of a controller as follows:

IBOutlet NSTextField * titleField;
IBOutlet NSTableView * userListTable;

Compartmentalization

It’s common for an application to have multiple xib files that contain portions of the UI. In all but the simplest applications, there are usually some parts of the application that the user won’t access in every session, so it’s not necessary to load every part of the UI every time the application is executed. Loading only those portions of the UI that are needed can make the application more responsive and can give it a smaller memory footprint.

An example of this would be the preferences window of a Mac OS application or the user account view of an iOS application. These are user interface elements that should be kept in their own separate nibs and their associated controllers only created as needed.

The first advantage of this approach is performance. Your application will save memory by loading only the parts of the interface the user needs when they need it, which is a necessity on an iOS device. Since your application is creating controllers and their associated UI on demand, it takes less time to launch the application and reach a ready state for the user.

The second advantage is maintainability for the developer. By separating the user interface into distinct areas of responsibility (the preferences, the user login window, the export sheet, the map view), your application’s architecture is clearer and more easily managed and navigable.

Note

The details of the target/action mechanism and its various forms are beyond the scope of this book. Consult the Cocoa Fundamentals Guide in Apple’s Cocoa documentation (found in Xcode’s documentation browser or on the ADC Web site) for more information.

Getting Familiar with Interface Builder

The Interface Builder tools in Xcode 4 consist of the Editor, the Utility area (which includes a library of user interface elements and inspectors with which to configure them), and the Assistant for defining actions and outlets. Figure 5.1 shows a project nib ready to edit in the Interface Builder Editor. The Assistant, whose role in the Interface Builder Editor we’ll explore later in this chapter, is also shown in Figure 5.1.

Figure 5.1 Interface Builder showing a nib

The Editor Area

The Editor area (Figure 5.2) is where you construct the interface. This involves dragging interface elements from the Utility area’s object library into the canvas (the grid area) of the Editor and sizing and positioning them as needed. You can also create interface elements and controller objects by dragging them into the Dock, immediately to the left of the canvas.

Figure 5.2 The Interface Builder Editor area

The dock bar along the left side of the Editor (to the left of the grid) in Figure 5.2 is expanded to show more detail about the objects contained in the xib. Use the button at the bottom of the dock to expand or collapse the dock.

Only user interface elements (such as buttons and windows) can be dragged into the canvas. Instances of controllers aren’t part of the user interface but are created or represented in the nib to serve as a connection point between the UI and your code; therefore, they exist only in the Dock.

You can make connections to outlets by holding down the Control key and dragging from the controller in which the outlet is defined to the desired interface element. The controller could be File’s Owner (the controller to which the contents of the nib belong) or some other controller object that you’ve instantiated in your nib.

You can make connections to actions by holding down the Control key and dragging from the interface element to the controller that defines the desired action. For example, a button could be connected to a Create User action. More than one user interface element (such as a menu item) can be connected to a given action. The sender of the action is always passed along to the action, allowing you to respond differently depending on the sender or to query the sender for its state, such as whether a check box is selected or deselected.

Right-clicking an object in the Editor displays a semitransparent window that contains a list of the object’s outlets, the outlets of other objects that reference it, and actions the object can receive (Figure 5.3). Connections can be formed from this window by dragging a connection from the circle that is to the right of a given outlet or action to the target. To disconnect an outlet or action, click the X in the middle of the connection.

Figure 5.3 The connections window

The Jump Bar follows the same hierarchy as the windows and views in the nib and represents the currently selected object. For example, the selected object could be a button within a tab view within a window within the nib.

The Utility Area

When a nib is selected in the navigator, the Utility area (Figure 5.4) adds additional inspectors to the File and Quick Help panes, such as the control’s style, auto-sizing settings, and animation settings. Select any element or controller object in the canvas or the Dock to view or adjust its properties using the inspectors.

Figure 5.4 The Utility area showing available Interface Builder inspectors

Connections can also be formed with the Utility area, using the Connections inspector (Figure 5.5). This inspector is similar to the window that appears when right-clicking an object in the Editor, and it behaves in the same way.

Figure 5.5 The Connections inspector

Below the inspectors is the Libraries pane mentioned in Chapter 3. The Object library (Figure 5.6) contains a list of standard Cocoa objects as well as objects belonging to other frameworks and code libraries (such as QTKit or WebKit).

Figure 5.6 The Interface Builder Object library

The pop-up at the top filters the list by library while the search field at the bottom filters by search term. Hovering the mouse pointer over an object provides a description of the object if one exists. Drag an object from the library to the canvas or the Dock to add it to the nib (or to a specific view or window). You can also double-click an object to add it.

The Assistant

As you learned in Chapter 3, the Assistant acts as a secondary editor that can display “counterparts” to the selected project member. In the case of a nib, the counterpart is the interface (usually in a separate header file) of the class represented by the File’s Owner placeholder or that of a selected controller object.

Using the Assistant with Interface Builder goes a step beyond simply allowing you to add outlets and actions by typing them yourself. You can add actions and outlets by dragging a connection from a control directly into class interface source code in the Assistant area. Xcode responds by inserting the appropriate source code for the action or outlet.

Available Assistant Behaviors

Automatic behavior shows the files Xcode considers to be the best choice for the selected item or view in the xib.

Top Level Objects behavior shows the objects at the “top” of the xib’s object hierarchy. This can include the windows and views as well as any instantiated objects (such as custom classes and ready-made object controllers).

Sent Actions behavior shows any files containing actions called by the selected item.

Outlets and Referencing Outlets behaviors show any files containing outlets for the selected item or referenced by its outlets.

Class behavior shows any file containing the class of the selected item.

Adding User Interface Elements

Now that you’re familiar with Interface Builder, you’re ready to add some actions and outlets to TestApp. You’ll start by adding a button that displays the traditional “Hello World” in a dialog box. You’ll then add a text field with corresponding outlet in which to display the greeting.

To prepare, locate and select the MainMenu.nib file in the Project navigator. Click the window icon in the Dock to open the application’s main window in the canvas. Click the Assistant button so the Assistant area is visible, and make sure the Assistant is showing the TestAppAppDelegate.h file (the interface for the class represented by the File’s Owner placeholder of this nib). The project window should look similar to Figure 5.1.

Adding an Action Button

To add the Hello World action, you’ll need a button. Find the Push Button control in the Object library, and drag it into the window. Double-click the button, set its title to Say Hello, and then press Return. Control-drag a connection from the button to the source code in the Assistant. For best results, place the action after the – (IBAction)saveAction:sender; line and before the @end directive, as in Figure 5.7.

Figure 5.7 Dragging a connection into the Assistant

A pop-up will appear (Figure 5.8). Make sure the Action connection type is selected, and then type sayHello in the Name field. The method name is actually sayHello: (with a colon), but Xcode will add this for you automatically. Press Return or click Connect to add the action.

Figure 5.8 The connection creator pop-up window

You’ll need to add some code to make the action do something interesting. Navigate to the TestAppAppDelegate.m file (the implementation file for the TestAppAppDelegate class), and scroll down to find the - sayHello: method. Edit it to look like the following:

- (IBAction)sayHello:(id)sender {
  [[NSAlert alertWithMessageText:@"Important Message"
                   defaultButton:@"Hello Yourself"
                 alternateButton:nil
                     otherButton:nil
       informativeTextWithFormat:@"Hello World"] runModal];
}

Click the Run button to build and run the application. Give your Say Hello button a test click to make sure it’s working. You should see something similar to Figure 5.9. When you’re satisfied, quit the application and navigate back to the MainMenu.nib file.

Figure 5.9 TestApp displaying its Hello World dialog box

Adding a Text Field

Perhaps you believe modal dialog boxes are overused, so you’ll want to put that text into a text field in the application’s window. Find the Text Field control in the Object library, and drag it into your window. To communicate with the text field and set its string value to Hello World, you’ll need to create an outlet for it.

To add the outlet, drag a connection from the text field to the source code in the Assistant. This time, place the connection within the curly braces (because outlets are instance variables of a class). Choose the Outlet connection type, name it textField, and then press Return to finish adding the outlet.

Now that your code has a reference to the text field, you can change the action to display the message there rather than in a modal dialog box. Navigate back to the –sayHello: action in the TestAppAppDelegate.m file, and change it to look like the following:

- (IBAction)sayHello:(id)sender {
  [textField setStringValue:@"Hello World"];
}

Build and run the application, and verify everything is working. Your application should look something like Figure 5.10.

Figure 5.10 TestApp showing its Hello World message in a text field

Layout

You’ve learned the basics of creating and wiring up a simple user interface. There’s one small problem, however. Run TestApp again if it isn’t running already, and try resizing the window. The controls stubbornly stay where they are, refusing to do something smart (Figure 5.11).

Figure 5.11 Improperly behaving layout

There are, as of the release of Mac OS X 10.7 Lion, two mechanisms through which you can define the sizing and positioning behavior of views: the original “springs and struts” and the new Autolayout feature.

Note

Each of the two layout mechanisms has a well-defined API that allows you to use code to control layout behavior. Because this book focuses on Xcode and not Cocoa development, the coding topic will not be covered.

Using Springs and Struts

The “springs and struts” concept has been around since the earliest days of Cocoa. It’s not without its frustrations, but for iOS and pre-Mac OS X 10.7 applications, it still reigns.

The concept is simple: Views (custom views, tables, buttons, and so on) are contained within a “superview” and may be resized or moved around if the superview is resized. Springs dictate whether the view will be stretched or compressed vertically and horizontally relative to the superview. Struts dictate whether the left, right, top, and bottom edges of the view maintain a certain distance from the bounds of the superview or are free to float around.

Figure 5.12 shows the Autosizing control, found in the Utility area under the Size Inspector panel. The Say Hello button is selected in this case. The springs are shown in the inner box (the vertical and horizontal red lines with arrows on their ends); the struts are the outer red lines. The selected (active) springs and struts are a solid, brighter red; the inactive ones are lightly shaded. Clicking any spring or strut will toggle it active or inactive. The Example control, on the right, animates and shows how the view (the red rectangle) would behave relative to its superview (the enclosing white rectangle).

Figure 5.12 The Autosizing control

What’s Wrong?

Note the settings for the Say Hello button. Only the top and left struts are active, indicating that the button will maintain the same distance on its top and left edges from the bounds of its superview (the window’s content view) and will not resize vertically or horizontally. This is exactly the case in Figure 5.11; the button (and the text field below it) will remain stubbornly stationary even when the window is too small to show it.

Positioning

In this case, the fix may seem simple. For both the button and the text field, none of the springs or struts should be active. This means they won’t resize, and they’ll float freely within the superview as it’s resized (in response to the window being resized). Because both controls are more or less in the middle of the window, they will (more or less) stay that way as the window is resized.

Figure 5.13 shows the Autosizing control with all springs and struts deactivated. Note that the Example view shows the view (the red rectangle) remaining centered in the superview (the white rectangle). Do this for both the button and the text field. Select each view, one at a time, and click the top and left struts in the Autosizing control to turn them off.

Figure 5.13 Springs and struts deactivated in the Autosizing control

Figure 5.14 shows that a problem remains. Although the button and the text field are “more or less” centered, they’re moving relative to one another as well, which causes them to overlap (and when the window is made larger, they move farther apart). A common trick for controls you want to group together is to enclose them in a box (which has a nice bounding line to group its contents visually) or a plain custom view (which is invisible).

Figure 5.14 Overlapping controls

To employ this trick, drag a selection around the button and text view to select both at the same time (Figure 5.15). Choose Editor > Embed > Custom View from the main menu. The controls are now subviews of a new custom view, which is, in turn, a subview of the window’s content view. The custom view is selected. Now deselect, as in Figure 5.13, all springs and struts in the Autosizing control so the custom view floats freely. Since the custom view won’t be resized, its subviews (the button and the text field) won’t move at all.

Figure 5.15 Selecting multiple controls

Run TestApp and play with the window size once again. Figure 5.16 shows that the controls now maintain the same distance from one another and remain properly centered.

Figure 5.16 Centered controls

Sizing

For the sake of brevity, we’ll skip an exhaustive exploration of each possible combination of the settings. However, you’ll need the basics of the spring behavior. Say your goal is to make the button and the text field grow and shrink horizontally as the window is resized, but you still want to maintain the grouping of the two.

Because there is now a hierarchy several levels deep (the window’s content view contains the custom view, which contains the button and the text field), you must consider the sizing behavior of more than just the text field. For example, if you only set the text field to size horizontally in response to its superview being resized, nothing will happen. This is because the custom view is not set to autosize horizontally.

You’ll have to enable the horizontal spring for both the text field and the custom view. Figure 5.17 shows the Autosizing control with only the horizontal spring enabled. Do this for both the text field and the custom view. Interface Builder respects the autosizing behavior even when resizing views in the editor. Select the custom view, if it’s not already selected, and make it wider using the resize grips on its sides. Notice how the text field has also grown wider, while the button has stayed the same width and has remained centered within the view. Recenter it in the window so it looks nice.

Figure 5.17 Autosizing control set to size horizontally

Constraints

Run TestApp once again and play with the window size. Notice how the text field now grows and shrinks. And notice that if the window gets too small, the button is cut off and the field gets a little too narrow (Figure 5.18). This is a limitation of the springs and struts model: The only way to apply any kind of constraints is by setting a minimum size so things don’t get smooshed together or cut off.

Figure 5.18 Cut-off controls in a small window

The simplest fix is to set a minimum window size. Select the window, and in the Constraints section of the Size inspector, select the Minimum Size check box and set a reasonable minimum size (such as 200 by 150), as shown in Figure 5.19.

Figure 5.19 Setting window size constraints

Now when you run TestApp and play with the sizing, the controls should more or less behave themselves. You may need to play with the minimum window size or the sizes of the text field and enclosing custom view to get it right.

Using Autolayout in Lion

As mentioned, Lion (Mac OS X 10.7) introduces a new layout mechanism called Autolayout. Although it certainly has vast improvements over springs and struts (and a nifty layout language all its own for use in code), its use is not compulsory on Lion or above. That is, the springs and struts mechanism will still work as it always has. In fact, you must turn on Autolayout for each Interface Builder document in which you intend to use it, otherwise springs and struts still rule. Correspondingly, Autolayout can only be used with applications that target OS X 10.7 and above.

Note

You’ll need to be running Xcode version 4.1 or later to use the Autolayout features of the editor.

Activating Autolayout

To activate Autolayout for MainMenu.xib, navigate to it and make sure the Utility area is visible with the File Inspector panel selected. Under the Interface Builder Document section (Figure 5.20), select the Use Autolayout check box.

Figure 5.20 The Interface Builder document’s file settings

You may be prompted to upgrade your project’s minimum deployment version to Mac OS X 10.7 if it’s set to a lower version, as in Figure 5.21. Click the Continue and Upgrade button to accept the upgrade.

Figure 5.21 The Mac OS X 10.7 upgrade prompt

Note

Accepting the Autolayout upgrade and setting the minimum deployment version to 10.7 means your application will not run on versions of Mac OS X prior to 10.7. As mentioned, 10.7 is required for Autolayout.

Constraints

You’ll notice something different immediately. Figure 5.22 shows the new Constraints entries in Interface Builder’s Objects dock. Constraints are real objects, just like buttons and windows. They define the sizing and positioning behavior of the controls they constrain. Because they’re real objects, you can select, configure, or remove them in Interface Builder the same as you would a button or a window.

Figure 5.22 Constraint objects added to the document

Figure 5.23 shows a vertical space constraint selected. This constraint manages the vertical space between the Say Hello button and the custom view’s top border. With Autolayout, dragging controls into a window or view and snapping them to the guides will automatically create the constraint that the system determined appropriate to maintain the best positioning.

Figure 5.23 A vertical space constraint selected

You can add constraints manually by choosing Editor > Pin from the main menu and selecting the desired type of constraint. We won’t explore each of these exhaustively here, but it’s important to note the variety of constraint types available: width, height, horizontal and vertical spacing, leading white space to superview, top and bottom space to superview, equal widths and heights, and more.

Constraints have properties that you can adjust in the Attributes Inspector pane of the Utility area. For example, if you select the text field’s Width constraint, you’ll see the Width Constraint settings in the Attributes inspector (Figure 5.24).

Figure 5.24 Constraint settings in the Utility area

One behavior that didn’t make it past the upgrade to Mac OS X 10.7 (in this version, anyway) is the automatic width sizing of the custom view containing the button and field. Run TestApp to see for yourself.

Tip

For details about the Autolayout system, including the types of constraints and which ones are best for a given scenario, see the Cocoa Autolayout Guide at http://xcodebook.com/autolayoutguide.

To fix this (and explore adding constraints), select the custom view and choose Editor > Pin > Leading Space to Superview from the main menu. Select the custom view again and choose Editor > Pin > Trailing Space to Superview. Your window should look something like Figure 5.25.

Figure 5.25 The custom view’s leading and trailing space constraints

If you run TestApp now, you’ll see that this didn’t quite fix things. Although the button stays the same distance from the field below it, and the custom view seems to be resizing (as evidenced by the text field’s left edge following along), nothing else seems to be behaving itself.

The fix for the text field is easy enough. By snapping the left and right edges to the blue guides inside the custom view (Figure 5.26), the appropriate constraints are created for you automatically.

Figure 5.26 Creating constraints by snapping to guides

Figure 5.27 shows the constraints that were added as a result of your snapping the text field’s edges to the left and right guides. The constraints indicate that you want to maintain the space between the field’s sides and the sides of the superview’s bounds. Running TestApp once more shows that the Autolayout constraints now work as the original springs and struts did.

Figure 5.27 Newly added constraints

New Functionality

In the springs and struts demo, you needed the custom view so that the button and field would maintain the same vertical distance from each other as the window was resized (to prevent them from overlapping or growing apart).

Here’s where Autolayout with constraints really shines. To get this working the way it should have for years, you’ll remove that custom view and do it right. A simple trick to remove the view without moving the button and field is to select the custom view, then choose Editor > Unembed from the main menu. The custom view is removed and its subviews are left exactly as they are.

To fix the Autolayout constraints, just select the button and the field and drag them to the middle until they snap (as a group) to the blue vertical and horizontal centerlines that appear. You should see something similar to Figure 5.28. Run TestApp, and you’ll see an improvement. Although the text field doesn’t yet size horizontally as before, the button and the field maintain their positions relative to one another without the help of an otherwise pointless custom view. This is because of the vertical space constraint between the field and the button.

Figure 5.28 Simpler constraints for maintaining vertical spacing

To finish the job, you can once again add the leading and trailing spacing to the text field. Select the text field, and choose Editor > Pin > Leading Space to Superview from the main menu; select the text field again, and choose Editor > Pin > Trailing Space to Superview. Select the text field once again, and your constraints should look something like Figure 5.29.

Figure 5.29 The final constraints for a horizontally growing text field

Now TestApp should behave as expected when you run it. This should give you a pretty good idea of how the new Autolayout system works, as well as some of its advantages over the springs and struts system.

Wrapping Up

Unless you write server applications and command-line tools, you will need to build at least a basic user interface. Now that you’re familiar with Interface Builder and the basics of actions and outlets, you have enough knowledge to get started with some test applications of your own for learning purposes. More complicated applications often require more than a single controller and likely more than a single nib. In the next chapter, you’ll learn how to add additional source code and resources (including additional nib files) to your project.

6. Adding Files to a Project

All but the simplest applications will likely need additional source code files, multiple nibs, artwork, HTML-based help files, and frameworks or libraries. There are two basic categories of files you might add to a project: source code and resources. In this chapter, you will learn how to add new or existing source and resource files to your project as well as how to remove them.

Adding Existing Files

There are two ways to add existing files to an Xcode project: You can use the Add Files sheet, or you can use drag and drop.

Using the Add Files Sheet

You can choose files to add to your project by using the Add Files sheet, which you can access by choosing File > Add Files To “TestApp” from the main menu.

The sheet (Figure 6.1) is a standard Open File sheet with additional options at the bottom. These options tell Xcode what do with the files when you click the Add button.

Figure 6.1 The Add Files sheet

Destination

The Destination check box instructs Xcode to copy the selected files into the physical disk folder represented by the group that is currently selected in the Project navigator. Leaving this option deselected will cause Xcode to add a reference to the file without actually copying the file into the project.

Note

In most cases, it’s best to allow files to be copied into the project folder. This ensures all the parts of your project are kept together. However, referencing files outside the project folder has its advantages. One reason would be when using resources stored on a shared network volume for team development.

Folders

The Folders option lets you choose what Xcode will do when adding file system folders to the project. The first option creates groups of the same name as the folder and then adds the folder’s contents under that group. The second option creates folder references. These are similar to groups but represent the physical folder itself, preserving its file system hierarchy.

Add to Targets

The Add to Targets option instructs Xcode to add the files to the appropriate build phases for the selected targets within your project, depending on the file type. Xcode automatically adds source files to the Compile Sources build phase of the selected targets. Most other file types are added to the Copy Bundle Resources build phase. Targets and build phases are discussed in more detail in Part III.

Using Drag and Drop

In addition to using the Add Files sheet, you can add files to your project by dropping them into the Project navigator. A sheet (Figure 6.2) will appear, offering the same options shown in the Add Files sheet. Choose your options, and click Finish to add the files to the project.

Figure 6.2 The Add Files drag and drop options sheet

Note

It is common to add additional libraries and frameworks to a project. Adding libraries and frameworks, as well as packaging frameworks for distribution with the application, is discussed in depth in Part III.

Creating New Files

Xcode includes templates and options for creating a variety of common file types and adding them to your project. To begin adding a new file, choose File > New File from the main menu. A sheet similar to Figure 6.3 will appear.

Figure 6.3 The New File sheet

The sheet contains a sidebar on the left that categorizes the available templates first by SDK and then by file type. The top area to the right of the sidebar contains the specific templates that are available for the selected category. Select your desired template there. The area immediately below the templates shows a description of the selected template.

Some templates have additional options that allow you to specify things such as a superclass. Such options are displayed on the next sheet when you click the Next button. Keep clicking Next and you’ll eventually be prompted to save the file with a standard Save As sheet with a few additional options (Figure 6.4): the group in which to place the new file and the targets in which to include it. Click Save to complete the file creation.

Figure 6.4 The Save As sheet

Using the File Template Library

You can also use the Utility area’s File Template library (Figure 6.5) to add files to your project. Just drag the desired template straight into the Project navigator and drop it in the desired folder. A Save As sheet similar to Figure 6.4 will appear with which you can name the file and specify its group and targets.

Figure 6.5 The File Template library

Removing Files from the Project

To remove a file from a project, select it in the Project navigator and press Delete. Xcode will prompt you to make a decision (Figure 6.6) to remove only the reference to the file within the project or to remove the reference and delete the file from disk. The operation cannot be undone, so you’ll need to restore the file if you’ve deleted it and then add it to the project as shown earlier in this chapter.

Figure 6.6 Deleting a file

Wrapping Up

A typical project will require adding many new source and resource files. You should also expect to remove files while maintaining and improving the application. You’ve seen how straightforward both of these actions are. In the next chapter, you’ll learn how to use the Source Editor effectively to write and edit source code.

7. Writing Code with the Source Editor

Xcode’s Source Editor is loaded with features that help you write, navigate, and research code. You’ve already used the Source Editor when working directly in the code. In this chapter, you’ll be introduced to more of its features.

Exploring the Source Editor Interface

The Source Editor (Figure 7.1) appears when you select source code files, when you view issues within source code files, or when you stop at a breakpoint in your own source in the debugger. This is the editor in which you will spend most of your time.

Figure 7.1 The Source Editor

Note the gutter that runs along the left edge of the Source Editor. The gutter can display breakpoints, line numbers, and the code-folding and focus ribbon. Breakpoints are discussed in more depth in Chapter 9. You can toggle line numbers and the code-folding ribbon via Xcode’s preferences.

When editing source code, the Assistant window—which you saw in Chapter 3—can be used to open one or more files (or even separate parts of the same file) alongside the file displayed in the main editor. The Assistant in this case serves as a split-pane editor. You can use the various automatic modes (selected in the Assistant pane’s Jump Bar), such as Counterparts, Includes, Categories, and so on, which will cause the Assistant to display context-sensitive files depending on the main selection in the Project navigator. You can add as many panes as you like, and they’ll be arranged according to the settings you saw in Chapter 3.

Note

The Source Editor also has a Version Editor mode, the button to the right of the Assistant button. This feature is covered in Chapter 21.

Navigating Source Code

The Source Editor provides several ways to navigate your code. These include moving to symbols, showing only the code you want to work with, and splitting the editor to view multiple parts of the file at once.

The Jump Bar

One of the most common ways to move between symbols in your source is to use the Jump Bar discussed in Chapter 3 (Figure 7.2). When a source file with defined symbols is open, the last segment of the Jump Bar shows another level beneath the file itself—a list of the symbols within the source. The segment shows the symbol in which the insertion point of the editor resides. Choosing a different symbol takes you to its location in the source.

Figure 7.2 The Jump Bar showing the symbols belonging to the selected file

Jump to Definition

Another common navigation action is to jump to the definition of a symbol. The Source Editor makes this simple by turning symbols into hyperlinks while holding down the Command key (Figure 7.3). Clicking a symbol while holding the Command key jumps to its definition (which is not necessarily within the currently selected file). Recall the similar action for obtaining inline help—Option-clicking a symbol brings up the inline Quick Help pop-up.

Figure 7.3 Symbols made hyperlinks by holding down the Command key

Code Focusing and Folding

The code-folding ribbon is enabled by default. It is the narrow strip in the gutter directly to the left of the text area of the Source Editor. The ribbon lets you concentrate on a particular scope within your code (anything within a matching pair of brackets) through folding or focusing. Nested scopes are depicted by darker shading within the ribbon (Figure 7.4). The boundaries of each scope are marked with arrows when you hover your mouse over them.

Figure 7.4 The code-folding ribbon showing nested scopes

Focusing on Code

Focusing refers to darkening out all but the desired scope. Focusing does not obscure text; it only shades out anything outside the focused scope. Figure 7.5 shows the focused body of a simple if statement in the -applicationDidFinishLaunching: method.

Figure 7.5 Focused code, using the code-folding ribbon

To focus on a scope, hover the mouse over the desired scope in the ribbon. Xcode will leave only the code within that scope unshaded.

Folding Code

Folding refers to collapsing and hiding the text within the desired scope. This does not change the text within the file but rather obscures it, making the file effectively shorter and easier to navigate. Figure 7.6 depicts the TestAppAppDelegate.m file with the -applicationDidFinishLaunching: method folded; the “folded” code is depicted as a yellow marker containing an ellipsis.

Figure 7.6 Folded code, using the code-folding feature

To fold code, click the desired scope in the folding ribbon. In cases where there are nested scopes, it’s easiest to click one of the arrows at either end of the desired scope.

Using Code Completion

Xcode’s Source Editor provides code completion of symbols as you type. When you begin to type a symbol that Xcode recognizes from your project or linked libraries and frameworks, an inline suggestion as well as a list of other possible suggestions appears (Figure 7.7).

Figure 7.7 Code completion suggestions

You can choose to accept the inline suggestion by pressing Tab. To select an alternative suggestion, use the arrow keys to choose and then press Return to use the selection. When there is more than one suggestion for a given prefix (such as NSSet or NSSetFocusRingStyle()), the common prefix will be underlined and pressing Tab will complete only up to the underlined portion. Subsequent Tabs will complete to the next whole or part of the inline suggestion.

Code completion can be canceled by pressing Escape or Control+spacebar. Completion can also be requested by placing the text insertion point at the end of an incomplete symbol and pressing Control+spacebar.

Although Xcode will automatically suggest code completion while you type by default, you can turn this feature off in the Text Editing panel of Xcode’s preferences. To do this, toggle the check box named “Suggest completions while typing.” When this feature is disabled, you may still request suggestions by pressing Control+spacebar while the text insertion point is at the end of an incomplete symbol.

Code completion uses the same information in the Symbol navigator, which you saw in Chapter 3. This information is derived from all available sources and libraries within the workspace, which means separate projects within the same workspace can share it among themselves. This feature is discussed in Chapter 16.

Exploring the Code Snippet Library

The Code Snippet library (Figure 7.8) is a place to keep common chunks of code such as a class declaration, a try/catch block, or a -dealloc method. The library comes with a number of ready-to-use snippets and allows you to add your own as well.

Figure 7.8 The Code Snippet library

The Code Snippet library is located at the bottom of the Utility area. You can filter the snippets using the pop-up button at the top; you can choose to show all snippets, Mac OS, iOS, or your own custom snippets. You can also filter by keyword using the search bar at the bottom of the library panel.

Examining and Using Snippets

To examine the contents of a snippet, click to select it in the library. A pop-up (Figure 7.9) window will appear containing a description and the code snippet.

Figure 7.9 The snippet details pop-up

Using a snippet is as easy as dragging it into your source code. When you drop the snippet into your source, the full code will be present as if you had pasted it from the pasteboard.

Creating and Editing Snippets

To create a snippet, drag the desired “template” code into the snippet library. The snippet will be added to the list of available snippets. To edit the snippet, select it in the library. When the pop-up window appears, click the Edit button in the lower-left corner. The pop-up will reveal editing controls (Figure 7.10).

Figure 7.10 The snippet details pop-up in edit mode

You can set the title and description that appear in the library list, and the platform and language the snippet targets. You can also set a completion shortcut to use when editing code. Finally, you can edit the snippet itself. When you’re finished editing, click Edit or Done.

An example of a useful snippet is a ready-to-go set of the three primary NSTableViewDataSource protocol methods. When using this protocol to populate an NSTableView programmatically, the quickest way to get up and running used to be to copy the method signatures from the documentation and then insert the brackets, the if conditionals for determining the table being operated on, and so on. Now you need to define this only once, format it as you want, and then save it as a snippet for reuse in any future projects and workspaces.

You can also insert placeholder tokens that are parts of the snippet (such as arguments) that must be filled in to complete the code. For example, to add a placeholder for an NSNumber argument, you would type <#NSNumber#> where the argument belongs. When the snippet is used, the text that appears between the hash marks is what will appear in the snippet. The token’s text should serve as a helpful prompt regarding what should be filled in when using the snippet.

The Assistant

When editing source files, the Assistant can act as a smarter split-screen editor, showing (and allowing you to edit) different parts of the current file or any other file of your choosing. As mentioned in Chapter 3, the Assistant can become contextually aware, depending on the behavioral mode you select.

In any context, you can manually choose a file to display in the Assistant and of course create as many assistants (each with any behavioral mode you like) as you need.

Available Assistant Behaviors

Counterparts behavior shows files that are considered to be counterparts of the selected item. A counterpart might be the header file for a selected implementation file, or vice versa.

Superclasses and Subclasses behaviors show any known superclasses or subclasses of the selection, respectively.

Siblings behavior shows any files within the same Project navigator group as the selection.

Categories and Protocols behaviors show available Objective-C categories or protocols for the selected file, respectively.

Includes and Included By behaviors show all files that include the selection or those included by the selection, respectively.

Wrapping Up

You’re now familiar with the basics of Xcode’s Source Editor. Additional features, including the Refactor tool, Fix-it, and the ability to rename symbols, will be covered in depth in Part III. In the next chapter, you’ll learn how to perform a project-wide search and replace.

8. Searching and Replacing

Xcode provides many ways to search and filter project members, source code, and documentation. You briefly scratched the surface of searching your source code with the Search navigator in Chapter 3. In this chapter, you’ll learn how to search and filter project members and how to perform replacements to all or specific parts of your project source.

Using the Search Navigator

As mentioned in Chapter 3, initiating a basic search is simple. Type a term into the familiar search box at the top of the Search navigator and press Return. The results are displayed in the navigator outline (Figure 8.1), organized by source file. Selecting a file or a matching line within a file will cause Xcode to navigate to it in the appropriate editor. The search results themselves can be further refined by typing an additional term in the search field at the bottom of the Search navigator. You can start a project-wide search by choosing Edit > Find > Find in Workspace from the main menu.

Figure 8.1 The Search navigator showing matches

The basic scope of the search can be selected as you are typing the search term, before you press Return. A context menu will appear as you type (Figure 8.2), allowing you to limit the scope to your project or to your project and all frameworks, as well as choosing a “begins with” or “contains” type of search. You can select one of these options rather than pressing Return; Return always chooses the first option, which is defined by your chosen find options.

Figure 8.2 The search options context menu

Tip

You can jump immediately to the Search navigator by pressing Command+Shift+F (for Find). The search field is focused so you can immediately begin typing your search term.

Using the Find Options

A number of options are available to specify your search. Click the magnifying glass icon at the left edge of the top search field to reveal a context menu. Choose Show Find Options, and the Find Options panel will emerge (Figure 8.3).

Figure 8.3 The Find Options panel

Using the Style Option

This option allows you to specify a textual search or a regular expression search. A textual search matches the literal text term you type. A regular expression (or regex) search will search for patterns using the regular expression syntax.

Although you can perform reasonably complex changes with carefully chosen search-and-replace strings, regular expressions are a far more powerful pattern-matching tool. Support for regex is built directly into many modern APIs and text editors. Although the subject is beyond the scope of this book, there exists an abundance of books and online tutorials.

Using the “Hits Must” Option

This option allows you to specify the location of the search term within the searched items. That is, you can choose to view any results containing the term, only those that begin or end with the term, or only those that exactly match the entire term.

Using the Match Case Option

This option lets you choose whether the search is case sensitive. For example, with Ignore Case selected, the term hello would produce three results across two files in your TestApp project: the -sayHello: method in your header and implementation files, and the @”Hello World” string in the body of the -sayHello: method. If you choose Match Case, there would be no results since all the instances of the word hello are capitalized.

Using the “Find In” Option

This option lets you narrow the scope to specific projects in a multi-project workspace or any custom scope you define. Workspaces are covered in detail in Chapter 16. Custom scopes are covered in the next section. You can also choose to include any frameworks your project links by selecting the “And linked frameworks” check box.

Custom Find Scopes

This powerful feature lets you define search scopes with user-defined rules that can match locations, names, paths, extensions, or file types. To define a custom scope, choose Custom from the Find In pop-up button menu. A sheet will appear listing custom scopes (empty by default) and their associated rules (Figure 8.4).

Figure 8.4 The Find Scopes sheet

A good use case for a custom scope would be to narrow it to only HTML files within the workspace. This can be useful if you include an HTML-based Mac Help Book with your application and need to find all references to a feature you intend to rename or expand upon.

Creating a Custom Find Scope

To create a custom find scope, make sure the Find Scopes sheet is open and then click the plus (+) button at the lower-left edge of the sheet. A new scope will be created with a basic rule (Location is within workspace). Double-click the My Scope entry in the scopes list, rename it to something useful, such as HTML Source, and press Return.

Since the default rule narrows the scope to matches anywhere within the current workspace, you need only one additional rule to narrow it to HTML files. To add this rule, click the plus (+) button to the right of the first rule (Location is within workspace). A new default rule will appear (Name is equal to). Click the Name pop-up and select Type. Click the any pop-up and select “html.” Your Find Scopes sheet should now look like Figure 8.5.

Figure 8.5 A new custom find scope

Note

Help Book is Apple’s term for the application’s documentation. Application Help Books are accessed through the application’s Help menu.

Click the Done button to close the sheet. The new scope is now selected in the Find In pop-up and will remain as one of the available search scopes. You can edit or delete it or add new scopes at any time by choosing the Custom option from the Find In pop-up.

With Ignore Scope selected in the “Hits must” pop-up and the new HTML Source scope selected in the Find In pop-up, type hello into the search field again and press Return. Note there are no matches because the only files in your project that currently contain the term are not HTML files.

Replacing Text

To the left of the top search field is a pop-up button with Find selected. Click the pop-up and choose Replace. More options are revealed below the search field (Figure 8.6). An additional field, in which you can specify the replacement term, accompanies three buttons (Preview, Replace, and Replace All). When the navigator area is not wide enough to contain all three buttons, the Preview button is represented by an icon representing a loupe.

Figure 8.6 The replace options

Note

The additional Find options revealed when choosing Show Find Options from the search field’s magnifying glass menu are also available when performing a Find and Replace.

You can replace specific instances by selecting them (hold down the Command key and click individual results) and clicking the Replace button. This will replace only those instances with the replacement term. To replace all instances, click Replace All. Xcode will replace the desired instances, and the changes will be saved automatically when you build or close your project.

Previewing Replacements

Xcode has a visual replacement preview interface for previewing replacements. When you click the Preview button, a sheet similar to Figure 8.7 appears. The preview sheet lets you “cherry-pick” the replacements you want and view the effect each change will have before you apply it.

Figure 8.7 The Replace preview sheet

To test this, assume you want to change only the -sayHello: action in your project to -sayGreeting:. You don’t want to change the actual message that is presented to the user, only the method name.

Perform a case-sensitive search for Hello. Once you have results, make sure Replace is selected in the pop-up so that the replace options are revealed. Enter the term Greeting in the replace field.

Click the Preview button to reveal the replacement preview sheet. As in Figure 8.7, select the -sayHello: method declaration in the header file and the implementation in the implementation file. Leave the line with the @”Hello World” string deselected. You can do this by placing a check mark next to the desired matches in the left-hand outline view or by flipping the switches to the right in the preview panel.

Click the Replace button in the lower-right corner of the sheet to see your changes applied. You may be prompted to take a snapshot of the project so you can revert the changes.

Once the changes are applied, you’ll notice that only the @”Hello World” string was unchanged, as expected. If you build and run your application, you’ll also notice complaints being logged to the console and that the Say Hello button no longer works. You’ll need to reconnect the button to the newly named -sayGreeting: method as you learned in Chapter 5.

Blindly replacing symbols (as opposed to literal strings) is seldom a victimless crime. It can break outlet and action connections in Interface Builder files, unintentionally replace substrings within other strings to ill effect, and more. A much better way to rename a symbol throughout a project is to use the Refactor tool. This tool can rename a symbol and replace any references to it, as well as even rename classes and associated files without breaking their connections or references. The Refactor tool is covered in Chapter 13.

Note

Snapshots are covered in Chapter 21.

Searching within Files

You can also perform a search or a search and replace within the currently selected source file in the Source Editor. The simpler UI works much the same way as the Search navigator, including additional options (by clicking the search field’s magnifying glass icon) and a replace field (Figure 8.8).

Figure 8.8 The Source Editor’s Find panel

To find a word or phrase, select Edit > Find > Find from the main menu. Enter a search term and press Return. You can navigate the matches within the file using the back and forward buttons to the left of the search field.

Although there is no preview as with a project-wide search and replace, you can choose Replace All to replace all matches, Replace to replace the current selection, or Replace & Find to replace the current selection and select the next match.

Click Done to close the Find panel.

Tip

You can initiate a search within the Source Editor by pressing Command+F. This is similar to the Command+Shift+F shortcut that opens the Search navigator. You can navigate the matches by pressing Command+G to go to the next match and Command+Shift+G to go to the previous one.

Wrapping Up

You’ve seen how you can search and replace within your project or the currently selected file. The comprehensive set of options—including user-customizable, rules-based scopes—is flexible enough to help you find exactly what you’re looking for. The replace preview system lets you cherry-pick exactly what you want to replace. All this code editing and text replacing is bound to introduce bugs. In the next chapter, you’ll learn the basics of debugging an application using Xcode’s built-in debugger.

9. Basic Debugging and Analysis

Xcode provides a comprehensive set of well-integrated tools to approach the tasks of debugging and analyzing your applications. In this chapter, you’ll learn how to use Xcode’s built-in debugger. In Chapter 17, you’ll learn more advanced debugging techniques.

Compile-Time Debugging

In Xcode, errors, warnings, and analyzer results are collectively called issues. Xcode is constantly compiling and checking your code for issues. Errors are red, warnings are yellow, and static analyzer issues are blue. Like any modern integrated development environment, Xcode flags issues by highlighting them directly in the source code (Figure 9.1) with a corresponding icon in the gutter along the left edge of the Source Editor. In addition to the immediate issues in the selected source file, all issues Xcode finds in your entire workspace are displayed in the Issue navigator (as described in Chapter 3).

Figure 9.1 A compiler issue highlighted in the Source Editor

Using the Static Analyzer

Xcode integrates the Clang Static Analyzer, which goes a step beyond basic compiler errors and warnings. It knows enough about C, Objective-C, and Cocoa patterns to find memory management problems, unused variables, and more. Its integration with Xcode means it can show an impressive amount of detail, including the path of execution leading to the problem and the conditions that caused it along the way.

Figure 9.2 shows an analyzer issue. In this case, an instance of NSArray has been created on one line and leaked on the next. On each line, the instructions that led to the problem are highlighted and explained.

Figure 9.2 An analyzer issue highlighted in the Source Editor

Notes

You can learn more about the Clang Static Analyzer at http://clang-analyzer.llvm.org.

More complicated analyzer scenarios are explored in Chapter 17.

Fixing Errors with Fix-it

You can fix common errors with Xcode’s Fix-it feature. When you click an issue in the Source Editor, Xcode will display a pop-up window with suggestions for possible fixes if it has any to offer (Figure 9.3). To apply a suggested fix, click the suggestion in the Fix-it pop-up. The code will be changed according to the chosen fix.

Figure 9.3 The Fix-it window suggesting a fix

Using the Log Navigator

The full results of each build are stored in the Log navigator, which you explored in Chapter 3. You can filter and explore the results. Double-clicking an issue will navigate to the corresponding file. Figure 9.4 shows a build error that resulted when class Bob was referenced but not declared. It’s a good idea to expand issues by clicking the disclosure triangle to the left of the issue. This reveals crucial details about the issue that can help you figure out how to fix it.

Figure 9.4 The undeclared Bob build error in the Log navigator

Runtime Debugging

For runtime debugging, Xcode integrates with GDB and the new LLDB debugger. Xcode provides a UI for managing breakpoints, controlling program execution, exploring the threads and stacks of the running application, accessing the debugger console, and more.

By default, all newly created Xcode projects are run in the debugger. The application will pause at the point of failure if it crashes or at any breakpoints you set if they’re encountered. The Debug area (Figure 9.5) appears when running an application with a debugger attached. The current instruction is highlighted with a green arrow in the Source Editor gutter.

Figure 9.5 TestApp paused in the debugger

Note

Whether or not a debugger is attached to the running application is controlled by the active scheme. Schemes are covered in Chapter 14.

Using the Debugger Bar

The basic program execution controls—including Step Into, Step Over, Continue, and others—and the Threads and Stacks navigator are located in the Debugger Bar (Figure 9.6) at the top of the Debug area. You can pause a program (or trigger other actions in Xcode) by setting breakpoints. You can navigate threads and stacks using the navigation pop-up.

Figure 9.6 The Debugger Bar

Using the Basic Controls

The Pause/Continue button pauses and resumes program execution. The keyboard shortcut for this action is Control+Command+Y.

The Step Over button executes the currently highlighted instruction while execution is paused. If the instruction is a routine, the routine is executed and the debugger stops at the next instruction in the current file. The keyboard shortcut is F6.

The Step Into button executes the currently highlighted instruction while execution is paused. If the instruction is a routine, the debugger moves on to the first line of that routine and pauses. The keyboard shortcut is F5.

The Step Out button finishes the current routine and jumps back to the calling routine or next instruction after the routine was called. The keyboard shortcut is F8.

You can find additional debugger actions under the Product > Debug submenu of the main menu.

Tip

Holding Option or Option+Shift while clicking the step buttons will vary the functionality of the buttons. You can step through assembly instructions or through only the instructions in the current thread. See the Xcode documentation for details.

Navigating Threads and Stacks

The Threads and Stacks navigator, which occupies the rest of the Debugger Bar, is used to switch between threads and navigate the call stack. It works in the same way as the Jump Bar. Figure 9.7 shows the current call stack while TestApp is paused at a breakpoint in the -applicationDidFinishLaunching: method.

Figure 9.7 Viewing the call stack in the Threads and Stacks navigator

Working in the Console

The console (Figure 9.8) displays the console output of your application and, while debugging, serves as a command-line interface to the debugger (whether you’re using GDB or LLDB).

Figure 9.8 The debugger console

The output can be filtered to show only debugger or target output using the pop-up menu in the upper-left corner of the console area. The debugger prompt is available only when the application is paused in debug mode. When the prompt is available, you can click to the right of the text prompt and input debugger commands, such as the GDB command po (print object).

The panel to the left of the console area, the Variables pane (Figure 9.9), shows the current variables and registers when debugger is paused. The pop-up button in the upper-left corner of the pane can be used to choose all variables, those that were recently accessed, or variables local to the current scope only.

Figure 9.9 The Variables pane

Using Breakpoints

Breakpoints are used to pause the application (or perform other actions) in the debugger when a particular instruction (point in code) is reached. There are several ways to manage breakpoints in Xcode 4.

Enabling Breakpoints

For Xcode to stop at breakpoints in the debugger, breakpoints must be active. You can use the Breakpoints button at the top of the project window to activate or deactivate all breakpoints. If this button is not selected, the debugger will stop only when a program signal (such as a memory-management-related crash) is encountered. Alternatively, you can use Command+Y to toggle breakpoints.

Note

In previous versions of Xcode, Command+Y would launch the targeted application in the debugger, whereas Command+R would run it without the debugger attached. Starting in Xcode 4, pressing Command+Y toggles activation of all breakpoints, and the running application is effectively always in debug mode.

Managing Breakpoints in the Source Editor

You can set breakpoints in the Source Editor by clicking the gutter on the left edge of the editor beside an instruction. A blue marker appears, showing that a breakpoint is set at that location (Figure 9.10).

Figure 9.10 A breakpoint set in the greeting action of TestApp

You can toggle individual breakpoints in the editor by clicking them once. The breakpoint will turn lighter, appearing translucent when inactive. To remove a breakpoint entirely, you can drag it from the gutter and release it. It will disappear in a puff of animated smoke to indicate it has been deleted.

You can also set breakpoints in the editor with a keyboard shortcut. Command+\ (Command and the backslash character) will set a breakpoint at the current line in the code. If a breakpoint already exists, the shortcut will remove it.

Using the Breakpoint Navigator

As you learned in Chapter 3, you can use the Breakpoint navigator to manage individual breakpoints, navigate your project by set breakpoints, or view only active breakpoints. There are a few more important features to note:

• Right-clicking a breakpoint in the navigator and choosing Edit Breakpoint from the context menu reveals a pop-up window that presents a number of options (Figure 9.11). You can set a condition under which the reached breakpoint will break (such as x == 21); ignore the breakpoint a number of times before breaking; add one or more actions (such as playing a sound, logging something to the console, executing a shell command) when the breakpoint is reached; and automatically continue after performing actions.

Figure 9.11 The breakpoint options pop-up

• You can also set exception or symbolic breakpoints using the + button at the bottom of the Breakpoint navigator. When you add either type of breakpoint, a pop-up similar to the breakpoint options pop-up will appear (Figure 9.12), allowing you to further specify their individual options.

Figure 9.12 The options pop-up for an exception breakpoint

Note

Refer to Xcode’s documentation for a full explanation of the various options for user, exception, and symbolic breakpoints.

Interacting with the Source Editor

While the application is paused, you can interact with the debugger directly in the Source Editor in several helpful ways.

Inspecting Variables in the Source Editor

The Variables panel isn’t the only way to examine the state or content of variables in the debugger. While the application is paused, you can hover the mouse pointer over a variable to examine it as long as it is within the current scope. A yellow box will appear, showing the details of the inspected variable (Figure 9.13).

Figure 9.13 Examining a variable in the Source Editor

Note

You’ve seen that pointers to Objective-C objects can be examined in the Source Editor, in the Variables panel, and when using the print object command in the console. The information that is displayed is the result of calling the -description method, inherited from the NSObject class.

Using Continue-To-Here

Sometimes it may be advantageous to continue to a point in your code farther down from where you’re currently paused or to continue through a loop back to the top. You can continue execution to the desired point using the continue-to-here command.

To continue execution to a chosen instruction, hover your mouse pointer over the gutter next to the instruction. A green button will appear (Figure 9.14). Click the button to execute up until that instruction.

Figure 9.14 The continue-to-here button

Moving the Execution Pointer

You can drag the execution pointer and place it anywhere within the local scope. You can use this to skip parts of code or to jump backward to repeat instructions. To move the execution pointer, grab the green arrow along the left edge of the Source Editor and drag it to the desired instruction.

Moving the execution pointer backward to repeat instructions will not undo the instructions that were just executed. It will execute them again when you continue or step through your code. If you are new to debugging, missing this distinction can be confusing.

Using the Debug Navigator

As you learned in Chapter 3, the Debug navigator shows the threads and stacks when execution is paused in the debugger. This view represents the same information found in the Threads and Stacks navigator in the Debugger Bar. You can organize the navigator by thread or by Grand Central Dispatch queue.

You can further refine the navigator using the controls at the bottom. The button at the left side of the slider ( ∑ ), when enabled, filters the threads and stacks to show only the threads that have your code in them or for which debugging symbols exist. The slider controls how much stack detail to show—the left side shows only the top frame of each stack while the right shows all stack frames.

Note

For more information about Grand Central Dispatch, refer to the Apple developer documentation.

Wrapping Up

You should now have a firm grasp of the basic debugging facilities that Xcode 4 offers. You’ll find more debugging techniques in Chapter 17. In the next chapter, you’ll explore Xcode’s graphical data modeler and use it to add some data management and storage capabilities to TestApp.

10. Using the Data Model Editor

Xcode comes with an integrated data model editor tool. In this chapter, you’ll learn how to use the data modeler to give your application the ability to create, manage, manipulate, save, and load its data without writing a single line of code.

Introducing Core Data

A data model gives your application a well-defined structure for managing and persisting its data. The model corresponds with the Model layer of the Model-View-Controller design pattern. There are a number of ways to manage your application’s model layer but Apple has created a solution that works well in many situations: Core Data. This facility is well integrated with Xcode.

Apple is very careful to specify Core Data as an “object graph management and persistence framework.” Although the framework shares much in common with a relational database, it is important to note that it is not intended to act as one. Core Data is primarily focused on the needs of desktop applications (though it can be used in server applications as well, provided care is taken to manage it properly).

The framework provides standard persistent store types (binary, SQLite, and XML) and can be extended with custom store types. The minimum requirement the developer must supply is a managed object model, which describes the application’s entities (such as Person, Group, Account, or BlogPost) and their relationships to one another, if any. With this model and UI to manipulate it, Core Data is smart enough to handle managing, saving, and loading your application’s data without writing a single line of code. In practice, however, a moderately complex application will need further customization.

There are a few key concepts you’ll need to understand to use this API and its related Xcode features.

Note

Core Data relies on several underlying Cocoa technologies. This is considered an advanced topic. This book will introduce the basic concepts but will focus on Xcode’s Core Data features only. For more information, refer to Apple’s developer documentation.

Managed Object Models

A managed object model (MOM) is Core Data’s facility for describing the application’s data model. It can be described in code but is most often built with the Data Model Editor. When you create a project from a template that uses Core Data, all the necessary code is included as well as an empty MOM file that shares the application’s name. For TestApp, the file is TestAppDataModel.xcdatamodel.

Persistent Stores

A persistent store is the on-disk representation of the data created with your managed object model. Core Data supports three store types by default: XML, SQLite, and binary. Each store type has its advantages and disadvantages (see the Core Data documentation for details). Additionally, Core Data supports developer-implemented custom store types. The managed object model “does not care” about how (or even if) the data is persisted in a store.

Developers new to Core Data sometimes confuse the model with a data store created using the model. Some even look for a way to browse (in Xcode) the data they put into a store with their application. It’s important to understand that the data created in your application is not stored in the managed object model but rather in a store.

Note

Throughout the rest of this chapter, the term model can be assumed to refer to a Core Data managed object model.

Entities

Entities represent your model objects. Entity in this context means the same as it does in relational databases. It is a description of a type of object and its properties. In Core Data terminology, a managed object is an instance of an entity.

When an entity is selected in the editor, containers appear that allow you to add attributes, relationships, and fetch properties.

An attribute requires, at minimum, a name (such as lastName or age) and a type (such as a string or a number). A relationship requires a name (such as parentFolder) and a destination entity (such as Folder) and can be a one-to-one or one-to-many relationship.

Managed Object Contexts

A managed object context can be thought of as a “scratch pad,” a context in which managed objects are created or pulled from a persistent store, potentially modified, and potentially saved back to the store. To work with Core Data, you must have at least one context.

You may have multiple contexts to keep sets of changes separate. For example, a desktop application might create a separate context for an “import” task that runs in the background while the user continues using the existing data. A server application might have one context for each session (connected user) to isolate their activities until they’re ready to “commit” any additions, changes, or deletions they may have made.

Separate contexts are merged using one of several available merge policies that dictate how conflicting changes are to be handled. The merged contexts can then be persisted to the store. In the case of this import example, the contexts can be merged (and persisted) when the import completes successfully, revealing the newly imported data to the user in the main user interface.

Using the Data Model Editor

When you select an .xcdatamodeler file in the Project navigator, the file is opened with the Data Model Editor (Figure 10.1). The editor is separated into two main areas: the outline and the main editor area. The Jump Bar reflects the model’s hierarchy, and the Utility area, when visible, shows the details of the selected items in the Data Model inspector.

Figure 10.1 A simple MOM in the Data Model Editor

The outline represents the entities, fetch requests, and configurations of the MOM. New entities, fetch requests, and configurations can be added by clicking and holding the blue Add Entity ( + ) button in the bottom toolbar or by using the Editor > Add... items in the main menu. These items can be deleted by selecting them and pressing Delete.

The main editor has two primary styles: table and graph. Table mode is what you saw in Figure 10.1. Graph mode is shown in Figure 10.2 and represents the relationships and inheritance of the model. When using the graph editor style, you will need to use the Utility area to edit entities and their attributes and relationships.

Figure 10.2 A MOM in the model graph mode

Creating a Basic Data Model

Now that you’ve toured the Data Model Editor, you’re ready to expand TestApp’s capabilities by adding a simple data model. For this example, assume the goal is to add the ability to create, edit, save, and restore simple to-do items. A to-do item will have a content string and a due date.

To create the to-do entity, navigate to the TestAppDataModel.xcdatamodel file. Click the Add Entity button. An entity will be added with a default name of Entity, ready to be renamed. Type ToDoItem, and press Return to rename the entity.

Add the due date attribute by clicking the Add ( + ) button in the Attributes table in the editor. Change the attribute name to dueDate and set its type to Date. Do the same for the content attribute, setting its name to content and its type to String. The MOM should now look like Figure 10.3.

Figure 10.3 TestApp’s managed object model

That is all that is required to give TestApp the ability to maintain and persist a list of to-do items. To let the user manipulate a list (including adding, editing, and deleting), you’ll need to add a user interface (UI).

Creating a UI for the Model

To manage TestApp’s to-do items, you’ll need a table view and a few buttons to add and remove items. Cocoa’s NSArrayController object can fulfill all of the controller layer needs with no code via the Cocoa Bindings mechanism. To create the interface, select the MainMenu.xib file in the Project navigator. The file will open in Interface Builder.

Laying Out the Interface

First, make room for more user interface elements. You can do this by moving the Say Hello button and its text field to the top of the window (Figure 10.4). You could also make more room by making the window larger.

Figure 10.4 Making room in the TestApp interface

Drag two NSButtons into the window (Figure 10.5). Position the buttons, then double-click each and set their titles to Add and Remove. You should end up with something like Figure 10.6. These buttons will let the user add and remove instances of the ToDoItem entity.

Figure 10.5 Adding buttons to the interface

Figure 10.6 The Add and Remove buttons

To display the to-do items to the user and provide a means by which to manipulate them, a simple table view will work just fine. Find the NSTableView control and drag one into the window, positioning it as in Figure 10.7. Double-click the headers of each of the two columns and set them to Due and Description. You’ll bind these columns to the dueDate and content attributes of the ToDoItem instance the table will display.

Figure 10.7 Placing the table view control into the interface

The Due column will need some extra formatting to display dates properly. A cell formatter can be used to do this automatically for all cells in the column. Drag an NSDateFormatter into the Due column just beneath the column header, atop the words Text Cell (Figure 10.8). This will create and attach a date formatter to the prototype cell the column uses to represent each row’s content.

Figure 10.8 Adding a date formatter

The date formatter’s settings should be visible in the Attributes inspector. Choose Short Style from the Date Style pop-up. Your user interface should now resemble Figure 10.9.

Figure 10.9 The new user interface

Tip

Prior to Xcode 4, formatters attached to a column’s cell were indicated in the editor with a small “medallion” beneath the cell. Clicking this would let you edit the formatter’s settings. Presently, the only way to get to this setting is to expand the Interface Builder dock or use the Jump Bar to drill down through the window and view hierarchy to the table column’s text cell. The formatter is found under the cell to which it is attached, and selecting it reveals its settings.

Creating the Controller

Core Data works well with another Cocoa mechanism called Cocoa Bindings. The Cocoa Bindings controller layer provides several easy-to-use controllers (such as NSArrayController) that simplify displaying and managing Core Data information. Locate and drag an NSArrayController into the Interface Builder dock (Figure 10.10). Select the array controller in the dock, then select the Attributes inspector in the Utility panel. (Note: Controllers are dragged into the Interface Builder dock because they’re not visual user interface elements.)

Figure 10.10 Adding an array controller

Select the Auto Rearrange Content check box so that newly created to-do items are properly sorted. Change the Mode pop-up to Entity Name. Change the Entity Name field to ToDoItem to tell the array controller it is managing the ToDoItem entity from the MOM. Select the Prepares Content check box to avoid having to manually fetch its contents. The Attributes inspector should look like Figure 10.11.

Figure 10.11 The array controller attribute settings

Next you’ll need to bind the array controller to its contents, which come from the Core Data persistent store. Select the Bindings inspector and expand the Managed Object Context binding. Select the Bind To check box and select Test App App Delegate from the pop-up menu next to it. Set the Model Key Path field to managedObjectContext. The Bindings inspector should look like Figure 10.12. This will cause the array controller to use the managed object context (MOC) from the TestAppAppDelegate class (via its -managedObjectContext method).

Figure 10.12 The array controller bindings settings

Wiring Up the UI

To finish the interface, you’ll need to wire the controls to the array controller so the to-do items are shown and editable in the table and the Add and Remove buttons work.

First, connect the Add and Remove buttons’ actions to the array controller’s -add: and -remove: actions, respectively. As you learned in Chapter 5, you can do this by Control-dragging a connection from the buttons to the array controller in the Placeholders and Objects panel and choosing the appropriate action.

Lastly, you’ll need to bind the table columns to the content of the array controller. This will let each column represent the corresponding attribute (the due date and content string) of each instance of ToDoItem the table represents (one item per row). Select the Bindings inspector in the Utility area if it’s not already selected. Select the Due column (it will take several clicks on the column to descend through the window and view hierarchy). Expand the Value binding and select the Bind To check box. Select Array Controller in the pop-up. Set the Model Key Path field to dueDate (Figure 10.13). Do the same for the Description column, using content for the Model Key Path field.

Figure 10.13 The Due column’s bindings settings

Taking the UI for a Test-Drive

TestApp is ready for a test-drive. Build and run the application. Click the Add button to add a to-do item. Set a date (using the M/D/YY format you chose in the formatter’s attributes) and a description. Quit the application and relaunch. You’ll notice that the changes were automatically persisted. Now try sorting the table by clicking either of the column headers, and then try removing an item. Figure 10.14 shows TestApp in action.

Figure 10.14 TestApp with its new to-do feature

It’s just as easy to add another attribute to the ToDoItem entity. To-dos need a completion check box. To do this, you could add a completed Boolean attribute to the ToDoItem entity and add another table column with a check box cell.

Creating Custom Classes

It’s often necessary to create a custom NSManagedObject subclass to customize an entity instance’s behavior. The class behind an entity must be specified in the managed object model.

To create a subclass for an entity, select the entity in the editor and choose File > New > New File from the main menu. In the sheet that appears, choose the Core Data category and select the NSManagedObject Subclass option. Click Next. You’ll be prompted to choose the folder and group (but not the filename) under which to store the new class. Click Create to complete the action. The new file will be created and added to your project, and the selected entity’s class will be reflected in the Utility area of the Data Model inspector.

To point an entity at an existing NSManagedObject subclass in your project, select the entity in the editor and open the Utility area. Select the Data Model inspector, and change the Class field to reflect the name of the desired class.

Creating Accessors Quickly

When using custom NSManagedObject subclasses, you can generate accessor source code automatically for the attributes of your entities. To do so, select the entity and then select one or more attributes. Choose Edit > Copy from the main menu. You can either select the custom NSManagedObject subclass in the Project navigator or use the Assistant (discussed in the next section) so that the implementation for the subclass is visible. Place the cursor at the point in the source file where you want the accessors to be inserted, and then choose Edit > Paste Attribute Implementation. Xcode will generate and insert valid accessor code in the desired location. You can repeat the process for the header file (the menu item will be Paste Attribute Interface in this case).

Using the Assistant

When editing a data model, additional Assistant behaviors are revealed. In this case, the Assistant shows only source code files that are associated with (or hold references to) custom NSManagedObject subclasses defined in your workspace and used in your managed object model.

Automatic behavior shows the files that Xcode considers to be the best choice for the data model or the selected entity.

Runtime Classes behavior shows all custom NSManagedObject subclasses defined in your workspace that are used by your managed object model.

References behavior shows any files containing references to any NSManagedObject subclasses defined in your workspace that are used by your managed object model.

Wrapping Up

Core Data and Cocoa Bindings are a complex set of Cocoa topics. You’ve only scratched the surface of creating a very simple data model and accompanying UI with Xcode. In the next chapter, you’ll learn how to give TestApp a custom icon.

11. Customizing the Application Icon

Both Mac OS and iOS use the same icon file format (.icns). Icon files are used primarily for application and document icons but can be used as standard images in your application like any other image format. In this chapter, you’ll learn how to use the Xcode Tools utility application Icon Composer to turn your artwork into icon files, as well as how to use these icons in your application.

Picking the Ideal Artwork

The ideal artwork for a Mac OS or iOS icon is a PNG (.png) or TIFF (.tif) image. The image should use transparency to let the background show through “empty” areas of your design. You should also have a version of the artwork in 512×512, 256×256, 128×128, 64×64, 32×32, and 16×16 sizes, each with an appropriate amount of detail for its given size. Though it takes more effort, this multisize approach helps the operating system maintain a crisp image no matter the size of the icon when displayed.

For the examples in this chapter, I’ve created a simple piece of artwork that communicates the “test” nature of TestApp.

Creating Icons

The Icon Composer application (found in the same folder as Xcode, under the Utilities subfolder) takes your artwork and generates an .icns file. Launch this application, and you’ll be presented with an empty document with a series of wells (one for each of the sizes listed in the previous section).

Creating the Icon Document

Drag your artwork into each of these wells. This would be the point where you drag the appropriately sized artwork into the matching well if your graphic designer has created icons with varying detail for each size. Otherwise, just drag the largest copy of the artwork you have into each well (Figure 11.1).

Figure 11.1 A filled-in Icon Composer document

Testing and Verifying the Icon

Icon Composer provides a way to examine your icon at various sizes against various backgrounds. This allows you to make sure the drop shadow and alpha transparency look correct, and it shows how fine details appear when the icon is sized too small for such detail to survive (Figure 11.2).

Figure 11.2 The new icon downsized against a desktop background image

To use this feature, click the Preview button along the bottom edge of the icon document. You can then manipulate the pop-up to choose a background, and the slider to vary the size of the document.

Saving the Icon

When you’re satisfied, save your document icon somewhere sensible. Give it a name such as TestAppIcon.icns. You can now use it to set your application’s icon using Xcode.

Setting the Application Icon

Switch to the TestApp project in Xcode, and select the main TestApp project item at the top of the Project navigator. Under the Targets list, you should see the TestApp target. Select the TestApp target, and your project window should look like Figure 11.3. The App Icon image well claims “No image specified.”

Figure 11.3 The TestApp target editor with no application icon

Note

You will further explore configuring a target in Chapter 14.

To set the application icon, drag the icon file from wherever you saved it and drop it onto the App Icon image well. Because the icon file will become part of the project, you will be prompted to add it with the Add Files sheet you encountered in Chapter 6. Leave the Add Files sheet’s default options and click Finish. The icon will appear in the image well and the file is added to the Project navigator. Since Xcode puts it at the root level of the project, now is a good time to file it properly by dragging it into the Resources folder of the Project navigator.

You can now run the program. Note that the new icon appears in the Dock. You can also choose About > About TestApp from the main menu to see the About panel. It should look like Figure 11.4.

Figure 11.4 TestApp’s About panel showing the new icon

Setting Document Icons

When working with document-based Cocoa applications, you’ll need to add document types (covered in Chapter 14) that the application recognizes. Setting a document type’s icon is just as easy as setting its application icon.

After selecting the target as you did in the previous section, click the Info tab at the top of the editor. Expand the desired document type (or add one; again, see Chapter 14) and note the image well similar to the App Icon well (Figure 11.5). Drag the desired .icns file into the well, and let Xcode add the file to the project. Documents of this type will use this icon when created or edited with your application.

Figure 11.5 A custom document type

Wrapping Up

In this brief chapter, you learned the simple process behind creating and using icons. This is often one of the final touches before deploying an application. In the next chapter, you’ll learn how to configure Xcode to build a deployment-ready application.

12. Deploying an Application

To deploy an application, you must build it in Release mode. Whether you’re turning the application over to an employer, selling it on your own Web site, submitting it to Apple’s App Store, or just sharing it with a friend, your application must be built for release. In Xcode 4, this is accomplished most directly with the Archive action.

Archiving

In previous versions of Xcode, you would switch between Debug and Release modes and then build the application for that mode. Xcode 4 introduces the Archive action, which automatically builds in Release mode and packages the build target along with its dSYM files (containing separate debugging information for analyzing release-built applications) into an archive file.

Creating the Archive

Open the TestApp project if it’s not already open. To perform the Archive action, choose Product > Archive from the main menu. Xcode will build in Release mode and then archive any built products that are part of your project or workspace in addition to their corresponding dSYM files.

Finding the Archive

The archives of any given project are stored in the default Archives folder Xcode creates. The default folder is ~/Library/Developer/Xcode/Archives. You can change this and other locations in the Locations panel of Xcode’s preferences (Figure 12.1). Archives are stored at the path labeled Archives Location. You can click the arrow button to the right of the path to open the folder in the Finder. Archives are organized by date (under folders named in YYYY-MM-DD format) and then by project name.

Figure 12.1 The Locations preferences panel

The Archives tab of the Organizer (Figure 12.2) serves as a collection point and browser for the archives you create. Using the Organizer, you can annotate the archives as well as share them with others or submit them to the App Store. To open the Organizer, click the Organizer button in the toolbar or choose Window > Organizer from the main menu. When the Organizer window appears, select the Archives tab.

Figure 12.2 The TestApp archive in the Organizer

Examining the Archive

Currently the only available archive format is the Xcode Archive (.xcarchive) format. An Xcode archive file is a package (a folder that appears to be a single file). This means you can view its contents in the Finder as well. To do this, right-click (or Control-click) the archive file and choose Show Package Contents from the context menu.

Inside you’ll see the dSYM folder, the Products folder (where the built application resides), and an Info.plist file. The .plist (property list) file, which can be opened in Xcode’s Property List Editor (Figure 12.3), contains a description of the package’s contents.

Figure 12.3 The Info.plist file in the Property List Editor

To find the application (TestApp.app), navigate through the Products folder. The products are placed in a folder structure mirroring that of the Installation Directory build setting for the target (see Chapter 14). When you get to the end of the trail of folders, you should see the TestApp application bundle, along with the icon you added to it in Chapter 11 (Figure 12.4).

Figure 12.4 The TestApp.app bundle in the Xcode archive file

Testing the Application

A lot can be said on the subject of thoroughly testing an application before deployment, but that is beyond the scope of this book (except unit tests, which are covered in Chapter 18). For now, you can verify that the application launches and performs the functionality you added in previous chapters. When you’re satisfied that TestApp says hello when asked and properly manages, saves, and loads a list of task items, quit the application.

Sharing the Application

Use the Share button in the Organizer’s Archive tab to let Xcode help you share the application with others by saving it to a readily accessible location. Alternatively, you can navigate to the application itself and create a zip file with it. To do this, right-click (or Control-click) the application and choose Compress “TestApp” from the context menu. A zip file will be created, which you can easily transmit.

Tip

Zipping any package or bundle, including .xcarchive and .app files, is a good idea since most e-mail systems and many file systems can mangle them.

Submitting to the App Store

To submit to the App Store, you must first have signed up for one of Apple’s developer programs and have provided Apple with the required information for eligibility to sell products in the store. Contact the Apple Developer Relations department if you’re unsure about your status.

Before submitting, you’ll need to validate the app. Validation is a series of tests Xcode 4 runs as a simple way of helping make sure your application isn’t doing something or using code and resources Apple does not approve of. It’s wise to perform this step prior to submission. To validate the app, click the Validate button in the Organizer’s Archive tab and follow any instructions it gives.

Once you’re satisfied, click the Submit button to submit the application to the App Store for review and (ideally) eventual acceptance.

Alternatives to Archiving

Although the Archive action makes App Store submission easier, it makes getting at your built application to package it for other purposes slightly less convenient. Independent Mac developers, for example, have their own staged archive folders into which they dump the latest release build. This folder may include a “quick start guide” in PDF format, a .webloc (web location file) shortcut to their site, and other marketing goodies. This folder is archived as a zip file or disk image to form a user-friendly downloadable.

Xcode 4’s Archive action does not currently provide enough options to support this level of customization. Until the Archive action is built up with more options, the best workaround for independent developers is to create your own scheme to perform all of this staging with your own custom packaging and accoutrements. Alternatively, you can add minimal convenience in the form of a script at the end of the Archive action, which opens the built product’s enclosing folder within the archive in a Finder window.

All is not lost, however. An important set of environment variables was added to Xcode’s build system that can be used within build scripts to manipulate aspects of the build environment. These are ARCHIVE_PATH, ARCHIVE_PRODUCTS_PATH, and ARCHIVE_DSYMS_PATH. Arguably ARCHIVE_PRODUCTS_PATH is the most important, since it makes it relatively easy to extend the Archive action to build your own custom archives alongside those that Xcode curates.

See Chapter 14 for an overview of the new Schemes system. For more ideas regarding how to customize the build process to perform extra tasks, see Chapter 19.

Wrapping Up

In this brief chapter, you learned how to create a release build of your application and archive it for sharing or App Store submission. You also learned there are alternatives for further customization and that Xcode’s Archive action certainly leaves plenty of room for improvement. You’ll revisit the topic of alternatives in Chapter 14. In the next chapter, you’ll discover some more features available to you in the Source Editor.

Part III: Going Beyond the Basics

13. Advanced Editing

In Chapter 7, you explored the Source Editor and some of its features. In this chapter, you’ll explore a few more powerful features and familiarize yourself with some additional tips and tricks to make better use of the editor.

Renaming Symbols

The Edit All in Scope command is a simple and often overlooked editor feature. As its name suggests, you can edit a symbol name and automatically change each instance of it within the current scope at the same time.

Consider a local variable named bob. You’ve decided a variable should sound more formal, so you want to change bob to robert. Assuming bob is reused throughout the current scope of a long method, it would be tedious and error-prone to find and rename each instance, even though they’re temporarily underlined when one instance is selected. To formalize bob, you can click the symbol, placing the insertion point somewhere inside its text. All instances of bob within the current scope then appear with a dotted underline (Figure 13.1).

Figure 13.1 All instances of the symbol bob underlined

If you hover your mouse pointer over any highlighted bob, you’ll notice a button appears immediately to its right. Click this button to open a context menu, and select Edit All in Scope. Xcode responds by highlighting each bob in the current scope, ready to edit them all. Begin typing to replace the text, or move the cursor around within the highlighted text to modify it. In this example, every instance of bob has been renamed to robert (Figure 13.2).

Figure 13.2 In the current scope, bob is now robert.

Click to place the text insertion point somewhere outside the symbol to end editing. Note that only the symbol name changed. It remains a pointer to the string literal @”Bob”. You could further edit the symbol to give robert a sex change. Repeat the procedure, but instead of replacing the text, place the cursor after the t in robert and then add an a. The symbol should now be roberta, who is suddenly in need of a new wardrobe or at least a new string literal.

It’s important to note that this operation works only within the current scope. You cannot use this feature to rename an instance variable or a method.

Refactoring

The programming term refactor is perhaps overused but in general means to “repurpose” or “reengineer” code or even architecture. Xcode’s Refactor function allows you to modify code in an intelligent way.

In the previous section, you learned how to rename symbols within a given scope. The Edit All in Scope function is a more surgical approach than a blind search and replace, since replacing all instances of the common iterator i, for example, would likely make a mess of anything containing the letter i. Still, renaming symbols is limited to the current scope, so you cannot rename an instance variable.

The Refactor function goes a step beyond Edit All in Scope, using its knowledge of your code base to make more intelligent decisions about your code, simplifying common but error-prone refactoring tasks.

Refactoring Options

You can find the various types of refactoring Xcode can automate for you in the Edit > Refactor menu.

Rename

Rename works in much the same way as Rename Symbols, with one exception: It is not limited to scope. This distinction means you can rename an instance variable. In the case of an Interface Builder outlet, Rename will update the outlet in your xib as well (a huge time-saver). In the case of a class, filenames themselves can also be automatically changed to match.

Extract

Extract takes a selected block of code and creates a method or function (depending on your choice) with it. If the code block depends on local variables, they will be converted to arguments of the method or function.

Create Superclass

Create Superclass does just as the name suggests—it creates a superclass from the selected class. You can choose to place the declaration and implementation in the selected class’s files or in their own new files.

Move Up/Move Down

Move Up takes the declaration and implementation of the selected item and moves them to a superclass. Move Down moves the selection to one or more subclasses of the current class.

Encapsulate

Encapsulate creates accessor methods (getters and setters) for a selected instance variable and changes all direct references to them so the accessors are used instead.

Modernize Loop

Modernize Loop converts while or C-style for loops to Objective-C 2.0 for loops.

Convert to Objective-C 2.0

Convert to Objective-C 2.0 modifies the code in the selected source files to take advantage of Objective-C 2.0 features. This includes modernizing loops and converting accessor methods to properties and synthesized accessors.

Using Refactor

To familiarize yourself with the Refactor feature, you can rename the NSTextField outlet you created in Chapter 5 from textField to a more descriptive helloTextField. To begin, open the TestApp project and navigate to the TestAppAppDelegate.m file. Double-click the textField symbol on line 13, and select Edit > Refactor > Rename from the main menu. A sheet will appear similar to Figure 13.3.

Figure 13.3 The Rename sheet

Change the name to helloTextField, and click Preview. Xcode will present a preview sheet similar to Figure 13.4 and analyze your project to locate all references to the symbol. You can use the Rename preview sheet to verify and cherry-pick individual replacements.

Figure 13.4 The Rename preview sheet

You can use the list on the left side of the window to jump directly to each instance that will be renamed. Each item has a check box that lets you choose whether that file will be included in the renaming changes. In this case, there are three files that will be modified: TestAppAppDelegate.h, TestAppAppDelegate.m, and the English version of MainMenu.xib. The right pane shows two versions (“before” and “after”) of the selected file. If you select TestAppAppDelegate.m in the list, you’ll notice two red tick marks in the track of the scroll bar. These indicate the places within the file where the symbol is referenced or defined (where changes will be made). Click Save to make the changes.

If you examine all three files (right-click the text field in the xib to examine its referencing outlets), you’ll notice the change has been applied. You should now be able to build and run the application to test it. Click the Say Hello button to make sure the greeting still appears in the renamed field.

The process is similar for each of the available Refactor actions. Though the preview sheet works the same, the initial sheet (shown in Figure 13.3) will contain the various options available for each action.

Tip

Not all refactoring actions can be carried out without your intervention. The Issues button above the change list can be used to explore any problems that Refactor anticipates with performing the proposed action.

Organizing with Macros

Xcode includes CPP, the C preprocessor, through which your code is run just prior to compilation. The preprocessor transforms your code wherever macros are encountered. For example, when it encounters an #import directive, the preprocessor replaces it with the referenced file (nearly always a header file) so its contents are available to the compiler.

A less obvious use of preprocessor macros is for organization within a graphical editor. Using the #pragma mark directive, you can define areas within your source file. When you have this file open in the Source Editor, the last segment of the Jump Bar (which, as you’ll recall, lists class members for easy navigation) will reflect your marks by grouping them in its pop-up menu. For example, Figure 13.5 shows one possible organization of the TestAppAppDelegate.m file.

Figure 13.5 The Jump Bar pop-up organized using #pragma mark

To use the directive, just place it (along with a name for the section) on a blank line by itself as follows:

#pragma mark Constructors / Destructors

You can go a step further and place a separating line in the menu by using a dash as the mark as follows:

#pragma mark –

There is no defined standard dictating how you should use this directive, nor does it have any effect on your compiled code (it is not part of the compiled code). Although it’s easy to get carried away and pepper your code with marks, most take a minimalist approach and group methods by their primary function.

As an example, you might create a section for UI actions in a controller class, another section for model manipulation methods, another for initialization and deallocation, and another still for accessors. Figure 13.5 roughly follows this general approach. Your style may vary.

Changing Editor Key Bindings

Although the focus of the Key Bindings preferences panel (Figure 13.6) is not limited to the Source Editor, it’s worth pointing out that you can customize even the most basic Mac OS text editing and navigating keyboard shortcuts in Xcode 4. Developers familiar with the shortcuts of other environments will find this invaluable.

Figure 13.6 The Key Bindings preferences panel

To open the Key Bindings preferences panel, choose Xcode > Preferences from the main menu and then select Key Bindings from the toolbar. The left side of the panel provides controls for managing command sets you create or customize. The right side lets you locate and customize shortcuts.

The shortcuts are grouped by function in the list. You can filter the list using the search bar at the top. To the left of the search bar, you can choose to show only menu- or text-editing shortcuts.

Note

The shortcuts for most any item in Xcode’s menu can be customized (or added if none yet exist). The list of customizable shortcuts is quite extensive and worth a few minutes of your time to browse.

Managing Command Sets

You can think of command sets as “keyboard shortcut profiles.” For example, if you were nostalgic (or stubborn), you could create a command set whose text shortcuts match those of Vim or CodeWarrior.

Use the + and - buttons at the bottom of the list to create or remove command sets. Although not really obvious, the currently selected command set is the one currently in effect and is persistent. To switch to a different command set, just select it.

Customizing Shortcuts

To customize a shortcut, double-click the field in the Key column next to the shortcut. The field will become highlighted, and + and - buttons will appear near its right side. The - button removes a shortcut, and the + button lets you add shortcuts (so multiple shortcuts can fire the same action). To set a shortcut, press the key combination you’d like and then click outside the field to end editing (or press the + button to add another).

Jump to Definition

The Source Editor hides a simple navigational shortcut you won’t be able to live without once you know it’s there. Although not strictly an editing feature, the need to navigate to the definition of a symbol (possibly one of many) while writing your code is common. Xcode makes this simple. Hold down the Command key and hover the mouse pointer over any symbol to turn the symbol into a hyperlink. Click the link (while still holding down Command) to navigate to the symbol’s definition (or implementation). When multiple definitions exist for the clicked symbol, a pop-up similar to Figure 13.7 appears, listing all known definitions of the symbol (and the file and line number where each appears). Select any definition to navigate to it.

Figure 13.7 Various definitions of a symbol in the Jump to Definition pop-up

My Company Name

Very few developers are likely to work for a company called “My Company Name,” yet Xcode insists on inserting this in the copyright block at the top of any source files it creates. If you’re not currently employed by My Company Name, it’s wise to change the Organization field associated with the project so the copyright of newly created files reflects your actual organization (or even just your name).

To do this, select the project itself (the top-level object) in the Project navigator; then open the Utility area and select the File Inspector pane. Under the Project Document section, type the name of the desired copyright holder in the Organization field. Any source files Xcode creates from that point forward will insert that name instead of the standard __My Company Name__ placeholder.

Wrapping Up

This gentle introduction to the more advanced (or simply less common) aspects of Xcode 4 has given you a handful of powerful Source Editor features. These features offer elegant solutions to tedious and error-prone editing tasks developers encounter often when writing or maintaining code.

In the next chapter, you’ll learn about Xcode 4’s new Schemes system and how to customize the build and archive process, set up target dependencies, and more.

14. The Build System

Xcode 4 offers an overhauled user interface for its build system that de-emphasizes switching between separate build configurations for Debug and Release and focuses more on what developers spend most of their time doing within the IDE: coding and debugging.

Developers are meant to handle release builds with the Archive action. The Archive action in version 4.0 is heavily biased toward the preparation of a release build for sale in Apple’s App Store. Fortunately, the new build system UI is flexible enough to offer the full functionality with which veterans are familiar. There is nothing preventing you from creating a build scheme that generates a release build and bypasses the Archive action entirely.

An Overview

Let’s take a brief tour of the terminology before exploring each term in depth. The end result of a build is some sort of product—an application, a plug-in, a command-line program, a framework, or a library.

Targets

A target describes a product (an application, a plug-in, a library, a unit testing bundle, or an aggregate of other targets) to be built and the instructions for building it. The instructions specify source code and resource files within the project, build settings, phases, and rules. A project might contain more than one target. For example, a project might contain targets for a desktop application, a companion command-line program, and a library of shared code used by both. A target can also specify another target and a script to run, giving you the ability to create a “deployment package” target.

Schemes

A scheme describes one or more targets to build, a configuration to use when building them, custom build scripts to execute before and after a given action, and tests to execute against the target (see Chapter 18). A project will have at least one scheme but can contain as many as you need. A scheme can be shared with others who use the project or workspace and can be exported for use in other, unrelated projects to save the trouble of re-establishing settings used commonly in your organization. Xcode will also create new schemes as you add targets (a feature that can be disabled in the Manage Schemes sheet). Schemes (and a corresponding run destination) are selected when building and running applications in order to specify which target and dependencies to build with what configuration, and in what environment to run the built product.

Build Settings

Build settings include the target architecture and SDK, the location of intermediate build files, compiler selection (LLVM versus GCC, for example), linker settings, search paths, and more. The settings can be project-wide or target-specific, and a separate value can be defined for a given configuration (Debug versus Release, for example).

Configurations

A configuration describes a collection of build settings for the build environment. By default, an Xcode project has two configurations: Debug and Release. The configuration Xcode uses when performing a given action (such as Run, Analyze, or Archive) is dictated by the settings in the active scheme. For example, the Run action of the default scheme of a Cocoa application project would use the Debug configuration, while the Archive action would use the Release configuration. Common configurations can be exported and imported to enable sharing and reuse between an organization’s projects.

Run Destinations

A run destination describes the environment in which to run an executable product (that is, a target that specifies an application or command-line program). The environment can be your Mac (in 32-bit or 64-bit mode), the iOS Simulator, or an actual iOS device. The available run destinations shown in the Scheme controls are determined automatically by the build settings specified for the associated target—specifically, the combination of settings specified in the Supported Platforms, Architectures, and Base SDK build settings.

Build Phases

A build phase is a stage in the build process of the current target (build dependencies, compile, link, copy resources, run a postprocessing script, and so on). In addition to the standard compile, link, and dependencies phases, you can add phases to a target, such as Copy Files or Run Script. This can be a simple way of adding the additional step to the target’s build process, such as copying an embedded framework into an application bundle. It can also provide a hook for more-complex manipulations during the build process using shell scripts. See Chapter 19 for more details regarding customizing the build process.

Build Rules

A build rule defines associations between a type of file (such as a C or Objective-C source file) and the program used to compile or process it. The default build rules for common file types are target-independent, but you can define target-specific rules as well. You might define a custom build rule for a new file type Xcode does not know how to handle or to specify an alternative tool to use (or the same tool with different arguments) when handling that file type.

Working with Targets

Since a target represents a built product (or an aggregate of other targets), it’s an “end result” of your coding efforts. Xcode 4 provides template targets for the most common types of target, such as Mac or iOS applications, command line programs, frameworks, and so on (Figure 14.1).

Figure 14.1 The target template chooser

Numerous other target templates exist for less common tasks as well. These include system plug-ins for Spotlight importers, screen savers, device drivers, and others (Figure 14.2). Templates exist for specific applications bundled with the Mac OS as well, including Address Book, Automator, and WebKit.

Figure 14.2 Other target types

Finding Your Project’s Targets

When you create a new Xcode project, an initial target is created and configured for you, sharing the name you specified for your project. You can find every project’s targets by selecting the project itself in the Project navigator (Figure 14.3). You’ll recall the target view in Figure 14.3 (the result of selecting the TestApp target in the Targets list) from Chapter 11.

Figure 14.3 Selecting a project’s target

Note the other target in the list: TestAppTests. This particular target produces a .octest bundle, which Xcode uses to run unit tests (see Chapter 18). Note the different icon—a building block signifying a plug-in bundle.

Project-Wide Settings

Selecting the TestApp project under the Project group reveals project-wide settings. These settings serve as the “global” settings used by the targets defined within it.

The Info tab reveals three main groups: Deployment Target, Configurations, and Localizations.

The Deployment Target group currently holds only one setting (depending on the platform—Mac OS or iOS): the minimum OS version for which your project’s targets are built.

The Configurations group lets you define the configurations available to your targets. As mentioned at the beginning of the chapter, Xcode creates Debug and Release configurations (and appropriate build settings for each) by default. Here you can add, rename, or remove configurations as desired. At the bottom of this group is an option to specify which configuration command-line builds use when builds are initiated using Xcode’s command-line interface (which is beyond the scope of this book).

The Localizations group lets you specify to which languages your Cocoa applications are localized, which helps you automatically manage the individual copies of user interface and other resource files that are specific to a language. Localization is also beyond the scope of this book.

Exploring a Target

Application targets (a standard Mac or iOS Cocoa application bundle) have the most settings, so the TestApp target is a good one to explore. Make sure you’ve selected it, as in Figure 14.3. You’ll explore each tab along the top of the editor, starting with the Summary tab.

The Summary Tab

The Summary tab displays the basic information—mostly reflecting the options you chose when you created the project—in the top panel, titled Mac OS X Application Target. The Application Category pop-up menu is used to categorize the application if you plan to sell it in Apple’s App Store. The Identifier field is the canonical name you chose (which should correspond to your organization’s domain name in most cases). The Version number is the string that the Finder and the application’s About panel display for the application. The deployment target specifies the version of Mac OS for which your application is built. The image well, as you learned in Chapter 11, holds the application’s icon (and sets its corresponding configuration entry when a new .icns image is dragged into it).

The next section, Linked Frameworks and Libraries, displays (and lets you edit) the frameworks and libraries to which your application is linked. This affects the Link Binary With Libraries build phase in the Build Phases tab. The Add (+) and Remove (−) buttons let you edit this information directly. Clicking the Add button reveals a searchable list of libraries and frameworks available on your computer from which you can choose (Figure 14.4). You can also choose Add Other from this sheet to locate a library or framework not present in the default locations that Xcode knows to search.

Figure 14.4 Choosing frameworks and libraries against which to link a target

For iOS targets, there are some differences in the Summary tab. In Figure 14.5, you’ll notice a Devices pop-up under the iOS Application Target group. This lets you select whether your project produces an application for iPhone, iPad, or both (a “Universal” application). Under the Deployment Info group, you’ll see options (enabled by pressing them) to specify which orientations your application supports—that is, which directions will your applications follow when the user rotates the device. The App Icons wells work the same way as the App Icon well in a Mac OS target, except the second well (marked Retina Display) holds a high-resolution version of the icon, appropriate for the high-resolution Retina display in newer devices. The Launch Images wells are used to specify the images used at launch time (one for normal resolution and one for high-resolution Retina displays).

Figure 14.5 The Summary tab (for iOS targets)

There is one more section, named “Entitlements.” Entitlements are explored in more detail later in this chapter.

The Info Tab

The Info tab (Figure 14.6) lets you edit the information contained in the app bundle’s Info.plist file—the file Cocoa bundles use to describe themselves to the operating system. This file contains some of the information you can manage on the Summary tab, but it’s got a great deal more responsibility.

Figure 14.6 The Info tab

The editor is much like the one used to edit .plist (property list) files. You can see this for yourself by navigating to the TestApp-Info.plist file under the Supporting Files group. You’ll see something similar to Figure 14.7—a simple property list editor. Navigate back to the target’s Info tab, and you’ll see the difference: This particular editor is custom tailored to work with Cocoa bundle property lists and automatically loads the contents (the same as in TestApp-Info.plist) and organizes the interesting parts into sections.

Figure 14.7 The property list editor

The Custom Mac OS X Application Target Properties section lists all the basic parts of the property list that define your unique application (including version number, the principal class used to load the application, the main nib or xib file to use, and so on). Selecting an individual row reveals more aspects of the editor (Figure 14.8). Each row’s type (the key used to specify its corresponding value) can be edited by clicking the arrows to reveal a list of other available keys (Figure 14.9). Double-clicking a key or value lets you edit each directly. See the “Bundle Structures” section of the Bundle Programming Guide in Apple’s documentation for more information about the keys used and their meaning.

Figure 14.8 More (to the row) than meets the eye

Figure 14.9 Choosing keys

The Document Types section holds any document types defined for your application. Since TestApp is not a document-based application, this section is empty by default. That’s not to say a non-document-based application can’t be given document types that it can recognize and provide viewing or editing capabilities for, however. Figure 14.10 shows an example of what some custom document types might look like.

Figure 14.10 Some example document types

The Exported UTIs and Imported UTIs sections (also empty) let you define any UTIs (Uniform Type Identifiers) your application imports or exports. Defining UTIs here is a way of letting your application “claim” (and provide icons or system services for) a particular data type as well as define new data types and lineage that your application provides. See the Uniform Type Identifiers guide in Apple’s documentation for more information.

The URL Types section allows you to define URL schemes your application understands. An example might be a URL that takes the form of testapptask://taskid and causes your application to be launched and display the task with the specified taskid. See the Launch Services Programming Guide in Apple’s documentation for more information.

The Services section lets you define system services (such as Insert Employee ID Here), which can be accessed from other applications. See the Services Implementation Guide in Apple’s documentation for more information.

The Build Settings Tab

The Build Settings tab (Figure 14.11) contains all the build settings for the selected target, grouped by category. The simplest view, as shown in Figure 14.11, can be seen by setting the filter bar (just beneath the tab bar) to show Basic and Combined. This instructs the editor to show you only the most commonly used settings and only the values for the selected target.

Figure 14.11 The Build Settings tab

For each setting, you can edit the matching value under the column named after your target. Some values are simple strings while others are presented in a pop-up menu. In cases where you can make more than one selection (such as the Architectures setting), you can select Other from the menu and you’ll be presented with a pop-up window (Figure 14.12) that allows you to add multiple selections. In the figure, an environment variable is used that, to Xcode, means the standard 32/64-bit universal binary.

Figure 14.12 A multiple-selection pop-up window

You can also have per-configuration settings. That is, separate settings for Debug versus Release configurations (or any others you define). In Figure 14.13, you see that the Strip Debug Symbols During Copy setting has an open disclosure triangle next to it and has separate settings for the two configurations—Debug and Release. It would be pointless to remove debugging information from a debug build, so the build system will strip debug symbols only from a release build, leaving them intact for debug builds. This is an excellent example of why different configurations (or at least separate settings for debug and release) are necessary. The information is removed from a release version to reduce the size of the executable and to improve performance.

Figure 14.13 A per-configuration setting

Note

The disclosure control appears only for settings that already have per-configuration values defined.

For projects with multiple targets (or workspaces with multiple projects), you may need finer control than you get by choosing Combined versus Levels in the filter bar. Choosing Levels reveals multiple columns after the Setting column, showing what the settings are for each “level” (Figure 14.14). From right to left, the columns represent global defaults down to project- and target-specific settings.

Figure 14.14 Build settings arranged by level

Starting from the right and working to the left, you see the default settings for the platform (Mac OS Default). These settings cannot be edited because they are the same for every Mac OS target. All levels below this one inherit its settings. Project- and workspace-level settings come next, then target-level settings. The Resolved column shows the final state of all inherited settings for the selected target.

The simplest example of the usefulness of multi-level inherited settings is the Product Name setting (exposed by the Packaging disclosure triangle). Each target produces an application bundle or executable, which must have a name. No two targets are likely to share the same name, so each target would have its own non-inherited name. Of course the product name isn’t specified at the OS or project levels. An example of this can be seen with the Wrapper Extension setting (also in the Packaging settings). An application bundle always gets an extension of .app. Other bundle types would have different extensions. Take a look at the same setting for the TestAppTests target. The Mac OS Default setting is .bundle; at the target level it’s .octest.

When viewing settings arranged by level, settings defined for a given level are outlined in green (also seen in Figure 14.14). You can see this in the Product Name setting. If a value is overridden further down the hierarchy (working toward the left), that value is also outlined in green. This helps you determine the level at which a setting is customized and, when considered with the Resolved column, lets you easily determine the precise setting for your individual targets.

You can also add user-defined build settings by using the Add Build Setting button at the bottom of the editor. This lets you further customize the build process by passing custom settings not shown in the editor. User-defined settings appear at the bottom of the list in a group called User-Defined. For example, you might want to include a “This app is BETA!” user interface element for beta builds. You might add a “Show Beta UI” setting with a value of Yes if building a beta release (using a “Beta Release” configuration you can add to the project’s Configurations), or with a value of No otherwise. You can use the preprocessor to check the value of this setting at compile time and include or exclude your custom “add the beta UI element” code. See Chapter 19 for more information on using similar approaches.

There are many settings in this tab that affect the build environment, the built product, and even what kinds of errors and warnings the build system should respect or ignore. The depth and breadth of these settings is beyond the scope of this book, but it’s worth noting that the Quick Help pane of the Utility area will give you detailed information on each. Just select the setting in the editor and the Quick Help pane will provide an overview of the setting, its options, and its implications.

The Build Phases Tab

The Build Phases tab (Figure 14.15) lets you manage, add, and remove build phases for your target. The available phases depend on the type of target you are building. For example, only bundles can have bundle resources (such as images, sounds, Help Book files, and so on), so the build phase would not be used for a command-line tool.

Figure 14.15 The Build Phases tab

You can add phases using the Add Build Phase button at the bottom of the editor. Those that are removable can be removed by clicking the remove (x) button in the upper-right corner of the phase’s table.

The first build phase—Target Dependencies—is the one phase that cannot be removed. This special phase lets Xcode know of other dependencies (such as a framework or plug-in for an application) that must be built before the currently selected target can be built. This build phase defines implicit dependencies as opposed to allowing Xcode to determine target dependencies automatically as configured in the active scheme. You can add and remove targets (any target except the selected one, for obvious reasons) for this phase using the Add (+) and Remove (−) buttons at the bottom of the phase’s table.

The Compile Sources phase compiles any source files belonging to your target using the appropriate compiler for the file type as defined in the Build Rules. You can set compiler flags (such as optimization settings like -funroll-loops or -O3) for each individual file by double-clicking in this phase’s Compiler Flags column, typing the flags, and then pressing Return. You can add source files to and remove source files from this phase using the Add (+) and Remove (−) buttons at the bottom of the phase’s table. This phase seems like it should not be optional, however if you recall that there can be aggregate targets and other types, you can see why this phase is not always necessary.

The Link Binary With Libraries phase lets you control which libraries your product is linked against using the linker. While it’s true you don’t have to use a library or framework in your source code to make use of it in your application (because it might be used from an instantiated object in your xib), you’ll always have to link against it if you use it at all. By default, all Cocoa applications are linked against the Cocoa framework, which explains the framework’s presence in the TestApp target. When using additional libraries and frameworks, it’s easiest to add them here. You can add and remove linked libraries and frameworks for your product using the Add (+) and Remove (−) buttons at the bottom of the phase’s table. Pressing the Add button reveals the same Frameworks and Libraries sheet you saw in Figure 14.4, from which you can select the library or framework to which to link.

The Copy Bundle Resources phase copies any resources included with your bundle into a ../Contents/Resources folder relative to your bundle’s file path (the standard location for resources in any type of Cocoa bundle). Resources include application and button icons, video and sound clips, template files, and so on. Notice the TestAppIcon.icns file you added to the project in Chapter 11 is included in this phase, ensuring it will be available as a resource to the application at runtime and to the Finder when displaying the application in the file system.

Note

Linking is accomplished using a “linker,” which can be the ld command, evoked by the GCC (GNU Compiler Collection) compiler, or llvm-ld, evoked by the LLVM (Low Level Virtual Machine) compiler.

There are three other types of build phases that you can add to your target using the Add Build Phase button at the bottom of the editor. These phases don’t show up by default for a standard Cocoa application target.

The Copy Files phase (Figure 14.16) lets you identify a path into which to copy the files you specify. You can choose a predefined destination path from the Destination pop-up or specify a custom path. Most often, a Copy Files phase would specify a location within a bundle (the bundle built by the target), but this phase can be used to copy files or even built products to a variety of locations. Predefined paths include a bundle’s Resources or Frameworks folders, the Shared Frameworks system path, and more. It’s not uncommon to have multiple Copy Files build phases in a target. For example, you may specify a framework you either built yourself or are including from a third-party source, and choose to copy it into the application bundle’s Frameworks path so the framework is available to the application at runtime (see Chapter 15). You might also add a Copy PlugIns build phase, with which you can copy a set of built plug-ins included with your main application into the application bundle’s PlugIns folder. The Subpath field lets you append a subpath to whichever path you’ve selected in the Destination pop-up. The “Copy only when installing” check box instructs Xcode to copy the files only when your current scheme’s build settings include the install flag. The Add and Remove buttons work the same way as in the other phases, allowing you to specify the files that are copied to the selected location.

Figure 14.16 The Copy Files build phase

The Run Script phase (Figure 14.17) lets you run any script (by typing in the script editor field or dropping a script file into it). Again, you might have multiple Run Script phases in a given target. The Shell field lets you choose the shell you wish to use (it defaults to sh). Using the check boxes beneath the script field, you can choose whether to show the script’s environment variables in the build log and whether to run the script only when installing. You can specify input files from which your script can pull information, as well as output files into which the script’s results can be placed.

Figure 14.17 The Run Script build phase

The Copy Headers phase (Figure 14.18) lets you specify header files and their visibility for products such as frameworks, plug-ins, or drivers. The scopes (Public, Private, and Project) determine the visibility of the header in the built product. A public header is included in the product as readable source code; a private header is included in the product but is marked as private so clients know not to use its symbols directly; a project header is not included in the product and is meant to be used only by the project when building the target. The Add and Remove buttons work the same way as in the other phases, but in this case, when you add, you’ll see a sheet similar to Figure 14.4, but which lets you select only header files. Once added, a header will first appear in the Project scope. You can then drag it into Private or Public scope as desired.

Figure 14.18 The Copy Headers build phase

The Build Rules Tab

Xcode maintains a default list of predefined (system) rules that determine which file types are processed by which script or program during the build process. This is found under the Build Rules tab (Figure 14.19). For example, C source files are compiled using GCC System Version (which is LLVM GCC 4.2 in Xcode 4.0). The Build Rules tab lets you customize these rules or define new ones for the selected target.

Figure 14.19 The Build Rules tab

With the filter bar set to All, you see all the default system build rules and any target-defined rules. Set the Build Rules tab’s filter bar to Target to see the rules overridden or defined only for the target (that is, to filter out the default system rules).

To customize a system build rule for a given file type, locate it in the list and click its Copy to Target button. The new custom rule will be added to your target, ready for you to specify the script or predefined program to use to process the file type. You can also add a rule to your target for a file type not covered by the system rules by clicking the Add Build Rule button at the bottom of the editor.

As an example, pretend you want to let Xcode compile some Pascal files (with a .pp extension) and that you have Free Pascal (www.freepascal.org) installed. Figure 14.20 shows a possible rule for this scenario. You could add a build rule (using the Add Build Rule button) and choose “Source files with names matching” from the Process pop-up and specify .pp as the text to match. The Using pop-up could be set to Custom Script, and the script body itself could merely call fpc (the Free Pascal compiler program) with your .pp source file as its argument. Now, for this target, Xcode can recognize and properly compile Pascal source files. While the Pascal rule should not affect your TestApp project (because there are no Pascal files in it), it’s unwise to leave meaningless things in your project. You should remove any added or customized rules from your TestApp target to avoid any unexpected behavior as you follow along for the remainder of the book.

Figure 14.20 A custom build rule showing its .pp

It’s easy to see how much power this simple feature, hidden away as it is, can give you. With this feature, you can teach Xcode how to handle other types of files automatically during the build process.

Adding New Targets

There are several reasons why you might want to add multiple targets to a project. Your application might need a Spotlight plug-in (kept in its bundle’s Resources subfolder so OS X can find it easily). A Spotlight importer plug-in can be kept in a separate project, but it makes more sense to keep it within the same project as its parent application. Therefore, your project might have a separate target to build that plug-in (which would be a dependency of the application’s target and would be included in a Copy Files build phase that copies the built plug-in into the app bundle’s Resources folder when it is built). The same applies to other plug-ins, libraries, bundles, and so on.

Another example might be two separate builds of the same application: a free version and a paid “Pro” version. Both applications might share 95 percent of the source code and resources but differ only in that the Pro version has the ability to access certain features, or in that the free version expires 30 days after its first launch. Or, because of Apple’s App Store policies, you might choose to link against, include, and use your own registration system in one build of your app, while using the App Store receipt validation process in an App-Store-only build.

You might also add a unit test target, which executes unit tests against your code. Unit tests are covered in Chapter 18.

To add a new target, use the Add Target button at the bottom of the editor while a target or project is selected. A sheet appears (Figure 14.21), similar to the one that appears when creating a new project. In the figure, a Spotlight importer target (for teaching the OS X Spotlight searching facility how to index your application’s information) is selected.

Figure 14.21 The target template sheet

If you were to click Next and continue defining the target to add to your TestApp project, you’d be prompted with much the same line of questioning as when you created the TestApp project (which was necessary to create the TestApp application bundle target). In the case of a Spotlight importer target, you only need to give it a sensible name (such as TestAppImporter) and a company identifier (preferably the same as that of your application). Xcode will add the target to the project’s targets list (complete with build settings appropriate to the target type), create a separate build scheme for the target, and add the necessary source and resources to the project, as seen in Figure 14.22.

Figure 14.22 The new target’s resources

Note

The New Target sheet is similar to the New Project sheet primarily because Xcode needs to know what kind of target (or targets) to add to your newly created project.

Since the importer should be a part of the app, you would need to take a few extra steps for it to become part of TestApp. First, select the app’s target, select the Build Phases tab, and drag the importer target into the Target Dependencies build phase (Figure 14.23) to instruct Xcode to build it first so it’s available when building the application target. Then, add the importer target to the app target’s Copy Bundle Resources build phase. The next time you build TestApp, the importer will be built first, then copied into the app bundle’s Resources folder when TestApp itself is built.

Figure 14.23 Establishing a target dependency

Tip

In Xcode 4.0, you cannot drag the importer target directly into the resources for some reason. You’ll need to click the Add (+) button and choose the product from the Products folder in the sheet.

The importer would not function as it currently exists. To make it work, you would need to customize the code in the MySpotlightImporter.m source file to teach it to interpret the application’s data. You would also need to teach Spotlight, by other means, how to gather interesting information from the data model you created in Chapter 10. The importer is otherwise harmless if left in the TestApp project, so you could leave it, customize it to get it working if you’re feeling adventurous, or remove the target and its source and resources from the project to keep things tidy.

Note

The code and knowledge necessary to customize the importer is beyond the scope of this book. Search the documentation for the Spotlight Importer Programming Guide for more information.

Working with Schemes

You learned that schemes tie together one or more targets with a build configuration and destinations. There is no hard set of rules that determines how many schemes a target has or how many targets a scheme has. Schemes are meant to be a simple way to switch between conceptual sets of these items—sets that make sense to your project and workflow.

There are many ways you might use the system, but the simplest example is creating separate schemes for an Apple App Store build of your application and a build that uses your own customer relations and registration management system. You might have a separate scheme to run, analyze, test, and deploy a server-side registration key generator—a command-line program that is called from your Web store’s server upon successful payment. Any way you look at it, schemes are meant to give you an extra layer of flexibility as well as a collection point for these conceptual products and code/build/run/test/distribute scenarios.

Finding Your Project’s Schemes

Unlike many of the target-related settings, schemes are right in front of you at all times. The Scheme selector control, in addition to letting you select schemes and destinations, allows you to manage, edit, and create schemes. This control, which behaves similarly to the Jump Bar, is used to select the scheme and destination but is also used to edit the currently selected scheme or manage the list of schemes. The first (leftmost) segment lets you select the scheme or lets you create, edit, and manage schemes. The second (rightmost) segment selects the destination (Mac, device, simulator, and so on) available for the selected scheme.

Managing Schemes

Figure 14.24 shows the TestApp project’s schemes, which Xcode automatically created for each target (except unit test targets—see Chapter 18). Recall the Spotlight importer example from earlier in this chapter and note its presence in the schemes list. Because the app and plug-in targets are for Mac OS X only and support both 32- and 64-bit architectures, each scheme has a 32- and 64-bit Mac destination.

Figure 14.24 The Scheme pop-up’s menu

Choose Manage Schemes from the Scheme control to display the sheet shown in Figure 14.25. The sheet lets you create, duplicate, delete, reorder, rename, and generally wrangle schemes within the current workspace.

Figure 14.25 The scheme manager sheet

Creating Schemes

You can create a scheme by clicking the Add (+) button at the bottom of the schemes table and choosing New Scheme from the menu. A sheet (Figure 14.26) will appear asking for a target and a name. As you recall, schemes are linked to targets, so a new scheme must be given a target when created. Once you give the scheme a target and a name, click OK and you’re finished.

Figure 14.26 The New Scheme sheet

Duplicating Schemes

To duplicate a scheme, select it in the list, click the Add button, and then choose Duplicate from the menu. The duplicate scheme will be created and the editing sheet (discussed in the “Editing Schemes” section) will appear.

Reordering Schemes

You can reorder schemes by dragging them into the desired order in the list. This affects the order in which they appear in the Scheme control.

Removing Schemes

To remove a scheme, just select it and click the Remove (–) button. You’ll be prompted before the scheme is removed because this cannot be undone. If you’re certain you want to remove the scheme, click Delete to confirm and the scheme will be removed.

Importing and Exporting Schemes

You can also import and export schemes to share across unrelated projects by using the Action button to the right of the Remove button. You’ll be prompted with a standard save panel for export and a standard open panel for import.

Auto-Creating Schemes

As mentioned previously, Xcode can create schemes automatically as targets are created or duplicated within the project. This feature is active by default so that appropriate schemes will be created for targets in projects created by previous versions of Xcode and opened in Xcode 4.

To prevent Xcode from automatically creating schemes, deselect the Autocreate Schemes check box. If you want to have Xcode generate schemes automatically only when you want it to, open the Manage Schemes sheet and click the Autocreate Schemes Now button. Otherwise, you can leave this feature disabled and manage schemes manually.

Xcode version 4.0 does not remove schemes for deleted targets regardless of the auto-create setting; you must remove schemes manually.

Editing Schemes

To edit a scheme, you can double-click it in the table in the Manage Schemes sheet or select it in the Schemes control (remember to click the scheme name on the left part of the control; the right side chooses the destination) and then choose Edit Scheme from the menu. The Scheme Editor sheet (Figure 14.27) will appear. This is the same edit sheet that appears when duplicating an existing scheme. In the figure, the main TestApp target is shown.

Figure 14.27 The Scheme Editor sheet

Note

At the time this book was written, Apple’s documentation of some of the settings available in the Scheme Editor was terse or nonexistent. In some cases, this book provides a best guess at an explanation and may be incomplete. Please consult Apple’s documentation if some settings don’t appear to work quite as they’ve been explained.

The Scheme Controls

The main scheme controls (Figure 14.28) are shown across the top of the editor sheet. These controls match the functionality of the Scheme pop-up as well as of the Breakpoints button next to it. The behavior of these controls can be confusing.

Figure 14.28 The main Scheme Editor controls

The Scheme pop-up in the editor changes the scheme currently being edited as well as the active scheme in the Scheme pop-up. Its purpose is primarily to allow you to move between schemes without closing the editor sheet. Be aware that it also affects the active scheme even after you close the editor.

The Destination pop-up is somewhat more confusing. It directly sets the active destination in the main Scheme control but does not appear to do anything more. Its presence implies you might have separate destination-dependent settings within the scheme, but this is not the case in version 4.0.

The buttons along the bottom of the editor sheet let you duplicate the current scheme, go back to the scheme manager sheet, or dismiss the editor sheet (using the OK button, which should probably be a Done button).

In the middle of the sheet are two panels, used to edit the settings of each action for the scheme. The left panel shows a list of actions corresponding to those found under the Product menu in the main menu. Selecting each action reveals that action’s scheme settings in the right panel.

The Build Action

The Build action serves as the basis for the rest of the actions. As it’s necessary to build a product before it can be run, tested, or profiled, the Build action is always performed before performing any of the other actions that need a built product. To edit this action, select it from the list on the left of the Scheme Editor sheet. Figure 14.29 shows the settings for the Build action.

Figure 14.29 The Build action’s options

Two build options are visible at the top of the editor. The Parallelize Build option allows Xcode to build multiple independent targets—targets that do not depend on other targets—to be built in parallel, taking advantage of your modern multicore Mac. The Find Implicit Dependencies option allows Xcode to try identifying dependencies automatically. That is, if one target’s product is linked against or copied into the resources of another, Xcode can probably figure this dependency out automatically. This lets Xcode build the targets in the necessary order without your having to define the dependencies yourself. You’ll explore this in more detail in Chapters 15 and 16.

The complicated-looking table beneath the build options lists all the targets that are to be built for the current scheme. Obviously there would need to be at least one target listed here for the Build action to be helpful. Note the columns with check boxes that correspond to each of the remaining actions. These check boxes control whether the target is built automatically (if necessary) before each action is run. In the figure, two targets are listed—the TestApp application itself and the tests bundle (see Chapter 18 for more on unit tests). Notice that the check box for the Test action is selected and disabled so you cannot deselect it. Likewise, TestApp’s Test, Run, and Profile actions are selected and disabled. This indicates that a built product is required for these actions.

You can use this table to define dependencies directly (especially useful in complex situations where Xcode is unable to determine the dependencies itself). Use the Add (+) button at the bottom to choose another target within the workspace (including multi-project workspaces). You can drag the dependencies into the required order if necessary (just remember to deselect the Parallelize Build option if order truly is important).

There’s one other item of interest hiding in the Build action’s settings. Notice the disclosure triangle beside the TestApp target. If you expand it, you’ll see the TestAppImporter target you created earlier in the chapter. Because you placed the Spotlight importer product into the TestApp target’s Target Dependencies build phase, it’s been automatically included in the list (and has the same per-action settings as TestApp).

The Run Action

The Run action specifies the executable to run, the debugger to use, arguments to pass, and some environmental settings when you ask Xcode to run with the active scheme. Figure 14.30 shows the Run action’s multi-tab editor.

Figure 14.30 The Run action’s Info tab

The Info tab (Figure 14.30) holds the basic settings for the Run action. The Build Configuration pop-up lets you select the configuration (such as Debug or Release) to use when running. The default is the Debug configuration so the debugger can be used. The Executable pop-up, predictably, lets you choose the executable to run. In this case, it’s the only executable available in the project: TestApp.app. Targets without executables (such as our Spotlight importer) will have their Executable set to None, since they can’t be “run” on their own. The Debugger pop-up lets you choose among installed debuggers. In Xcode 4.0, GDB is the default, while LLDB is available. The Launch options instruct Xcode either to launch the executable automatically when the Run action is evoked (the default and most common behavior) or to wait for you to launch it yourself before running, attaching the debugger, and so on.

The Arguments tab (Figure 14.31) lets you control the launch arguments, environment variables, and debug symbol loading during runtime. The Base Expansions On pop-up specifies which executable’s specific environment variables (as seen in the run logs) are to be used when expanding those Xcode supplies (such as BUILT_PRODUCTS_DIR). The Arguments Passed On Launch list lets you use the Add (+) button to add specific arguments to be passed when the application launches. This makes the most sense when running command-line programs. You use the Add button in the Environment Variables list to add or override the environment variables present (such as USER) in the application’s environment. The Module Names To Load Debug Symbols For list lets you instruct Xcode to load debugging symbols for libraries to which your application links. If you have debug symbols available for a given library, you can make their debugging information available to Xcode for use in debugging sessions by specifying the module name.

Figure 14.31 The Run action’s Arguments tab

The Options tab (Figure 14.32) is for the more general runtime options. The Persistent State option disables the restoration of an application’s persistent state (API added to Mac OS X 10.7). The Document Versions option turns on additional debugging support for browsing versions in the new 10.7 document versions API. The Working Directory option lets you specify a custom working directory for the executable at runtime.

Figure 14.32 The Run action’s Options tab

The Diagnostics tab (Figure 14.33) specifies a number of options for memory management debugging, logging details, and debugger behavior during runtime. The specifics of each of these options are beyond the scope of this book. Please see Apple’s documentation for details.

Figure 14.33 The Run action’s Diagnostics tab

The Test Action

The Test action specifies the unit test bundle to use for the scheme. Figure 14.34 shows the Info tab of the Test action editor. When you created the TestApp project, you chose to include unit tests. This caused Xcode to create a unit test bundle for the TestApp product and add it to the tests to be run in this action. The TestAppTests bundle appears in the Tests list as a result (and it will not be skipped in this scheme because the Test check box is selected). The Build Configuration pop-up menu defaults to the Debug configuration (since Release would make it difficult to debug if the test fails). The Debugger pop-up works the same way as in the Run action—it specifies the debugger to use when running unit tests.

Figure 14.34 The Test action’s Info tab

The Arguments tab (Figure 14.35) allows you to specify options similar to those of the Run action (without the ability to load extra debug symbols). The only difference is the check box at the top (“Use the Run action’s options”). This check box is selected by default and, when active, disables the Test action’s own arguments controls, using those defined in the Run action instead. Deselect this to specify a separate set of arguments and environment variables for testing. For more information on unit testing, see Chapter 18.

Figure 14.35 The Test action’s Arguments tab

The Profile Action

The Profile action is Xcode’s gateway to launching Instruments, Apple’s code-profiling tool (covered in Chapter 20). Figure 14.36 shows the Info tab of the Profile action editor. The Build Configuration, Executable, Working Directory, and UI Resolution settings all work the same as in previously discussed actions. The key setting here is the Instrument pop-up. The Ask on Launch setting will open Instruments’ Trace Template sheet (Figure 14.37), prompting you to choose a trace instrument to use when profiling your executable. All other settings in the pop-up launch the executable within Instruments with the chosen trace instrument selected.

Figure 14.36 The Profile action’s Info tab

Figure 14.37 Instruments templates

The Arguments and Options tabs work in the same way as those of the Test action. That is, you can specify arguments and environment variables or use the Run action’s settings.

Note

If you’ve selected Ask on Launch and Instruments is already running (that is, you’ve already selected a trace instrument the first time), subsequent calls to the Profile action will immediately run your executable using the previously chosen instrument without asking again. Close the Instruments window to be prompted again next time.

The Analyze Action

The Analyze action runs the static analyzer (introduced in Chapter 9 and covered in more depth in Chapter 17) against the targets specified in the Build action.

The editor has only one option: the Build Configuration pop-up. As with other actions, use this to specify the configuration (usually the default Debug or a debugger-friendly configuration) to use when analyzing the built target(s).

The Archive Action

The Archive action, covered in Chapter 12, is responsible for creating an archive of all built targets and their dSYM debugging information. The archives are suitable for submission to Apple’s (Mac and iOS) App Stores.

The editor (Figure 14.38) has only three options. The first, Build Configuration, works as expected. A Release build makes the most sense and is the default, but you’re free to create your own release-friendly configurations for use here. The Archive Name field lets you specify a name to use for the created archives. The Options section (with only one option) lets you specify via the check box that you’d like Xcode to reveal the archive in the Archives tab of the Organizer (also mentioned in Chapter 12) when the action is complete.

Figure 14.38 Archive action options

Pre-Actions and Post-Actions Scripts

You may have noticed the disclosure triangle next to each action in the Scheme Editor’s actions list. When expanded, you’ll see three entries (Figure 14.39). When you select the action, you’re viewing the options for the action itself (the middle item in the expanded action’s children), but what about the Pre- and Post-actions items? Pre-actions are things that can be done prior to the start of an action. Post-actions are done after. If you select one of them, you’ll see an empty editor.

Figure 14.39 Extra action options

In Xcode 4.0, there are two different pre/post action types you can perform: execute script or send e-mail. Using the Add (+) button, you can add one or more of either type of action. Figure 14.40 shows a simple set of actions that notifies the pathetic humans (and their pointy-haired masters) of the completion of an Archive action.

Figure 14.40 Some example post-actions

These extra hooks into Xcode’s main actions open up the possibilities for process customization considerably. See Chapter 19 for more ideas regarding interesting ways of taking advantage of Xcode’s various scripting hooks.

Entitlements (Sandboxing)

Application sandboxing is a security concept introduced in Mac OS X 10.7. Opting into this system makes your application more secure by limiting its access to various system resources unless specifically requested in the application’s entitlements.

Because of the flexibility and openness of an Objective-C application, foreign code can be “injected” into the application or the application’s binary can be modified. This code would run with the same privileges your application enjoys. By voluntarily limiting your application’s system access to only those resources it actually needs, you are reducing the chances for malicious code to achieve whatever goal it has in its evil little bytes. Much could be said on the topic, and likely will be by plenty of other books, but as always, this book’s focus is on the IDE, not the technologies it helps you control.

Xcode makes managing your application’s entitlements easy. To find their settings, navigate to the desired build target and click the Summary tab. The Entitlements section (Figure 14.41 contains a list of toggles and choices.

Figure 14.41 The Entitlements controls

Note

Application sandboxing relies on code signing. For more information, see the Code Signing and Application Sandboxing Guide at http://xcodebook.com/codesigning.

Activating Entitlements and Sandboxing

You can turn on entitlements for your app by selecting the Enable Entitlements check box at the top of the list. You then choose an entitlements file from the Entitlements File pop-up. Xcode helpfully creates one matching the name of your target and adds it to your project (Figure 14.42. The file is a simple preference list. You can edit it by selecting it using the same preference list editor you’ve used elsewhere, but it is easier to use the Entitlements section you’re exploring now.

Figure 14.42 The Entitlements file

To sandbox your application, select the App Sandbox check box. Now you must grant your application access to the functionality it needs.

Setting Specific Entitlements

The remaining settings in the Entitlements section grant specific entitlements to your application.

File System

Use the File System pop-up to allow your application to read and write, to read-only, or to have no access to the file system. Select the Allow Downloads Folder Access check box to grant access to the Downloads folder regardless of the general file system access setting. File system access is disallowed by default.

Network

Use the Network check boxes to allow incoming or outgoing connections. Network communication is disallowed by default.

Hardware

Use the Hardware controls to allow access to cameras, microphones, USB devices, and printers attached to or accessible by the system. None of these are allowed by default.

Apps

Use the Apps controls to allow access to the user’s address book and calendar data as well as to location services. None of these are allowed by default.

Media Folders

Use the Music, Movies, and Pictures folders to access pop-ups that grant read-only or read and write access to each of these folders. Access is disallowed for each by default.

Wrapping Up

This chapter covers a lot of material, but Xcode’s new build system is easily the most important and arguably the most difficult concept to understand. An IDE is an environment that helps the developer manage the most basic actions performed during the course of development: building, running, debugging, testing, and deploying a product. The Xcode 4.0 approach differs significantly from that of previous versions and, as Xcode veterans will attest, has quite a learning (or un-learning) curve.

In the next chapter, you’ll expand on this knowledge by exploring the concept of plug-ins and frameworks a bit further. Then, in Chapter 16, you’ll learn to work with Xcode’s workspaces concept and the true power of automatic dependency detection by combining a framework project with the TestApp project.

15. Libraries, Frameworks, and Loadable Bundles

In previous chapters, you saw the templates Xcode provides for a variety of projects. You also learned that the project templates dictate the types of targets that will be set up for you. There’s a rich world full of products beyond applications. Not only can you write them yourself, but you can also use the work of others in the form of third-party plug-ins, libraries, and frameworks. In this chapter, you’ll explore the distinctions between these things as well as how to use them or build your own.

What are Libraries, Frameworks, and Bundles?

Libraries, frameworks, and bundles are similar in that you can think of them as prepackaged code meant to be used from within another library or application. They’re all meant to improve or expand the functionality of an executable (including those that are part of the operating system) by making their code available to it. Plug-ins, which we’ve discussed in previous chapters, are in fact a specific type of bundle.

Purists may take exception to the oversimplified descriptions that follow, but because this is a book about Xcode, we’ll keep things simple and leave the details (or extreme accuracy) for programming books.

Libraries

The term library has the same meaning on every platform. A library is the most basic form of prepackaged, shared code meant to be reused in multiple applications. Mac OS and iOS come with a number of standard C libraries and libraries specific to the operating system. In the Mac and iOS world, static libraries have the .a extension (a static object code library archive), while dynamically loaded libraries have a .dylib extension.

Static Libraries

Static libraries are linked into the executable by the linker at build time. That is, the code in the library is un-archived and copied into the executable along with your program’s compiled object (.o) files. Static libraries result in a larger executable because the library’s code isn’t shared but merely “available to copy.” An example of a common static library is libc.a, the standard C library.

Dynamic Libraries

Dynamic libraries can be loaded at launch time or when needed at runtime. The code from the library is shared and is not part of the executable. This gives the potential for faster launch times, smaller executables, and less wasted space (as a result of many executables carrying the same code linked from a static library). An example of a popular dynamic library Cocoa developers use every day (perhaps without realizing it) is libobjc.a.dylib, which contains the Objective-C runtime library.

Frameworks

A framework is a bundle of files and folders that can contain dynamic shared libraries, Interface Builder files, localized (translated) strings, headers, and media resources. It could contain nothing but a dynamic library or nothing but resources. If you’ve used Cocoa, you’ve used a collection of frameworks already.

You’ve likely heard Cocoa being called “the Cocoa frameworks.” That’s because Cocoa.framework actually is an “umbrella framework” that encompasses a number of sub-frameworks. One such sub-framework is Foundation.framework, which gives you basic strings, container classes, and so on. On a Mac, things like windows, buttons, and drawing routines come from AppKit.framework, a Cocoa sub-framework. The same goes for AppKit’s iOS cousin, UIKit.framework.

Unless your Cocoa application is fairly simple, it’s likely you’ll be using other frameworks, provided by the system or by third parties, that can be linked against to provide functionality not found in the core Cocoa frameworks themselves. At the very least, you may end up using a Cocoa framework that’s not normally automatically linked. In fact, when you created the TestApp project and specified it should use Core Data, Xcode automatically included CoreData.framework and added it to the Link Binary With Libraries build phase of the TestApp target.

Loadable Bundles

A bundle is a directory structure that appears to the end user as a single file. Applications, frameworks, plug-ins, and kernel extensions are all specific kinds of bundles.

A loadable bundle contains code and resources that can be loaded and unloaded at runtime. This enables developers to divide up their applications into modules and even provide extensibility in the form of plug-ins. For example, the Spotlight search system comes with a core set of plug-ins that teach it how to index various types of files. Third-party developers can create Spotlight importer plug-ins to allow Spotlight to index even more file types (usually files created by their own applications). Screen savers are another example. Each screen saver is a plug-in (a bundle) that teaches the screen saver application how to display yet another form of eye candy, while the screen saver application itself only takes care of loading the effects or stopping when the user moves the mouse (and possibly provides a password to unlock the screen).

Xcode comes with a dazzling array of bundle types. As you saw in the previous chapter, there are templates to create plug-ins for Spotlight, Address Book, QuickLook, System Preferences, Automator, Dashboard, and even the kernel. Alternatively, you can just choose the generic Bundle template (found under the Framework & Library template group) and optionally tack on your own extension (such as .testappplugin) to stand out from the crowd.

Loadable bundles are like libraries or frameworks that your users can install and remove by drag and drop. Although things like Spotlight plug-ins often come embedded within an application bundle (which Spotlight automatically finds), their power as standalone plug-ins that a user can add or remove themselves is often overlooked. It’s important to be aware that loadable bundles can just as often be a product in themselves as a component embedded in another product.

Using Existing Libraries and Frameworks

Using an existing library or framework is simple in Xcode, especially if it’s included as part of the operating system. At a minimum, you need to link your target against the library or framework. You learned how to do this in Chapter 14. To use a framework in code, you may need to include one or more of its shared headers.

If you’re using a framework that isn’t part of the operating system, you’ll have to distribute it with your product. This means you would have to add a Copy Files build phase to the product, specifying the framework to copy into the bundle’s Frameworks folder.

System Framework Example

Let’s use WebKit.framework as a simple example of how to use a system framework to add Web browsing capabilities to a product. You’ll add a simple window containing a Web view that automatically loads Google’s home page.

Linking Against the Framework

To link against WebKit, select the project in the Project navigator. Select the TestApp target, then click the Build Phases tab. Expand the Link Binary With Libraries phase and click the Add (+) button. A sheet (Figure 15.1) will appear, prompting you to choose from the list of available system or workspace libraries and frameworks or to add another from an alternative location. Type web to filter the list, select WebKit.framework, and click Add. In addition to Cocoa.framework, TestApp will now be linked against WebKit to gain all its super Web powers (Figure 15.2).

Figure 15.1 The Framework and Library sheet

Figure 15.2 The WebKit framework in the linking build phase

Wiring Up the UI

To display this great power (and with it, its great responsibility), you need to add some UI. Navigate to MainMenu.xib, which holds TestApp’s user interface. Add another window to the interface by dragging it from the Object library, as you learned to do in Chapter 5. I suggest a textured window for Safari-like fun. Filter the Object library for the word “web,” drag a Web view to your new window, and position it to taste. You should have something similar to Figure 15.3.

Figure 15.3 A simple Web view

A Web view isn’t very useful without a Web site to visit. To save time, assume your only user is your grandmother, who of course ignores the address bar completely and Googles every Web address. You need an IBOutlet that you can use to communicate with the Web view, so that you can tell it to load Google.com. Use the Assistant to drag a connection from the Web view to the TestAppAppDelegate.h file, as you learned in Chapter 5. Name it webView. When you’re finished, you should have things configured as you see in Figure 15.4.

Figure 15.4 The finished workspace changes

Using the Framework In Code

Now you just need to add some code to load Google.com into the Web view when the application launches. Before you can use symbols from WebKit, you have to include its main header. Since you reference a WebView as an outlet in the app delegate’s header, it’s easiest to import the WebKit header there. Since the Assistant window is already open to it, find the #import statement near the top of the source file and add the following code on a new line after it:

#import <WebKit/WebKit.h>

Navigate to the implementation file (TestAppAppController.m) and find the -applicationDidFinishLaunching: method. Add the following code into the body of the method:

NSURL * googleURL = [NSURL URLWithString:@"http://google.com"];
NSURLRequest * request = [NSURLRequest requestWithURL:googleURL];
[[webView mainFrame] loadRequest:request];

Tip

The WebKit.h header is an “umbrella” header that includes any other headers in the WebKit framework. Referencing this header includes all headers from WebKit.

That’s it. Run the application. You might have to fish around for the second window (look behind the one you’re familiar with), but it should be waiting there with Google loaded and ready for a search (Figure 15.5). Go ahead and try it out.

Figure 15.5 A working WebView showing Google.com

Negative Reinforcement

Now break it. To prove that the power to use a Web view comes from linking against WebKit.framework, unlink it. Navigate back to the TestApp target in the project, and then remove WebKit.framework from the Link build phase. Try running the app. I dare you. The app should terminate on launch on signal SIGABRT and spew a bunch of messages and a stack trace into the debugger console. The most interesting console message is the second one, that mentions “cannot decode object of class (WebView),” which is a good indicator you’re referencing symbols from a library that hasn’t been loaded (usually because you haven’t linked against it). To fix it again, just add WebKit.framework back into your Link build phase.

Third-Party Framework Example

Third-party frameworks require a little more work to use. Since they aren’t a part of the operating system, they must be distributed with the application. The most common way to do this is to embed the framework inside the application bundle so that it goes along for the ride when the user installs your application.

Adding a Framework to the Project

Most third-party frameworks are open source and many must be built before they can be used in your project. For this example, you can download a simple (and almost entirely useless) framework called Foo.framework from this book’s Web site. The direct download URL is http://files.xcodebook.com/fooframework/FooFramework.zip. Download the file and unzip its contents. You should see a folder titled Foo.framework.

Note

You can skip copying the framework into the project folder, but you’ll have to keep track of where all the pieces necessary to build your project are located. One way to do so is to create a conveniently located folder called Third-Party Frameworks or something similar so you always know where it is, no matter the project.

To add the framework to the project, drag Foo.framework into the Project navigator and drop it inside the Frameworks group (Figure 15.6) for neatness (although it doesn’t actually matter where you drag it—you can organize your project however it best suits you). The Add Files sheet you encountered in Chapter 6 will appear (Figure 15.7). Make sure to select the “Copy items into destination group’s folder (if needed)” check box and click Finish. The framework will be copied into the project folder and appear in the Project navigator.

Figure 15.6 Adding the framework to the project by dragging and dropping

Figure 15.7 Copying items into the project folder via the Add Files sheet

Linking Against the Framework

Unlike in the last example, Xcode has automatically added the framework to the Link build phase of the TestApp target. This was done for you because, as you saw in Figure 15.7, you accepted the default settings for the Add to Targets table (that is, you asked Xcode to add the framework to the TestApp target only). Xcode is smart enough to know that a library should be added to the Link build phase of the selected targets. You can verify this for yourself by examining the target’s Link phase (Figure 15.8).

Figure 15.8 The Foo framework in the target’s Link build phase

Embedding the Framework

To embed the framework within the application, navigate to the Build Phases tab of the TestApp target. Add a Copy Files build phase by clicking the Add Build Phase button at the bottom of the window and selecting Add Copy Files. Double-click the title of the new build phase and change it to Copy Frameworks for clarity. Expand the build phase and set the Destination pop-up to Frameworks. Now drag Foo.framework from the Project navigator into the Copy Frameworks phase. Your new build phase should look like Figure 15.9.

Figure 15.9 Adding the Foo framework to a Copy Files build phase with Frameworks as its destination

Note

You can opt to install a framework in a shared location, but the ins and outs of framework distribution are beyond the scope of this book. See the Framework Programming Guide in Apple’s documentation for more details.

Using the Framework in Code

Foo.framework doesn’t have any UI components, but it provides two classes: MyFoo and MyBar. You can verify this by creating an instance of two classes provided by the framework and logging their descriptions to the console. You’ll do this at application launch, as in the previous example, so navigate to the -applicationDidFinishLaunching: method of the TestAppAppDelegate.m source file and add the following to its body:

MyFoo * foo = [[[MyFoo alloc] init] autorelease];
MyBar * bar = [[[MyBar alloc] init] autorelease];
NSLog(@"Foo says: %@", foo);
NSLog(@"Bar says: %@", bar);

Remember to add the following to import the framework’s header so Xcode is aware of the new symbols the framework provides:

#import <Foo/Foo.h>

Tip

If you’re unsure which header to include, you can either use AutoComplete or expand the framework itself in the Project navigator list, open its Headers subfolder, and take a look around. Also, most frameworks have an umbrella header named for the framework itself, such as “Foo.h” for Foo.framework or “WebKit.h” for WebKit.framework.

Run TestApp and watch the debugger console’s output. You should see something like the following:

2011-03-05 15:50:57.623 TestApp[40877:903] Foo says: <MyFoo: 0x1006f0b10> - Foo!
2011-03-05 15:50:57.623 TestApp[40877:903] Bar says: <MyBar: 0x1006f1670> - Bar!

To summarize, the extra steps to use a third-party framework are: adding it to your project, optionally copying it into the project folder when adding it, and embedding it into your application bundle so it’s distributed with the application.

Creating a Framework

In addition to using system and third-party frameworks, it can be useful to create your own. One simple benefit is that you can place code that is shared between a Mac OS version and an iOS version of your application in a single, common location. Both can link against the same framework and benefit from improvements and bug fixes from the same source.

To familiarize you with this process, you’ll create a simple framework in a separate project and learn how to build it for release so it’s ready to use in other projects. In Chapter 16, you’ll learn how to combine projects into a single workspace, allowing Xcode to recognize it as a dependency and build and include it in TestApp automatically.

Create the Project

To create a new project, choose File > New > New Project from the main menu. Choose the Framework & Library group under the Mac OS X section. Select Cocoa Framework from the list and click Next.

The project options sheet (Figure 15.10) will appear. In the Product Name field, enter TestAppSharedFramework so you can distinguish it from the TestApp project. It’s also a good idea to make sure the Company Identifier value is the same as the one you gave for the TestApp project. You can deselect the Include Unit Tests check box for simplicity. Click Next.

Figure 15.10 Creating a new framework project

Select the “Create local git repository for this project” check box and select the same folder that contains the TestApp project folder (the TestApp folder’s parent). Make certain you don’t save it in the TestApp project folder, but one level above. Click Create to create the project. You should have a shiny new project window, as seen in Figure 15.11. Now you’re ready to add some code.

Figure 15.11 The new framework project workspace

Add Some Code

As you read in earlier chapters, TestApp isn’t particularly useful for anything beyond exploring Xcode. Its shared framework won’t help it sell on the App Store either, but it will be a handy demonstration in Chapter 16.

To start with, a framework should have a simple umbrella header—that is, a header that includes all other headers needed to use the framework and that allows a one-stop import into other classes. To add this umbrella header, select the TestAppSharedFramework group in the Project navigator and then choose File > New > New File from the main menu. From the Add File sheet, choose the C & C++ category under the Mac OS X header in the list, choose the Header File template (as in Figure 15.12), and click Next. When prompted to save, leave the folder location, Group, and Add to Targets settings as they are, name the header TestAppSharedFramework (to match its parent framework’s name), and click Save. You’ll have an empty header file ready for later use.

Figure 15.12 Creating a new header file

Next, you’ll add a simple class whose only mission in life is to answer its –description method with a simple “Hello World!” Repeat the New File process, selecting the Objective-C Class template from the Cocoa category. When you click Next, supply the class name NSObject for the “Subclass of” field. Click Next again to be prompted to save. Change the filename in the Save As field to TestFoo, and click Save. Make sure the TestFoo.m source file is selected in the Project navigator so that its source is visible in the editor. Just above the @end directive at the end of the file, add the following method:

- (NSString *)description
{
    return @"Hello World!";
}

This gives the TestFoo class the ability to say hello when asked for its description. You’ll use that later. For now, you need to add its header file, TestFoo.h, to the framework’s umbrella header for later import. Navigate to TestAppSharedFramework.h in the Project navigator and add the following on a new line at the end of the file:

#import "TestFoo.h"

Any other classes you add to your framework can be similiarly included in this umbrella header. This way, when your framework is used, there is only one header to import, which brings the headers of any other classes along for the ride.

Try a build (Command+B) and verify there are no build issues. The framework should build cleanly.

Configure the Headers

In order to use a framework’s headers, they must be configured in the Copy Headers build phase. To do so, navigate to the project itself and then select the TestAppSharedFramework target in the list. Next, select the Build Phases tab and expand the Copy Headers phase (Figure 15.13).

Figure 15.13 The Copy Headers build phase

Note that the headers automatically appear in the Project group. In order to use the framework’s code, the headers must be made public. To do so, drag both the TestAppSharedFramework.h and TestFoo.h headers into the Public group, as shown in Figure 15.14.

Figure 15.14 The framework’s headers made public in the Copy Headers phase

To have a look at the innards of your newly minted framework, build one more time (Command+B) and then expand the Products group in the Project navigator. Right-click (or Control-click) the TestAppSharedFramework.framework product and choose Show in Finder from the pop-up menu. Figure 15.15 shows the fully expanded folder structure with the code library and its public headers.

Figure 15.15 The built framework’s file structure

Tip

If you wanted to use this framework right now, you’d have to archive it or manually create a release build scheme and build it with that scheme. See Chapter 19 for alternative deployment build approaches.

That’s all there is to it. You have a fully functional framework with some custom code that could be shared between multiple projects. You’ll use this framework in TestApp in Chapter 16.

Tip

It’s very common (and considered good practice) for developers to create test application targets alongside the framework. This application is used to test your framework as it’s being developed.

Wrapping Up

You’ve seen how to create plug-ins and frameworks and learned how to use them in other projects. In the next chapter, you’ll see how you can combine multiple projects into a single workspace and even create dependencies between them so you can build your new TestAppSharedFramework framework and include it in TestApp on each build.

16. Workspaces

Up to this point, the TestApp project has been just that—an Xcode project. The collection of files and folders are bound by an .xcodeproj file that contains all the project-wide settings (such as a description of your schemes and targets). Throughout the book, however, the word “workspace” has been used as a more general description of the project and the window that contains it all. A true workspace encompasses multiple projects.

What Is a Workspace?

Xcode 4 introduces the idea of a workspace as a kind of project binder—a container for multiple projects. A project groups together its related files and settings; a workspace binds multiple related projects. A workspace merely contains pointers to Xcode projects. Projects remain distinct in that you can remove them from a workspace without affecting the project’s content or settings. In other words, the project can still be opened and edited outside its workspace. Workspaces give you several advantages over projects that reference files and built products from other projects.

Projects contained within the same workspace share a common build location. This makes it possible for one project to use another’s built products. This one feature makes a world of difference for managing complex applications and application suites. It makes it far easier, for example, to include the built product of a common framework project into one or more of your application projects.

The automatic dependency detection you learned about in Chapter 14 extends to the workspace level as well. This means that including a product’s framework in the target of an application project within the same workspace usually requires no additional work for Xcode to recognize the dependency. As with dependent targets within the same project, Xcode will see this dependency and build the framework before building the application. In other words, you don’t have to copy shared libraries into each project folder in which you intend to use the library.

Note

Xcode may not be able to detect complex dependencies automatically. In this case, you’ll need to disable the Find Implicit Dependencies setting of the affected scheme and add and sort the interdependent targets manually.

Another benefit of a workspace is shared indexing. A project index is used primarily for features such as code completion (Code Sense). Xcode’s automatic code completion and refactoring facilities will take the symbols of all projects included in the workspace into account. This means code completion will automatically find your framework project’s symbols and make them available to you when editing source files in the application project that uses the framework.

Still another benefit of workspaces pertains to schemes. A standalone project might contain a primary scheme for building, testing, and profiling a primary product in addition to schemes for smaller, dependent targets (such as a Spotlight plug-in). In a workspace, you may only want to see the scheme for each project’s primary product. Using the Manage Schemes panel you explored in Chapter 14, you can specify whether the schemes for those smaller “sub-targets” are visible at the workspace level or only when the project is opened individually. This can help keep the list of schemes short and manageable, hiding unnecessary detail from the various projects within the workspace.

When to Use a Workspace

It’s hopefully obvious that a workspace is useless without two or more projects. Less obvious but just as important is that a workspace doesn’t help with multiple unrelated projects. A workspace is only helpful for two or more projects that must share each other’s code and resources. Let’s look at two real-world examples.

Distinct Applications

Imagine Acme Corporation has a whole host of unrelated desktop (and even mobile) applications. Here, “unrelated” means a calculator application, a calendar application, and an address book application. Each of these applications has only one thing in common: They’re products of Acme Corporation.

Being the property of the same business entity, the applications presumably use the same software registration system, company logo, contact information, and so on. They may even be able to share user data among them. This means each application would use the same code, resources, or both.

A change to the Person and Event classes, for example, might need to be updated in both the address book and calendar applications. While these classes may or may not be wrapped in a library or framework, it makes little sense to maintain two copies of Person and Event (one in each project). Here, a separate project that at least contains the common model-layer classes (and corresponding unit tests) makes sense. A separate framework project makes even better sense.

Since the applications are otherwise unrelated, each application might have its own workspace that includes the application project and the shared framework project.

Application Suites

Imagine Acme Corporation’s desktop calendar application has gone where no calendar application has gone before. Against all odds, it has become a best seller, and users are clamoring for mobile versions for their various devices. Acme Corporation, in addition to its other products that share company-wide resources, now has a product that supports two platforms, shares company-wide resources, and has a device synchronization library to let users share calendar information between their devices and their desktop computers.

In this case it would make sense to have a workspace containing the two application projects (Mac OS and iOS), their sync library project, and the company-wide resource project.

Creating a Workspace

Creating the workspace is easy. Choose File > New > New Workspace from the main menu. A new workspace window will appear with a Save As sheet prompting you for a location in which to save it (Figure 16.1). Note in Figure 16.1 the two project folders you created in previous chapters—TestApp and the shared framework you created in Chapter 15.

Figure 16.1 Saving a workspace

The common parent folder that contains these two project folders is a good place to keep the workspace file so that it’s easy to find. Enter TestApp Suite as the workspace name so it’s clear that this workspace contains subprojects belonging to the whole TestApp suite of applications (a Mac OS X app, an iOS app, and a shared framework between them, in the product plan of your imagination). Once you’ve chosen the name and location, click Save. The sheet will close and leave you with a disconcertingly empty workspace window.

Adding Projects to the Workspace

Now it’s time to add the projects to the workspace. Using the Finder, navigate to the folder containing the workspace and projects. For each project (the application and the framework), find its .xcodeproj file (Figure 16.2) and drag it into the Project navigator list of the TestApp Suite workspace window (Figure 16.3).

Figure 16.2 Locating individual project files with the Finder

Figure 16.3 Dragging projects into a workspace

After you add the first project, take care to drop subsequent projects either above or below existing projects, keeping the blue insertion bar as far left as possible. Dropping a project into another makes it a subproject, which is not the same thing. Figure 16.4 shows the TestApp project being inserted above the framework project and not inside it.

Figure 16.4 Carefully inserting additional projects into a workspace

Note

A subproject is treated as an implicit dependency of the project in which it is contained and doesn’t benefit from shared build locations without careful configuration.

Managing Inter-Project Dependencies

You can allow TestApp to use the shared framework you created in Chapter 15 (building it first if necessary) by adding the framework to the TestApp target’s Link and Copy Frameworks build phases. To do so, navigate to the TestApp project, select the TestApp target, and then select the Build Phases tab. Expand the Link Binary With Libraries phase and click its Add (+) button. You’ll be prompted with the standard libraries and frameworks chooser (Figure 16.5).

Figure 16.5 Choosing the framework product from the frameworks and libraries panel

Note the new “Workspace” group at the top of the list. Xcode knows that a framework target exists within one of the projects within the TestApp Suite workspace. Select TestAppSharedFramework.framework and click Add. The framework is now part of TestApp (Figure 16.6).

Figure 16.6 Linking the TestApp product against the shared framework

To test it, clean the workspace by selecting Product > Clean from the main menu. Then make sure the TestApp scheme is selected in the Scheme pop-up and build the application.

Of course, as you learned in Chapter 15, TestAppSharedFramework isn’t a system-provided framework, so you’ll need to distribute it within TestApp. Although TestApp would run in the development environment, it would crash due to a missing library were you to distribute it in its current state (recall this from Chapter 15 when you added a Copy Frameworks build phase for the foreign Foo.framework). You can simply drag TestAppSharedFramework.framework from the TestApp project into the TestApp target’s Copy Frameworks phase (Figure 16.7).

Figure 16.7 Adding the shared framework to the Copy Frameworks build phase

As you may also recall from Chapter 15, in order to use the framework, you’ll need to include its header. To verify that everything is working, add the following to the header include section near the top of the TestAppAppDelegate.m file:

#import <TestAppSharedFramework/TestAppSharedFramework.h>

At the end of the -applicationDidFinishLaunching: method—which should now be familiar to you—add the following:

TestFoo * testFoo = [[[TestFoo alloc] init] autorelease];
NSLog(@"TestFoo says: %@", testFoo);

Figure 16.8 shows the complete -applicationDidFinishLaunching: method. Once you’ve finished, run TestApp and check the debugger console for a successful message from the TestFoo class that comes from TestAppSharedFramework.

Figure 16.8 The complete -applicationDidFinish Launching: method

Managing Schemes in Workspaces

You learned the ins and outs of managing schemes in Chapter 14. Here you’ll manage them from another perspective—schemes as they exist within a workspace.

You’ve no doubt noticed schemes from each project show up in the Schemes pop-up in your new TestApp Suite workspace. The schemes are inherited from the workspace projects in which they exist. Figure 16.9 shows the schemes from both the TestApp and TestAppSharedFramework projects.

Figure 16.9 The Schemes pop-up menu showing workspace-wide schemes

Choose Manage Schemes from the Schemes pop-up to reveal the now-familiar scheme manager (Figure 16.10). There are two major questions to consider for each scheme in a workspace: Should it be shown, and in what container should it exist?

Figure 16.10 The scheme manager

Showing and Hiding Schemes

In Figure 16.10, note the Show column in the list of schemes. Though all schemes are visible in the scheme manager, deselecting the Show check box for a scheme removes it from the Schemes pop-up control.

In the TestApp Suite, you have only an application and its shared library. When looking at it from the workspace perspective, it may be necessary to show only the application and the framework schemes. Since the TestAppImporter target that you created earlier is a dependency of the TestApp target, you may not want to bother seeing it from the workspace perspective.

It’s important to note that the Show settings for each scheme persist whether you’ve opened a workspace containing it or the project itself. In other words, if you change this setting for a project’s scheme, the change appears in the workspace (and if you change it in the workspace, it appears in the project’s settings as well).

Changing a Scheme’s Container

The Container field of the scheme manager indicates where the scheme is stored. This field lets you move schemes by changing their container to another project. When viewing the schemes at the workspace level, you can move schemes to be contained entirely in that workspace. This capability lets you create a shared scheme that builds an entire suite of products from disparate projects with a scheme that only appears when working with the entire workspace.

Note

Recall that the scheme manager’s Shared check boxes dictate whether a scheme shows for other users who open the project or workspace. In a team setting, there will likely be at least one shared scheme—the scheme to build them all.

Another Kind of Workspace

The term workspace has been overloaded in the software industry. Its meaning in Xcode is no exception. It makes sense that Xcode calls its new feature “workspaces” (a good name for a feature that binds projects together), but in the broader sense, your workspace refers more to the layout and configuration of your project.

Your Xcode workspace includes, among other things, controls for whether or not certain auxiliary views are enabled. Xcode 4 helps you maintain control of your workspace by using behaviors. Under Xcode’s Preferences (Command-Comma), the Behaviors panel reveals a number of configurable options (Figure 16.11).

Figure 16.11 The Behaviors panel

Although there are many options, the feature is simple. Each item in the list on the left can trigger any of the actions on the right. Behaviors affect all projects and workspaces (the bound-together-projects kind). With Lion’s auto-hiding scroll bars, it’s easy to miss, but both the left and right lists are scrollable. Figure 16.11 shows the window large enough to see the contents of both lists without scrolling.

Uses for Behaviors

An example of a custom behavior would be to not show the debugger when the app runs (“Run starts”) unless the application generates output (“Run generates output”). Another might be to create a new tab and navigate to the current run log in that tab if the app crashes (“Run quits unexpectedly”). The options are simple and speak for themselves. They allow navigation, activation of the various editing modes and assistant panels, running scripts, and so on.

Defining Behaviors

Xcode already has a number of common situations in the list on the left side of the Behaviors panel. To configure a behavior for a given situation, select the situation on the left and use the check boxes to enable each custom behavior. Those that are customizable have additional controls to the right of their check boxes. Situations that have defined behaviors have a check mark to the left of their names.

Creating Custom Behaviors

In Xcode 4.1, Apple has introduced custom behaviors. Although these behaviors aren’t triggered automatically like the built-in ones, you can create them and trigger them via the Xcode application menu (Figure 16.12) or with a custom keyboard shortcut.

Figure 16.12 The Behaviors menu

To create a new behavior, open the Behaviors panel and click the Add (+) button in the lower-left corner. You can name the new behavior whatever you wish. Figure 16.13 shows a custom behavior named “Alert Me!” whose only action is “Show bezel alert.”

Figure 16.13 A custom behavior

Double-click the Command symbol (the same symbol you see on your Command key) to the right of the custom action name to assign a custom keyboard shortcut to it. Press the combination of keys, then use your mouse to select another entry and end editing the shortcut. Figure 6.14 shows the custom action with a new (and hard to press) shortcut.

Figure 16.14 Defining a behavior’s keyboard shortcut

When you press the keyboard shortcut (while Xcode is active), the bezel alert will appear for a moment (Figure 16.15). While unexciting (the bezel alert function only shows the name of custom alerts), it’s easy to see how a simple set of keyboard shortcuts could easily switch your Xcode workspace among a number of different configurations tailored to the task at hand.

Figure 16.15 A useless bezel alert invoked by a behavior shortcut

Wrapping Up

The idea of Xcode’s new workspaces feature can seem intimidating at first. You’ve seen that it’s really quite straightforward. A workspace provides a way of tying related projects together to take advantage of Xcode’s (usually) intelligent dependency discovery. In the next chapter, you’ll explore some of Xcode’s more advanced debugging and analysis capabilities.

17. Debugging and Analysis in Depth

You scratched the surface of Xcode’s debugging and analysis capabilities in Chapter 9 by looking at the most common features developers are likely to use. In this chapter, you’ll explore another powerful feature—the static analyzer—and then delve deeper into the Debug navigator. After that, you’ll take a close look at the debugger console and some of its useful command-line interface tricks. You’ll round out the tour by learning how to debug iOS applications on the device or by using the iOS Simulator.

Using the Clang Static Analyzer

LLVM (the modular compiler) provides static analysis functionality via Clang, its C language family front end. The Clang Static Analyzer performs semantic analysis and can find logic problems, memory management errors, dead stores (unused variables), and API usage problems. This functionality is built right into Xcode.

When you invoke Xcode’s Analyze action, the analyzer works to identify problems with your code. If an issue is found, it is flagged in the Source Editor and in the Issue navigator alongside errors and warnings (Figure 17.1). Clicking the issue in the editor or the Issue navigator reveals details about the issue in the editor, including helpful blue lines indicating the problematic code path with descriptions of your errant actions along the way (Figure 17.2).

Figure 17.1 An issue highlighted by the static analyzer

Figure 17.2 A static analyzer issue expanded into steps

Tip

The Clang Static Analyzer can be run as a standalone tool, providing textual output of its analysis results. Its integration with Xcode is what provides the much nicer graphical interface.

For issues that are spread over longer bodies of code, following all the curved blue lines can be confusing. Xcode helps you with this in two ways. First, expanding an analyzer issue in the Issue navigator reveals the individual points in the problematic code path. Second, and by far more helpful, an analyzer results bar (similar to a search bar) appears at the top of the editor (Figure 17.3). This bar lets you navigate the analyzer issue step by step so it’s easier to follow along with the analyzer’s complaints.

Figure 17.3 The analyzer results bar atop the Source Editor

You can find some of the following issues with Instruments (see Chapter 20) and by using draconian warning levels, but the analyzer can find them while you’re coding and show you exactly where and how you went wrong. Apple’s own documentation suggests you get into the habit of analyzing early and often.

Note

Recall that errors, warnings, and analyzer results are called “issues.”

Exploring Analyzer Results

Following are a few examples of the types of issues the static analyzer can identify for you, with a walk-through of each result.

Memory Leaks

A simple description of a memory leak in a Cocoa application is an object to which you’ve lost any references and which thus can no longer be told to release its memory and go away. In this sense, the object’s memory is “leaked” as it cannot be reclaimed for the remainder of the application’s lifetime. Further, the object keeps living, which, depending on what the object does, can cause unexpected and sometimes very bad behavior.

Figure 17.2 showed an analyzer result for a memory leak. In this case, an NSString is leaked. From the top of the -init method, execution path is followed through the method. The issue is broken down into the two “steps” in the code that caused it.

In the first step, the instruction on line 16 returns an object with a +1 retain count (which, in a memory-managed environment, makes you responsible for properly releasing the object when necessary). In the second step, the method returns without releasing (or autoreleasing) the NSString instance beforehand. This means the NSString instance has been leaked at this point.

In the example, the fix is simple: Just uncomment line 19, where the string instance (assigned to message) is sent a -release (or you could send it an -autorelease).

Notes

The code examples used are “quick and dirty” demonstrations and should not be used as examples of good coding practices for a number of reasons.

The memory management descriptions given here are oversimplified, but the particulars are beyond the scope of this book. For the purposes of this chapter, memory management issues refer to Objective-C objects in a manually memory-managed (versus garbage-collected) environment.

Memory Over-Releases

Again in simple terms, an over-release in a Cocoa application is when an object is sent a -release too many times, causing its memory to be deallocated too soon. Any subsequent attempt to communicate with it will cause your application to crash. In Figure 17.4, the analyzer finds a potential over-release scenario on line 27.

Figure 17.4 A memory issue flagged by the static analyzer

When expanded (by clicking the blue issue bar in the editor), you see the description of the problem is considerably more complex (Figure 17.5). There are four steps to follow through the problem this time. Some sets of blue arrows are bold and some are light. Two of the steps are on line 27 (both can be seen by clicking the gray disclosure triangle on the right side of the step).

Figure 17.5 The complexity of the memory issue revealed by the static analyzer

To make sense of all this, it helps to use the arrow buttons in the analyzer result bar navigator to jump between steps. As you navigate the highlighted code paths, you’ll notice different sets of arrows are bold to emphasize that particular step along the path. In Figure 17.6, the second step is selected, so Xcode highlights the flow of execution from line 22 to 26 to 27, where the analyzer tells you that the object created on line 22 is released if the if condition on line 26 is met.

Figure 17.6 The highlighted second step of the memory issue

Taking the issue step by step, you see that the first step shown in Figure 17.5 tells you an object is created and assigned to objectID with a retain count of +1, meaning you’re responsible for its release.

The second step in Figure 17.6 shows that the object is released on line 27. While there’s no guarantee that its retain count is now zero (flagging it for deallocation) because other objects might have since retained it, the third step (not shown) demonstrates the code path returning to the head of the loop it was in.

The fourth and final step (Figure 17.7) reveals the end result: if ever the if condition on line 20 evaluates to false, the object in question will be accessed after having been released.

Figure 17.7 The highlighted fourth step of the memory issue

This is a good demonstration of the power the static analyzer puts in your hands. It follows all the possible paths through your code, highlighting a problem if one series of logical branches is followed.

Note

The static analyzer is smart enough to know when Objective-C garbage collection is unsupported, supported, or required in your code and adjusts accordingly for memory-management-related issues.

Logic Errors

Logic errors can cause crashes or more subtle problems. In complex code, they can be easy to miss and difficult to debug, but the static analyzer picks them up and highlights them easily.

One type of logic error is using an uninitialized variable. A variable declared without an initial value can point to any old garbage lying around in RAM. Attempting to access that variable gives you undefined or garbage values. Figure 17.8 demonstrates this problem in a basic scenario (the second step is highlighted in the figure).

Figure 17.8 A logic issue flagged by the static analyzer

On line 20, a BOOL variable named positiveFlag is declared with no initial value. Because the code inside the if/else if blocks (lines 22-27) may not be executed, the positiveFlag may never have a defined value assigned to it before the value is returned in line 29.

Threads and Stacks

Chapter 3 introduced the Debug navigator, and Chapter 9 took you in for a closer look at features a typical developer will use most often. Here you’ll see several other features that more-experienced developers will be looking for.

Reviewing the Debug Navigator

The button bar at the bottom of the Debug navigator has two controls (Figure 17.9). When activated, the button on the left side of the bar filters out any threads that aren’t relevant to the current debugging session. That is, only crashed threads and threads with debugging symbols available (those for which you have source code or have saved debugging symbols) will be shown. When the button is inactive, all threads are shown.

Figure 17.9 The Debug navigator’s bottom control bar

The slider control affects how much of each thread’s stack you are shown. When the slider is all the way to the left (Figure 17.10), only the top frame of each thread’s stack is shown. When the slider is all the way to the right (Figure 17.11), all frames of each thread’s stack are shown. As you slide the control from right to left, Xcode begins to collapse the stack by filtering out frames that represent recursive function calls, internal Cocoa API calls, disassembled object code, and finally all code that doesn’t belong to your workspace. Figure 17.12 shows the slider three quarters of the way to the right with the collapsed portions of the stack represented by a dashed line.

Figure 17.10 A minimal stack

Figure 17.11 A full stack

Figure 17.12 A semi-filtered stack

You also learned in earlier chapters that you can navigate to a method by clicking a stack frame in the Debug navigator. If source or disassembled object code is available for the frame, it will be displayed in the Editor area.

Working with Dispatch Queues

With Mac OS X 10.6, Apple introduced Grand Central Dispatch. This new facility makes it far easier for developers to take advantage of multiple cores. Rather than focusing on the deeper complexities of threads, thread pool management, and all that they entail, Grand Central Dispatch is intended to abstract these notions away into “units of work submitted to a queue.”

Queues act as a logical group of background tasks and are created at runtime. A queue can be paused and resumed, can process tasks serially or in parallel, and can even be given simple names to help the developer with debugging efforts. By default, your application’s main thread runs in a dispatch queue named com.apple.main-thread. You might create a queue to process pictures into thumbnails (one task per picture) in parallel and name it com.acme.testapp.thumbnailer.

In Xcode’s Debug navigator, you can choose to view the list of threads grouped by the Grand Central Dispatch queues to which each belongs. Figure 17.13 shows the Debug navigator as it appears with By Queue selected in the filter bar at the top of the view. Here, TestApp is paused in its -applicationDidFinishLaunching: method, which is being run in the main thread, which in turn belongs to the com.apple.main-thread queue. Other queues may be visible, depending on your code and that of the various frameworks and libraries you use.

Figure 17.13 The Debug navigator grouped by queue

Tip

Learn more about Grand Central Dispatch at http://developer.apple.com.

The most important reason for remembering this is that when you create your own queues with Grand Central Dispatch, you can give them a meaningful name so you can identify them clearly in the Debug navigator and (as you’ll discover in Chapter 20) when using Instruments to profile your code.

Suspending Threads

Grand Central Dispatch notwithstanding, threads are still threads, and the typical Cocoa application has several of them hanging around whether you created them or not. If you have created some threads of your own directly, chances are you did it wrong the first (several) times. You realize this because things are freezing, crashing, or just not acting right. It can be helpful in these cases to suspend a thread at runtime to keep it from interfering with other parts of your application or simply to examine it.

Why not just use breakpoints? Suspending a thread is different from using a breakpoint in two important ways. First, a breakpoint will pause execution regardless of the thread calling the instruction. That is, each time a breakpoint is encountered and execution is paused, the thread that hit the breakpoint could be any thread. Second, your goal may be to suspend only some background process your application is performing, not the entire application itself.

To suspend a thread is simple. Make sure you’ve paused the application in the debugger (either at a breakpoint or by using the Pause button in the Debugger Bar), then right-click (or Control-click) the thread in the Debug navigator and choose Suspend Thread from the menu. A red indicator will appear to the right of the suspended thread, showing that it is suspended. You could at this point resume the application (by hitting the Continue button in the Debugger bar) and the thread will remain paused—for good or ill—while your application goes about its business. To resume the thread, you’ll need to be paused again, right-click (or Control-click) the paused thread, and choose Resume Thread from the menu.

Note

Suspending a thread can cause unintended consequences that make your application act strangely at best or corrupt its data, freeze, or crash at worst. Pausing a thread that holds a lock, for example, could deadlock other threads. Use with caution.

Inspecting Memory

In addition to allowing you to set watches (instructing Xcode to notify you if a memory address has changed), Xcode 4 allows you to view the contents of locations in memory. Given a memory address (usually found by a specific variable that uses it), Xcode can let you examine the memory contents directly. These tools are useful when you want to know when a variable’s value changes and the precise nature of the changes to a location or region in memory.

Watching Addresses

The ability to set a watch on a variable’s memory address and be notified when its content changes is a common feature in most any IDE. In Xcode 4, this is done by pausing the debugger and showing the Debug area’s Variables view (Figure 17.14), then right-clicking the variable and choosing Watch Address of “variableName” from the menu.

Figure 17.14 The Variables view in the Debug area

Figure 17.15 shows how to set a watch for the bar variable you created in TestApp in earlier chapters. Nothing special happens immediately after you set the watch. It’s only when the contents of the watched variable’s address changes that you are notified in the debugger console.

Figure 17.15 Setting a watch

In Figure 17.16, you see that the instruction on line 47 was executed, assigning a newly created object to the bar pointer. The memory for that address was updated to point to the address of the new object, so the contents of the memory address for the bar pointer is now the memory address of the newly created object assigned to it. This information is shown in the console.

Figure 17.16 The bar pointer, updated

Watching addresses is a quick and dirty way to see what’s going on with a particular variable in memory, but it’s like looking at memory through a keyhole. Xcode provides a much better way of viewing the contents of your application’s memory.

Viewing Memory

The easier way to inspect the contents of your application’s memory requires pausing the application at least momentarily and locating the memory address you want to view by the variable that represents it. This works the same way as setting a watch. This time, however, when you right-click the variable, choose View Memory of “variableName” from the menu. A new group called Memory will appear in the Debug navigator with the address you chose to view under it (Figure 17.17). When a memory address is selected in the Debug navigator for viewing, the memory’s contents are displayed in the Editor area (Figure 17.18).

Figure 17.17 A memory view added to the Debug navigator

Figure 17.18 The memory view

The view is manipulated via the controls at its bottom (Figure 17.19). The Address field shows the exact memory address the view will begin with. The Memory Page controls let you page forward and backward. The Number of Bytes control lets you adjust the memory page size you’re viewing. The Byte Grouping control lets you control how many bytes are grouped together as a single word.

Figure 17.19 The memory view controls

The Lock button’s behavior isn’t as intuitive as the rest. Your first thought might be that it locks the memory contents, preventing it from being modified. This is not the case. Instead, it lets you lock the current view of the contents from being updated. Since the memory view is normally updated as the memory changes, locking the display prevents it from being updated until you unlock it again. The memory continues to be changed (or not) as it normally would be while execution continues, but what’s displayed will remain the same as it was when you locked it.

Since the memory addresses are valid only while the application is running, all viewed addresses are removed from the Debug navigator when the debugging session ends. If you’d like to remove an address during the session, simply select it and press the Delete key.

Conferring with the Console

The debugger console is your command-line interface to the debugger. Whether you’re using GDB or LLDB, you can do more than read messages spat out by your applications. Both debuggers provide command-line interfaces to the same features that Xcode gives you graphically. Nevertheless, a few quick commands to the debugger via the console (Figure 17.20) can be helpful. Especially so if you want a text dump of the results.

Figure 17.20 The debugger console

In order to issue commands to the debugger console, you must click inside the console window to place the cursor to the right of the debugger prompt ((gdb) or (lldb), depending on the debugger you’re using). The examples that follow will use GDB, as LLDB is still “under construction.”

Following are a few common tasks that can sometimes be done more easily with the console.

Note

As of this writing, LLDB is incomplete, and some commands that are available in GDB are not available or are incomplete in LLDB.

Printing Objects and Values

There are a few different ways to print objects and values from the console. The command you use depends on the kind of information you want to see.

Printing Objects

“Print object” (po) is the single most commonly used debugger command for Cocoa developers. The command will ask Objective-C objects to print the result of their common -description method. Inherited from NSObject, the method returns a string that describes the object. This description is intended to be useful for debugging. When the application is paused in the debugger, all the symbols in the current stack are available to you. This lets you issue a print object command to inspect objects (or other objects to which those objects hold references).

To print an object, you’ll need to pause the application in the debugger. Usually it’s most convenient to use a breakpoint. Once paused, find something interesting to print. Figure 17.21 shows TestApp paused once again in its -applicationDidFinishLaunching: method. This time, it’s paused below the line where you create an NSURL object and assign it to the googleURL variable, giving you a handy object to print. To print the object assigned to googleURL, type the following command into the console and press Return:

po googleURL

Figure 17.21 TestApp paused in the debugger

The debugger will respond by logging the string returned when the NSURL object is asked for its -description. Figure 17.22 shows the results in the debugger console.

Figure 17.22 Printing an object in the debugger console

You can also print self when stopped within a method belonging to an instance of an Objective-C class. In the current scope of the example, self refers to an instance of the TestAppAppDelegate class. Figure 17.23 shows the result of printing self in this scope. In this case, the TestAppAppDelegate class doesn’t override -description, so the information displayed is the default description format inherited from NSObject. That is, the class name and address of the instance being printed are given.

Figure 17.23 Printing self

Of course you can also print objects through the accessors of other objects. For example, NSURL has a string property called -scheme. To print the scheme of the NSURL instance assigned to googleURL, you can issue the following command:

po [googleURL scheme]

The debugger calls the URL object’s -scheme method, then calls the returned object’s -description and prints this:

http

The information you see in the examples isn’t particularly exciting, but it can be enough to differentiate two similar objects inside a printed NSArray or NSDictionary object. While many objects in the Cocoa API come with reasonably useful descriptions, it’s up to the developer to override -description in their own objects and provide meaningful descriptions for their own debugging.

Printing Values

The po command works only on objects. What about values of primitives? What if you wanted to know the length of the string returned by the URL object’s scheme for some reason? You might expect the following command to work:

po [[googleURL scheme] length]

It won’t work because the -length method of NSString returns an NSUInteger—a primitive type, not an object. For primitive values, you use a different print command.

p (NSUInteger)[[googleURL scheme] length]

The debugger responds with this:

$1 = 4

There certainly are four characters in the string http. Let’s take a quick look at the structure of the command and its response.

The command p (short for print) expects the result of the statement you give it to evaluate ([[googleURL scheme] length]) to be cast to the expected type (NSUInteger) so it knows how to represent it. This type should be the return type of the method or function that ultimately returns the value (the outermost call in nested calls). In the case of NSString’s -length method, that’s an NSUInteger.

The response is actually more interesting than it looks. The debugger not only prints the result but kindly assigns it to a local variable for you to use in future evaluations. In this example, the number 4 (the length of the scheme string) was assigned to the variable $1. To use this is simple. Imagine you can’t work out in your head the math necessary to multiply the length by two. No problem! GDB can do it for you!

p (NSUInteger)($1 * 2)

GDB performs this complex computation and responds with:

$2 = 8

Notice how even that evaluation was assigned to a new variable, $2. There are many more tricks up print’s sleeves, which you can find at http://xcodebook.com/printf, but let’s move on.

Viewing the Backtrace

The backtrace in the current (paused) point in the application is the same information that is displayed under a paused thread in the Debug navigator: the stack. While Xcode’s user interface gives you nicely formatted information that can be used to navigate and control the debugging session, it’s not very handy for sharing information with others on a forum or mailing list, for example. It’s often helpful to be able to obtain a textual representation of the backtrace. Assuming TestApp is still paused in the same place as in the previous examples, issuing a backtrace command (bt for short) produces the following output:

#0   -[TestAppAppDelegate applicationDidFinishLaunching:] (self=0x10015e520, _cmd=0x7fff84ad29c5, aNotification=0x114029af0) at /Users/jnozzi/Path/To/TestApp Suite/TestApp/TestApp/TestAppAppDelegate.m:42

#1  0x00007fff83b568ea in _nsnote_callback ()

#2  0x00007fff835f1000 in __CFXNotificationPost ()

#3  0x00007fff835dd578 in _CFXNotificationPostNotification ()

#4  0x00007fff83b4d84e in -[NSNotificationCenter postNotificationName:object:userInfo:] ()

#5  0x00007fff83e3e3d6 in -[NSApplication_postDidFinishNotification] ()

#6  0x00007fff83e3e30b in -[NSApplication_sendFinishLaunchingNotification] ()

#7  0x00007fff83f09305 in -[NSApplication(NSAppleEventHandling)_handleAEOpen:] ()

#8  0x00007fff83f08f81 in -[NSApplication(NSAppleEventHandling)_handleCoreEvent:withReplyEvent:] ()

#9  0x00007fff83b84e42 in -[NSAppleEventManager dispatchRawAppleEvent:withRawReply:handlerRefCon:] ()

#10 0x00007fff83b84c72 in _NSAppleEventManagerGenericHandler ()

#11 0x00007fff88b50323 in aeDispatchAppleEvent ()

#12 0x00007fff88b5021c in dispatchEventAndSendReply ()

#13 0x00007fff88b50123 in aeProcessAppleEvent ()

#14 0x00007fff84e2c619 in AEProcessAppleEvent ()

#15 0x00007fff83e0e04b in _DPSNextEvent ()

#16 0x00007fff83e0d7a9 in -[NSApplication nextEventMatchingMask:untilDate:inMode:dequeue:] ()

#17 0x00007fff83dd348b in -[NSApplication run] ()

#18 0x00007fff83dcc1a8 in NSApplicationMain ()

#19 0x00000001000010c2 in main (argc=1, argv=0x7fff5fbff670) at /Users/jnozzi/Path/To/TestApp Suite/TestApp/TestApp/main.m:12

If you expand the frames under Thread 1 in the Debug navigator and then slide the detail slider all the way to the right (to reveal all stack frames), you’ll see that the information truly is the same. It’s nowhere near as pretty as what you see in Xcode’s UI, but it’s helpful when sharing your misery with other developers in hopes that they can help you.

Controlling Program Execution

You can control program execution from within the console just as you can by using the Debugger Bar or the menu system. This can be handy if you’re working heavily with the console. Here are a few basic commands:

There are many more execution control commands but these are the basics you’re likely to need most. The debugger itself can offer help.

Code Completion

Recall from Chapter 7 that the Source Editor offers code completion, the ability for the editor to predictively suggest completions for the symbols you type. The debugger console offers limited support for this as well.

Getting Debugger Help

There are an impressive number of commands available in GDB (and the list is growing for LLDB as well, as its development progresses). Getting help with these commands is easy. Type help in the debugger and press Return for a list of categories of commands. Type help categoryname to list commands that fall under the named category. Type help commandname for help on the given command. To use one of the previous examples, type the following into the console:

help print

Here are the first few lines of the debugger’s response:

Print value of expression EXP.

Variables accessible are those of the lexical environment of the selected stack frame, plus all those whose scope is global or an entire file.

...

Remember to use the help command to find your way around the debugger’s toolkit.

Viewing Generated Output

The build process entails a number of steps. Along the way, your code is run through the preprocessor (covered in Chapter 19), where macros are expanded, includes are included, and so on. Further down the line, the assembly code is generated by the compiler. Xcode provides several ways to view this generated output.

Generating the Output Manually

You can generate and view this output at any time by choosing Product > Generate Output from the main menu. From there you can choose Generate Preprocessed File or Generate Assembly File. Xcode will produce the requested output and display it. Figure 17.24 shows the preprocessed result of TestAppAppDelegate.m.

Figure 17.24 Preprocessor output from TestAppAppDelegate.m

In Figure 17.24, content from all the included headers is shown. The toolbar at the bottom of the editor has two controls. The Refresh button forces the content to generate again. The pop-up lets you choose the build action for which to generate the output. This is helpful because of the differences between the various build actions (Running, Profiling, Archiving, and so on). Figure 17.25 shows the assembly code for the same file.

Figure 17.25 Assembly output from TestAppAppDelegate.m

Using the Assistant

The Assistant editor can keep this output visible as well. Use the Generated Output mode, and select either Preprocessed content or Assembly content. When the debugger is paused you can see the disassembly as well by using the Assistant’s Disassembly mode (Figure 17.26).

Figure 17.26 Disassembly of TestAppAppDelegate.m

Debugging Apps for iOS Devices

Much of your Xcode exploration to this point has been done with a Mac OS X application because it’s simpler to demonstrate. If you happen to be an iOS developer (or plan to become one), however, this won’t work because of hardware differences. Your debugging, therefore, will have to be done using the iOS Simulator or a connected and provisioned iOS device.

For this demonstration, you’ll need to create an iOS project. Name it TestApp Touch. Refer to Chapter 2 to review how to create a new project. In the New Project template chooser (Figure 17.27), select the Application list under the iOS group, choose Tab Bar Application, and click Next. In the next sheet (Figure 17.28), specify the name and company identifier, leave the Device Family pop-up set to iPhone, do not include unit tests, and click Next. When prompted, save the project in the same folder in which your TestApp Suite workspace lives.

Figure 17.27 The New Project template sheet

Figure 17.28 The iPhone project settings