Add Iris Android APK tooling

readme.md

@@ -6,6 +6,76 @@ It's currently designed around using retained data structures (widgets), rather
 
 Examples are in `examples`, eg. `cargo run --example tabs`.
 
+## Android applications
+
+An Android application is a library because Android loads its Rust code as a
+native shared library:
+
+```toml
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+iris = { path = "../iris" }
+
+[package.metadata.iris.android]
+application-id = "com.example.myapp"
+label = "My app"
+```
+
+`#[iris::app_init]` marks the factory called when Android creates the Iris
+view. The attribute supplies its own Android target gate and generates the JNI
+loader glue. The returned state chooses its resources through
+`AndroidAppState::Resources`; `StdRsc` is the standard bundle, not a
+requirement.
+
+```rust
+use iris::prelude::*;
+
+#[derive(AndroidUiState)]
+struct State {
+    ui_state: AndroidUiState,
+}
+
+impl AndroidAppState for State {
+    type Resources = StdRsc<Self>;
+}
+
+#[iris::app_init]
+fn create(mut ui_state: AndroidUiState, rsc: &mut StdRsc<State>) -> State {
+    rect(PaintId::RED).set_root(rsc, &mut ui_state);
+    State { ui_state }
+}
+```
+
+Install the Cargo subcommand from a checkout, then invoke it from the
+application's directory:
+
+```sh
+cargo install --path /path/to/iris/cargo-iris
+cargo iris apk --abi arm64-v8a
+cargo iris run --abi x86_64 --device emulator-5554
+```
+
+`cargo iris` packages directly with `cargo-ndk`, `javac`, `d8`, `aapt2`,
+`jar`, `zipalign`, and `apksigner`; it does not require Gradle. The caller
+provides a JDK, Android SDK and NDK, and any emulator or physical device. Set
+`ANDROID_HOME` to the SDK. `run` always requires an explicit device and never
+creates or starts one.
+
+Debug APKs use the standard key at `~/.android/debug.keystore`, creating it
+with `keytool` when absent. A release build requires the long-lived signing
+identity explicitly:
+
+```sh
+IRIS_KEYSTORE_PASSWORD=... IRIS_KEY_PASSWORD=... \
+  cargo iris apk --release --keystore /secure/upload.jks --key-alias upload
+```
+
+APK staging and output live under
+`target/iris-android/<package>/<debug|release>/<abi>/`; the command's final
+line is the verified APK's absolute path.
+
 Goals, in general order:
 1. does what I want it to (text, images, video, animations)
 2. very easy to use ignoring ergonomic ref counting