rust-ios-android

Example project for building a library for iOS + Android in Rust. macOS is required for iOS development.

• ✓ Rust 1.20 – 1.25
• ✓ Android 4.1 – 8.1 (Jelly Bean – Oreo) (API 16–27)
• ✓ iOS 7 – 11

(probably works on earlier versions but I don't bother to check 😛)

Note: The purpose of this project is not to create a pure Rust app, but rather use Rust as a shared native component between the mobile platforms.

You may also want to check https://github.com/Geal/rust_on_mobile.

Setup

1. Install the common build tools like C compiler and linker. On macOS, get Xcode, and install the command line tools.

   xcode-select --install

2. Get Android NDK. We recommend installing it via Android Studio or sdkmanager:

   sdkmanager --verbose ndk-bundle

   Otherwise, please define the environment variable $ANDROID_NDK_HOME to the path of the current version of Android NDK.

   export ANDROID_NDK_HOME='/usr/local/opt/android-ndk/android-ndk-r14b/'

3. Create the standalone NDKs.

   ./create-ndk-standalone.sh

4. Download rustup. We will use this to setup Rust for cross-compiling.

   curl https://sh.rustup.rs -sSf | sh

5. Download targets for iOS and Android.

   # iOS. Note: you need *all* five targets
   rustup target add aarch64-apple-ios armv7-apple-ios armv7s-apple-ios x86_64-apple-ios i386-apple-ios
   
   # Android.
   rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android

6. Copy the content of cargo-config.toml (consists of linker information of the Android targets) to ~/.cargo/config

   cat cargo-config.toml >> ~/.cargo/config

7. Install cargo-lipo to generate the iOS universal library.

   cargo install cargo-lipo

Creating the libraries

You use use the sample/ project as an example. (Note that the sample itself does not contain proper error checking.)

1. Write the library and expose a C interface. See the FFI chapter in the Rust Book for an introduction.

2. Expose the Java interface with JNI when target_os="android".

3. Build the libraries.

   cd sample/cargo
   
   # iOS
   cargo lipo --release
   
   # Android
   cargo build --target aarch64-linux-android --release
   cargo build --target armv7-linux-androideabi --release
   cargo build --target i686-linux-android --release
   
   cd ../..

4. Build the Xcode project.

   cd sample/ios
   xcodebuild -configuration Release -scheme RustSample | xcpretty
   cd ../..

   When you create an Xcode project yourself, note the following points:

   • Add the C header rust_regex.h to allow using the Rust functions from C.
   • Copy target/universal/release/lib???.a to the project. You may need to modify LIBRARY_SEARCH_PATHS to include the folder of the *.a file.
   • Note that cargo-lipo does not generate bitcode yet. You must set ENABLE_BITCODE to NO. (See also http://stackoverflow.com/a/38488617)
   • You need to link to libresolv.tbd.

5. Build the Android project.

   cd sample/android
   ./gradlew assembleRelease
   cd ../..

   When you create an Android Studio project yourself, note the following points:

   • Copy or link the *.so into the corresponding src/main/jniLibs folders:

     Copy from Rust	Copy to Android
     target/armv7-linux-androideabi/release/lib???.so	src/main/jniLibs/armeabi-v7a/lib???.so
     target/aarch64-linux-android/release/lib???.so	src/main/jniLibs/arm64-v8a/lib???.so
     target/i686-linux-android/release/lib???.so	src/main/jniLibs/x86/lib???.so

   • Don't forget to ensure the JNI glue between Rust and Java are compatible.