From ce1d16d90d818683a579187f21eb897c9dba547c Mon Sep 17 00:00:00 2001
From: Nicholas Rishel <rishel.nick@gmail.com>
Date: Mon, 2 Nov 2020 22:54:08 -0800
Subject: [PATCH] Add Android instructions to example README (#775)

Bonus: Fixed iOS formatted text by adding preceding newline.
---
 examples/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/examples/README.md b/examples/README.md
index 6de19fbeb5..8bbd8ba85c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -147,15 +147,18 @@ Then serve `examples/wasm` dir to browser. i.e.
 #### build & run
 
 Using bash:
+
     $ cd examples/ios
     $ make run
 
 In an ideal world, this will boot up, install and run the app for the first
 iOS simulator in your `xcrun simctl devices list`. If this fails, you can
 specify the simulator device UUID via:
+
     $ DEVICE_ID=${YOUR_DEVICE_ID} make run
 
 If you'd like to see xcode do stuff, you can run
+
     $ open bevy_ios_example.xcodeproj/
 
 which will open xcode. You then must push the zoom zoom play button and wait
@@ -169,3 +172,45 @@ variable in the "`cargo_ios` target" to be either `x86_64-apple-ios` or
 
 Note: if you update this variable in Xcode, it will also change the default
 used for the `Makefile`.
+
+## Android
+
+#### pre-req
+
+    $ rustup target add aarch64-linux-android armv7-linux-androideabi
+    $ cargo install cargo-apk
+
+The Android SDK 29 must be installed, and the environment variable `ANDROID_SDK_ROOT` set to the root Android `sdk` folder.
+
+When using `NDK (Side by side)`, the environment variable `ANDROID_NDK_ROOT` must also be set to one of the NDKs in `sdk\ndk\[NDK number]`.
+
+#### build & run
+
+To run on a device setup for Android development, run:
+
+    $ cargo apk run --example bevy_android --features="supported_android_features" --no-default-features
+
+:warning: At this time Bevy does not work in Android Emulator.
+
+When using Bevy as a library, the following fields must be added to `Cargo.toml`:
+
+    [package.metadata.android]
+    build_targets = [ "aarch64-linux-android", "armv7-linux-androideabi" ]
+    target_sdk_version = 29
+    min_sdk_version = 29
+
+    [[package.metadata.android.feature]]
+    name = "android.hardware.vulkan.level"
+    version = "1"
+
+Please reference `cargo-apk` [README](https://crates.io/crates/cargo-apk) for other Android Manifest fields.
+
+#### old phones
+
+Bevy by default requires Android API level 29 which is the [Play Store's minimum API to upload or update apps](https://developer.android.com/distribute/best-practices/develop/target-sdk). Users of older phones may want to use an older API when testing.
+
+To use a different API, the following fields must be updated in Cargo.toml:
+
+    [package.metadata.android]
+    target_sdk_version = >>API<<
+    min_sdk_version = >>API or less<<