< Previous PageNext Page > Hide TOC

Finding Previously Installed Software

This section describes the Find File feature, which allows you to provide Installer with information to help it find software from a previous installation. This feature was introduced in Mac OS X version 10.2. Enhancements introduced in Mac OS X version 10.3 are noted throughout this section.

Installer looks for a receipt in /Library/Receipts that matches the current package to determine whether you are installing software for the first time or upgrading it. However, the receipt doesn’t necessarily specify where the software currently resides. If Installer can’t find previously installed software, it can’t upgrade it, and instead must do a full installation.

You can use the Find File feature to provide rules to help Installer find software from a previous installation. This feature is most useful for software that can easily be moved by the user after installation, such as self-contained application bundles. It isn’t needed for any software that must reside in a certain location, such as a KEXT (kernel extension). Application bundles are described in “Drag-and-Drop Installation.”

In conjunction with using the Find File feature to help Installer find previously installed software, you can use the feature described in “Specifying Version Information for Packaged Software” to help Installer determine which software needs to be upgraded.

PackageMaker does not currently provide a user interface for accessing the Find File feature. As a result, to use it, you supply information by directly editing the information in property list files in a package. The information you need to supply is described below; for information on how to edit property list files, see “Examining and Modifying Property Lists.”

Contents:

Tokens Definitions and Path Mappings
Application Selection By the User
Search Methods

Tokens Definitions and Path Mappings

To help Installer find your previously installed software, you provide information about the software items to search for and the search methods to use. To do this, you create token definitions and path mappings in your package.

Token Definitions

A token acts as an identifier for an abstract place in the file system. A token may resolve to different locations depending on how the user has arranged his or her files. For example, you could define a token “iChat” whose value is the path to the iChat.app application bundle, wherever the user has placed it.

To define tokens within your package, you create a property list file named TokenDefinitions.plist in your package’s Resources directory. The top-level container in this file should be a dictionary, and each key should be the name of a token that you wish to define in your package. The value for each token should be an array of one or more invocations to search methods, specifying the search logic to use when resolving the token. For more detailed information on creating token definitions, including documentation of the specific search methods, see “Search Methods.”

Listing 1 shows a sample TokenDefinitions.plist file in XML format. This property list defines a token “ClockToken” corresponding to Clock.app, which is typically located in /Applications. This example uses the search method CommonAppSearch, which is specified as the value for the searchPlugin key. For information on this search method, see “CommonAppSearch.”

Listing 1  A TokenDefinitions.plist file

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

<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">

<plist version="0.9">

    <dict>

        <key>ClockToken</key>

        <array>

            <dict>

                <key>searchPlugin</key>

                <string>CommonAppSearch</string>

                <key>path</key>

                <string>/Applications/Clock.app</string>

                <key>identifier</key>

                <string>com.apple.clock</string>

            </dict>

        </array>

    </dict>

</plist>

Path Mappings

A path mapping entry tells Installer which files within your package should be installed at the location defined by the token, rather than at the default location where the package would otherwise install them. That is, the token is resolved according to the search method or methods it specifies, and the result is used to specify the installation location.

A path mapping specifies the beginning part of a path, and every file within the package whose path begins with the specified path beginning will be installed at the new location.

If you don’t specify a token and a path mapping, or if you specify them but the software to be updated is not found at the location they specify, files in your package are installed at a location that is constructed from the installation volume chosen by the user, the default location specified in your package, and the relative path to the file in the package (which is based on how you set up the files relative to your root directory when you created the package).

If you do specify a token (with one or more search methods) and a path mapping, and the software to be updated is found, the token is resolved to the path to the location where the software was found. This path includes volume information—a token may resolve to a location on a different volume than the installation volume chosen by the user. Files that match the path mapping are then installed at a location constructed from the resolved path (including volume), plus the part of the path in the package that wasn’t matched by the path mapping.

To add path mappings, you create a new key IFPkgPathMappings in your package’s Info.plist file. The value of this property is a dictionary where each key is a partial path inside the package. These paths should correspond to the relative paths output by the lsbom tool. The value for each entry is a string that specifies the new path that a file should be mapped to. The path can begin with a symbolic reference to a token, surrounded by curly braces—for example, {ClockToken}.

Listing 2 shows an entry for the IFPkgPathMappings key from a package’s Info.plist file. This mapping causes the Clock.app bundle and all of its contained files to be installed in the location resolved by the token defined in Listing 1.

Listing 2  An entry for the IFPkgPathMappings key in an information property list

    <key>IFPkgPathMappings</key>

    <dict>

        <key>./Applications/Clock.app</key>

        <string>{ClockToken}</string>

    </dict>

Application Selection By the User

Starting in Mac OS X version 10.3, a package can specify that the user should be consulted regarding which version to update if multiple copies are found. This is accomplished by defining a special token named UserLocation. The UserLocation token is resolved like any other token, but if multiple copies of the specified software are found, the user is asked to choose which copy to upgrade. The value that the user chooses becomes the new value of the token when it is used in path mappings (described in “Path Mappings.”

Listing 3 shows a UserLocation token definition in a TokenDefinitions.plist file (described in “Token Definitions”).

Listing 3  A UserLocation token in a TokenDefinitions.plist

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

<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">

<plist version="0.9">

    <dict>

        <key>UserLocation</key>

        <array>

            <dict>

                <key>searchPlugin</key>

                <string>CommonAppSearch</string>

                <key>path</key>

                <string>/Applications/Clock.app</string>

                <key>identifier</key>

                <string>com.apple.clock</key>

            </dict>

        </array>

    </dict>

</plist>

Search Methods

You can use token definitions to create highly customized behaviors for locating and identifying your software. You do this by stringing together search method invocations. The search methods are invoked in the order specified in the token definition, until one of them returns a success code. At that time, the array of search results is returned to Installer. The array contains the path to the location to which the token resolves.

To define a token that specifies how to locate your software, you add a key for the token, with an appropriate token name, to the TokenDefinitions.plist file. You then add an array of dictionaries as the value for that key. Each dictionary specifies a search method that is invoked during installation. Listing 1 shows a token definition that specifies a single search method.

The following sections describe the search methods Installer currently supports and the required and optional keys for those search methods.

CheckPath

You use the CheckPath search method to specify the path where installed software might be found. This is the simplest search method—it succeeds if a file or directory exists at the specified path, and fails otherwise.

The CheckPath search method has one key:

path

required

A string specifying the path to search (such as /Applications).

Listing 4 shows a token definition that uses CheckPath to sequentially check several locations where the application may reside.

Listing 4  A token definition that uses the CheckPath search method

    <key>ClockToken</key>

    <array>

        <dict>

            <key>searchPlugin</key>

            <string>CheckPath</string>

            <key>path</key>

            <string>/Applications/Clock.app</string>

        </dict>

        <dict>

            <key>searchPlugin</key>

            <string>CheckPath</string>

            <key>path</key>

            <string>/Applications/Utilities/Clock.app</string>

        </dict>

        <dict>

            <key>searchPlugin</key>

            <string>CheckPath</string>

            <key>path</key>

            <string>~/Applications/Clock.app</string>

        </dict>

    </array>

LaunchServicesLookup

You use the LaunchServicesLookup search method to consult the database maintained by Launch Services in looking for the software.

The LaunchServicesLookup search method has the following keys:

identifier

optional

The CFBundleIdentifier for the bundle the search is intended to locate A CFBundleIdentifier is the unique identifier string for a bundle and should be in the form of a java package name (for example, com.apple.clock).

Prior to Mac OS X version 10.3 (v10.3), this key was required. Starting in Mac OS X v10.3, you must specify either this key or the creator key.

creator

optional

A string that specifies a four-character creator (for example, ttxt for the TextEdit application).

Prior to Mac OS X v10.3, this key was required. Starting in Mac OS X v10.3, you must specify either this key or the identifier key.

type

optional

A string that specifies a four-character document type the application can open (for example, TEXT).

Starting in Mac OS X v10.3, this key is ignored, and you must specify either the creator key or the identifier key.

extension

optional

The extension for a file type the application can open (for example, .txt).

Starting in Mac OS X v10.3, this key is ignored, and you must specify either the creator key or the identifier key.

Listing 5 shows a token definition that uses LaunchServicesLookup.

Listing 5  A token definition that uses the LaunchServicesLookup search method

    <key>ClockToken</key>

    <array>

        <dict>

            <key>searchPlugin</key>

            <string>LaunchServicesLookup</string>

            <key>identifier</key>

            <string>com.apple.clock</string>

        </dict>

    </array>

BundleIdentifierSearch

The BundleIdentifierSearch search method performs an exhaustive search of the entire file system, looking for bundles with the specified CFBundleIdentifier.

The BundleIdentifierSearch search method has the following required and optional keys:

startingPoint

optional

A string specifying the path to from which to start searching. If this is not specified, / is assumed.

identifier

required

The CFBundleIdentifier for the bundle that the search is intended to locate (for example, com.apple.clock).

successCase

optional

Specifies the behavior to use when the BundleIdentifierSearch search method succeeds. It can take one of three values:

• findOne Terminates the search as soon as a match is identified. This can be the most efficient choice. It is also the default choice.

• findAll Exhaustively iterates over the entire file system, looking for all matches. Succeeds if any matches are found.

• neverSucceed Iterates over the entire file system, and compiles results that can be used by the “BundleVersionFilter” search method. See Listing 7 for an example.

maxDepth

optional

The maximum directory depth to descend in the search. For example, specifying a depth of 3 would limit the search to no more than three directories deep. Provided for efficiency, so that searching needn’t proceed down deeply nested hierarchies that are unlikely to contain the software.

excludedDirs

optional

An array of one or more strings, each of which identifies a directory that should be excluded from the search. This key is also provided for efficiency: for example, you can avoid a great deal of searching by excluding the locations /System and /Developer if your software is unlikely to be located within either of those directories.

Listing 6 shows a token definition that uses BundleIdentifierSearch.

Listing 6  A token definition that uses the BundleIdentifierSearch search method

<key>ClockToken</key>

<array>

    <dict>

        <key>searchPlugin</key>

        <string>BundleIdentifierSearch</string>

        <key>identifier</key>

        <string>com.apple.clock</string>

        <key>excludedDirs</key>

        <array>

            <string>/System</string>

            <string>/Developer</string>

            <string>/AppleInternal</string>

        </array>

        <key>maxDepth</key>

        <integer>6</integer>

        <key>startingPoint</key>

        <string>/</string>

        <key>successCase</key>

        <string>findOne</string>

    </dict>

</array>

BundleVersionFilter

You use the BundleVersionFilter search method to filter the results returned by the previous invocation of a search method. It succeeds if one or more bundles fall within the specified version range, and fails otherwise. This search method was added in Mac OS X version 10.3.

The BundleVersionFilter search method has the following keys (you must specify at least one of the keys):

maxVersion

optional

The maximum version allowed. Specified as a 5-tuple version in a string. The first three numbers correspond to the CFBundleShortVersionString. For more information, see “How Installer Computes a Version.”

minVersion

optional

The minimum version allowed.

Listing 7 shows a token definition that uses BundleVersionFilter.

Listing 7  A token definition that uses the BundleVersionFilter search method

<key>ClockToken</key>

<array>

    <dict>

        <key>searchPlugin</key>

        <string>BundleIdentifierSearch</string>

        <key>identifier</key>

        <string>com.apple.clock</string>

        <key>maxDepth</key>

        <integer>6</integer>

        <key>successCase</key>

        <string>neverSucceed</string>

    </dict>

    <dict>

        <key>searchPlugin</key>

        <string>BundleVersionFilter</string>

        <key>maxVersion</key>

        <string>1.0.0.99999999.9</string>

        <key>minVersion</key>

        <string>1.0.0.0.0</string>

    </dict>

</array>

CommonAppSearch

If you do not require a highly customized search behavior, you can use the CommonAppSearch search method and save a lot of typing. This search method, which is first available in Mac OS X version 10.3, attempts to locate at least one copy of the specified application.

The CommonAppSearch search method has the following required keys:

path

required

The default path to the application to locate.

identifier

required

The CFBundleIdentifier of the bundled application to locate.

Listing 1 provides an example of how to use CommonAppSearch.

A Token Definition for a Complex Search

Listing 8 provides an example of a token definition that combines three search methods: CheckPath, LaunchServicesLookup, and BundleIdentifierSearch.

Listing 8  Expansion of the CommonAppSearch macro

<key>ClockToken</key>

<array>

    <dict>

        <key>searchPlugin</key>

        <string>CheckPath</string>

        <key>path</key>

        <string>{path Argument}</string>

    </dict>

    <dict>

        <key>searchPlugin</key>

        <string>LaunchServicesLookup</string>

        <key>identifier</key>

        <string>{identifier Argument}</string>

    </dict>

    <dict>

        <key>searchPlugin</key>

        <string>BundleIdentifierSearch</string>

        <key>identifier</key>

        <string>{identifier Argument}</string>

        <key>excludedDirs</key>

        <array>

                <string>/System</string>

                <string>/Developer</string>

                <string>/AppleInternal</string>

        </array>

        <key>maxDepth</key>

        <integer>6</integer>

        <key>startingPoint</key>

        <string>/</string>

        <key>successCase</key>

        <string>findOne</string>

    </dict>

</array>

< Previous PageNext Page > Hide TOC