diff --git a/.gitignore b/.gitignore index ff719ce6c1..b0e8861134 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,7 @@ xcuserdata # UniFFI generated artifacts components/**/ios/Generated +megazords/ios-rust/Sources/MozillaRustComponentsWrapper/Generated # We don't car about Cargo.lock for our tests. testing/sync-test/Cargo.lock diff --git a/docs/howtos/locally-published-components-in-firefox-ios.md b/docs/howtos/locally-published-components-in-firefox-ios.md index 59c11becc0..4cbd20324c 100644 --- a/docs/howtos/locally-published-components-in-firefox-ios.md +++ b/docs/howtos/locally-published-components-in-firefox-ios.md @@ -13,6 +13,7 @@ 1. Build an **XCFramework** from your local `application-services`. 2. Point **Firefox iOS’s local Swift package** (`MozillaRustComponents/Package.swift`) at that artifact (either an HTTPS URL + checksum, **or** a local `path:`). +3. Update UniFFI generated swift source files. 3. Reset package caches in Xcode and build Firefox iOS. 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. @@ -26,25 +27,27 @@ A legacy flow that uses the **`rust-components-swift`** package is documented at --- -## Step 1 — Build the XCFramework from Application Services +## Step 1 — Build all artifacts needed from Application Services. -From your `application-services` checkout: +This step builds an XCFramework and also generates swift sources for the components with UniFFI. + +From the root of your `application-services` checkout, execute: ```bash -cd megazords/ios-rust -./build-xcframework.sh +./automation/build_ios_artifacts.sh ``` -This produces MozillaRustComponents.xcframework.zip (and you can also unzip it to get MozillaRustComponents.xcframework) containing: +This produces: -- The compiled Rust code as a static library (for all iOS targets) -- C headers and Swift module maps for the components +- `megazords/ios-rust/MozillaRustComponents.xcframework`, containing: + - The compiled Rust code as a static library (for all iOS targets) + - C headers and Swift module maps for the components +- `megazords/ios-rust/MozillaRustComponents.xcframework.zip`, which is a zip + of the above directory. By default, firefox-ios consumes the .zip file, although + as we discuss below, we will change firefox-ios to use the directory itself. +- `megazords/ios-rust/Sources/MozillaRustComponentsWrapper/Generated/*.swift`, which are + the source files generated by UniFFI. -> Tip: If you plan to use the URL-based approach below, compute the checksum once you have the zip: - -```bash -swift package compute-checksum MozillaRustComponents.xcframework.zip -``` ## Step 2 — Point Firefox iOS to your local artifact @@ -54,39 +57,35 @@ Firefox iOS consumes Application Services via a local Swift package in-repo at: {path-to-firefox-ios}/MozillaRustComponents/Package.swift ``` -update it in one of two ways: - -### Option A: URL + checksum (zip artifact) +update it as described below: -1. Host your MozillaRustComponents.xcframework.zip at an HTTPS-accessible URL (e.g., a Taskcluster or GitHub artifact URL). -2. Edit MozillaRustComponents/Package.swift and set the binaryTarget to the zip URL and checksum: +1. Switch the binaryTarget to a local path - note however that the path can't be absolute but must be relative to `Package.swift`. + For example, if you have `application-services` checked out next to the `firefox-ios` repo, a suitable relative path might be + `../../application-services/megazords/ios-rust/MozillaRustComponents.xcframework` +2. Comment out or remove the `url` and `checksum` elements - they aren't needed when pointing to a local path: ```swift // In firefox-ios/MozillaRustComponents/Package.swift .binaryTarget( name: "MozillaRustComponents", - url: "https://example.com/path/MozillaRustComponents.xcframework.zip", - checksum: "" + // ** Comment out the existing `url` and `checksum` entries + // url: url, + // checksum: checksum + // ** Add a new `path` entry. + path: "../../application-services/megazords/ios-rust/MozillaRustComponents.xcframework" ) ``` -> Note: Every time you produce a new zip, you must update the checksum. - -### Option B: Local path (fastest for iteration) +3. Update UniFFI generated files: manually copy `./megazords/ios-rust/Sources/MozillaRustComponentsWrapper/Generated/*.swift` from + your `application-services` directory to the existing `./MozillaRustComponents/Sources/MozillaRustComponentsWrapper/Generated/.` + directory in your `firefox-ios` checkout. -1. Unzip the XCFramework near the package (or anywhere on disk). -2. Switch the binaryTarget to a local path: +for example, from the root of your application-services directory: -```swift -// In firefox-ios/MozillaRustComponents/Package.swift -.binaryTarget( - name: "MozillaRustComponents", - path: "./MozillaRustComponents.xcframework" -) +```bash +cp ./megazords/ios-rust/Sources/MozillaRustComponentsWrapper/Generated/*.swift ../firefox-ios/MozillaRustComponents/Sources/MozillaRustComponentsWrapper/Generated/. ``` -> 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). - ## Step 3 — Reset caches and build In Xcode: @@ -106,6 +105,38 @@ If you still see stale artifacts (rare), delete: --- +## Using an external XCFramework artifact. + +The instructions above all assume you have an XCFramework you built locally. However, it might be +the case where you want to use a `MozillaRustComponents.xcframework.zip` from an HTTPS-accessible URL +(e.g., a Taskcluster or GitHub artifact URL). + +In this scenario, you also need the checksum of the zip file - this can be obtained by executing + +```bash +swift package compute-checksum megazords/ios-rust/MozillaRustComponents.xcframework.zip +``` + +However, that means you need to have the .zip file locally - in which case you might as well +unzip it and use the instructions above for consuming it from a local path! + +But for completeness, once you have a https URL and the checksum you should +edit `MozillaRustComponents/Package.swift` and set the binaryTarget to the zip URL and checksum: + +```swift +// In firefox-ios/MozillaRustComponents/Package.swift +.binaryTarget( + name: "MozillaRustComponents", + url: "https://example.com/path/MozillaRustComponents.xcframework.zip", + checksum: "" +) +``` + +> Note: Every time you produce a new zip, you must update the checksum. + +> Note: The above instructions do not handle copying updated files generated by UniFFI. +If you have changed the public API of any components, this process as written will not work. + ## Disabling local development To revert quickly: diff --git a/docs/howtos/locally-published-components-in-focus-ios.md b/docs/howtos/locally-published-components-in-focus-ios.md index e629a2350f..b59eea38a2 100644 --- a/docs/howtos/locally-published-components-in-focus-ios.md +++ b/docs/howtos/locally-published-components-in-focus-ios.md @@ -1,6 +1,8 @@ # How to locally test Swift Package Manager components on Focus iOS > This is a guide on testing the Swift Package Manager component locally against a local build of Focus iOS. For more information on our Swift Package Manager design, read the [ADR that introduced it](../adr/0003-swift-packaging.md) +**NOTE** - This guide is slightly out of date and needs to be updated. Better instructions can be found in the [instructions for Firefox](./locally-published-components-in-firefox-ios.md), but that process needs some Focus-specific tweaks. + > 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. To test a component locally, you will need to do the following: