---

Guidelines for Configuring Applications

The primary way to configure an application is with an information property list file. In this file goes the information needed to register the application with the Finder and Launch Services. The following sections show you which keys to use when configuring an application and some legacy techniques for configuring an application.

Contents:

Information Property List Files
Document Configuration
The PkgInfo File
Using a ‘plst’ Resource
Using Launch Arguments

Information Property List Files

An application bundle should always contain an information property list file with keys to identify the application to the Finder and Launch Services. The sections that follow describe the required and recommended keys you should include. For a complete description of these keys, see “Property List Key Reference.”

Required Properties

The following sections list the keys applications should include in their information property list files.

Application Keys

At a minimum, all applications should contain the following keys in their information property list file:

• CFBundleDisplayName

• CFBundleIdentifier

• CFBundleName

• CFBundlePackageType

• CFBundleShortVersionString

• CFBundleSignature

• CFBundleVersion

• LSHasLocalizedDisplayName

• NSHumanReadableCopyright

• NSAppleScriptEnabled

These keys identify your application to the system and provide some basic information about the services it provides. Cocoa applications should also include the following keys to identify key resources in the bundle:

• NSMainNibFile

• NSPrincipalClass

Document Keys

If your application associates itself with one or more document types, you should include a CFBundleDocumentTypes key to identify those types. The entry for each document type should contain the following keys:

• CFBundleTypeIconFile

• CFBundleTypeName

• CFBundleTypeRole

In addition to these keys, it must contain at least one of the following keys:

• LSItemContentTypes

• CFBundleTypeExtensions

• CFBundleTypeMIMETypes

• CFBundleTypeOSTypes

The LSItemContentTypes key takes precedence over other keys present when the application runs in Mac OS X v10.4 and later. You can continue to include the other keys for compatibility with older versions of the system, however.

Recommended Properties

If you are building a universal binary, you should generally specify the preferred executable architectures you support. Although the native architecture for the current platform is preferred, you may need to run your application under a different architecture to support legacy plug-ins.

To specify which environment you want your application to run in, include the following key in your information property list file:

• LSExecutableArchitectures

• LSRequiresNativeExecution

The LSRequiresNativeExecution key is recommended only if you want to ensure that your universal binary does not run under Rosetta because a PowerPC architecture is preferred over Intel-based architectures. For more information, see “LSExecutableArchitectures.”

Localized Properties

The following list contains the keys that are appropriate to include in your language-specific InfoPlist.strings files:

• CFBundleDisplayName

• CFBundleName

• CFBundleShortVersionString

• NSHumanReadableCopyright

• CFBundleGetInfoString

Document Configuration

Information property list files let you define the role your application plays for its supported document and Clipboard (pasteboard) types. This role defines the relationship between your application and the associated type. Your application can take one of the following roles for any given type:

• Editor. The application can read, manipulate, and save the type.

• Viewer. The application can read and present data of that type.

• Shell. The application provides runtime services for other processes—for example, a Java applet viewer. The name of the document is the name of the hosted process (instead of the name of the application), and a new process is created for each document opened.

• None. The application does not understand the data, but is just declaring information about the type (for example, the Finder declaring an icon for fonts).

The role you choose applies to all of the concrete formats associated with the document or Clipboard type. For example, the Safari application associates itself as a viewer for documents with the “.html”, “.htm”, “shtml, or “jhtml” filename extensions. Each of these extensions represents a concrete type of document that falls into the overall category of HTML documents. This same document can also support MIME types and 4-byte OS types used to identify files in Mac OS 9.

The PkgInfo File

The PkgInfo file is an alternate way to specify the type and creator codes of your application or bundle. This file is not required, but can improve performance for code that accesses this information. Regardless of whether you provide this file, you should always include type and creator information in your information property list file using the CFBundlePackageType and CFBundleSignature keys, respectively.

The contents of the PkgInfo file are the 4-byte package type followed by the 4-byte signature of your application. Thus, for the TextEdit application, whose type is 'APPL' and whose signature is 'ttxt', the file would contain the ASCII string “APPLttxt”.

Using a ‘plst’ Resource

It is possible to incorporate configuration information into a single-file, CFM-based application. However, if you want your application to run natively in Mac OS X—as opposed to running in the Classic compatibility environment—you must provide a 'plst' resource. The 'plst' resource allows the Finder to handle your application and document types properly. If your application does not contain this resource, the Finder automatically runs your application in the Classic compatibility environment.

To create a 'plst' resource, add a new instance with ID 0 to your application resource fork. The content of this resource is the raw XML text from what would be your Info.plist file if your application were bundled. The encoding of this XML data should be UTF-8.

See “Putting Info.plist Files in a Flat Executable” for information on including an information-property list file in an unbundled Mach-O executable.

Using Launch Arguments

If you have a Cocoa application, you can override many user defaults settings by specifying them on the command line. In addition, Cocoa recognizes a few additional arguments for opening and printing files. Table 1 lists some of the more commonly used command-line arguments for Cocoa applications.

---