android-rs-glue

deprecated in favor of https://github.com/rust-windowing/android-ndk-rs which works with winit master

Android Glue

Usage

With Docker

The easiest way to compile for Android is to use Docker and the philipalldredge/cargo-apk image.

In order to build an APK, simply do this:

docker run --rm -v :/root/src philipalldredge/cargo-apk cargo apk build

For example if you're on Linux and you want to compile the project in the current working directory.

docker run --rm -v "$(pwd):/root/src" -w /root/src philipalldredge/cargo-apk cargo apk build

Do not mount a volume on /root or you will erase the local installation of Cargo.

After the build is finished, you should get an Android package in target/android-artifacts/debug/apk.

Manual usage

Setting up your environment

Before you can compile for Android, you need to setup your environment. This needs to be done only once per system.

• Install rustup.
• Run rustup target add for all supported targets to which you want to compile. Building will attempt to build for all supported targets unless the build targets are adjusted via Cargo.toml.
  • rustup target add armv7-linux-androideabi
  • rustup target add aarch64-linux-android
  • rustup target add i686-linux-android
  • rustup target add x86_64-linux-android
• Install the Java JRE or JDK (on Ubuntu, sudo apt-get install openjdk-8-jdk).
• Download and unzip the Android NDK.
• Download and unzip the Android SDK.
• Install some components in the SDK: ./android-sdk/tools/bin/sdkmanager "platform-tools" "platforms;android-29" "build-tools;29.0.0".
• Install cargo-apk with cargo install cargo-apk.
• Set the environment variables NDK_HOME to the path of the NDK and ANDROID_HOME to the path of the SDK.

Compiling

In the project root for your Android crate, run cargo apk build. You can use the same options as with the regular cargo build.

This will build an Android package in target/android-artifacts//apk.

Compiling Multiple Binaries

cargo apk build supports building multiple binaries and examples using the same arguments as cargo build. It will produce an APK for each binary.

Android packages for bin targets are placed in target/android-artifacts//apk.

Android packages for example targets are placed in target/android-artifacts//apk/examples.

Testing on an Android emulator

Start the emulator, then run:

cargo apk run

This will install your application on the emulator, then run it.
If you only want to install, use cargo apk install.

To show log run: cargo apk logcat | grep RustAndroidGlueStdouterr

Interfacing with Android

An application is not very useful if it doesn't have access to the screen, the user inputs, etc.

The android_glue crate provides FFI with the Android environment for things that are not in the stdlib.

How it works

The build process

The build process works by:

• Using rustc to always compile your crate as a shared library by:
  • Creating a custom CMake toolchain file and setting environment variables which expose the appropriate NDK provided build tools for use with the cc and cmake crates.
  • Creating a temporary file in the same directory as your crate root. This temporary file serves as the crate root of the static library. It contains the contents of the original crate root along with an android_main implementation.
  • Compiling a forked version of android_native_app_glue. android_native_app_glue is originally provided by the NDK. It provides the entrypoint used by Android's NativeActivity that calls android_main.
  • Linking using the NDK provided linker.

This first step outputs a shared library, and is run once per target architecture.

The command then builds the APK using the shared libraries, generated manifest, and tools from the Android SDK. If the C++ standard library is used, it adds the appropriate shared library to the APK. It signs the APK with the default debug keystore used by Android development tools. If the keystore doesn't exist, it creates it using the keytool from the JRE or JDK.

Supported [package.metadata.android] entries

…

Environment Variables

Cargo-apk sets environment variables which are used to expose the appropriate C and C++ build tools to build scripts. The primary intent is to support building crates which have build scripts which use the cc and cmake crates.

• CC : path to NDK provided clang wrapper for the appropriate target and android platform.
• CXX : path to NDK provided clang++ wrapper for the appropriate target and android platform.
• AR : path to NDK provided ar
• CXXSTDLIB : c++ to use the full featured C++ standard library provided by the NDK.
• CMAKE_TOOLCHAIN_FILE : the path to the generated CMake toolchain. This toolchain sets the ABI, overrides any target specified, and includes the toolchain provided by the NDK.
• CMAKE_GENERATOR : Unix Makefiles to default to Unix Makefiles as opposed to using the CMake default which may not be appropriate depending on platform.
• CMAKE_MAKE_PROGRAM: Path to NDK provided make.

C++ Standard Library Compatibility Issues

When a crate links to the C++ standard library, the shared library version provided by the NDK is used. Unfortunately, dependency loading issues will cause the application to crash on older versions of android. Once lld linker issues are resolved on all platforms, cargo apk will be updated to link to the static C++ library. This should resolve the compatibility issues.