< Previous PageNext Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Examining and Modifying Property Lists

This section describes how to examine and directly modify the property lists that are used to store installation information in a package. It also provides reference for the Installer keys that you can add or modify.

For additional information on Installer keys, see “Specifying Installation Requirements.”

Installer Keys

When you create a package with PackageMaker, you use the PackageMaker user interface to supply information that is then stored in property list files in the package. PackageMaker creates two kinds of property lists, described in “Installer Keys” and “The PackageMaker Description Property List.” For information on additional property lists you may need to modify, see “Property Lists You Can Create.”

The information in a property list is stored as a series of keys and associated values. For example, if your package does not require user authorization, the Info.plist file will contain the key IFPkgFlagAuthorizationAction with the string value “NoAuthorization”. The “IF” in the key name stands for Installation framework. Listing 1 shows the property list for a simple package.

Listing 1 The property list for a simple package

<?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>IFMajorVersion</key>

    <integer>0</integer>

    <key>IFMinorVersion</key>

    <integer>0</integer>

    <key>IFPkgFlagAllowBackRev</key>

    <false/>

    <key>IFPkgFlagAuthorizationAction</key>

    <string>NoAuthorization</string>

    <key>IFPkgFlagDefaultLocation</key>

    <string>/</string>

    <key>IFPkgFlagInstallFat</key>

    <false/>

    <key>IFPkgFlagIsRequired</key>

    <false/>

    <key>IFPkgFlagOverwritePermissions</key>

    <true/>

    <key>IFPkgFlagRelocatable</key>

    <false/>

    <key>IFPkgFlagRestartAction</key>

    <string>NoRestart</string>

    <key>IFPkgFlagRootVolumeOnly</key>

    <false/>

    <key>IFPkgFlagUpdateInstalledLanguages</key>

    <false/>

    <key>IFPkgFlagUseUserMask</key>

    <false/>

    <key>IFPkgFormatVersion</key>

    <real>0.10000000149011612</real>

</dict>

</plist>

Editing a Property List

Some developers will never need to directly edit a package’s information property list or description property list, but there are several reasons why you might. These reasons are described in “The Package as a Black Box.” For example, you might need to use a feature that is not accessible through the PackageMaker user interface.

“Other Keys You Might Want to Modify” lists examples of several property list keys you might want to directly modify. For an example that provides step-by-step instructions for editing the property list file of a metapackage, see “Hiding the Packages Contained in a Metapackage.”

You can examine the contents of a package in the Finder by Control-clicking it and choosing Show Package Contents from the contextual menu. You can then view or edit the Info.plist and Description.plist files in an appropriate XML or text editor. You may have to change the file’s permissions before editing one of these files.

Note: Double-clicking the Info.plist file opens it in Property List Editor, but due to a bug in some versions prior to the one released with Mac OS X version 10.3, Property List Editor may not display the keys correctly in its table view. It does howevever display the underlying text correctly in its text view (click the Dump button).

You can also examine the contents of a package in a Terminal window using the find command. It’s also possible to directly edit a property list file as you would any XML file. Listing 2 shows the result of using the find command to display the contents of a package in the current directory. The types of files contained in a package are described in “Anatomy of a Package.”

Warning: If you open a package definition file (a file with extension .pmsp) in PackageMaker and recreate its package with the same name and location, you overwrite any changes you may have made to the Info.plist file or other package files created by PackageMaker. Therefore, if you switch back and forth between direct editing and editing with PackageMaker, be sure to save copies of your edited files and reinsert your changes.

Listing 2 Displaying the contents of a package in a Terminal window

% find Simple.pkg

Simple.pkg

Simple.pkg/Contents

Simple.pkg/Contents/Archive.bom

Simple.pkg/Contents/Archive.pax.gz

Simple.pkg/Contents/Info.plist

Simple.pkg/Contents/PkgInfo

Simple.pkg/Contents/Resources

Simple.pkg/Contents/Resources/Description.plist

Simple.pkg/Contents/Resources/Simple.bom

Simple.pkg/Contents/Resources/Simple.info

Simple.pkg/Contents/Resources/Simple.pax.gz

Simple.pkg/Contents/Resources/Simple.sizes

The PackageMaker Information Property List

An information property list contains key-value pairs that specify various information about an application or bundle that can be used at runtime. When you create a package, PackageMaker stores much of the information you supply in the package’s Info.plist file. Each package has one such file, stored in the Contents directory. This file is not localizable.

You’re most likely to be interested in Installer key information if you want to modify a package directly by editing its property list files. The Installer keys used in the Info.plist file are documented in the following sections:

Some keys are not actually defined by Installer—for example, CFBundleName and CFBundleIdentifier are standard bundle keys that are used by many other applications. However, as described here, they are used in a package property list to provide installation information.

Important: For clarity, sample values for string keys are shown in quotation marks. However, the actual value does not include the quotation marks.

Keys That Can Appear in Any Package

The following keys, listed in alphabetical order, can be used in packages or metapackages:

CFBundleGetInfoString

optional

data type: string

default value: none

example: “My Great Application 1.0”

Provides information for the Finder to display about the package.

CFBundleIdentifier

required

data type: string

default value: none

example: “com.mycompany.mygreatapplication”

A unique identifier string for the bundle. It should be in the form of a Java-style package name. For more information, see “Property List Key Reference” in Runtime Configuration Guidelines.

CFBundleName

optional

data type: string

default value: none

example: “My Great Application”

Provides information for the Finder to display about the package.

CFBundleShortVersionString

optional

data type: string

default value: none

example: “1.0”

Provides information for the Finder to display about the package.

IFMajorVersion

optional

data type: int

default value: none

example: 1

Although some versions of Package Maker allow you to enter a value for this key in the “Major” field, and you may see it in the information property list for a package, this key is not used by Installer.

IFMinorVersion

optional

data type: int

default value: none

example: 0

Although some versions of Package Maker allow you to enter a value for this key in the “Minor” field, and you may see it in the information property list for a package, this key is not used by Installer.

IFPkgFlagBackgroundAlignment

optional

data type: string

values: “left”, “right”, “top”, “bottom”, “center”, “topleft”, “topright”, “bottomleft”, “bottomright”

default value: “center”

example: “bottom”

Specifies the alignment for a background image. Most useful for an image that is smaller than the installer window. Background images and alignment are described in “Supplying a Background Image.”

IFPkgFlagBackgroundScaling

optional

data type: string

values: “none”, “tofit”, “proportional”

default value: “tofit”

example: “proportional”

Specifies the scaling for a background image. Most useful for an image that is larger, in at least one dimension, than the installer window. Background images and scaling are described in “Supplying a Background Image.”

IFPkgFormatVersion

required

data type: float

default value: none

example: 0.10000000149011612

Used internally by Installer to determine the package format and version. If missing, or if value is not greater than 0.1, the package is not read correctly, and fails to load.

You should not change this key.

Keys That Can Appear Only in Single Packages

The following keys, listed in alphabetical order, can be used only in packages:

IFPkgFlagAllowBackRev

optional

data type: BOOL

default value: No

example: Yes

Should Installer allow reverting to an earlier version of the package?

IFPkgFlagAuthorizationAction

optional

data type: enum

values: NoAuthorization, AdminAuthorization, RootAuthorization

default value: NoAuthorization

example: AdminAuthorization

Should Installer require authorization (and prompt the user to authenticate)?

For related information, see Table 1.

IFPkgFlagDefaultLocation

optional

data type: string

default value: “/”

example: “/Applications”

The initial install location. If the package is relocatable, the user can change the install location.

Keys That Can Appear Only in Metapackages

The following keys, listed in alphabetical order, can be used only in metapackages.

IFPkgFlagComponentDirectory

required

data type: string

default value: “..”

example: “../.contained_packages”

Specifies the location of the contained packages or metapackages, as a path relative to the containing metapackage. Prepended to the name field of each package or metapackage to locate it.

The building of paths to subpackages for a metapackage starts with the path to the metapackage. The component directory is then added. The use of “..” specifies one directory up from the current path, which is the directory containing the metapackage. So the default option is to look for contained packages at the same level as the metapackage itself.

Setting the value of this key to “../.contained_packages” would specify a directory named contained_packages within the directory containing the metapackage.

For an example that modifies this key, see “Hiding the Packages Contained in a Metapackage.”

IFPkgFlagPackageList

required

data type: array of dictionaries

default value: none

Specifies the contained packages or metapackages. Array includes a dictionary for each package or metapackage; each dictionary has the following keys: IFPkgFlagPackageLocation and IFPkgFlagPackageSelection.

Since a metapackage cannot be created without at least one package in the package list, this array will be filled in and the dictionaries for each package will be built as well.

IFPkgFlagPackageLocation

required

data type: string

default value: none

example: “MyPackage.pkg”

The full name of the contained package or metapackage. Must have the extension .pkg or .mpkg.

Used as a key in a dictionary defined as part of the IFPkgFlagPackageList key.

IFPkgFlagPackageSelection

optional

data type: enum

values: selected, unselected, required

default value: selected

example: required

Used in determining whether checkbox for installing the package or metapackage is shown as selected or not, and whether it is enabled. For more information, see “When a Package or Metapackage Is Required.”

Used as a key in a dictionary defined as part of the IFPkgFlagPackageList key.

The PackageMaker Description Property List

When you create a package, some of the information you supply in PackageMaker winds up in the description property list file (Description.plist). This file is similar to the Info.plist file, in that both contain key-value pairs that store information about the package. However, the description property list contains information that is localizable (currently gathered from the PackageMaker Description pane). PackageMaker provides a Description pane for both packages and metapackages, and both types of package have Description.plist files.

By default, the Description.plist file is located in the package’s Resources directory, but it may instead be in one of the language project subdirectories, such as French.lproj. Currently, Installer uses the value of the IFPkgDescriptionTitle key as part of the title of the installer window, and on the Welcome page as well. It uses the value of the IFPkgDescriptionDescription key in the Custom Install pane (available only to metapackages) when a package or metapackage is selected.

Important: For clarity, sample values for string keys are shown in quotation marks. However, the actual value does not include the quotation marks.

Description Property List Keys

The following keys, listed in alphabetical order, can be used in all packages.

IFPkgDescriptionTitle

required

data type: string

default value: none

example: “My Excellent Software”

The name of the package or metapackage, or other short, descriptive information about it.

IFPkgDescriptionVersion

optional

data type: string

default value: none

example: “1.1”

Specifies the version for the package or metapackage. Not currently used.

Property Lists You Can Create

You can provide information to help Installer find your previously installed software during future upgrades. If you do, you’ll need to create a property list named TokenDefinitions.plist to specify information about the search methods to employ.

For information about the structure and keys used in this property list, see “Finding Previously Installed Software.” For another situation in which you might work with this list, see the section “Bundle Requirements” in “Specifying Installation Requirements.”

Other Keys You Might Want to Modify

There are several situations where you may need to modify a property list key as part of specifying a feature.

Starting in Mac OS X version 10.3, you can provide information to specify requirements for the installation of your software, as described in “Specifying Installation Requirements.”
In providing information to help Installer find your previously installed software, you supply various keys and values, as described in “Finding Previously Installed Software.”
You specify alignment and scaling for a background image by setting the IFPkgFlagBackgroundAlignment and IfPkgFlagBackgroundScaling keys, respectively, as described in “Supplying a Background Image.”
To hide the package files in a metapackage, you may need to set the value of the IFPkgFlagComponentDirectory key, as described in “Hiding the Packages Contained in a Metapackage.”
You can change the default behavior of the Installer application in treating symbolic links by setting the value of the IFPkgFlagFollowLinks key, as described in “Installing Can Convert Symbolic Links to Actual Directories.”
Starting in Mac OS X version 10.3, you can specify that an installation requires a logout by setting the value of the IFPkgFlagRestartAction key in the package’s information property list to RequiredLogout. For information on other restart actions, see “Restarting, Logging Out, or Shutting Down.”

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Legacy Document

Examining and Modifying Property Lists

Contents:

Installer Keys

Editing a Property List

The PackageMaker Information Property List

Keys That Can Appear in Any Package

Keys That Can Appear Only in Single Packages

Keys That Can Appear Only in Metapackages

The PackageMaker Description Property List

Description Property List Keys

Property Lists You Can Create

Other Keys You Might Want to Modify