< Previous PageNext Page > Hide TOC

Information Property List Files

An information property list file contains 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. Variants of this file may also be present depending on the platforms and languages supported by the bundle.

The contents of an Information property list file are organized hierarchically, with each node in the hierarchy containing an entity such as an array, dictionary, string, or other scalar type. Information property list files are typically saved as XML files in a text file format that uses the Unicode UTF-8 encoding. Although you may encounter versions of these files encoded using ASCII text and binary formats, the XML format is recommended for any new files you save. Regardless of the format, you can open property list files saved in ASCII, XML, and binary formats using the Property List Editor application.

Contents:

Standard Information Property List Files
Localizing Property List Values
Creating and Editing Property Lists
An Example of an Information Property List File
Putting Info.plist Files in a Flat Executable

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 directory. The name of each file is of the form “Info-<platform>.plist.” The currently supported platforms are macos and macosclassic, thus you can define the following platform-specific information property list files:

• Info-macos.plist contains properties specific to a Mac OS X application.

• Info-macosclassic.plist contains properties specific to an application run in the Classic compatibility environment.

NSBundle and CFBundle load only one information property list file from your bundle, preferring the platform-specific version over the generic version. Thus, if you provide platform-specific information property list files for your bundle, make sure each of them contains all of the necessary keys to configure the application. Otherwise, if you split the required keys between an Info-macos.plist file and a Info.plist file, the keys in the Info.plist file are ignored.

You can create custom property lists as needed to store the values for application-specific configuration keys. If you create custom property lists, put them in your Contents/Resources directory with the rest of your application-specific resources. You can include your keys in your bundle’s information property list file if you want all of your keys stored in one place.

Localizing Property List Values

If your information property list file contains values that might be displayed to the user, you should provide localized values for those properties. To deliver localized values, you create an InfoPlist.strings file in each language-specific resource directory of your bundle. Inside this strings file, you specify the key for each property you wish to localize along with the appropriate translated value.

At runtime, when your code retrieves the value of a property, the NSBundle and CFBundle routines check to see if an InfoPlist.strings file of the appropriate language exists and if it contains the requested key. If it does, the routines return the value from the strings file. If the key does not exist in any language files, the routines return the default version of the key from your bundle’s Info.plist file.

For example, the TextEdit application has several keys that are displayed in the Finder and thus should be localized. Suppose your information property list file defines the following keys:

<key>CFBundleDisplayName</key>

<string>TextEdit</string>

<key>NSHumanReadableCopyright</key>

<string>Copyright © 1995-2002, Apple Computer, Inc.,All Rights Reserved.

</string>

The French localization for TextEdit then includes the following strings in the InfoPlist.strings file of its Contents/Resources/French.lproj directory:

CFBundleDisplayName = "TextEdit";

NSHumanReadableCopyright = "Copyright © 1995-2002 Apple Computer Inc.\nTous droits réservés.";

See Bundle Programming Guide for more about localizing bundles.

Creating and Editing Property Lists

The simplest way to create a new property list file or edit an existing file is to use the Property List Editor application. This application comes with Xcode and is installed in the <Xcode>/Applications/Utilities directory (where <Xcode> is the root directory of your Xcode installation). When you launch the application, it automatically opens a new, empty property list for you to edit.

To create a basic property list, add a root element and one or more children. The root element is always a dictionary. The children of the root can be any of the simple types (String, Number, Boolean, Date, or Data) or one of the collection types (Array or Dictionary).

Once you save the property list, you can edit it either with the Property List Editor or with any text editor that supports UTF-8 encoding. Although you can edit the file with an XML editor, make sure your editor saves the file in the UTF-8 encoding.

An Example of an Information Property List File

Listing 1 shows the Info.plist file of the Sketch sample application from Mac OS X v10.5. Sketch is a Cocoa application so it includes the NSMainNibFile and NSPrincipalClass keys to identify the location of the primary application resources. Sketch registers several supported document types (using both UTIs and the file extensions) to make it easier to work with those types of files. UTIs are supported in Mac OS X v10.5 and later and are the preferred way to register support for file types. For more information about the meaning of each key, see “Property List Key Reference.” (Note, many of the comments in this XML file were removed or edited for brevity.)

Listing 1  The Info.plist file for the Sketch demo application

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

    <key>CFBundleDevelopmentRegion</key>

    <string>English</string>

    <key>CFBundleDocumentTypes</key>

    <array>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>sketch2</string>

            </array>

            <key>CFBundleTypeIconFile</key>

            <string>Draw2File</string>

            <key>CFBundleTypeName</key>

            <string>Apple Sketch document</string>

            <key>CFBundleTypeRole</key>

            <string>Editor</string>

            <!-- The LSItemContentTypes key is ignored in Mac OS X v10.4 because it’s introduced in 10.5. -->

            <key>LSItemContentTypes</key>

            <array>

                <string>com.apple.sketch2</string>

            </array>

            <key>NSDocumentClass</key>

            <string>SKTDrawDocument</string>

            <!-- This key is ignored in Mac OS X 10.5 because of the presence of the LSItemContentTypes key. -->

            <key>NSExportableAs</key>

            <array>

                <string>NSPDFPboardType</string>

                <string>NSTIFFPboardType</string>

            </array>

            <!-- The NSExportableTypes key is ignored in Mac OS X 10.4 -->

            <key>NSExportableTypes</key>

            <array>

                <string>com.adobe.pdf</string>

                <string>public.tiff</string>

            </array>

        </dict>

        <!-- These keys are for compatibility with Mac OS X v10.4. -->

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>pdf</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>NSPDFPboardType</string>

            <key>CFBundleTypeRole</key>

            <string>None</string>

        </dict>

        <dict>

            <key>CFBundleTypeExtensions</key>

            <array>

                <string>tiff</string>

                <string>tif</string>

            </array>

            <key>CFBundleTypeName</key>

            <string>NSTIFFPboardType</string>

            <key>CFBundleTypeRole</key>

            <string>None</string>

        </dict>

    </array>

    <key>CFBundleExecutable</key>

    <string>Sketch</string>

    <key>CFBundleIconFile</key>

    <string>Draw2App</string>

    <key>CFBundleIdentifier</key>

    <string>com.apple.CocoaExamples.Sketch</string>

    <key>CFBundleInfoDictionaryVersion</key>

    <string>6.0</string>

    <key>CFBundlePackageType</key>

    <string>APPL</string>

    <key>CFBundleShortVersionString</key>

    <string>2.0</string>

    <key>CFBundleSignature</key>

    <string>sktc</string>

    <key>CFBundleVersion</key>

    <string>46.1</string>

    <key>NSAppleScriptEnabled</key>

    <string>YES</string>

    <key>NSMainNibFile</key>

    <string>Draw2</string>

    <key>NSPrincipalClass</key>

    <string>NSApplication</string>

    <key>OSAScriptingDefinition</key>

    <string>Sketch.sdef</string>

    <!-- UTI keys are for ignored in Mac OS X v10.4 but used in Mac OS X v10.5. -->

    <key>UTExportedTypeDeclarations</key>

    <array>

        <dict>

            <key>UTTypeDescription</key>

            <string>Apple Sketch document</string>

            <key>UTTypeConformsTo</key>

            <array>

                <string>public.data</string>

            </array>

            <key>UTTypeIconFile</key>

            <string>Draw2File</string>

            <key>UTTypeIdentifier</key>

            <string>com.apple.sketch2</string>

            <key>UTTypeTagSpecification</key>

            <dict>

                <key>public.filename-extension</key>

                <array>

                    <string>sketch2</string>

                </array>

            </dict>

        </dict>

    </array>

</dict>

</plist>

Putting Info.plist Files in a Flat Executable

Even if your program does not use the bundle structure, it should still include an information property-list file to identify key pieces of information to the system. For unbundled CFM executables, you can place the contents of the program's Info.plist file in a 'plst' resource. For unbundled Mach-O executables, you can create an __info_plist section in the executable's __TEXT segment and put the contents of your information property-list file there. To create an __info_plist section, you would create an Info.plist file as you would for a bundled program and then add the following linker options to your makefile or Xcode project:

-sectcreate __TEXT __info_plist Info.plist

To retrieve the Info.plist information, your unbundled program can use many of the CFBundle functions for accessing bundle properties. Although your program is not bundled, you can still get the "main bundle" and pass that object to any functions you call.

< Previous PageNext Page > Hide TOC