Add README instructions for running on Android emulator and devices

1 files changed, 34 insertions, 5 deletions

diff --git a/README.md b/README.md
index e500c48e57..81bc1d6d52 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ Target OS X: 10.9+
 
 #### CocoaPods
 
-[CocoaPods](https://cocoapods.org) is preferred. Put the following in your `Podfile`: 
+[CocoaPods](https://cocoapods.org) is preferred. Put the following in your `Podfile`:
 
 ```ruby
 use_frameworks!
@@ -59,7 +59,7 @@ pod 'MapboxGL'
 #### Manually
 
 1. Use [Homebrew](http://brew.sh/) to install Boost headers: `brew install boost`.
-1. Install [appledoc](http://appledoc.gentlebytes.com/appledoc/) for API docs generation. We recommend [`2.2v963`](https://github.com/tomaz/appledoc/releases/tag/v2.2-963), which currently isn't available in Homebrew. 
+1. Install [appledoc](http://appledoc.gentlebytes.com/appledoc/) for API docs generation. We recommend [`2.2v963`](https://github.com/tomaz/appledoc/releases/tag/v2.2-963), which currently isn't available in Homebrew.
 1. Run `make ipackage`. The packaging script will produce the statically-linked `libMapboxGL.a`, `MapboxGL.bundle` for resources, a `Headers` folder, and a `Docs` folder with HTML API documentation.
 1. Copy the contents of `build/ios/pkg/static` into your project. It should happen automatically, but ensure that:
    - `Headers` is in your *Header Search Paths* (`HEADER_SEARCH_PATHS`) build setting.
@@ -79,15 +79,15 @@ pod 'MapboxGL'
 1. [Set the Mapbox API access token](#mapbox-api-access-tokens).
 1. `#import "MapboxGL.h"`
 
-### Development 
+### Development
 
 If you want to build from source and/or contribute to development of the project, run `make iproj`, which will create and open an Xcode project which can build the entire library from source as well as an Objective-C test app. If you don't have an Apple Developer account, change the destination from "My Mac" to a simulator such as "iPhone 6" before you run and build the app.
 
-You can run `make itest` to run the included integration tests. Requires `gem install xcpretty`. If you want to run the tests in Xcode instead, first `make ipackage` to create a local static library version, then open `test/ios/ios-tests.xcodeproj`, and lastly `Command + U` on the `Mapbox GL Tests` application target. 
+You can run `make itest` to run the included integration tests. Requires `gem install xcpretty`. If you want to run the tests in Xcode instead, first `make ipackage` to create a local static library version, then open `test/ios/ios-tests.xcodeproj`, and lastly `Command + U` on the `Mapbox GL Tests` application target.
 
 Target devices: iPhone 4S and above (5, 5c, 5s, 6, 6 Plus) and iPad 2 and above (3, 4, Mini, Air, Mini 2, Air 2).
 
-Target iOS: 7.0 through latest 8.x. 
+Target iOS: 7.0 through latest 8.x.
 
 
 ## Linux
@@ -194,6 +194,35 @@ Run:
 
 You can then open `android/java` in Android Studio via "Import Non-Android Studio Project".
 
+### Setting up Android emulator
+
+If you want to run the test app in the simulator, we reccomend the x86 build because it will run a lot faster.
+
+To create an x86 build in the terminal run:
+
+    ANDROID_ABI=x86 make android
+
+In Android studio create an x86 AVD (Android Virtual Device):
+- Open AVD Manager via the Tools menu -> Andorid -> AVD Manager
+- Click "Create Virtual Device" at the bottom on AVD Manager window
+- Select one of the device profiles, for example the Nexus 4
+- Click "Next"
+- Select a Lollipop or Kitkat release with ABI of x86. If the line is greyed out click Download to download the OS files.
+- Click "Next"
+- Under "Emulated Performance" check "Host GPU" and uncheck "Store a snapshot for faster startup"
+- Click "Finish"
+- Close the AVD Manager
+
+Now when you run or debug the Android project you will see a window "Choose Device". Select your new AVD from drop down under "Launch emulator". If you select "Use same device for future launches" Android Studio will remember the selection and not ask again.
+
+### Running on a hardware device
+
+First read the [Google documentation](http://developer.android.com/tools/device.html) to set up your device and your OS to connect to the device.
+
+When you plug your device in and then run or debug the Android project you will see a window "Choose Device". Choose your device from the "Choose a running device" list.
+
+If your device does not show you have not set it up properly, double check the [Google documentation](http://developer.android.com/tools/device.html).
+
 # Troubleshooting
 
 To trigger a complete rebuild, run `make clean` and then start over generating the Xcode projects or Makefiles as described above.