Module winit::platform::android

source ·
Available on android_platform only.
Expand description

§Android

The Android backend builds on (and exposes types from) the ndk crate.

Native Android applications need some form of “glue” crate that is responsible for defining the main entry point for your Rust application as well as tracking various life-cycle events and synchronizing with the main JVM thread.

Winit uses the android-activity as a glue crate (prior to 0.28 it used ndk-glue).

The version of the glue crate that your application depends on must match the version that Winit depends on because the glue crate is responsible for your application’s main entry point. If Cargo resolves multiple versions, they will clash.

winit glue compatibility table:

winitndk-glue
0.30android-activity = "0.6"
0.29android-activity = "0.5"
0.28android-activity = "0.4"
0.27ndk-glue = "0.7"
0.26ndk-glue = "0.5"
0.25ndk-glue = "0.3"
0.24ndk-glue = "0.2"

The recommended way to avoid a conflict with the glue version is to avoid explicitly depending on the android-activity crate, and instead consume the API that is re-exported by Winit under winit::platform::android::activity::*

Running on an Android device needs a dynamic system library. Add this to Cargo.toml:

[lib]
name = "main"
crate-type = ["cdylib"]

All Android applications are based on an Activity subclass, and the android-activity crate is designed to support different choices for this base class. Your application must specify the base class it needs via a feature flag:

Base ClassFeature FlagNotes
NativeActivityandroid-native-activityBuilt-in to Android - it is possible to use without compiling any Java or Kotlin code. Java or Kotlin code may be needed to subclass NativeActivity to access some platform features. It does not derive from the AndroidAppCompat base class.
GameActivityandroid-game-activityDerives from AndroidAppCompat, a defacto standard Activity base class that helps support a wider range of Android versions. Requires a build system that can compile Java or Kotlin and fetch Android dependencies from a Maven repository (or link with an embedded release of GameActivity)

For more details, refer to these android-activity example applications.

§Converting from ndk-glue to android-activity

If your application is currently based on NativeActivity via the ndk-glue crate and building with cargo apk, then the minimal changes would be:

  1. Remove ndk-glue from your Cargo.toml
  2. Enable the "android-native-activity" feature for Winit: winit = { version = "0.30.0", features = [ "android-native-activity" ] }
  3. Add an android_main entrypoint (as above), instead of using the ’[ndk_glue::main] proc macro from ndk-macros (optionally add a dependency on android_logger and initialize logging as above).
  4. Pass a clone of the AndroidApp that your application receives to Winit when building your event loop (as shown above).

Modules§

  • activity
    Re-export of the android_activity API

Traits§