Xcode Project Management Guide Development Environments: Xcode 2009-09-09 Simultaneously published in the United States Apple Inc. and Canada. © 2009 Apple Inc. Even though Apple has reviewed this document, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, No part of this publication may be reproduced, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS stored in a retrieval system, or transmitted, in PROVIDED “AS IS,” AND YOU, THE READER, ARE any form or by any means, mechanical, ASSUMING THE ENTIRE RISK AS TO ITS QUALITY electronic, photocopying, recording, or AND ACCURACY. otherwise, without prior written permission of IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR Apple Inc., with the following exceptions: Any CONSEQUENTIAL DAMAGES RESULTING FROM ANY person is hereby authorized to store DEFECT OR INACCURACY IN THIS DOCUMENT, even documentation on a single computer for if advised of the possibility of such damages. personal use only and to print copies of THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL documentation for personal use provided that OR WRITTEN, EXPRESS OR IMPLIED. No Apple the documentation contains Apple’s copyright dealer, agent, or employee is authorized to make any modification, extension, or addition to this notice. warranty. The Apple logo is a trademark of Apple Inc. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or Use of the “keyboard” Apple logo consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives (Option-Shift-K) for commercial purposes you specific legal rights, and you may also have without the prior written consent of Apple may other rights which vary from state to state. constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 .Mac is a registered service mark of Apple Inc. Apple, the Apple logo, AppleScript, Carbon, Cocoa, Logic, Mac, Mac OS, Macintosh, Objective-C, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. Finder, Instruments, iPhone, and Spotlight are trademarks of Apple Inc. Intel and Intel Core are registered trademarks of Intel Corportation or its subsidiaries in the United States and other countries. PowerPC and and the PowerPC logo are trademarks of International Business Machines Corporation, used under license therefrom. Contents Introduction Introduction 11 Organization of This Document 11 See Also 12 Part I Part I: Project Organization 13 Chapter 1 Overview of an Xcode Project 15 Components of an Xcode Project 15 Source Files 15 Targets 16 Executables 16 Product Information 16 The Project Directory 18 The Project Info Window 18 General Project Attributes 19 Chapter 2 Creating Projects 21 Choosing a Project Template 21 Specifying the Project Name 22 Opening and Closing Projects 22 Choosing the Project Format 23 Viewing Project Format Conflicts 23 Chapter 3 Files in Projects 25 Files in Xcode 25 The Files in a Project 26 Managing Files and Folders in a Project 27 Adding Files and Folders 27 How Files Are Referenced 29 Removing Files 29 Renaming a Project 30 Managing Libraries and Frameworks 32 Source Trees 35 Referencing Other Projects 36 The Xcode Cache 36 3 2009-09-09 | © 2009 Apple Inc. All Rights Reserved. CONTENTS Chapter 4 Searching Files and Projects 37 Searching in a File 37 Searching Text 37 Replacing Text 39 Searching in a Project 40 The Project Find Window 40 Choosing What to Search For 41 Specifying Which Files to Search 42 Creating Sets of Search Options 42 Viewing Search Results 44 Replacing Text in Multiple Files 45 Shortcuts for Finding Text and Symbol Definitions 46 Chapter 5 Viewing Project Symbols and Classes 47 Symbol Indexing 47 Viewing the Symbols in Your Project 48 Viewing Your Class Hierarchy in the Class Browser 50 Choosing What the Class Browser Displays 52 Saving and Reusing Class Browser Options 53 Chapter 6 Localizing Files 55 Marking Files for Localization 56 Adding Files for a Locale 56 Chapter 7 Using the Organizer 57 Using Organizer Actions 58 Managing Organizer Actions 59 Searching Organizer Items 60 Editing Text Files in the Organizer 60 Part II Part II: Product Development 61 Chapter 8 Building Products 63 Build Locations 63 Setting Default Build Locations 64 Setting Project-Specific Build Locations 64 Editing Build Settings 64 Viewing Build Settings 65 Editing Build Setting Specifications 67 Adding and Deleting Build Settings 67 4 2009-09-09 | © 2009 Apple Inc. All Rights Reserved. CONTENTS Editing Conditional Build Settings 68 Editing Build Settings for Legacy and External Targets 68 Per-File Compiler Flags 69 Search Paths 72 Building with Xcode 74 Setting Build Factors 74 Building a Target 75 Viewing Preprocessor Output 76 Compiling Files 76 Viewing Assembly Code 76 Removing Build Products and Intermediate Build Files 76 Finding Header Files 77 Viewing Build Status 78 Viewing Build Results 78 Viewing Build Messages in the Text Editor 80 Building with xcodebuild 81 Building Projects Created with Early Versions of Xcode 81 Building with the xcodebuild Tool Versus with Xcode 82 Building in Parallel 82 Building for Release 82 Building for Debugging 84 Building Universal Binaries 85 Building for Multiple Releases of an Operating System 85 Building Preferences 86 Chapter 9 Analyzing Code 89 Static Analysis Overview 89 Static Analysis Workflow 91 Interpreting Static Analyzer Messages 94 Viewing Static Analyzer Results 96 Specialized Static Analyzer Checks 97 Memory-Management Checks 97 API-Usage Checks 99 Suppressing Static Analyzer Messages 99 Chapter 10 Defining Executable Environments 101 Executable Environment Overview 101 Setting the Active Executable 102 Creating Custom Executable Environments 102 Configuring Executable Environments 103 Executable-Environment General Settings 103 Executable-Environment Arguments 105 Executable-Environment Debugging Information 106 5 2009-09-09 | © 2009 Apple Inc. All Rights Reserved. CONTENTS Chapter 11 Running Programs 109 Viewing Console Output 109 Halting a Program 109 Document Revision History 111 Index 113 6 2009-09-09 | © 2009 Apple Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 Overview of an Xcode Project 15 Figure 1-1 The key components of a project 15 Figure 1-2 An Xcode project 17 Figure 1-3 General pane of the Project Info window 19 Chapter 2 Creating Projects 21 Figure 2-1 Status bar notification of project format conflicts 22 Figure 2-2 Incompatibility between project format and project configuration 23 Figure 2-3 The project format conflicts window 24 Chapter 3 Files in Projects 25 Figure 3-1 A source file 25 Figure 3-2 The project contents in the Groups & Files list 26 Figure 3-3 Specifying how to add files to a project 28 Figure 3-4 Project to be renamed 30 Figure 3-5 The project-rename dialog 31 Figure 3-6 Project on which a project-rename operation has been performed 31 Chapter 4 Searching Files and Projects 37 Figure 4-1 The search bar on a text editor window 38 Figure 4-2 The search & replace bar on a text editor window 39 Figure 4-3 The Project Find window 41 Figure 4-4 The Batch Find Options window 43 Figure 4-5 Search results in the project window 45 Table 4-1 Shortcuts for performing a projectwide search using the current selection in the editor 46 Chapter 5 Viewing Project Symbols and Classes 47 Figure 5-1 Viewing symbols in your project 48 Figure 5-2 Filtering the symbols in a project 49 Figure 5-3 The class browser 51 Figure 5-4 The class browser options dialog 52 Chapter 6 Localizing Files 55 Figure 6-1 The Info window for a localized item 55 7 2009-09-09 | © 2009 Apple Inc. All Rights Reserved. FIGURES, TABLES, AND LISTINGS Figure 6-2 A localized item in the Groups & Files list and the project directory 56 Chapter 7 Using the Organizer 57 Figure 7-1 The Organizer 57 Figure 7-2 The Organizer action editor 59 Table 7-1 Root-directory-specifier choices and resulting root directories 60 Chapter 8 Building Products 63 Figure 8-1 Build settings for a target 65 Figure 8-2 Build setting conditions 68 Figure 8-3 Conditional build setting 68 Figure 8-4 External Target Info window 69 Figure 8-5 File compiler flags 70 Figure 8-6 Header Search Paths list 73 Figure 8-7 Clean Target dialog 77 Figure 8-8 Build Results window 78 Figure 8-9 Displaying a build-step transcript in the Build Results window 80 Figure 8-10 Text editor displaying build error messages 81 Figure 8-11 Building preferences pane 87 Table 8-1 Build settings for installation builds 83 Table 8-2 Build settings for installing a framework in the local domain 83 Chapter 9 Analyzing Code 89 Figure 9-1 Dereferencing a null pointer 90 Figure 9-2 Memory-management violation 94 Figure 9-3 Flow path of memory-management violation 94 Figure 9-4 Logic violation 96 Figure 9-5 Build Results window showing analyzer