docs: document running Android examples with cargo-apk

xilem/Cargo.toml

@@ -95,6 +95,7 @@ doc-scrape-examples = false
 name = "http_cats"
 
 # Also add to ANDROID_TARGETS in .github/ci.yml if adding a new Android example
+# and update the list in xilem/examples/android/README.md.
 # A custom example target which uses the same `mason.rs` file but for android
 [[example]]
 name = "mason_android"

xilem/examples/android/README.md

@@ -2,4 +2,39 @@
 
 All the examples in this folder are just glue code importing from the respective examples in the parent folder.
 
-(TODO: Include note about how to use `cargo apk` here.)
+## Running on Android
+
+The examples are built and packaged with [`cargo-apk`](https://crates.io/crates/cargo-apk).
+
+### Prerequisites
+
+- The Android SDK and NDK, and the `ANDROID_HOME` and `ANDROID_NDK_ROOT` environment variables set so that `cargo-apk` can find them. See the [`cargo-apk` README](https://github.com/rust-mobile/cargo-apk) for the full requirements.
+- An Android Rust target installed via `rustup`, for example:
+
+  ```sh
+  rustup target add aarch64-linux-android
+  ```
+
+- `cargo-apk` itself:
+
+  ```sh
+  cargo install cargo-apk --locked
+  ```
+
+### Build and run
+
+From the repository root, build any of the examples in this folder with `cargo apk build --example <name>`, for example:
+
+```sh
+cargo apk build -p xilem --example calc_android
+```
+
+The supported examples are `calc_android`, `emoji_picker_android`, `http_cats_android`, `mason_android`, `stopwatch_android`, `to_do_mvc_android`, and `variable_clock_android`.
+
+To install and run the example on a connected device or running emulator, use `cargo apk run` instead:
+
+```sh
+cargo apk run -p xilem --example calc_android
+```
+
+`cargo apk check` (with the same target selectors) is used by CI to verify that every Android example still compiles for `aarch64-linux-android`.