Runtime Configuration Guidelines 2006-09-05 Java and all Java-based trademarks are Apple Computer, Inc. trademarks or registered trademarks of Sun © 2003, 2006 Apple Computer, Inc. Microsystems, Inc. in the U.S. and other All rights reserved. countries. Simultaneously published in the United No part of this publication may be States and Canada. reproduced, stored in a retrieval system, or Even though Apple has reviewed this document, transmitted, in any form or by any means, APPLE MAKES NO WARRANTY OR mechanical, electronic, photocopying, REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS recording, or otherwise, without prior DOCUMENT, ITS QUALITY, ACCURACY, written permission of Apple Computer, Inc., MERCHANTABILITY, OR FITNESS FOR A with the following exceptions: Any person PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND is hereby authorized to store documentation YOU, THE READER, ARE ASSUMING THE on a single computer for personal use only ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. and to print copies of documentation for IN NO EVENT WILL APPLE BE LIABLE FOR personal use provided that the DIRECT, INDIRECT, SPECIAL, INCIDENTAL, documentation contains Apple’s copyright OR CONSEQUENTIAL DAMAGES notice. RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if The Apple logo is a trademark of Apple advised of the possibility of such damages. Computer, Inc. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN Use of the “keyboard” Apple logo LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, (Option-Shift-K) for commercial purposes or employee is authorized to make any without the prior written consent of Apple modification, extension, or addition to this may constitute trademark infringement and warranty. unfair competition in violation of federal Some states do not allow the exclusion or limitation of implied warranties or liability for and state laws. incidental or consequential damages, so the above limitation or exclusion may not apply to No licenses, express or implied, are granted you. This warranty gives you specific legal with respect to any of the technology rights, and you may also have other rights which vary from state to state. 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 or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleScript, Carbon, Cocoa, Mac, Mac OS, Quartz, Sherlock, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder and Safari are trademarks of Apple Computer, Inc. Objective-C is a registered trademark of NeXT Software, Inc. Contents Introduction to Runtime Configuration Guidelines 9 Organization of This Document 9 Information Property List Files 11 Standard Information Property List Files 11 Localizing Property List Values 12 Creating and Editing Property Lists 12 An Example of an Information Property List File 13 Putting Info.plist Files in a Flat Executable 14 Property List Key Reference 15 Key Summary 15 Key Descriptions 20 APInstallerURL 20 APFiles 20 CFAppleHelpAnchor 20 CFBundleAllowMixedLocalizations 21 CFBundleDevelopmentRegion 21 CFBundleDisplayName 21 CFBundleDocumentTypes 21 CFBundleExecutable 23 CFBundleHelpBookFolder 23 CFBundleHelpBookName 23 CFBundleIconFile 23 CFBundleIdentifier 23 CFBundleInfoDictionaryVersion 24 CFBundleLocalizations 24 CFBundleName 24 CFBundlePackageType 24 CFBundleShortVersionString 24 CFBundleSignature 25 CFBundleURLTypes 25 CFBundleVersion 25 CFPlugInDynamicRegistration 25 CFPlugInDynamicRegisterFunction 26 3 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. CFPlugInFactories 26 CFPlugInTypes 26 CFPlugInUnloadFunction 26 CSResourcesFileMapped 26 LSBackgroundOnly 27 LSEnvironment 27 LSGetAppDiedEvents 27 LSHasLocalizedDisplayName 27 LSMinimumSystemVersion 27 LSMultipleInstancesProhibited 28 LSPrefersCarbon 28 LSPrefersClassic 28 LSRequiresCarbon 28 LSRequiresClassic 28 LSUIElement 29 LSUIPresentationMode 29 LSVisibleInClassic 30 NSAppleScriptEnabled 30 NSHumanReadableCopyright 30 NSJavaNeeded 30 NSJavaPath 30 NSJavaRoot 30 NSMainNibFile 30 NSPersistentStoreTypeKey 31 NSPrefPaneIconFile 31 NSPrefPaneIconLabel 31 NSPrincipalClass 31 NSServices 31 The Preferences System 33 How Preferences Are Stored 34 Preference Domains 34 The defaults Utility 35 Environment Variables 37 Environment Variable Scope 37 User Session Environment Variables 37 Application-Specific Environment Variables 38 Guidelines for Configuring Applications 39 Information Property List Files 39 Required Properties 39 Recommended Properties 40 4 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Localized Properties 40 Document Configuration 41 The PkgInfo File 41 Using a ‘plst’ Resource 42 Using Launch Arguments 42 Document Revision History 43 5 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. 6 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Tables and Listings Information Property List Files 11 Listing 1 The Info.plist file for the Sketch demo application 13 Property List Key Reference 15 Table 1 Summary of standard keys 15 Table 2 Keys for APFiles dictionary 20 Table 3 Keys for type-definition dictionaries 21 Table 4 Keys for CFBundleURLTypes dictionaries 25 Table 5 Keys for NSServices dictionaries 31 The Preferences System 33 Table 1 Preference domains in search order 35 Guidelines for Configuring Applications 39 Table 1 Command-line arguments for Cocoa applications 42 7 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. 8 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Introduction to Runtime Configuration Guidelines Dynamic configuration is a convenient way to adjust the properties of your executable without recompiling your code. Rather than relying on hardcoded information, your application implements slightly different behaviors based on external settings. There are several ways to record these settings, ranging from user preferences to property lists stored with your bundle. Bundles use property lists extensively to store information about the bundle and its contents. The information in these property lists is used by system entities, such as the Finder and Launch Services, to determine what to do with the bundle. For example, Launch Services uses data in an application’s information property list to bind one or more document types to the application. Organization of This Document This document contains the following articles: ■ “Information Property List Files” (page 11) discusses information property list files and how you use them to configure your bundled application. ■ “Property List Key Reference” (page 15) provides a reference for the keys that can go into an information property list file. ■ “The Preferences System” (page 33) discusses the role and scope of user preferences and describes the use of the defaults tool for accessing preferences. ■ “Environment Variables” (page 37) discusses the role of environment variables in configuring applications. This section also covers some of the ways you can establish environment variables for a given user session or process. ■ “Guidelines for Configuring Applications” (page 39) lists the required and recommended configuration options for applications. This article also describes additional ways to configure both bundled and non-bundled applications. Organization of This Document 9 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Introduction to Runtime Configuration Guidelines 10 Organization of This Document 2006-09-05 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Information Property List Files Information property list files contain essential configuration information for a bundled executable. Most bundles have at least one file of this type (usually named Info.plist) containing most of the bundle’s configuration information. Other files may also be present depending on the bundle’s contents. All property list files contain text data encoded using Unicode UTF-8 and organized using Extensible Markup Language (XML) code. The XML structure is a great programmatic convenience as it permits the information in the file to be organized hierarchically. Elements of XML correspond to entities such as arrays, dictionaries, strings, and other simple types. Individual properties can represent simple types or containers for other properties. Important: In the sections that follow, pay attention to the capitalization of files and directories that reside inside a bundle. CFBundle and NSBundle consider case when searching for resources inside a bundle directory. Case mismatches could prevent you from finding your resources at runtime. Standard Information Property List Files By convention, a bundle’s information property list file has the name Info.plist. This file resides in the bundle’s Contents directory and contains configuration information for all supported platforms. However, if you want to configure your application differently on different platforms, you can include platform-specific versions of your information property list file. These files reside in your Contents