Installation Path

Substrate extensions are compiled to dynamic libraries (using the extension .dylib) and are placed in the Substrate Dynamic Libraries folder.

/Library/MobileSubstrate/DynamicLibraries

Property Lists

Configuration for the extension is provided using Cocoa "property lists", a serialization format for common Objective-C data structures (dictionaries, arrays, numbers, strings, and data). This is a file with the same name as the .dylib, but with the extension .plist.

Property lists can be stored on disk in one of three formats: XML, binary, or "OpenStep" (a format more similar to encodings such as JSON). For more information on these files and how they are stored, we provide a guide to the various property list formats.

# ls -la /Library/MobileSubstrate/DynamicLibraries
total 48
drwxr-xr-x 2 root wheel   136 Jan 26 16:32 ./
drwxr-xr-x 4 root wheel   238 Jan 26 16:32 ../
-rwxr-xr-x 1 root wheel 33216 Oct 12 20:14 Veency.dylib*
-rw-r--r-- 1 root wheel    49 Sep 11 02:41 Veency.plist

# cd /Library/MobileSubstrate/DynamicLibraries
# cat Veency.plist 
Filter = {Bundles = ("com.apple.springboard");};

Configuration Structure

At the top-level of the configuration property list is a dictionary with a single key, Filter, the value of which is itself a dictionary.

Under this key are a number of different ways to limit the scope of your extension, each of which will be documented below.

Standard Filters

Most uses of Substrate come down to a need to modify the code of a specific library or set of classes. The configuration system therefore provides a way to specify the set of such injection targets.

This is done using a set of arrays that are linked under the Filter key, each of which considers to "match" if any one of the elements in that set matches.

As an example, if your extension modifies the code of UIKit (the standard iOS library dealing with graphics and interface) and the background "launch services" daemon (used to lookup applications and load icons), you would use the "Any" Mode and two filters: Bundles (to match UIKit) and Executables (to match "lsd").

Filtering on OS Version

An additional filter that is often requested is "this only works on iOS 3.x". Substrate exposes functionality similar to this through a CoreFoundationVersion filter.

This value is checked using kCFCoreFoundationVersionNumber, and the values are described in Apple's CFBase.h in the form kCFCoreFoundationVersionNumber_iPhoneOS_3_0.

The contents of this filter is an array containing either one or two numbers; the first being the "lower bound" and the latter being the "upper bound". The upper bound is optional.

Note: As the OpenStep property list format does not support storing numbers, to use this feature you must store your property list using the XML (discouraged) or binary (recommended) format.

<key>CoreFoundationVersion</key>
<array>
    <real>478.47</real>
    <real>550.32</real>
</array>