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

LaunchServicesLookup

BundleIdentifierSearch

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.

CommonAppSearch

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.