Building library for iOS

Generate library (.a file):

Rustup installation

• Install rustup
• Add device target: rustup target add aarch64-apple-ios,
• Add simulator target: rustup target add x86_64-apple-ios
• Proceed with scripted/manual flow

A) Scripted flow

• Install rust-bitcode library (it will handle issues arising from iOS and Rust toolchain using different LLVM versions)
• Add the path to your local clone of the iOS app to create_ios_universal.sh.
• Execute create_ios_universal.sh script in ./scripts/ios/ to generate a universal static library with Bitcode support. This will place the output in ./target/universal/release. It will also overwrite the library in the iOS app's Carthage folder, allowing to update the dependency locally without creating new releases.

Creating a new release:

• Run the [make_framework.sh] (https://github.com/Co-Epi/app-backend-rust/blob/master/scripts/ios/make_framework.sh) script to create a static framework with the generated library. Alternatively, you can download one of the released versions and replace the binary (CoEpiCore) and header(s) inside the folder.
• Create a new Release in Github and attach this framework as binary.

B) Manual flow (alternative)

With Bitcode

Build for device

Xcode uses often a different LLVM version than Rust, which generates incompatible Bitcode. The rust-bitcode library helps us with this.

• Install rust-bitcode library

After you've installed this library, in this repo's root folder,

• execute:

RUSTFLAGS="-Z embed-bitcode" cargo +ios-arm64 build --target aarch64-apple-ios --release --lib

This will generate the library for the device and save it in ./target/aarch64-apple-ios/release/

Build for simulator

The simulator doesn't require bitcode, independently of the project's settings. So you can create the library with only cargo build --target=x86_64-apple-ios

Create universal library with bitcode

We've now 2 separate libraries for the simulator and the device. We have to merge them into one, which can be used by Xcode. From the root directory of this repo, execute:

libtool -static -o libtcn_client.a ./target/aarch64-apple-ios/release/libtcn_client.a ./target/x86_64-apple-ios/release/libtcn_client.a

The generated libtcn_client.a will be where you indicate, in this case, in the same directory where libtool was executed.

Without Bitcode (not recommended)

• Turn off Bitcode support in Xcode
• Run in the root directory of this repo: cargo lipo --release. This generates a universal library for all supported architectures.
• You will find the library in ./target/universal/release/

Using library in the iOS app

• Copy libtcn_client.a file into the iOS app's root dir.

Updating the library interface (API)

Any changes to the library API require that a header file mobileapp-ios.h be modified accordingly.

• Update the headers in mobileapp-ios.h (located in the iOS app repo).