Home

Awesome

rust-ios-android

Build status

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

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

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 RustCopy to Android
      target/armv7-linux-androideabi/release/lib???.sosrc/main/jniLibs/armeabi-v7a/lib???.so
      target/aarch64-linux-android/release/lib???.sosrc/main/jniLibs/arm64-v8a/lib???.so
      target/i686-linux-android/release/lib???.sosrc/main/jniLibs/x86/lib???.so
    • Don't forget to ensure the JNI glue between Rust and Java are compatible.