|
1 | 1 | # How to locally test Swift Package Manager components on Firefox iOS |
2 | | -> This is a guide on testing the Swift Package Manager component locally against a local build of Firefox iOS. For more information on our Swift Package Manager design, read the [ADR that introduced it](../adr/0003-swift-packaging.md) |
3 | 2 |
|
4 | | -> This guide assumes the component you want to test is already distributed with the [`rust-components-swift`](https://github.com/mozilla/rust-components-swift) repository, you can read [the guide for adding a new component](./adding-a-new-component.md#including-the-component-in-the-swift-package-manager-megazord) if you would like to distribute a new component. |
| 3 | +> This guide explains how to build and test **Firefox iOS against a local Application Services** checkout. |
| 4 | +> For background on our Swift Package approach, see the [ADR](../adr/0003-swift-packaging.md). |
5 | 5 |
|
| 6 | +--- |
6 | 7 |
|
7 | | -**The goal for this document is to be able to build a local firefox iOS against a local application-services**. On a high level, that requires the following: |
| 8 | +## At a glance |
8 | 9 |
|
9 | | -1. Build an xcframework in a local checkout of `application-services` |
10 | | -1. Include the xcframework in a local checkout of `rust-components-swift` |
11 | | -1. Run the `generate` script in `rust-components-swift` using a local checkout of `application-services` |
12 | | -1. Include the local checkout of `rust-components-swift` in `firefox-ios` |
| 10 | +**Goal:** Build a local Firefox iOS against a local Application Services. |
13 | 11 |
|
| 12 | +**Current workflow (recommended):** |
14 | 13 |
|
15 | | -## Prerequisites: |
16 | | -1. A local checkout of [`firefox-ios` that is ready to build](https://github.com/mozilla-mobile/firefox-ios#building-the-code) |
17 | | -1. A local checkout of [`rust-components-swift`](https://github.com/mozilla/rust-components-swift) |
18 | | -1. A local checkout of [`application-services` that is ready to build for iOS](../building.md#building-for-firefox-ios) |
| 14 | +1. Build an **XCFramework** from your local `application-services`. |
| 15 | +2. Point **Firefox iOS’s local Swift package** (`MozillaRustComponents/Package.swift`) at that artifact (either an HTTPS URL + checksum, **or** a local `path:`). |
| 16 | +3. Reset package caches in Xcode and build Firefox iOS. |
19 | 17 |
|
20 | | -## Using the automated flow |
21 | | -For convenience, there is a script that will do all the necessary steps to configure your local `firefox-ios` build with a local `application-services` repository. You do **not** need to do the [manual steps](#using-the-manual-flow) if you follow those steps. |
| 18 | +A legacy flow that uses the **`rust-components-swift`** package is documented at the end while we're in mid-transition to the new system. |
22 | 19 |
|
23 | | -1. Run the following to execute the script, the example below assumes all of `firefox-ios`, `rust-components-swift` and `application-services` are in the same directory. Adjust the paths according to where they are on your filesystem. |
| 20 | +--- |
24 | 21 |
|
25 | | - ```bash |
26 | | - $ cd firefox-ios # This is your local checkout of firefox-ios |
27 | | - $ ./rust_components_local.sh -a ../application-services ../rust-components-swift |
28 | | - ``` |
| 22 | +## Prerequisites |
29 | 23 |
|
30 | | -1. Using Xcode, open `Client.xcodeproj` in `firefox-ios` |
| 24 | +1. A local checkout of **Firefox iOS** that builds: <https://github.com/mozilla-mobile/firefox-ios#building-the-code> |
| 25 | +2. A local checkout of **Application Services** prepared for iOS builds: see [Building for Firefox iOS](../building.md#building-for-firefox-ios) |
31 | 26 |
|
32 | | -1. Then, make sure to reset packages cache in Xcode. This forces Xcode to remove any previously cached versions of the Rust components. |
33 | | - - You can reset package caches by going to `File -> Packages -> Reset Package Caches` |
34 | | -1. If this is not the first time you run the script, make sure to also update package versions. This forces Xcode to pull the latest changes in the `rust-components-swift` branch. |
35 | | - - You can update package versions by going to `File -> Packages -> Update To Latest Package Versions` |
36 | | - - If this step fails, it's possible that the `Reset Package Caches` step above left some cruft behind. You can force this step by manually removing `~/Library/Caches/org.swift.swiftpm` and `~/Library/Developer/Xcode/DerivedData/Client-{some-long-string}` |
37 | | -1. Once the above steps are done, attempt building firefox ios. If you face problems, feel free to [contact us](../index.md#contact-us) |
| 27 | +--- |
38 | 28 |
|
39 | | -### Disabling local development |
40 | | -The easiest way to disable local development is to simply revert any changes to `firefox-ios/Client.xcodeproj/project.pbxproj`. |
| 29 | +## Step 1 — Build the XCFramework from Application Services |
41 | 30 |
|
42 | | -However, if there are other changes to the file that you would like to preserve, you can use the same script. To use the same script, you will need to: |
43 | | -1. Know what version of `rust-components-swift` was used beforehand. You can find this by checking the git diff on `firefox-ios/Client.xcodeproj/project.pbxproj`. |
44 | | -1. Run: |
45 | | - ```bash |
46 | | - $ ./rust_components_local.sh --disable <VERSION> ../rust-components-swift |
47 | | - ``` |
48 | | -1. Then, make sure to reset packages cache in Xcode. This forces Xcode to remove any previously cached versions of the Rust components. |
49 | | - - You can reset package caches by going to `File -> Packages -> Reset Package Caches` |
| 31 | +From your `application-services` checkout: |
50 | 32 |
|
| 33 | +```bash |
| 34 | +cd megazords/ios-rust |
| 35 | +./build-xcframework.sh |
| 36 | +``` |
51 | 37 |
|
52 | | -> If you happen to change branches in `rust-components-swift`, you will need to disable then re-enable local development. The script is not currently smart enough to switch branches. Alternatively, keep the branch in `rust-components-swift` the same. `rust-components-swift` serves only as a release surface so there is little use to switching branches and pushing changes to it, unless you are changing something related to the release process. |
| 38 | +This produces MozillaRustComponents.xcframework.zip (and you can also unzip it to get MozillaRustComponents.xcframework) containing: |
53 | 39 |
|
54 | | -## Using the manual flow |
55 | | -**It's important to note the automated flow runs through all the necessary steps in a script, so if possible use the script as it's a tedious manual process** |
| 40 | +- The compiled Rust code as a static library (for all iOS targets) |
| 41 | +- C headers and Swift module maps for the components |
56 | 42 |
|
57 | | -However, if the script is failing or you would like to run the manual process for any other reason follow the following steps. |
| 43 | +> Tip: If you plan to use the URL-based approach below, compute the checksum once you have the zip: |
58 | 44 |
|
59 | | -### Building the xcframework |
60 | | -To build the [xcframework](https://developer.apple.com/documentation/swift_packages/distributing_binary_frameworks_as_swift_packages) do the following: |
61 | | -1. In your local checkout of `application-services`, navigate to [`megazords/ios-rust/`](https://github.com/mozilla/application-services/tree/main/megazords/ios-rust) |
62 | | -1. Run the `build-xcframework.sh` script: |
63 | 45 | ```bash |
64 | | -$ ./build-xcframework.sh |
| 46 | +swift package compute-checksum MozillaRustComponents.xcframework.zip |
| 47 | +``` |
| 48 | + |
| 49 | +## Step 2 — Point Firefox iOS to your local artifact |
| 50 | + |
| 51 | +Firefox iOS consumes Application Services via a local Swift package in-repo at: |
| 52 | + |
| 53 | +``` |
| 54 | +{path-to-firefox-ios}/MozillaRustComponents/Package.swift |
| 55 | +``` |
| 56 | + |
| 57 | +update it in one of two ways: |
| 58 | + |
| 59 | +### Option A: URL + checksum (zip artifact) |
| 60 | + |
| 61 | +1. Host your MozillaRustComponents.xcframework.zip at an HTTPS-accessible URL (e.g., a Taskcluster or GitHub artifact URL). |
| 62 | +2. Edit MozillaRustComponents/Package.swift and set the binaryTarget to the zip URL and checksum: |
| 63 | + |
| 64 | +```swift |
| 65 | +// In firefox-ios/MozillaRustComponents/Package.swift |
| 66 | +.binaryTarget( |
| 67 | + name: "MozillaRustComponents", |
| 68 | + url: "https://example.com/path/MozillaRustComponents.xcframework.zip", |
| 69 | + checksum: "<sha256 from `swift package compute-checksum`>" |
| 70 | +) |
| 71 | +``` |
| 72 | + |
| 73 | +> Note: Every time you produce a new zip, you must update the checksum. |
| 74 | +
|
| 75 | +### Option B: Local path (fastest for iteration) |
| 76 | + |
| 77 | +1. Unzip the XCFramework near the package (or anywhere on disk). |
| 78 | +2. Switch the binaryTarget to a local path: |
| 79 | + |
| 80 | +```swift |
| 81 | +// In firefox-ios/MozillaRustComponents/Package.swift |
| 82 | +.binaryTarget( |
| 83 | + name: "MozillaRustComponents", |
| 84 | + path: "./MozillaRustComponents.xcframework" |
| 85 | +) |
65 | 86 | ``` |
66 | | -This will produce a file name `MozillaRustComponents.xcframework.zip` that contains the following, built for all our target iOS platforms. |
67 | | -- The compiled Rust code for all the crates listed in `Cargo.toml` as a static library |
68 | | -- The C header files and [Swift module maps](https://clang.llvm.org/docs/Modules.html) for the components |
69 | | -
|
70 | | -### Include the xcframework in a local checkout of `rust-components-swift` |
71 | | -After you generated the `MozillaRustComponents.xcframework.zip` in the previous step, do the following to include it in a local checkout of `rust-components-swift`. The file will be in the `megazords/ios-rust` directory. |
72 | | -1. Unzip the `MozillaRustComponents.xcframework.zip` into the `rust-components-swift` repository: (Assuming you are in the root of the `rust-components-swift` directory and `application-services` is a neighbor directory) |
73 | | - ```sh |
74 | | - unzip -o ../application-services/megazords/ios-rust/MozillaRustComponents.xcframework.zip -d . |
75 | | - ``` |
76 | | -1. Change the `Package.swift`'s reference to the xcframework to point to the unzipped `MozillaRustComponents.xcframework` that was created in the previous step. You can do this by uncommenting the following line: |
77 | | - ```swift |
78 | | - path: "./MozillaRustComponents.xcframework" |
79 | | - ``` |
80 | | - and commenting out the following lines: |
81 | | - ```swift |
82 | | - url: url, |
83 | | - checksum: checksum, |
84 | | - ``` |
85 | | - |
86 | | -### Run the generation script with a local checkout of application services |
87 | | -For this step, run the following script from inside the `rust-components-swift` repository (assuming that `application-services` is a neighboring directory to `rust-components-swift`). |
88 | | - |
89 | | -```sh |
90 | | -./generate.sh ../application-services |
| 87 | + |
| 88 | +> UniFFI bindings: If your component requires UniFFI-generated Swift, ensure the package targets reference the directory where generated Swift files are emitted (same pattern used in the repo’s Package.swift today). |
| 89 | +
|
| 90 | +## Step 3 — Reset caches and build |
| 91 | + |
| 92 | +In Xcode: |
| 93 | + |
| 94 | +- File → Packages → Reset Package Caches |
| 95 | +- (If needed) File → Packages → Update to Latest Package Versions |
| 96 | +- Product → Clean Build Folder, then build and run Firefox iOS. |
| 97 | + |
| 98 | +If you still see stale artifacts, delete: |
| 99 | + |
| 100 | +```swift |
| 101 | +~/Library/Caches/org.swift.swiftpm |
| 102 | +~/Library/Developer/Xcode/DerivedData/* |
91 | 103 | ``` |
92 | | -Once that is done, **stage and commit** the changes the script ran. Xcode can only pick up committed changes. |
93 | | - |
94 | | -### Include the local checkout of `rust-components-swift` in `firefox-ios` |
95 | | -This is the final step to include your local changes into `firefox-ios`. Do the following steps: |
96 | | -1. Open `Client.xcodeproj` in Xcode |
97 | | -1. Navigate to the Swift Packages in Xcode: |
98 | | - |
99 | | -1. Remove the dependency on `rust-components-swift` as listed on Xcode, you can click the dependency then click the `-` |
100 | | -1. Add a new swift package by clicking the `+`: |
101 | | - |
102 | | - 1. On the top right, enter the full path to your `rust-components-swift` checkout, preceded by `file://`. If you don't know what that is, run `pwd` in while in `rust-components-swift`. For example: `file:///Users/tarikeshaq/code/rust-components-swift` |
103 | | - 1. Change the branch to be the checked-out branch of rust-component-swift you have locally. This is what the dialog should look like: |
104 | | -  |
105 | | - > Note: If Xcode prevents you from adding the dependency to reference a local package, you will need to manually modify the `Client.xcodeproj/project.pbxproj` and replace every occurrence of `https://github.com/mozilla/rust-components-swift` with the full path to your local checkout. |
106 | | - 1. Click `Add Package` |
107 | | - 1. Now include the packages you would like to include, choose `MozillaAppServices` |
108 | | -1. Finally, attempt to build firefox-ios, and if all goes well it should launch with your code. If you face problems, feel free to [contact us](../index.md#contact-us) |
| 104 | + |
| 105 | +…and build again. |
| 106 | + |
| 107 | +--- |
| 108 | + |
| 109 | +## Disabling local development |
| 110 | + |
| 111 | +To revert quickly: |
| 112 | + |
| 113 | +1. Restore your changes to MozillaRustComponents/Package.swift (e.g., git checkout -- MozillaRustComponents/Package.swift). |
| 114 | +2. Reset Package Caches in Xcode. |
| 115 | +3. Build Firefox iOS. |
| 116 | + |
| 117 | +## Troubleshooting |
| 118 | + |
| 119 | +- Old binary still in use: Reset caches and clear DerivedData, then rebuild. |
| 120 | +- Branch switches in application-services: Rebuild the XCFramework and update the package reference (URL/checksum or path:). |
| 121 | +- Checksum mismatch (URL mode): Run swift package compute-checksum on the new zip and update Package.swift. |
| 122 | +- Build script issues: Re-run ./build-xcframework.sh from megazords/ios-rust. |
| 123 | + |
| 124 | +## Legacy: using rust-components-swift (remote package) |
| 125 | + |
| 126 | +[!WARNING] |
| 127 | +Status: rust-components-swift is deprecated for Firefox iOS. Prefer the local package at MozillaRustComponents/ unless you must validate against the legacy package for a specific task. |
| 128 | + |
| 129 | +Some teams may still need the legacy flow temporarily. Historically, Firefox iOS consumed Application Services through the rust-components-swift package. To test locally with that setup: |
| 130 | + |
| 131 | +1. Build the XCFramework from application-services. |
| 132 | +2. In a local checkout of rust-components-swift, point its Package.swift to the local path of the unzipped XCFramework: |
| 133 | + ```swift |
| 134 | + .binaryTarget( |
| 135 | + name: "MozillaRustComponents", |
| 136 | + path: "./MozillaRustComponents.xcframework" |
| 137 | + ) |
| 138 | + ``` |
| 139 | +3. Commit the changes in rust-components-swift (Xcode only reads committed package content). |
| 140 | +4. In Firefox iOS, replace the package dependency with a local reference to your rust-components-swift checkout (e.g., via Xcode’s “Add Local…” in Package Dependencies). |
0 commit comments