merge upstream

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: ci
 
 on:
   push:
-    branches: [main]
+    branches: '*'
   pull_request:
 
 env:
@@ -12,18 +12,32 @@ env:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
       matrix:
         # See top README for MSRV policy
-        rust_version: [1.64.0, stable]
+        rust-version: [1.73.0, stable]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      # Downgrade all dependencies to their minimum version, both to ensure our
+      # minimum version bounds are correct and buildable, as well as to satisfy
+      # our MSRV check when arbitrary dependencies bump their MSRV beyond our
+      # MSRV in a patch-release.
+      # This implies that downstream consumers can only rely on our MSRV when
+      # downgrading various (transitive) dependencies.
+      - uses: hecrj/setup-rust-action@v2
+        with:
+          rust-version: nightly
+        if: ${{ matrix.rust-version != 'stable' }}
+      - name: Downgrade dependencies
+        run: cargo +nightly generate-lockfile -Zminimal-versions
+        if: ${{ matrix.rust-version != 'stable' }}
 
-      - uses: hecrj/setup-rust-action@v1
+      - uses: hecrj/setup-rust-action@v2
         with:
-          rust-version: ${{ matrix.rust_version }}
+          rust-version: ${{ matrix.rust-version }}
 
       - name: Install Rust targets
         run: >
@@ -34,18 +48,7 @@ jobs:
           i686-linux-android
 
       - name: Install cargo-ndk
-        # We're currently sticking with cargo-ndk 2, until we bump our
-        # MSRV to 1.68+
-        run: cargo install cargo-ndk --version "^2"
-
-      - name: Setup Java
-        uses: actions/setup-java@v3
-        with:
-          distribution: 'temurin'
-          java-version: '17'
-
-      - name: Setup Android SDK
-        uses: android-actions/setup-android@v2
+        run: cargo +stable install cargo-ndk
 
       - name: Build game-activity
         working-directory: android-activity
@@ -68,7 +71,7 @@ jobs:
           build --features native-activity
 
       - name: Build agdk-mainloop example
-        if: matrix.rust_version == 'stable'
+        if: matrix.rust-version == 'stable'
         working-directory: examples/agdk-mainloop
         run: >
           cargo ndk
@@ -79,7 +82,7 @@ jobs:
           -o app/src/main/jniLibs/ -- build
 
       - name: Build na-mainloop example
-        if: matrix.rust_version == 'stable'
+        if: matrix.rust-version == 'stable'
         working-directory: examples/na-mainloop
         run: >
           cargo ndk
@@ -93,17 +96,20 @@ jobs:
         run: >
           cargo ndk -t arm64-v8a doc --no-deps
 
+      - name: Build doctests
+        # All doctests are set to no_run, because they require running in the
+        # context of an Android app.
+        # Only run on stable because cross-compiling doctests is only supported
+        # since Rust 1.89.
+        if: ${{ matrix.rust-version == 'stable' }}
+        run: |
+          cargo test --doc -F native-activity --target aarch64-linux-android
+          cargo ndk -t arm64-v8a -- test --doc -F game-activity
+
   format:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-
-      - uses: actions-rs/toolchain@v1
-        with:
-          profile: minimal
-          toolchain: stable
-          override: true
-          components: rustfmt
+      - uses: actions/checkout@v4
 
       - name: Format
         run: cargo fmt --all -- --check

Cargo.toml

@@ -1,8 +1,5 @@
 [workspace]
-members = [
-    "android-activity"
-]
+resolver = "2"
+members = ["android-activity"]
 
-exclude = [
-    "examples",
-]
+exclude = ["examples"]

README.md

@@ -1,4 +1,11 @@
-# Overview
+# `android-activity`
+
+[![ci](https://github.com/rust-mobile/android-activity/actions/workflows/ci.yml/badge.svg)](https://github.com/rust-mobile/android-activity/actions/workflows/ci.yml)
+[![crates.io](https://img.shields.io/crates/v/android-activity.svg)](https://crates.io/crates/android-activity)
+[![Docs](https://docs.rs/android-activity/badge.svg)](https://docs.rs/android-activity)
+[![MSRV](https://img.shields.io/badge/rustc-1.68.0+-ab6000.svg)](https://blog.rust-lang.org/2023/03/09/Rust-1.68.0.html)
+
+## Overview
 
 `android-activity` provides a "glue" layer for building native Rust
 applications on Android, supporting multiple [`Activity`] base classes.
@@ -22,14 +29,15 @@ applications.
 [ndk-glue]: https://crates.io/crates/ndk-glue
 [agdk]: https://developer.android.com/games/agdk
 
-# Example
+## Example
 
 Cargo.toml
-```
+
+```toml
 [dependencies]
 log = "0.4"
-android_logger = "0.11"
-android-activity = { version = "0.4", features = [ "native-activity" ] }
+android_logger = "0.13"
+android-activity = { version = "0.5", features = [ "native-activity" ] }
 
 [lib]
 crate_type = ["cdylib"]
@@ -38,6 +46,7 @@ crate_type = ["cdylib"]
 _Note: that you will need to either specify the **"native-activity"** feature or **"game-activity"** feature to identify which `Activity` base class your application is based on_
 
 lib.rs
+
 ```rust
 use android_activity::{AndroidApp, InputStatus, MainEvent, PollEvent};
 
@@ -69,22 +78,22 @@ fn android_main(app: AndroidApp) {
 }
 ```
 
-```
+```sh
 rustup target add aarch64-linux-android
 cargo install cargo-apk
 cargo apk run
 adb logcat example:V *:S
 ```
 
-# Full Examples
+## Full Examples
 
 See [this collection of examples](https://github.com/rust-mobile/rust-android-examples) (based on both `GameActivity` and `NativeActivity`).
 
 Each example is a standalone project that may also be a convenient templates for starting a new project.
 
 For the examples based on middleware frameworks (Winit and or Egui) they also aim to demonstrate how it's possible to write portable code that will run on Android and other systems.
 
-# Should I use NativeActivity or GameActivity?
+## Should I use NativeActivity or GameActivity?
 
 To learn more about the `NativeActivity` class that's shipped with Android see [here](https://developer.android.com/ndk/guides/concepts#naa).
 
@@ -96,31 +105,32 @@ It's expected that the `GameActivity` backend will gain more sophisticated input
 
 Even if you start out using `NativeActivity` for the convenience, it's likely that most moderately complex applications will eventually need to define their own `Activity` subclass (either subclassing `NativeActivity` or `GameActivity`) which will require compiling at least a small amount of Java or Kotlin code. This is generally due to Android's design which directs numerous events via the `Activity` class which can only be processed by overloading some associated Activity method.
 
-# Switching from ndk-glue to android-activity
+## Switching from ndk-glue to android-activity
+
+### Winit-based applications
 
-## Winit-based applications
 Firstly; if you have a [Winit](https://crates.io/crates/winit) based application and also have an explicit dependency on `ndk-glue` your application will need to remove its dependency on `ndk-glue` for the 0.28 release of Winit which will be based on android-activity (Since glue crates, due to their nature, can't be compatible with alternative glue crates).
 
 Winit-based applications can follow the [Android README](https://github.com/rust-windowing/winit#android) guidance for advice on how to switch over. Most Winit-based applications should aim to remove any explicit dependency on a specific glue crate (so not depend directly on `ndk-glue` or `android-activity` and instead rely on Winit to pull in the right glue crate). The main practical change will then be to add a `#[no_mangle]fn android_main(app: AndroidApp)` entry point.
 
 See the [Android README](https://github.com/rust-windowing/winit#android) for more details and also see the [Winit-based examples here](https://github.com/rust-mobile/rust-android-examples).
 
-## Middleware crates (i.e. not applications)
+### Middleware crates (i.e. not applications)
 
 If you have a crate that would be considered a middleware library (for example using JNI to support access to Bluetooth, or Android's Camera APIs) then the crate should almost certainly remove any dependence on a specific glue crate because this imposes a strict compatibility constraint that means the crate can only be used by applications that use that exact same glue crate version.
 
 Middleware libraries can instead look at using the [ndk-context](https://crates.io/crates/ndk-context) crate as a means for being able to use JNI without making any assumptions about the applications overall architecture. This way a middleware crate can work with alternative glue crates (including `ndk-glue` and `android-activity`) as well as work with embedded use cases (i.e. non-native applications that may just embed a dynamic library written in Rust to implement certain native functions).
 
-## Other, non-Winit-based applications
+### Other, non-Winit-based applications
 
 The steps to switch a simple standalone application over from `ndk-glue` to `android-activity` (still based on `NativeActivity`) should be:
 
 1. Remove `ndk-glue` from your Cargo.toml
-2. Add a dependency on `android-activity`, like `android-activity = { version="0.4", features = [ "native-activity" ] }`
-3. Optionally add a dependency on `android_logger = "0.11.0"`
+2. Add a dependency on `android-activity`, like `android-activity = { version="0.5", features = [ "native-activity" ] }`
+3. Optionally add a dependency on `android_logger = "0.13.0"`
 4. Update the `main` entry point to look like this:
 
-```
+```rust
 use android_activity::AndroidApp;
 
 #[no_mangle]
@@ -133,25 +143,22 @@ See this minimal [NativeActivity Mainloop](https://github.com/rust-mobile/androi
 
 There is is no `#[ndk_glue::main]` replacement considering that `android_main()` entry point needs to be passed an `AndroidApp` argument which isn't compatible with a traditional `main()` function. Having an Android specific entry point also gives a place to initialize Android logging and handle other Android specific details (such as building an event loop based on the `app` argument)
 
-
-## Design Summary / Motivation behind android-activity
+### Design Summary / Motivation behind android-activity
 
 Prior to working on android-activity, the existing glue crates available for building standalone Rust applications on Android were found to have a number of technical limitations that this crate aimed to solve:
 
 1. **Support alternative Activity classes**: Prior glue crates were based on `NativeActivity` and their API precluded supporting alternatives. In particular there was an interest in the [`GameActivity`] class in conjunction with it's [`GameTextInput`] library that can facilitate onscreen keyboard support. This also allows building applications based on the standard [`AppCompatActivity`] base class which isn't possible with `NativeActivity`. Finally there was interest in paving the way towards supporting a first-party `RustActivity` that could be best tailored towards the needs of Rust applications on Android.
 2. **Encapsulate IPC + synchronization between the native thread and the JVM thread**: For example with `ndk-glue` the application itself needs to avoid race conditions between the native and Java thread by following a locking convention) and it wasn't clear how this would extend to support other requests (like state saving) that also require synchronization.
 3. **Avoid static global state**: Keeping in mind the possibility of supporting applications with multiple native activities there was interest in having an API that didn't rely on global statics to track top-level state. Instead of having global getters for state then `android-activity` passes an explicit `app: AndroidApp` argument to the entry point that encapsulates the state connected with a single `Activity`.
 
-
 [`GameTextInput`]: https://developer.android.com/games/agdk/add-support-for-text-input
 [`AppCompatActivity`]: https://developer.android.com/reference/androidx/appcompat/app/AppCompatActivity
 
-
-# MSRV
+## MSRV
 
 We aim to (at least) support stable releases of Rust from the last three months. Rust has a 6 week release cycle which means we will support the last three stable releases.
-For example, when Rust 1.69 is released we would limit our `rust_version` to 1.67.
+For example, when Rust 1.69 is released we would limit our `rust-version` to 1.67.
 
-We will only bump the `rust_version` at the point where we either depend on a new features or a dependency has increased its MSRV, and we won't be greedy. In other words we will only set the MSRV to the lowest version that's _needed_.
+We will only bump the `rust-version` at the point where we either depend on a new features or a dependency has increased its MSRV, and we won't be greedy. In other words we will only set the MSRV to the lowest version that's _needed_.
 
-MSRV updates are not considered to be inherently semver breaking (unless a new feature is exposed in the public API) and so a `rust_version` change may happen in patch releases.
+MSRV updates are not considered to be inherently semver breaking (unless a new feature is exposed in the public API) and so a `rust-version` change may happen in patch releases.