Skip to content

Latest commit

 

History

History
 
 

apple

README.md

Apple platforms support

This project and build script demonstrate how to create an XCFramework that can be imported into an Xcode project and run on Apple platforms. It can compile and bundle an entire SDK, or only a smaller Crypto module that provides end-to-end encryption for clients that already depend on an SDK (e.g. Matrix iOS SDK)

Prerequisites for building universal frameworks

  • the Rust toolchain
  • Apple targets (e.g. rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios aarch64-apple-darwin x86_64-apple-darwin)
  • xcodebuild command line tool from Apple
  • lipo for creating the fat static libs

Building the SDK

cargo xtask swift build-framework

The build-framework task will go through all the steps required to generate a fully usable .xcframework:

  1. compile matrix-sdk-ffi libraries for iOS, the iOS simulator and macOS under /target. Some targets are not part of the standard library and they will be built using the nightly toolchain.
  2. lipo together the libraries for the same platform under /generated
  3. run uniffi and generate the C header, module map and swift files
  4. xcodebuild an xcframework from the fat static libs and the original iOS one, and add the header and module map to it under generated/MatrixSDKFFI.xcframework
  5. cleanup and delete the generated files except the .xcframework and the swift sources (that aren't part of the framework)

For development purposes, it will additionally generate a Package.swift file in the root of the repo that can be used to add the framework to your project and enable debugging through the use of rust-xcode-plugin (make sure to run the task with the argument --profile=reldbg).

When building the SDK for release you should pass the --release argument to the task, which will strip away any symbols and optimise the created binary.

Building only the Crypto SDK

build_crypto_xcframework.sh

The build_crypto_xcframework.sh script will go through all the steps required to generate a fully usable .xcframework:

  1. compile matrix-sdk-crypto-ffi libraries for iOS and the iOS simulator under /target
  2. lipo together the libraries for the same platform under /generated
  3. run uniffi and generate the C header, module map and swift files
  4. xcodebuild an xcframework from the fat static libs and the original iOS one, and add the header and module map to it under generated/MatrixSDKCryptoFFI.xcframework
  5. cleanup and delete the generated files except the .xcframework and the swift sources (that aren't part of the framework)

Building & testing the Swift package

The Package.swift file in this directory provides a simple example on how to integrate everything together but also a place to run unit and integration tests from.

It's pre-configured to link to the generated static lib and .swift files so successfully running cargo xtask swift build-library first is necessary for it to compile. Afterwards you can execute the tests with swift test. Note that for the moment this only works on macOS but we're planning to add Linux support in the future.

Distribution

The generated framework and Swift code can be distributed and integrated directly but in order to make things simpler we bundle them together as a Swift package in the case of SDK, and as a CocoaPods podspec in the case of Crypto SDK.

Publishing MatrixSDKCrypto

  1. Run build_crypto_xcframework.sh script which generates a .zip file with the framework
  2. Increment the version in MatrixSDKCrypto.podspec
  3. Create a new GitHub release with the same version (see example for naming)
  4. Upload the .zip file to this release
  5. Push new Podspec version to Cocoapods via pod trunk push MatrixSDKCrypto.podspec --allow-warnings