Order files can reduce app startup time by co-locating symbols that are accessed during app launch, reducing the number of page faults from the app. This package generates an order file by launching the app in an XCUITest. Read all about how order files work in our blog post.

Setting up your app to use order files requires 2 general steps:

1. Generate an order file from an XCUITest. FaultOrdering instruments app launch in the UI test and uses the results to generate an optimized order file.
2. Once the order file is generated, build the app again, this time passing the order file as an option to the linker.

• Create a UI testing target using XCUITest.
• Add https://github.com/getsentry/FaultOrdering to your project via Swift Package Manager.
• Add FaultOrderingTests and FaultOrdering as dependencies of your new UI test target.

In your app's Xcode target, set the following build settings:

LD_GENERATE_MAP_FILE = YES
LD_MAP_FILE_PATH = $(PROJECT_DIR)/Linkmap.txt

After adding these settings, make sure to build your app and verify the file exists.

Add Linkmap.txt in the build phases for your UI test target under Copy Bundle Resources.

In a UI test case, create an instance of FaultOrderingTest and optionally provide a closure to perform any necessary app setup.

Example:

import FaultOrderingTests
import XCTest

final class FaultOrderingLaunchTest: XCTestCase {
    @MainActor
    func testLaunch() throws {
        let app = XCUIApplication()
        let test = FaultOrderingTest { app in
            // Perform setup such as logging in
        }
        test.testApp(testCase: self, app: app)
    }
}

The test case can then be executed.

To run on a physical device, the app must link to the FaultOrdering product from this package. Update your main app target to include this framework in its embedded frameworks. If your app takes a different codepath on physical devices than simulators (such as using device only frameworks like Metal) it is best to generate an order file while running on the physical device.

After running the UI test, the order file will will appear as an XCTAttachment named "order-file". You can open the .xcresult file in Xcode to see the file, or extract it programatically with

xcrun xcresulttool export attachments --path /path/to/your_test.xcresult --output-path out_dir

In your app target's build settings, set "ORDER_FILE" to the path to your order file and rebuild the app.