[android] - update getting started and distribution docs (#8412)

* [android] - update project documentation

* add linux instructions

4 files changed, 88 insertions, 160 deletions

diff --git a/platform/android/CONTRIBUTING_LINUX.md b/platform/android/CONTRIBUTING_LINUX.md
deleted file mode 100644
index 875f7a800a..0000000000
--- a/platform/android/CONTRIBUTING_LINUX.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Contributing to the Android SDK on Linux
-
-_These instructions were tested on Ubuntu 16.04 LTS (aka Xenial Xerus)._
-
-Install the build dependencies:
-
-```
-$ sudo apt-get install -y android-tools-adb build-essential curl git \
-        lib32stdc++6 lib32z1 openjdk-8-jdk pkg-config python
-```
-
-Install the Android SDK. We recommend doing this by way of [Android command line tools for Linux](http://developer.android.com/sdk/index.html) but you can also achieve same results with the Android Studio package.
-
-Unpack the SDK and make sure you have the proper environment variables set.
-
-```
-$ export PATH=/path/to/android-sdk-linux/tools:$PATH
-$ export ANDROID_HOME=/path/to/android-sdk-linux
-```
-
-Update the Android SDK to the latest version:
-
-```
-$ android update sdk -u
-```
-
-## Setting Mapbox Access Token
-
-_The demo applications use Mapbox vector tiles, which require a Mapbox account and API access token. Obtain an access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/)._
-
-gradle will take the value of the `MAPBOX_ACCESS_TOKEN` environ variable and save it to `platform/android/MapboxGLAndroidSDKTestApp/src/main/res/values/developer-config.xml` where the app will read it from.  Otherwise, you can edit `developer-config.xml` and add the value manually as `mapbox_access_token`.
-
-## Building
-
-Checking out the code:
-
-```
-$ git clone https://github.com/mapbox/mapbox-gl-native.git
-$ cd mapbox-gl-native
-```
-
-Building a debug version will generated a self-signed test application that can be installed on the phone or emulator:
-
-```
-$ BUILDTYPE=Debug make android
-$ adb install -r platform/android/MapboxGLAndroidSDKTestApp/build/outputs/apk/MapboxGLAndroidSDKTestApp-debug.apk 
-```
-
-The debug version will emit considerable more log information (and run slower). Use simply `make android` to build a release version.
diff --git a/platform/android/CONTRIBUTING_MACOS.md b/platform/android/CONTRIBUTING_MACOS.md
deleted file mode 100644
index 6ab55921e3..0000000000
--- a/platform/android/CONTRIBUTING_MACOS.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Contributing to the Android SDK on macOS
-
-## Install JDK 7+ and Android Studio:
-
- Android Studio requires the Java Development Kit (JDK) which you can [download here](http://www.oracle.com/technetwork/java/javase/downloads/index.html). Once the JDK is installed, you can grab the [latest version of Android Studio here](https://developer.android.com/sdk/index.html) and install it following the on screen instructions.  
-
-Once Android Studio is installed, the [first time it's run it'll ask to install the Android SDK](http://developer.android.com/sdk/installing/index.html?pkg=studio) which you should do.  While doing so in the Android SDK Manager make sure to also select and install the latest versions of "Android Support Repository" and "Android Support Library" from "Extras":
-
-![image](https://cloud.githubusercontent.com/assets/98601/9915837/289f398e-5c6e-11e5-9a84-ed4d08d52d1f.png)
-
-By default, the Android SDK will be installed to `/Users/<user>/Library/Android/sdk/`.  For more information on how to [configure Android Studio](http://tools.android.com/tech-docs/configuration) and how to [set Project JDK vs IDE JDK](http://tools.android.com/tech-docs/configuration/osx-jdk) please see [Google's documentation](http://tools.android.com/overview).
-
-## Setting Mapbox Access Token
-
-_The test application (used for development purposes) uses Mapbox vector tiles, which require a Mapbox account and API access token. Obtain a free access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/)._
-
-If you start Android Studio from your terminal, gradle will take the value of the `MAPBOX_ACCESS_TOKEN` environment variable and save it to `MapboxGLAndroidSDKTestApp/src/main/res/values/developer-config.xml` where the app will read it from. Otherwise,
-you can edit `developer-config.xml` and add the value manually as `mapbox_access_token`.
-
-## Developing In Android Studio
-
-To work with the Mapbox Android SDK, you'll first need to get it set up as a Project in Android Studio.  To do so Open Android Studio and select "Import project (Eclipse ADT, Gradle, etc.)" from the Welcome to Android Studio dialog.  From there select the `platform/android` directory from the local file system where `mapbox-gl-native` was cloned.  For example:
-
-```sh
-/Users/<user>/development/mapbox-gl-native/platform/android
-```
-
-The Mapbox Android SDK is a multi-module Gradle based project.  Specifically, the SDK itself is an [Android Library](http://developer.android.com/tools/projects/index.html#LibraryModules) module and it utilizes a companion [test module](http://developer.android.com/tools/projects/index.html#testing) (aka "the TestApp") for daily development.  When Android Studio finishes importing the project both `MapboxGLAndroidSDK` and `MapboxGLAndroidSDKTestApp` modules should be visible.
-
-## Setting `ANDROID_HOME`
-
-For `build android` to work, you'll need to set the `ANDROID_HOME` environment
-to point to your Android SDK installation:
-
-```
-export ANDROID_HOME=/<installation location>/android-sdk-macosx
-```
-
-This environment variable configuration should go into a file that's read on
-your shell's startup, like `~/.profile`.
-
-## Speeding up gradle builds
-
-To optimise you development machine for faster gradle builds create the following `/Users/name/.gradle/gradle.properties`  file:
-
-```
-org.gradle.daemon=true
-org.gradle.jvmargs=-Xmx3072M
-```
-
-## Running The TestApp
-
-In order to run the TestApp on an emulator or device the Core GL portion needs to built first.  Core GL is the common C++ based OpenGL engine that powers the maps for iOS, Android, and Qt in the project.  To build it, open Terminal and run the following commands from the root of the `mapbox-gl-native` source code
-
-Run:
-
-    // From /Users/<user>/development/mapbox-gl-native
-
-    // Makes arm7 ABI version of Core GL
-    // Can be run on most Android phones and arm emulator
-    make android
-
-    // Make x86 version of Core GL
-    // Useful for running faster Anroid x86 emulator on Macs
-    make android-lib-x86
-
-Once Core GL has been built, the TestApp can be run by selecting `MapboxGLAndroidSDKTestApp` from the Run menu or toolbar in Android Studio.
-
-**Next: get your app [running on a hardware Android Device](platform/android/README.md#running-mapbox-gl-native-on-a-hardware-android-device) or [simulator](platform/android/README.md#setting-up-the-android-emulator)**
diff --git a/platform/android/DISTRIBUTE.md b/platform/android/DISTRIBUTE.md
index e7df5650f1..648f26ce25 100644
--- a/platform/android/DISTRIBUTE.md
+++ b/platform/android/DISTRIBUTE.md
@@ -1,21 +1,30 @@
 # Distributing Mapbox GL Native for Android
 
-Depending on your use case, you may want to support all or just a subset of [Android ABIs](http://developer.android.com/ndk/guides/abis.html).
-This can be achieved using the different `Makefile` targets that are available.
+Depending on your use case, you may want to support all or just a subset of [Android ABIs](http://developer.android.com/ndk/guides/abis.html). This document covers building an `.aar` file from the Mapbox Android SDK and building `.so` files for specific ABIs. In normal circumstances an application developer will use [APK splits](https://developer.android.com/studio/build/configure-apk-splits.html) to optimize this at application level.
 
-##### Build native libraries for all supported ABIs
+##### Build types
+
+With a `BUILDTYPE` var you can specify the build type for the `.so` and `.aar` files:
+
+```bash
+BUILDTYPE=Debug or BUILDTYPE=Release
+```
+
+##### Creating an Android Archive file that supports all ABIs
 
 ```sh
-make apackage
+BUILDTYPE=RELEASE make apackage
 ```
 
 This will build native libraries to support following ABIs:
- - armeabi
- - armeabi-v7a
- - arm64-v8a
- - x86
- - x86_64
- - mips
+- armeabi
+- armeabi-v7a
+- arm64-v8a
+- x86
+- x86_64
+- mips
+
+After succesfully finish building the native libraries, gradle will build the MapboxAndroidSDK module and generate an Android Archive file in `MapboxAndroidSDK/build/outputs/aar `. The packaged native libraries can be found in `MapboxAndroidSDK/src/main/jniLibs/<abi>`.
 
 ##### Build native libraries for a specific ABI
 
@@ -26,13 +35,13 @@ make android-lib-%%
 In the command above you'll need to replace `%%` with an ABI key listed below:
 
 | ABI Key | Android ABI |
-|---------|-------------|
-| arm-v5 | armeabi |
-| arm-v7 | armeabi-v7a |
-| arm-v8 | arm64-v8a |
-| x86 | x86 |
-| x86-64 | x86_64 |
-| mips | mips |
+| ------- | ----------- |
+| arm-v5  | armeabi     |
+| arm-v7  | armeabi-v7a |
+| arm-v8  | arm64-v8a   |
+| x86     | x86         |
+| x86-64  | x86_64      |
+| mips    | mips        |
 
 For example, to build the arm64-v8a ABI the Makefile target would be:
 
diff --git a/platform/android/README.md b/platform/android/README.md
index 67e08b963b..7c28433d96 100644
--- a/platform/android/README.md
+++ b/platform/android/README.md
@@ -4,49 +4,86 @@
 
 A library based on [Mapbox GL Native](../../README.md) for embedding interactive map views with scalable, customizable vector maps into Java applications on Android devices.
 
+## Getting Started 
+
+Alright. So, actually, you may be in the wrong place. From here on in, this README is going to be for people who are interested in working on and improving on Mapbox GL Native for Android.
+
+**To view our current API documentation, see our [JavaDoc](https://www.mapbox.com/android-sdk/api).**
+
 **To install and use the Mapbox Android SDK in an application, see the [Mapbox Android SDK website](https://www.mapbox.com/android-sdk/).**
 
 [![](https://www.mapbox.com/android-sdk/images/splash.png)](https://www.mapbox.com/android-sdk/)
 
-## Contributing to the SDK
+### Setup environment
 
 **These instructions are for developers interested in making code-level contributions to the SDK itself. If you instead want to use the SDK in your app, see above.**
 
-Building the SDK yourself requires [a number of dependencies and steps](../../INSTALL.md) that are unnecessary for developing production applications.
+#### Getting the source
+
+Clone the git repository
+
+```bash
+git clone https://github.com/mapbox/mapbox-gl-native.git
+cd mapbox-gl-native
+```
+
+#### Installing dependencies
+
+These dependencies are required for all operating systems and all platform targets.
+
+- Latest stable [Android Studio](https://developer.android.com/studio/index.html) 
+- Update Android SDK with latest
+  - Android SDK Build-Tools 
+  - Android Platform-Tools
+  - Android SDK Tools
+  - CMake
+  - NDK
+  - LLDB
+
+- Modern C++ compiler that supports -std=c++14
+  - clang++ 3.5 or later or
+  - g++-5 or later
+- [cURL](https://curl.haxx.se) (for build only)
+- [Node.js](https://nodejs.org/) or later (for build only)
+- [pkg-config](https://wiki.freedesktop.org/www/Software/pkg-config/) (for build only)
+
+##### Additional Dependencies for Linux
+
+_These instructions were tested on Ubuntu 16.04 LTS (aka Xenial Xerus)._
+
+```
+$ sudo apt-get install -y build-essential curl lib32stdc++6 lib32z1 pkg-config python
+```
+
+##### Additional Dependencies for macOS
+
+- Apple Command Line Tools (available at  [Apple Developer](https://developer.apple.com/download/more/))
+- [xcpretty](https://github.com/supermarin/xcpretty) (`gem install xcpretty`)
 
-* [Contributing on Linux](CONTRIBUTING_LINUX.md)
-* [Contributing on macOS](CONTRIBUTING_MACOS.md)
 
-### Setting up the Android emulator
+#### Open project in Android Studio
 
-The Mapbox Android SDK requires Android 4.0.3+ (API level 15+).
+##### macOS
 
-If you want to run the test app in the emulator, we recommend the x86 build because it will run a lot faster.
+Execute the following to generate the required build files and open the project with Android Studio:
 
-First ensure you have an `MAPBOX_ACCESS_TOKEN` environment variable set, as described below. Then, create an x86 build:
+```
+make aproj
+```
 
-    make android-lib-x86
+##### linux
 
-In Android Studio, create an x86 AVD (Android Virtual Device):
+Open Android Studio project in `/platform/android`, run `make android-configuration` in the root folder of the project.
 
-- Open AVD Manager via the Tools menu -> Android -> 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.
+##### Setting Mapbox Access Token
 
-### Running Mapbox GL Native on a hardware Android device
+_The test application (used for development purposes) uses Mapbox vector tiles, which require a Mapbox account and API access token. Obtain a free access token on the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/)._
 
-The Mapbox Android SDK requires Android 4.0.3+ (API level 15+).
+With the first gradle invocation, gradle will take the value of the `MAPBOX_ACCESS_TOKEN` environment variable and save it to `MapboxGLAndroidSDKTestApp/src/main/res/values/developer-config.xml`. If the environement variable wasn't set, you can edit `developer-config.xml` manually and add your access token to the `mapbox_access_token` resource.  
 
-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.
+#### Running project
 
-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.
+Run the configuration for the `MapboxGLAndroidSDKTestApp` module and select a device or emulator to deploy on. Based on the selected device, the c++ code will be compiled for the related processor architecture. You can see the project compiling in the `View > Tool Windows > Gradle Console`. 
 
-If your device does not show up, double check the [Google documentation](http://developer.android.com/tools/device.html).
+More information about building and distributing this project in [DISTRIBUTE.md][https://github.com/mapbox/mapbox-gl-native/blob/master/platform/android/DISTRIBUTE.md].