From 1d0b67f81b1775725e16cfb4b31c783c48c4fdcd Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Wed, 28 May 2025 17:07:22 -0400 Subject: [PATCH 1/4] Update README --- README.md | 44 +++++++++++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 4150dec..f87256e 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,52 @@ # FaultOrdering -Order files can reduce app startup time by co-locating symbols that are accessed during app launch, reducing overall memory used by the app code. This package generates an order +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](https://www.emergetools.com/blog/posts/FasterAppStartupOrderFiles). ## Installation Create a UI testing target using XCUITest. Add the package dependency to your Xcode project using the URL of this repository (https://github.com/getsentry/FaultOrdering). -Add `FaultOrderingTests` and `FaultOredering` as a dependency of your new UI test target. +Add `FaultOrderingTests` and `FaultOrdering` as a dependency of your new UI test target. + +## Usage + +This is a multi-step process: + +1. Generate a linkmap file for your main app +2. Copy that linkmap file into the UI test bundle resources +3. Setup and run the UI test, which then outputs the final order file + +### Generating a linkmap + +To use this package you'll need to generate a linkmap for your main app binary. In your app's Xcode target, set the following build settings: -### Linkmaps -To use this package you’ll need to generate a linkmap for your main app binary. In your xcode target for your applications main executable set the following build settings: ``` LD_GENERATE_MAP_FILE = YES LD_MAP_FILE_PATH = $(PROJECT_DIR)/Linkmap.txt ``` -The Linkmap.txt file needs to be included as a resource in your UI test target. Add it in the build phases for your target under Copy Bundle Resources. +We recommend using `$(PROJECT_DIR)` so that it generates within your project directory instead of derived data, but this can be changed to whatever makes sense for your setup. + +After adding these settings, make sure to build your app and verify the file exists. + +### Including the linkmap -![Copy Bundle Resources](images/copy.png) +After generating the `Linkmap.txt` file, it needs to be included as a resource in your UI test target. Add it in the build phases for your target under Copy Bundle Resources. -![Choose File](images/choose.png) -Choose "Add Other" and brows to the file in your project directory. You may need to create the file first, by building your main app target once with the new build settings. +Copy Bundle Resources -![Confirm](images/confirm.png) +Choose File +Choose "Add Other" and browse to where you generated the file. You may need to create the file first, by building your main app target once with the new build settings. + +Confirm Confirm your selection and **do not** check the box to copy the file. > [!IMPORTANT] > The generated Linkmap.txt file must be included in your UI test target. You don't need to specificly use "$(PROJECT_DIR)/Linkmap.txt" as the path, only that whatever the LD_MAP_FILE_PATH is set is also the file that you include in Copy Bundle Resources. -## Usage +### Running the test -Create an instance of FaultOrderingTest and provide a closure to performan any setup. The setup closure will be called before generating the order file -so you can put the app in a state that users commonly see. For example, you may want to log in to the app. Then the order file will generate -for the codepaths your app uses when users are logged in. +In a UI test, create an instance of `FaultOrderingTest` and optionally provide a closure to perform any required app setup. For example, you may want to log in to the app since that's the most common code path for the majority of your app users. The test case can then be executed. Example: @@ -46,8 +60,8 @@ test.testApp(testCase: self, app: app) ### Accessing results -Results are added as a XCTAttachment named "order-file" +Results are added as a XCTAttachment named `"order-file"`. ### Device support -To run on a physical device the app must link to the `FaultOrdering` product from this package. Update your main app target to have this framework in it’s embedded frameworks. +To run on a physical device the app must link to the `FaultOrdering` product from this package. Update your main app target to have this framework in it's embedded frameworks. From 61ac3edf1930095aaa89d13cb7c1569b910e27f9 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Wed, 28 May 2025 17:50:23 -0400 Subject: [PATCH 2/4] update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f87256e..81593c8 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ After adding these settings, make sure to build your app and verify the file exi ### Including the linkmap -After generating the `Linkmap.txt` file, it needs to be included as a resource in your UI test target. Add it in the build phases for your target under Copy Bundle Resources. +Once the `Linkmap.txt` file exists, it needs to be included as a resource in your UI test target. Add it in the build phases for your target under Copy Bundle Resources. Copy Bundle Resources From d286a5103c7b46ef0804150996ff5bd3dcf41b17 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Wed, 28 May 2025 17:54:53 -0400 Subject: [PATCH 3/4] fix --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 81593c8..dc9892d 100644 --- a/README.md +++ b/README.md @@ -35,14 +35,14 @@ Once the `Linkmap.txt` file exists, it needs to be included as a resource in you Copy Bundle Resources -Choose File +Choose File Choose "Add Other" and browse to where you generated the file. You may need to create the file first, by building your main app target once with the new build settings. Confirm -Confirm your selection and **do not** check the box to copy the file. +Confirm your selection and do not check the box to copy the file. > [!IMPORTANT] -> The generated Linkmap.txt file must be included in your UI test target. You don't need to specificly use "$(PROJECT_DIR)/Linkmap.txt" as the path, only that whatever the LD_MAP_FILE_PATH is set is also the file that you include in Copy Bundle Resources. +> The generated Linkmap.txt file must be included in your UI test target. You don't need to specificly use `"$(PROJECT_DIR)/Linkmap.txt"` as the path, only that whatever the `LD_MAP_FILE_PATH` is set is also the file that you include in Copy Bundle Resources. ### Running the test From 5d6949b573a579aeba2fc9c76c2b478b4942e435 Mon Sep 17 00:00:00 2001 From: Trevor Elkins Date: Wed, 28 May 2025 18:01:47 -0400 Subject: [PATCH 4/4] fix --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dc9892d..74db245 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ This is a multi-step process: 2. Copy that linkmap file into the UI test bundle resources 3. Setup and run the UI test, which then outputs the final order file -### Generating a linkmap +### Generating the linkmap To use this package you'll need to generate a linkmap for your main app binary. In your app's Xcode target, set the following build settings: @@ -35,7 +35,7 @@ Once the `Linkmap.txt` file exists, it needs to be included as a resource in you Copy Bundle Resources -Choose File +Choose File Choose "Add Other" and browse to where you generated the file. You may need to create the file first, by building your main app target once with the new build settings. Confirm