< Previous PageNext Page > Hide TOC

Specifying Installation Requirements

“Specifying Installation Requirements” describes how to insert information into the information property list for a package to request or require that certain criteria be satisfied before the package is installed.

You can use the requirements mechanism to ensure that your software is installed only on systems that meet specified criteria, such as minimum hardware or system requirements or the presence of required files or directories. You can also ensure that your software is installed only on volumes that meet specified criteria.

Before reading this article, you should be familiar with the information in “Examining and Modifying Property Lists.”

Contents:

New and Existing Requirements Checking
The Requirements Mechanism
When to Use Requirements
Adding Requirements to the Information Property List
Requirements Message Strings
Requirements Keys
Requirements Examples

New and Existing Requirements Checking

As of Mac OS X version 10.3 (v10.3), Installer supports two approaches to checking installation requirements:

• The requirements mechanism: allows you to specify requirements by inserting information into the information property list for a package.

  Available only in Mac OS X v10.3 and later.

• The InstallationCheck and VolumeCheck executables (typically implemented as shell scripts): allows you to add scripts to a package’s Resources folder to check for requirements. For details, see “Checking the Installation With InstallationCheck” and “Checking the Installation Volume With VolumeCheck.”

  Available prior to Mac OS X v10.3. Scripts will work in v10.3, but are ignored if the package also includes requirements information in its property list.

The requirements mechanism offers the benefits that it can be easier to use than working with InstallationCheck and VolumeCheck shell scripts and presents fewer security risks. However, for maximum flexibility, you can provide both requirements information and scripts in the same package.

Installer runs InstallationCheck and VolumeCheck executables, if present, at well-defined times during an installation, as described in “Installation Steps, in Order.” In Mac OS X v10.3, Installer does similar checking at similar times for a package that contains requirements specifications in its property list:

• At the time Installer would execute InstallationCheck, if present, it instead makes a pass through all the requirements, ignoring any requirements that are volume-specific. For example, it will evaluate gestalt and sysctl requirements, but skip plist and bundle requirements. (These terms are defined below.)

• At the time Installer would execute VolumeCheck, if present, it instead makes a pass through all the requirements, once for each volume, ignoring any requirements that are not volume-specific.

• For a metapackage, requirements are checked first for the metapackage itself, then for any packages it contains that specify requirements. Checking takes place at the same time it would for individual packages.

The Requirements Mechanism

The requirements mechanism is based on the commonly used practice of adding key-value pairs to an information property list—in this case, the property list of an installation package. A requirement is a well-defined collection of key-value pairs that together specify criteria that Installer checks before installing the contents of the package. For a complete list of these keys, including information on which are required and which are optional, see “Requirements Keys.”

The general structure of a requirement is shown on the left in Figure 1. The example on the right shows possible values for a requirement—in this case, a requirement that version 1.0 or greater of the application already be installed:

Figure 1  The installation requirements model

Each requirement contains several components:

• A level specifies how the requirement should be enforced (whether it is required, recommended, and so on).

• A specifier is a reference to a state or resource in the system upon which software can be dependent. Examples include the version of the iTunes application, the value of a hardware registry key, or the value within a preference plist.

• A test is a statement which uses the specifier and resolves to a value of true or false.

• Label, title, and message provide access to developer-supplied strings that Installer can use to describe the requirement to the user.

A specifier is resolved to an object value, then the object value is compared within the test. For example, a specifier might represent the version of iTunes and the test might be whether that object value is greater than 3. The result of the test is a boolean value, which indicates whether or not the test was satisfied.

The result of a test can be interpreted according to the requirement level and can be described to the user with title and message strings you supply, as described in “Requirements Message Strings.”

Listing 1 shows what the requirement example from Figure 1 might look like in a property list. For additional examples, see “Requirements Examples.”

Listing 1  A requirement for the MyApp installation package

<key>IFRequirementDicts</key>

<array>

    <dict>

        <key>Level</key>

        <string>requires</string>

        <key>SpecType</key>

        <string>bundle</string>

        <key>SpecArgument</key>

        <string>/Applications/MyApp</string>

        <key>SpecProperty</key>

        <string>CFBundleVersion</string>

        <key>TestOperator</key>

        <string>&gt;=</string>

        <key>TestObject</key>

        <string>1.0</string>

        <key>LabelKey</key>

        <string>MyAppLabelKey</string>

        <key>TitleKey</key>

        <string>MyAppTitleKey</string>

        <key>MessageKey</key>

        <string>MyAppMessageKey</string>

    </dict>

</array>

When to Use Requirements

Although the requirements mechanism is flexible, in general you should avoid specifying broad requirements such as Mac OS X >= 10.2.5 or RAM >= 256 MB. Such statements are useful in marketing or customer support contexts, but they are not well-defined in the machine-level context of software installation and management. Instead, where possible you should use fine-grained requirements such as the examples shown in Table 1.

These examples define requirements that in simple language equate to “the AppKit framework version must be greater than or equal to 663.7” and “the Safari build version must be greater than or equal to 74”. For Safari, that might be the equivalent of “Safari must be greater than or equal to version 1.0.2”.

Similarly, avoid using marketing versions, such as CFBundleShortVersionString, when specifying requirements. For example, the use of strings such as “1.0 Beta 2" and “0.9” might be useful in user-level marketing or customer support terms, but would not be not well-defined in the machine-level contexts of software installation and management. Instead, you should use CFBundleVersion when specifying requirements (as shown in examples throughout this article).

For information on editing a property list, see “Examining and Modifying Property Lists.” For information on the keys you use to define requirements in a property list, see “Requirements Keys.”

Adding Requirements to the Information Property List

The information property list for a package can contain zero or more requirements. To add requirements to the property list, you add the IFRequirementDicts key at the root level. The value associated with this key is an array that contains one or more requirements dictionaries. Each dictionary is comprised of a combination of the keys shown in Table 2. Several examples of these dictionaries are provided in “Requirements Examples.”

For information on editing a property list, see “Examining and Modifying Property Lists.” For information on the keys you use to define requirements in a property list, see “Requirements Keys.”

Requirements Message Strings

When you define a requirement in a property list, you can specify various message keys. Installer uses these keys to obtain information to display to the user if the requirement is not satisfied. You also supply the information Installer displays, in the form of a strings file based on the keys you defined. The mechanism works like this:

1. For each requirement, you add entries for any of the three keys LabelKey, TitleKey, or MessageKey.

2. For each key you supply a value.

   For example, you might add a MessageKey with the value "SafariRequirementOne".

3. You also supply a localizable strings file named IFRequirement.strings. A requirement strings file contains messages in the following format:

   "key string" = "message string";

   For the MessageKey described in the previous step, the strings file entry might look like this:

   "SafariRequirementOne" = "You must upgrade to Mac OS X v10.3 before installing this software.";

Format and Usage for Message Strings

When a requirement cannot be satisfied, Installer displays information to the user by assembling the message strings you supply according to its predefined usage pattern. If you supply no keys, Installer displays a generic message.

The following sections describe the available message keys, the kinds of strings you should supply for each key, and Installer’s usage for assembling the strings into a message.

LabelKey

The LabelKey specifies a string that provides a concise description of the requirement in grammatical object form. Some examples include:

"Mac OS X v10.3 or newer"

"at least 128 MB of memory"

"certain languages"

"a newer version of Java"

Because the label may be used in various forms, including lists, it should not be a complete sentence nor include ending punctuation.

TitleKey

The TitleKey specifies a string that provides a complete explanation of the requirement and why it could not be satisfied. Some examples include:

"Safari cannot be installed on this computer, because it requires a new version of the WebKit framework."

"Your computer doesn't have a SuperDrive. Do you want to install iDVD anyway?"

In the case of a single failed requirement, Installer displays the following:

<TitleKey string> <MessageKey string>

If the requirement does not define TitleKey, Installer constructs a generic one, where <name> represents the package title:

"<name> cannot be installed on this computer."

If the requirement does not define MessageKey, no text is displayed for that key.In the case of multiple failed requirements, Installer ignores any MessageKey strings (in Mac OS X version 10.3). Instead, it displays the generic title, followed by the titles from each of the requirements. If a requirement does not define a TitleKey, no TitleKey string is displayed for it.

<name> cannot be installed on this computer.

    <TitleKey1 string>

    <TitleKey2 string>

    <TitleKey3 string>

MessageKey

The MessageKey specifies a string that provides a short explanation of how to resolve the issue, if possible, when the requirement is not satisfied. Some examples include:

"You must upgrade to Mac OS X v10.3 before installing this software."

"Use Software Update to check for a newer version of this driver."

"This volume does not meet the requirements for this system update."

MessageKey is used in conjunction with TitleKey, as described in “TitleKey.”

Localizing the Requirements Strings File

If you localize your requirements strings file, Installer will display messages based on the user’s current Languages preference. You can use any of the folder names listed in “Localized Folder Names.” These folders should be located within the package’s Resources directory, so that the resulting location looks something like Resources/<language>.lproj/IFRequirement.strings. You can view the hierarchy of a package Resources directory containing localized folders in Listing 2. You would place your IFRequirement.strings file in place of the InstallationCheck.strings file in that listing.

If no IFRequirement.strings file is placed in a localized directory, or no localized version is found for the user’s current language selection, Installer looks for a default version at the highest level in the Resources directory.

Default Messages Provided by Installer

As noted in “TitleKey,” if you do not supply message keys or a IFRequirement.strings file, Installer supplies a generic message when a requirement is not satisfied.

Requirements Keys

Table 2 lists the keys you use to define a requirement in a package’s information property list. These keys correspond to the structure shown in Figure 1. Additional information for each key is provided in the sections that follow the table. For information on working with these keys, see “Adding Requirements to the Information Property List” and “Requirements Examples.”

LabelKey, TitleKey, and MessageKey

The value for a LabelKey, TitleKey, or MessageKey is a key that specifies a string in a localized strings file named IFRequirement.strings, stored in the package’s Resources folder. These keys and strings files are described in “Requirements Message Strings.”

All of these keys are optional and if you do not supply them, Installer supplies a generic message when a requirement is not satisfied.

Level

The value supplied for the Level key specifies the resulting behavior when a requirement is not satisfied on the user’s system at pre-installation time. The currently supported values are:

• requires: Used if the package should not be installed on systems where the requirement is not satisfied.

  This is the default value for the Level key. It constitutes a technical requirement (as opposed to a legal, marketing, or other non-technical requirement).

  Depending on the requirement strings supplied in the package, Installer might display a message like the following if the requirement is not satisfied:

  “Safari 1.0 requires Java version 1.3 or higher.”

• recommends: Used to specify anything above and beyond a minimal technical requirement. The package should be installed, even on systems where the recommendation is not satisfied; however, the user experience may be enhanced if the recommendation is satisfied. Some clients, including Installer, may display a recommendation to the user, such as the following:

  “iTunes 4 recommends QuickTime 6.2 or higher for full functionality.”

SpecArgument, SpecProperty, and SpecType

Together, the SpecType, SpecArgument, and SpecProperty keys constitute an object specifier for a particular system resource or state. Installer resolves the object specifier to return the actual object value for the user’s system, if possible. Examples of object specifiers include the version number of a given application or package receipt, a gestalt or sysctl value, or a specific value within a property list file or hardware registry. See “Requirements Examples” for samples of how to combine the type, argument, and property in a requirement.

Table 3 lists specifier types and the arguments and properties you use with them. You can think of the information from the first two columns (type and argument) as specifying a thing, and the third column (property) identifying some attribute of that thing. In some cases, you supply just the first two items to specify a requirement, while in other cases all three are required.

Additional information for each specifier type is provided in the sections that follow the table.

Package

Specifies an Installer package. The SpecArgument value should be a package identifier string (currently a bundle identifier string from the package’s info property list). You use this property to set a requirement within a metapackage that another package be present. You currently can only use this type of requirement in a metapackage. You can’t use this property to look up installed receipts on disk—it will access only “full” packages.

The SpecProperty value should be a property list key string in the package. You should always supply a SpecProperty entry.

Sysctl

Specifies a sysctl entry. The SpecArgument value should be a string specifying a MIB style sysctl name. See the man page for sysctl(8) for values. You can specify many system attributes, including the amount of physical memory (hw.sysmem) or the hardware model (hw.model).

An example of a value for a sysctl entry is hw.ncpu, which would specify a requirement based on the number of CPUs.

You don’t supply a SpecProperty entry for sysctl.

IORegistry

Specifies an IOKit Registry object. The SpecArgument value should be a string specifying an IORegistry path. The format is plane:path. For example:

IOService:/MacRISC2PE/pci@f0000000/AppleMacRiscAGP/*/*/*/AppleBacklightDisplay

The SpecType and SpecArgument together specify a hardware device in the IORegistry. The SpecProperty further refines the requirement by specifying an attribute of the device. The property should be a string that specifies a key path. Wildcards are supported using the ' *' character for nodes in the registry path, as well as for nodes in the key path.

The following example specifies the brightness value of the device:

IODisplayParameters:brightness:value

For more information on IOKit, see I/O Kit Fundamentals and other documents in Darwin Documentation.

Gestalt

Specifies a Carbon Gestalt selector. You can use Gestalt selectors to identify many attributes of the operating environment. The SpecArgument value should be a four character code string specifying a Gestalt selector.

You don’t supply a SpecProperty entry for gestalt.

For information on Gestalt, see Gestalt Manager Reference in Carbon Resource Management Documentation.

Bundle

Specifies a bundle (application, framework, plug-in, and so on). The SpecArgument value is a standard or tokenized file path. A standard path is just a path, such as /Applications/MyApplication.app. Tokenized paths are described in “Token Definitions.”

The SpecProperty value should be a string value from the property list of the specified bundle. If you just want to check whether the bundle [or file] exists, don’t supply a SpecProperty entry. In that case, the requirement will be satisfied if the bundle exists and not satisfied if it doesn’t.

Plist

Specifies a property list file. The SpecArgument value is a standard or tokenized file path to the specified file.

The SpecProperty value should be string specifying a key path. That is, for a top-level key, the property could be one word, such as NSAppleScriptEnabled (a key which indicates a Cocoa application uses Cocoa’s built-in AppleScript support). A nested property might have multiple keys, joined by periods, such as PhonePrefs.RingerPrefs.CurrentTune. Wildcards are supported using the ' *' character. Integers are used as array indices (that is, an index into the array for an array key).

File

Specifies a flat file. The SpecArgument value is a standard or tokenized file path. A standard path is just a path to a file. Tokenized paths are described in “Token Definitions.”

The SpecProperty value should be a file attribute constant string, defined in NSFileManager. There are many file attributes you can incorporate in a requirement, such as file size (NSFileSize) or creation date (NSFileCreationDate).

If you just want to check whether the file exists, don’t supply a SpecProperty entry. In that case, the requirement will be satisfied if the file exists and not satisfied if it doesn’t.

For example, if your package requires the presence of the file /mach_kernel, you can specify a SpecType of file, a SpecArgument of /mach_kernel, and no SpecProperty. As a result, Installer will only allow the package to be installed if the file /mach_kernel exists.

TestObject

The TestObject key specifies the “required” object value. See “TestOperator” for an explanation of how it is used.

TestOperator

The TestOperator key is used as follows: the left value (specified by the keys described in “SpecArgument, SpecProperty, and SpecType”) is tested with the operator specified by the TestOperator key against the right value specified by the TestObject key. As a value for the TestOperator key, you can use any of the comparison operators shown in the two right-hand columns in Table 4 (XML notation and Perl notation).

For example, the full value entry for greater than or equal in XML notation is:

<string>&gt;=</string>

The full value entry for greater than or equal using Perl notation is:

<string>ge</string>

Requirements Examples

This section provides examples of various common requirements definitions.

Bundle Requirements

Listing 2 shows a requirements definition that specifies a bundle version. This type of requirement is useful for software that links against external frameworks. In this example, the package requires version 663.7 or greater of the AppKit framework.

Listing 2  A requirements definition for a minimum framework version

<key>IFRequirementDicts</key>

<array>

    <dict>

        <key>SpecType</key>

        <string>bundle</string>

        <key>SpecArgument</key>

        <string>/System/Library/Frameworks/AppKit.framework</string>

        <key>SpecProperty</key>

        <string>CFBundleVersion</string>

        <key>TestOperator</key>

        <string>&gt;=</string>

        <key>TestObject</key>

        <string>663.7</string>

    </dict>

</array>

See “TestOperator” for a description of the valid test operators (such as &gt:= in this example).

If you’re packaging a relocatable application, you can use the same format shown in Listing 2, but also provide a token definition to specify that Installer should search for the item on disk and upgrade older versions as appropriate. You need to do this only if your package must upgrade or otherwise overwrite the relocated files. For a complete description of searching and token definitions, see “Finding Previously Installed Software.”

Property List Requirements

Listing 3 shows a requirements definition that specifies a simple test based on the bundle version value from a property list. In this example, the package requires Mac OS X version 10.3 or greater.

Listing 3  A requirements definition for a value from a property list

<key>IFRequirementDicts</key>

<array>

    <dict>

        <key>SpecType</key>

        <string>plist</string>

        <key>SpecArgument</key>

        <string>/System/Library/CoreServices/SystemVersion.plist</string>

        <key>SpecProperty</key>

        <string>ProductVersion</string>

        <key>TestOperator</key>

        <string>&gt;=</string>

        <key>TestObject</key>

        <string>10.3</string>

    </dict>

</array>

File Requirements

Listing 4 shows a requirements definition that specifies a flat file requirement. In this example, the package is not installed if the specified font file is present.

Listing 4  A requirements definition for a file

<key>IFRequirementDicts</key>

<array>

    <dict>

        <key>SpecType</key>

        <string>file</string>

        <key>SpecArgument</key>

        <string>/Library/Fonts/Apple Chancery.dfont</string>

        <key>TestOperator</key>

        <string>eq</string>

        <key>TestObject</key>

        <string></string>

        <key>Level</key>

        <string>requires</string>

        <key>LabelKey</key>

        <string>AppleChanceryLabel</string>

        <key>MessageKey</key>

        <string>AppleChanceryMessage</string>

    </dict>

</array>

The requirement effectively states that the specifier must resolve to an empty string. This evaluates to true if the file doesn’t exist in the Fonts folder on the installation volume, false if it does exist.

< Previous PageNext Page > Hide TOC