📘

Linkmaps required

This feature requires xcarchives with linkmaps included in the upload.

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. Emerge creates an order file tailored for reduced app launch time, results vary app to app, but aim to reduce launch time by 5-10%.

Generation Pipeline

An order file is generated for every build that contains the order_file_version flag. Each build uploaded will further fine-tune the order file maintained by Emerge. When you create a new build simply download the latest available order file, use it for your build, then upload the build. That will trigger 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. The order stabalizes around 4 or 5 iterations and then stays up to date with new changes to your code.

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

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.