Order files (iOS)

A binary ordering service that can speed up launch times by up to 18%.

📱

Note: This is an iOS only feature. For most significant improvement, you will need to upload a build that is auto-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. To integrate launch booster you need to be uploading apps through an automatic CI pipeline that can re-build and upload on a continuous fixed schedule - manual uploads are not supported.

📘

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. Each subsequent upload of the same version will continue to refine the order file, finding new symbols and combining them with the symbols already in that version. 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 Pipeline

Launch booster integration requires a CI pipeline that periodically builds apps with the latest order file downloaded from Emerge, and then uploads the result with the same order file version. Each build uploaded will further fine-tune the order file maintained by Emerge. Uploading triggers an update to the order file, and the process will repeat for your next build. With this pipeline the order file refines as your development continues. Usually 20 iterations are the minimum required for a single order file version.

When you upload, the app is 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

To check if you need to keep uploading, view the order file page for a build by selecting Order File from the sidebar. When you don't have enough builds yet, the page fault map will have many faults scattered around the middle of your binary, like this:

Once you have uploaded and re-linked enough times, the faults will be pushed to either end of your binary, and look like this:

Each upload will also show you a graph of page faults over time for the order file version associated with that upload. Once it starts to stabalize at a low value, you know there have been enough re-links.

By setting the order file version to your app’s version, you reset the process with each new release, allowing Emerge to keep the file up to date and not accumulate old symbols that are no longer used during startup.

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.