CFBundles

Bundle Programming Guide Data Management: File Management 2010-05-25 Apple Inc. © 2010 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. The Apple logo is a trademark of Apple Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 App Store is a service mark of Apple Inc. Apple, the Apple logo, Cocoa, Finder, iPhone, iPod, iPod touch, iTunes, Mac, Mac OS, Objective-C, Quartz, QuickTime, Spotlight, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. iPad is a trademark of Apple Inc. Intel and Intel Core are registered trademarks of Intel Corportation or its subsidiaries in the United States and other countries. Java and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. PowerPC and and the PowerPC logo are trademarks of International Business Machines Corporation, used under license therefrom. UNIX is a registered trademark of The Open Group Simultaneously published in the United States and Canada. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Contents Introduction Introduction 7 Organization of This Document 7 See Also 7 Chapter 1 About Bundles 9 Bundles and Packages 9 How the System Identifies Bundles and Packages 10 About Bundle Display Names 10 The Advantages of Bundles 11 Types of Bundles 11 Creating a Bundle 12 Programmatic Support for Accessing Bundles 13 Guidelines for Using Bundles 13 Chapter 2 Bundle Structures 15 Application Bundles 15 What Files Go Into an Application Bundle? 15 Anatomy of an iPhone OS Application Bundle 16 Anatomy of a Mac OS X Application Bundle 21 Creating an Application Bundle 25 Framework Bundles 26 Anatomy of a Framework Bundle 26 Creating a Framework Bundle 27 Loadable Bundles 27 Anatomy of a Loadable Bundle 27 Creating a Loadable Bundle 28 Localized Resources in Bundles 28 Chapter 3 Accessing a Bundle's Contents 31 Locating and Opening Bundles 31 Getting the Main Bundle 31 Getting Bundles by Path 32 Getting Bundles in Known Directories 33 Getting Bundles by Identifier 33 Searching for Related Bundles 34 Getting References to Bundle Resources 34 The Bundle Search Pattern 34 Device-Specific Resources in iPhone OS 35 3 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. Getting the Path to a Resource 36 Opening and Using Resource Files 37 Finding Other Files in a Bundle 37 Getting the Bundle’s Info.plist Data 38 Loading and Unloading Executable Code 39 Loading Functions 39 Loading Objective-C Classes 40 Unloading Bundles 41 Chapter 4 Document Packages 43 Defining Your Document Directory Structure 43 Registering Your Document Type 43 Creating a New Document Package 43 Accessing Your Document Contents 44 Glossary 45 Document Revision History 47 4 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. CONTENTS Tables and Listings Chapter 2 Bundle Structures 15 Table 2-1 Types of files in an application bundle 15 Table 2-2 Contents of a typical iPhone OS application bundle 17 Table 2-3 Required keys for the Info.plist file 18 Table 2-4 Keys commonly included in the Info.plist file 19 Table 2-5 Subdirectories of the Contents directory 21 Table 2-6 Expected keys in the Info.plist file 22 Table 2-7 Recommended keys for the Info.plist file 23 Listing 2-1 Bundle structure of an iPhone OS application 16 Listing 2-2 An iPhone OS application with localized and nonlocalized resources 20 Listing 2-3 The basic structure of a Mac OS X application 21 Listing 2-4 A Mac OS X application with localized and nonlocalized resources 24 Listing 2-5 A simple framework bundle 26 Listing 2-6 A simple loadable bundle 28 Listing 2-7 A bundle with localized resources 29 Chapter 3 Accessing a Bundle's Contents 31 Listing 3-1 Getting a reference to the main bundle using Cocoa 31 Listing 3-2 Getting a reference to the main bundle using Core Foundation 31 Listing 3-3 Locating a Cocoa bundle using its path 32 Listing 3-4 Locating a Core Foundation bundle using its path 32 Listing 3-5 Obtaining bundle references for a set of plug-ins 33 Listing 3-6 Locating a bundle using its identifier in Cocoa 33 Listing 3-7 Locating a bundle using its identifier in Core Foundation 34 Listing 3-8 Finding a single resource file using NSBundle 36 Listing 3-9 Finding multiple resources using NSBundle 36 Listing 3-10 Finding a single resource using a CFBundleRef 37 Listing 3-11 Finding multiple resources using a CFBundleRef 37 Listing 3-12 Obtaining the bundle’s version 38 Listing 3-13 Retrieving information from a bundle’s information property list 39 Listing 3-14 An example function for a loadable bundle 40 Listing 3-15 Finding a function in a loadable bundle 40 Listing 3-16 Loading the principal class of a bundle 41 5 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. 6 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. TABLES AND LISTINGS Bundles are a fundamental technology in Mac OS X and iPhone OS that are used to encapsulate code and resources. Bundles simplify the developer experience by providing known locations for needed resources while alleviating the need to create compound binary files. Instead, bundles use directories and files to provide a more natural type of organization—one that can also be modified easily both during development and after deployment. To support bundles, both Cocoa and Core Foundation provide programming interfaces for accessing the contents of bundles. Because bundles use an organized structure, it is important that all developers understand the fundamental organizing principles of bundles. This document provides you with the foundation for understanding how bundles work and for how you use them during development to access your resource files. Organization of This Document This document contains the following chapters: ■ “About Bundles” (page 9) introduces the concept of bundles and packages and how they are used by the system. ■ “Bundle Structures” (page 15) describes the structure and contents of the standard bundle types. ■ “Accessing a Bundle's Contents” (page 31) shows you how to use the Cocoa and Core Foundation interfaces to get information about a bundle and its contents. ■ “Document Packages” (page 43) describes the notion of document packages (which are loosely related to bundles) and how you use them. See Also Although the information in this document applies to all types of bundles, if you are working with more specialized types of bundles (such as frameworks and plug-ins), you should also consult the following documents: ■ Framework Programming Guide provides detailed information about creating and using custom frameworks. ■ Code Loading Programming Topics provides information about writing plug-ins using the Objective-C language. ■ Plug-ins provides information about writing plug-ins using the C language. Organization of This Document 7 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. INTRODUCTION Introduction 8 See Also 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. INTRODUCTION Introduction Bundles are a convenient way to deliver software in Mac OS X and iPhone OS. Bundles provide a simplified interface for end users and at the same time provide support for development. This chapter provides an introduction to bundles and discusses the role they play in Mac OS X and iPhone OS. Bundles and Packages Although bundles and packages are sometimes referred to interchangeably, they actually represent very distinct concepts: ■ A package is any directory that the Finder presents to the user as if it were a single file. ■ A bundle is a directory with a standardized hierarchical structure that holds executable code and the resources used by that code. Packages provide one of the fundamental abstractions that makes Mac OS X easy to use. If you look at an application or plug-in on your computer, what you are actually looking at is a directory. Inside the package directory are the code and resource files needed to make the application or plug-in run. When you interact with the package directory, however, the Finder treats it like a single file. This behavior prevents casual users from making changes that might adversely affect the contents of the package. For example, it prevents users from rearranging or deleting resources or code modules that might prevent an application from running correctly. Note: Even though packages are treated as opaque files by default, it is still possible for users to view and modify their contents. On the contextual menu for package directories is a Show Package Contents command. Selecting this command displays a new Finder window set to the top level of the package directory. The user can use this window to navigate the package's directory structure and make changes as if it were a regular directory hierarchy. Whereas packages are there to improve the user experience, bundles are geared more toward helping developers package their code and to helping the operating system access that code. Bundles define the basic structure for organizing the code and resources associated with your software. The presence of this structure also helps facilitate important features such as localization. The exact structure of a bundle depends on whether you are creating an application, framework, or plug-in. It also depends on other factors such as the target platform and the type of plug-in. The reason bundles and packages are sometimes considered to be interchangeable is that many types of bundles are also packages. For example, applications and loadable bundles are packages because they are usually treated as opaque directories by the system. However, not all bundles are packages and vice versa. Bundles and Packages 9 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. CHAPTER 1 About Bundles How the System Identifies Bundles and Packages The Finder considers a directory to be a package if any of the following conditions are true: ■ The directory has a known filename extension: .app, .bundle, .framework, .plugin, .kext, and so on. ■ The directory has an extension that some other application claims represents a package type; see “Document Packages” (page 43). ■ The directory has its package bit set. The preferred way to specify a package is to give the package directory a known filename extension. For the most part, Xcode takes care of this for you by providing templates that apply the correct extension. All you have to do is create an Xcode project of the appropriate type. Most bundles are also packages. For example, applications and plug-ins are typically presented as a single file by the Finder. However, this is not true for all bundle types. In particular, a framework is a type of bundle that is treated as a single unit for the purposes of linking and runtime usage, but framework directories are transparent so that developers can view the header files and other resources they contain. About Bundle Display Names Display names give the user some control over how bundles and packages appear in the Finder without breaking clients that rely on them. Whereas a user can rename a file freely, renaming an application or framework might cause related code modules that refer to the application or framework by name to break. Therefore, when the user changes the name of a bundle, the change is superficial only. Rather than change the bundle name in the file system, the Finder associates a separate string (known as the display name) with the bundle and displays that string instead. Display names are for presentation to the user only. You never use display names to open or access directories in your code, but you do use them when displaying the name of the directory to the user. By default, a bundle’s display name is the same as the bundle name itself. However, the system may alter the default display name in the following cases: ■ If the bundle is an application, the Finder hides the .app extension in most cases. ■ If the bundle supports localized display names (and the user has not explicitly changed the bundle name), the Finder displays the name that matches the user’s current language settings. Although the Finder hides the .app extension for applications most of the time, it may display it to prevent confusion. For example, if the user changes the name of an application and the new name contains another filename extension, the Finder shows the .app. extension to make it clear that the bundle is an application. For example, if you were to add the .mov extension to the Chess application, the Finder would display Chess.mov.app to prevent users from thinking Chess.mov is a QuickTime file. For more information about display names and specifying localized bundle names, see File System Overview. 10 Bundles and Packages 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. CHAPTER 1 About Bundles The Advantages of Bundles Bundles provide the following advantages for developers: ■ Because bundles are directory hierarchies in the file system, a bundle just contains files. Therefore, you can use all of the same file-based interfaces to open your bundle resources as you do to open other types of files. ■ The bundle directory structure makes it easy to support multiple localizations. You can easily add new localized resources or remove unwanted ones. ■ Bundles can reside on volumes of many different formats, including multiple fork formats like HFS, HFS+, and AFP, and single-fork formats like UFS, SMB, and NFS. ■ Users can install, relocate, and remove bundles simply by dragging them around in the Finder. ■ Bundles that are also packages, and are therefore treated as opaque files, are less susceptible to accidental user modifications, such as removal, modification, or renaming of critical resources. ■ A bundle can support multiple chip architectures (PowerPC, Intel) and different address space requirements (32-bit/64-bit). It can also support the inclusion of specialized executables (for example, libraries optimized for a particular set of vector instructions). ■ Most (but not all) executable code can be bundled. Applications, frameworks (shared libraries), and plug-ins all support the bundle model. Static libraries, dynamic libraries, shell scripts, and UNIX command line tools do not use the bundle structure. ■ A bundled application can run directly from a server. No special shared libraries, extensions, and resources need to be installed on the local system. Types of Bundles Although all bundles support the same basic features, there are variations in the way you define and create bundles that define their intended usage: ■ Application - An application bundle manages the code and resources associated with a launchable process. The exact structure of this bundle depends on the platform (iPhone OS or Mac OS X) that you are targeting. For information about the structure of application bundles, see “Application Bundles” (page 15). ■ Frameworks - A framework bundle manages a dynamic shared library and its associated resources, such as header files. An application can link against one or more frameworks to take advantage of the code they contain. For information about the structure of framework bundles, see “Anatomy of a Framework Bundle” (page 26). ■ Plug-Ins - Mac OS X supports plug-ins for many system features. Plug-ins are a way for an application to load custom code modules dynamically. The following list identifies some of the key types of plug-ins you might want to develop: ❏ Custom plug-ins are plug-ins you define for your own purposes; see “Anatomy of a Loadable Bundle” (page 27). ❏ Image Unit plug-ins add custom image-processing behaviors to the Core Image technology; see Image Unit Tutorial. The Advantages of Bundles 11 2010-05-25 | © 2010 Apple Inc. All Rights Reserved. CHAPTER 1 About Bundles ❏ Interface Builder plug-ins contain custom objects that you want to integrate into Interface Builder’s library window; see Interface Builder Plug-In Programming Guide. ❏ Preference Pane plug-ins define custom preferences that you want to integrate into the System Preferences application; see Preference Pane Programming Guide. ❏ Quartz Composer plug-ins define custom patches for the Quartz Composer application; see Quartz Composer Custom Patch Programming Guide. ❏ Quick Look plug-ins support the display of custom document types using Quick Look; see Quick Look Programming Guide. ❏ Spotlight plug-ins support the indexing of custom document types so that those documents can be searched by the user; see Spotlight Importer Programming Guide. ❏ Sync Schema plug-ins identify custom information that can be synchronized with the system; see Sync Services Programming Guide. ❏ WebKit plug-ins extend the content types supported by common web browsers; see WebKit Plug-In Programming Topics. ❏ Widgets add new HTML-based applications to Dashboard; see Dashboard Programming Topics. Although document formats can leverage the bundle structure to organize their contents, documents are generally not considered bundles in the purest sense. A document that is implemented as a directory and treated as an opaque type is considered to be a document package, regardless of its internal format. For more information about document packages, see “Document Packages” (page 43). Creating a Bundle For the most part, you do not create bundles or packages manually. When you create a new Xcode project (or add a target to an existing project), Xcode automatically creates the required bundle structure when needed. For example, the application, framework, and loadable bundle targets all have associated bundle structures. When