tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* [android] - update project documentation

* add linux instructions
This commit is contained in:
Tobrun
2017-03-31 15:11:20 +02:00
committed by GitHub
parent 83d22a5bd4
commit 05992c47ac
4 changed files with 88 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
platform/android/CONTRIBUTING_LINUX.md
View File

@@ -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.

69
platform/android/CONTRIBUTING_MACOS.md
View File

@@ -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)**

43
platform/android/DISTRIBUTE.md
View File

@@ -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:

87
platform/android/README.md
View File

@@ -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
* [Contributing on Linux](CONTRIBUTING_LINUX.md)
* [Contributing on macOS](CONTRIBUTING_MACOS.md)
Clone the git repository
### Setting up the Android emulator
```bash
git clone https://github.com/mapbox/mapbox-gl-native.git
cd mapbox-gl-native
```
The Mapbox Android SDK requires Android 4.0.3+ (API level 15+).
#### Installing dependencies
If you want to run the test app in the emulator, we recommend the x86 build because it will run a lot faster.
These dependencies are required for all operating systems and all platform targets.
First ensure you have an `MAPBOX_ACCESS_TOKEN` environment variable set, as described below. Then, create an x86 build:
- 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
make android-lib-x86
- 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)
In Android Studio, create an x86 AVD (Android Virtual Device):
##### Additional Dependencies for Linux
- 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
_These instructions were tested on Ubuntu 16.04 LTS (aka Xenial Xerus)._
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.
```
$ sudo apt-get install -y build-essential curl lib32stdc++6 lib32z1 pkg-config python
```
### Running Mapbox GL Native on a hardware Android device
##### Additional Dependencies for macOS
The Mapbox Android SDK requires Android 4.0.3+ (API level 15+).
- Apple Command Line Tools (available at [Apple Developer](https://developer.apple.com/download/more/))
- [xcpretty](https://github.com/supermarin/xcpretty) (`gem install xcpretty`)
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.
#### Open project in Android Studio
If your device does not show up, double check the [Google documentation](http://developer.android.com/tools/device.html).
##### 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.
##### 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].