Android cross-compilation

Running on a platform like Android involves cross-compiling from a host platform (e.g. Linux) to a target platform (a specific Android version and system architecture):

• IREE's compiler is built on the host and is used there to generate modules for the target
• IREE's runtime is built on the host for the target. The runtime is then either pushed to the target to run natively or is bundled into an Android APK

Prerequisites

Host environment setup

You should already be able to build IREE from source on your host platform. Please make sure you have followed the getting started steps.

Install Android NDK and ADB

The Android Native Developer Kit (NDK) is needed to use native C/C++ code on Android. You can download it here, or, if you have installed Android Studio, you can follow this guide instead.

Note

Make sure the ANDROID_NDK environment variable is set after installing the NDK.

ADB (the Android Debug Bridge) is also needed to communicate with Android devices from the command line. Install it following the official user guide.

Configure and build

Host configuration

Build and install on your host machine:

cmake -GNinja -B ../iree-build/ \
  -DCMAKE_INSTALL_PREFIX=../iree-build/install \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  .
cmake --build ../iree-build/ --target install

Target configuration

Build the runtime using the Android NDK toolchain:

Linux macOS Windows

cmake -GNinja -B ../iree-build-android/ \
  -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK?}/build/cmake/android.toolchain.cmake" \
  -DIREE_HOST_BIN_DIR="$PWD/../iree-build/install/bin" \
  -DANDROID_ABI="arm64-v8a" \
  -DANDROID_PLATFORM="android-29" \
  -DIREE_BUILD_COMPILER=OFF \
  .
cmake --build ../iree-build-android/

cmake -GNinja -B ../iree-build-android/ \
  -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK?}/build/cmake/android.toolchain.cmake" \
  -DIREE_HOST_BIN_DIR="$PWD/../iree-build/install/bin" \
  -DANDROID_ABI="arm64-v8a" \
  -DANDROID_PLATFORM="android-29" \
  -DIREE_BUILD_COMPILER=OFF \
  .
cmake --build ../iree-build-android/

cmake -GNinja -B ../iree-build-android/ \
  -DCMAKE_TOOLCHAIN_FILE="%ANDROID_NDK%/build/cmake/android.toolchain.cmake" \
  -DIREE_HOST_BIN_DIR="%CD%/../iree-build/install/bin" \
  -DANDROID_ABI="arm64-v8a" \
  -DANDROID_PLATFORM="android-29" \
  -DIREE_BUILD_COMPILER=OFF \
  .
cmake --build ../iree-build-android/

Note

See the Android NDK CMake guide and Android Studio CMake guide for details on configuring CMake for Android.

The specific ANDROID_ABI and ANDROID_PLATFORM used should match your target device.

Running Android tests

Make sure you enable developer options and USB debugging on your Android device and can see your it when you run adb devices, then run all tests through ctest:

# Build test dependencies
cmake --build ../iree-build-android/ --target iree-test-deps

# Ensure that your Android device is visible
adb devices

# Run tests
ctest --test-dir ../iree-build-android/ --output-on-failure

This will automatically upload build artifacts to the connected Android device, run the tests, then report the status back to your host machine.

Running tools directly

Invoke the host compiler tools to produce a bytecode module FlatBuffer:

../iree-build/install/bin/iree-compile \
  --iree-hal-target-backends=vmvx \
  samples/models/simple_abs.mlir \
  -o /tmp/simple_abs_vmvx.vmfb

Push the Android runtime tools to the device, along with any FlatBuffer files:

adb push ../iree-build-android/tools/iree-run-module /data/local/tmp/
adb shell chmod +x /data/local/tmp/iree-run-module
adb push /tmp/simple_abs_vmvx.vmfb /data/local/tmp/

Run the tool:

adb shell /data/local/tmp/iree-run-module --device=local-task \
  --module=/data/local/tmp/simple_abs_vmvx.vmfb \
  --function=abs \
  --input="f32=-5"