From 9aac976104f4c6453cf9e79e03a002565720f213 Mon Sep 17 00:00:00 2001 From: Tobrun Date: Sun, 29 Oct 2017 08:02:27 -0700 Subject: [PATCH] [android] - update getting started documentation --- platform/android/README.md | 158 ++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 88 deletions(-) diff --git a/platform/android/README.md b/platform/android/README.md index 3ce66526c..d8ec069c6 100644 --- a/platform/android/README.md +++ b/platform/android/README.md @@ -2,9 +2,9 @@ [![Circle CI build status](https://circleci.com/gh/mapbox/mapbox-gl-native.svg?style=shield)](https://circleci.com/gh/mapbox/workflows/mapbox-gl-native/tree/master) -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. +A library based on [Mapbox GL Native](../../README.md) for embedding interactive map views with scalable, customizable vector maps onto Android devices. -## Getting Started +## 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. @@ -14,15 +14,75 @@ Alright. So, actually, you may be in the wrong place. From here on in, this READ [![](https://www.mapbox.com/android-sdk/images/splash.png)](https://www.mapbox.com/android-sdk/) -#### Opening the project in Android Studio +### Setup environment -We recommend that you open this repository's `android` folder in Android Studio. +**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.** -mapbox-gl-native > platform > android +#### Getting the source -Once you open it in Android Studio and switch to the Android view in the left-hand sidebar, you should see the `MapboxGLAndroidSDK` and `MapboxGLAndroidSDKTestApp` folders. +Clone the git repository -Alternatively, you can use the Terminal application to open the project in Android Studio. Open your Terminal application, navigate to this repository's root folder, and run the `make aproj` command. +```bash +git clone git@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++-4.9 or later +- [Node.js](https://nodejs.org/) +- [ccache](https://ccache.samba.org/) (optional) + +**Note**: We partially support C++14 because GCC 4.9 does not fully implement the +final draft of the C++14 standard. More information in [DEVELOPING.md](DEVELOPING.md). + +**Note**: On macOS you can install clang with installing the [Apple command line developer tools](https://developer.apple.com/download/). + +### Opening the project + +#### macOS + +Execute the following command in this repository's root folder to generate the required build files and open the project with Android Studio: + +``` +make aproj +``` + +#### linux + +run `make android-configuration` in the root folder of the project and open the Android Studio project in `/platform/android`. + +### Project configuration + +#### Setup Checkstyle + +Mapbox uses specific IDE settings related to code and check style. +See [checkstyle guide](https://github.com/mapbox/mapbox-gl-native/wiki/Setting-up-Mapbox-checkstyle) for configuration details. + +##### 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/)._ + +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 environment variable wasn't set, you can edit `developer-config.xml` manually and add your access token to the `mapbox_access_token` resource. + +### Running project + +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`. + +More information about building and distributing this project in [DISTRIBUTE.md](https://github.com/mapbox/mapbox-gl-native/blob/master/platform/android/DISTRIBUTE.md). + +### Additional resources #### Using the SDK snapshot @@ -30,9 +90,9 @@ Instead of using the latest stable release of the Mapbox Android SDK, you can us ```java // Mapbox SDK dependency - compile('com.mapbox.mapboxsdk:mapbox-android-sdk:5.2.0-SNAPSHOT@aar') { +compile('com.mapbox.mapboxsdk:mapbox-android-sdk:5.2.0-SNAPSHOT@aar') { transitive = true - } +} ``` You need to have the section below in your build.gradle root folder to be able to resolve the SNAPSHOT dependencies: ``` @@ -44,86 +104,8 @@ allprojects { } ``` -### 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.** - -#### 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++-4.9 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) - -**Note**: We partially support C++14 because GCC 4.9 does not fully implement the -final draft of the C++14 standard. More information in [DEVELOPING.md](DEVELOPING.md). - -##### 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`) - - -##### macOS - -Execute the following to generate the required build files and open the project with Android Studio: - -``` -make aproj -``` - -##### linux - -Open Android Studio project in `/platform/android`, run `make android-configuration` in the root folder of the project. - -##### Setup Checkstyle - -Mapbox uses specific IDE settings related to code and check style. -See [checkstyle guide](https://github.com/mapbox/mapbox-gl-native/wiki/Setting-up-Mapbox-checkstyle) for configuration details. - -##### 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/)._ - -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. - -#### Running project - -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`. - -More information about building and distributing this project in [DISTRIBUTE.md][https://github.com/mapbox/mapbox-gl-native/blob/master/platform/android/DISTRIBUTE.md]. #### Symbolicating native crashes -When hitting native crashes you can use ndk-stack to symbolicate crashes. +When hitting native crashes you can use ndk-stack to symbolicate crashes. More information in [this](https://github.com/mapbox/mapbox-gl-native/wiki/Getting-line-numbers-from-an-Android-crash-with-ndk-stack) guide.