📱

Note: For a significant improvement, you will need to upload a build that follows the most common user path, such as being logged in.

Order files can automatically reduce iOS app launch time by up to 18%. This is done by creating an order file - a linker input that optimizes the final binary.

📘

Linkmaps required

This feature requires xcarchives with linkmaps included in the upload.

What is an order file?

Order files control how your code is arranged in the final app binary. By default functions declared in the same file are grouped together, but with a carefully designed order file you can organize code by the way it's used at runtime. When functions are grouped together they can be read from the phones flash memory faster, decreasing the time to run your code. Each line in an order file is a "symbol" which is the smallest unit the linker can re-arrange. Emerge creates an order file with symbols optimized to reduce the amount of the binary read from disk on app launch.

Order File Version

An order file is generated for every build that contains the orderFileVersion flag. The version number is used as a key to retrieve the order file after it generates. For most apps, the easiest way to choose an order file version is to simply set it to the version of your app, for example 1.0, 1.1, 1.2, etc...

Generation

To generate an order file first upload an app with linkmaps included . The app will be launched in a device lab with the env variable EMERGE_IS_RUNNING_ORDER_FILE set to 1. You can use this to ensure the app is set up to run successfully with how it is installed.

See Order File Integration for details on how to integrate with your CI pipeline

View the results for an upload by selecting Order File from the sidebar. On your first upload, the page fault map will have many faults scattered around the middle of your binary, like this:

After using the generated order file, the faults will be pushed to either end of your binary, and look like this:

Using the File

Xcode Project

Set the Order File build setting under linker settings to your order file's path.

Third Party Build Systems

Add -Wl,-order_file,file_path, -Wl,-order_file_statistics to your linker flags.

Under the Hood

❗️

This is a quick explanation of an advanced topic, it's not required for integrating order files, but may be helpful for anyone looking to dive deeper.

Order file performance improvements come from reducing the number of memory pages used during app startup, and improving locality of memory to take advantage of system prefetching.

The following scenarios illustrate how ordering leverages prefetching to reduce slow memory access.

In this example, the phone prefetches the next 3 pages every time a page fault occurs. When loading out of order this prefetching does not help, but when loading in order it saves one non-cached page fault. Further improvements to the order in this example would allow at most 4 pages of memory to be used with only one non-cached fault.