Specifying Locator Definitions by Hand
A warning before we begin: this is not for the faint of heart.
Locator definitions are spread over two files. The path mappings are put in Contents/Info.plist
, while the token definitions are put in Contents/Resources/TokenDefinitions.plist
.
Token Definitions
The TokenDefinitions.plist
file groups search methods together, giving each group a name, or token. This token is used to assign the group of search methods to a path in your root in the path mappings.
An example TokenDefinitions.plist
could look like the following:
<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>LaunchServicesLookup</string> <key>identifier</key> <string>com.apple.clock</string> </dict> <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>
As can be seen, it is a dictionary of tokens, with each token specifying an array of search methods. Each search method in the array is represented by a dictionary with certain parameters as specified below:
CheckPath
- path: required: A string specifying the path to search (such as
/Applications
).
LaunchServicesLookup
- identifier: optional: The
CFBundleIdentifier
for the bundle the search is intended to locate (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 thecreator
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 theidentifier
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 theidentifier
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 theidentifier
key.
BundleIdentifierSearch
- startingPoint: optional: A string specifying the path from which to start searching. If not specified, / is used.
- identifier: required: The
CFBundleIdentifer
for the bundle the search is intended to locate. - successCase: optional: Specifies the behavior to use with the search succeeds. The three legal values are:
findOne
: Terminates the search as soon as a match is identified. This is the default.findAll
: Does not stop if a match is found, so finds 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.- maxDepth: optional: The maximum directory depth to descend in the search.
- excludedDirs: optional: An array of one or more strings, each of which identifies a directory that should be exlcluded from the search. 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.
BundleVersionFilter
This search method is used to filter the results of the previous search method. It succeeds if one or more bundles fall in the specified version range. Available in OS 10.3 or later.
- maxVersion: optional: The maximum version allowed, specified as a 5-tuple version in a string. See “How Installer Computes a Version”.
- minVersion: optional: The minimum version allowed, specified the same way as
maxVersion
.
CommonAppSearch
- path: required: The default path to the application to locate.
- identifier: required: The
CFBundleIdentifier
for the application to locate.
Path Mappings
Path mapping entries are specified in a dictionary in the Info.plist of your package, and map a path in the package to a location associated with a token in your TokenDefinitions. A path mapping specifies the beginning part of a path, and every file beginning with the path will be installed at the new location.
To specify your path mappings, use a syntax like the following in your Info.plist:
<key>IFPkgPathMappings</key> <dict> <key>./Applications/Clock.app</key> <string>{ClockToken}</string> </dict>
In this example, if the ClockToken search succeeded, files starting with ./Applications/Clock.app
in your package would be installed to path associated with ClockToken. If the ClockToken search failed, the Installer would fall back to where it would normally install the file.