diff options
| -rw-r--r-- | INSTALL.md | 22 | ||||
| -rw-r--r-- | README.md | 36 | ||||
| -rw-r--r-- | docs/ANDROID_DEVICE.md | 7 | ||||
| -rw-r--r-- | docs/ANDROID_SIMULATOR.md | 21 | ||||
| -rw-r--r-- | docs/DEVELOP_NODE.md | 34 | ||||
| -rw-r--r-- | docs/DEVELOP_OSX.md | 19 | ||||
| -rw-r--r-- | ios/README.md | 1 | ||||
| -rw-r--r-- | platform/android/DISTRIBUTE.md (renamed from docs/DEVELOP_ANDROID_DISTRIBUTE.md) | 0 | ||||
| -rw-r--r-- | platform/android/INSTALL_LINUX.md (renamed from docs/DEVELOP_ANDROID_LINUX.md) | 0 | ||||
| -rw-r--r-- | platform/android/INSTALL_OSX.md (renamed from docs/DEVELOP_ANDROID_OSX.md) | 2 | ||||
| -rw-r--r-- | platform/android/README.md | 46 | ||||
| -rw-r--r-- | platform/ios/DEVELOPING.md (renamed from docs/DEVELOP_IOS_OSX.md) | 14 | ||||
| -rw-r--r-- | platform/ios/INSTALL.md (renamed from docs/BUILD_IOS_OSX.md) | 14 | ||||
| -rw-r--r-- | platform/ios/README.md | 12 | ||||
| -rw-r--r-- | platform/linux/README.md (renamed from docs/DEVELOP_LINUX.md) | 2 | ||||
| -rw-r--r-- | platform/node/DEVELOPING.md | 29 | ||||
| -rw-r--r-- | platform/node/README.md | 7 | ||||
| -rw-r--r-- | platform/osx/DEVELOPING.md | 23 | ||||
| -rw-r--r-- | platform/osx/INSTALL.md (renamed from docs/BUILD_OSX.md) | 13 | ||||
| -rw-r--r-- | platform/osx/README.md | 10 |
20 files changed, 180 insertions, 132 deletions
diff --git a/INSTALL.md b/INSTALL.md index 9eee0e27ed..83fc54d620 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -51,20 +51,10 @@ dependencies: ## 3: Setting up a development environment & building -This depends on what operating systems you're using, and what platforms you're -developing for: +See the relevant SDK documentation for next steps: -**on OS X** - -* [For OS X on OS X](docs/DEVELOP_OSX.md) -* [For iOS on OS X](docs/DEVELOP_IOS_OSX.md) -* [For Android on OS X](docs/DEVELOP_ANDROID_OSX.md) - -**on Linux** - -* [For Linux on Linux](docs/DEVELOP_LINUX.md) -* [For Android on Linux](docs/DEVELOP_ANDROID_LINUX.md) - -**Node.js bindings** - -* [Developing Node.js bindings](docs/DEVELOP_NODE.md) +* [Mapbox Android SDK](platform/android/) +* [Mapbox iOS SDK](platform/ios/) +* [Mapbox OS X SDK](platform/osx/) +* [Mapbox GL Native on Linux](platform/linux/) +* [node-mapbox-gl-native](platform/node/) @@ -1,29 +1,23 @@ # Mapbox GL Native -[](https://travis-ci.org/mapbox/mapbox-gl-native/builds) [](https://www.bitrise.io/app/7514e4cf3da2cc57) +A library for embedding interactive vector maps into native applications on multiple platforms. It takes stylesheets that conform to the [Mapbox GL Style Specification](https://github.com/mapbox/mapbox-gl-style-spec/), applies them to vector tiles that conform to the [Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec), and renders them using OpenGL. [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is the WebGL-based counterpart, designed for use on the Web. -An OpenGL-based renderer for [Mapbox Vector Tiles](https://www.mapbox.com/blog/vector-tiles), consisting of a C++ library for Linux and SDK bindings for iOS, Android, Node.js, and OS X. +## The Mapbox GL ecosystem -**This repository is for development on Mapbox GL Native itself.** +This repository hosts the cross-platform Mapbox GL Native library, plus convenient SDKs for several platforms. The cross-platform library comes with a [GLFW](https://github.com/glfw/glfw)-based demo application for Ubuntu Linux and OS X. The SDKs target the usual languages on their respective platforms: -If you want to use products _based on_ Mapbox GL, check out: +SDK | Languages | Build status +----|-----------|------------- +[Mapbox GL Native](INSTALL.md) | C++14 | [](https://travis-ci.org/mapbox/mapbox-gl-native/builds) +[Mapbox Android SDK](platform/android/) | Java | [](https://www.bitrise.io/app/79cdcbdc42de4303) +[Mapbox iOS SDK](platform/ios/) | Objective-C or Swift | [](https://www.bitrise.io/app/7514e4cf3da2cc57) +[Mapbox OS X SDK](platform/osx/) | Objective-C or Swift | [](https://www.bitrise.io/app/155ef7da24b38dcd) +[node-mapbox-gl-native](platform/node/) | Node.js | [](https://travis-ci.org/mapbox/mapbox-gl-native/builds) -- [Mapbox Mobile](http://mapbox.com/mobile) — iOS and Android native development libraries -- [`mapbox-gl-native`](https://www.npmjs.com/package/mapbox-gl-native) - Node.js native module -- [`react-native-mapbox-gl`](https://github.com/mapbox/react-native-mapbox-gl) — React Native library -- [`qmapboxgl`](https://github.com/tmpsantos/qmapboxgl) — Qt library -- [`Mapbox Cordova Plugin`](http://plugins.telerik.com/cordova/plugin/mapbox) - Telerik's Apache Cordova plugin +Additional Mapbox GL Native–based libraries are developed outside of this repository: --- +* [React Native Mapbox GL](https://github.com/mapbox/react-native-mapbox-gl) for React Native applications on iOS and Android +* [QMapboxGL](https://github.com/tmpsantos/qmapboxgl) for Qt-based applications +* Telerik’s [Mapbox plugin](http://plugins.telerik.com/cordova/plugin/mapbox) for Apache Cordova applications -## Targets - -* Ubuntu Linux -* OS X 10.10+ -* iOS 7.0+ - * iPhone 4S and above (5, 5c, 5s, 6, 6 Plus) - * iPad 2 and above (3, 4, Mini, Air, Mini 2, Air 2) - * iPod touch 5th gen and above -* Android 4.0.3+ (API level 15+) - -See [`INSTALL.md`](./INSTALL.md) for development setup and install instructions, including dependencies. +If your platform or hybrid application framework isn’t listed here, consider embedding [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) using the standard Web capabilities on your platform. diff --git a/docs/ANDROID_DEVICE.md b/docs/ANDROID_DEVICE.md deleted file mode 100644 index c10e2580c0..0000000000 --- a/docs/ANDROID_DEVICE.md +++ /dev/null @@ -1,7 +0,0 @@ -# Running Mapbox GL Native on a hardware Android 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 up, double check the [Google documentation](http://developer.android.com/tools/device.html). diff --git a/docs/ANDROID_SIMULATOR.md b/docs/ANDROID_SIMULATOR.md deleted file mode 100644 index 98959f298c..0000000000 --- a/docs/ANDROID_SIMULATOR.md +++ /dev/null @@ -1,21 +0,0 @@ -# Setting up Android emulator - -If you want to run the test app in the emulator, we recommend the x86 build because it will run a lot faster. - -First ensure you have an `MAPBOX_ACCESS_TOKEN` environment variable set, as described below. Then, create an x86 build: - - make android-lib-x86 - -In Android Studio, create an x86 AVD (Android Virtual Device): - -- 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. diff --git a/docs/DEVELOP_NODE.md b/docs/DEVELOP_NODE.md deleted file mode 100644 index 7422a40a08..0000000000 --- a/docs/DEVELOP_NODE.md +++ /dev/null @@ -1,34 +0,0 @@ -# Developing the Mapbox GL Native Node Module - -**Just want to use the module? You can install it via npm without doing any of -this:** -``` -npm install mapbox-gl-native -``` - -This repository contains the bindings from the C++ core of Mapbox GL Native -to [Node.js](https://nodejs.org/). To develop these bindings, -you'll need to build them from source. Building requires installing all of the basic -dependencies needed for Mapbox GL Native, then running: - - npm install --build-from-source - -From the root directory. This will compile the Node.js bindings and install module dependencies. - -To recompile just the C++ code while developing, run `make node`. - -To create an Xcode project and use a GUI debugger in the case of a crash, run `make xnode`. - -## Testing - -To test the Node.js bindings: - -``` -npm test -``` - -To run the visual render test suite: - -``` -npm run test-suite -``` diff --git a/docs/DEVELOP_OSX.md b/docs/DEVELOP_OSX.md deleted file mode 100644 index 4b30a1e94a..0000000000 --- a/docs/DEVELOP_OSX.md +++ /dev/null @@ -1,19 +0,0 @@ -# Developing on OS X - -To create projects, you can run: - -- `make xproj`: Creates an Xcode project with a native OS X application for testing changes to mapbox-gl-native on the desktop. -- `make lproj`: Creates an Xcode project with platform-independent handlers for downloads and settings storage. This is what is also being built on Linux. -- `make osx run-osx`: Builds and runs the OS X application on the command line with `xcodebuild`. - -Note that you can't have more than one project in Xcode open at a time because the static library project is shared across the OS X, Linux, and iOS projects. - -### Access tokens - -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/). You will be prompted for this access token the first time you launch the demo application. - -### Usage - -Through the OS X SDK, the demo application supports a variety of standard gestures and keyboard shortcuts. For more details, open Mapbox GL Help from the Help menu. - -You can also [integrate the Mapbox OS X SDK into your own Cocoa application](BUILD_OSX.md). diff --git a/ios/README.md b/ios/README.md new file mode 100644 index 0000000000..a5ee2d37e5 --- /dev/null +++ b/ios/README.md @@ -0,0 +1 @@ +The Mapbox iOS SDK is [located here](../platform/ios/). diff --git a/docs/DEVELOP_ANDROID_DISTRIBUTE.md b/platform/android/DISTRIBUTE.md index eb21979347..eb21979347 100644 --- a/docs/DEVELOP_ANDROID_DISTRIBUTE.md +++ b/platform/android/DISTRIBUTE.md diff --git a/docs/DEVELOP_ANDROID_LINUX.md b/platform/android/INSTALL_LINUX.md index 219bb7d0e9..219bb7d0e9 100644 --- a/docs/DEVELOP_ANDROID_LINUX.md +++ b/platform/android/INSTALL_LINUX.md diff --git a/docs/DEVELOP_ANDROID_OSX.md b/platform/android/INSTALL_OSX.md index 30462a0df7..f82bb80da0 100644 --- a/docs/DEVELOP_ANDROID_OSX.md +++ b/platform/android/INSTALL_OSX.md @@ -1,4 +1,4 @@ -# Developing for Android on OS X +# Installing the Mapbox Android SDK on OS X Install Oracle JDK 7+ and Android Studio: diff --git a/platform/android/README.md b/platform/android/README.md new file mode 100644 index 0000000000..891fe74a53 --- /dev/null +++ b/platform/android/README.md @@ -0,0 +1,46 @@ +# [Mapbox Android SDK](https://www.mapbox.com/android-sdk/) + +[](https://www.bitrise.io/app/79cdcbdc42de4303) + +A library based on [Mapbox GL Native](../../README.md) for embedding interactive vector maps into Java applications on Android devices. + +This repository is for day-to-day development of the SDK. Building the SDK yourself requires [a number of dependencies and steps](../../INSTALL.md) that are unnecessary for developing production applications. For production applications, please consider installing an official, prebuilt release instead; see the [Mapbox Android SDK website](https://www.mapbox.com/android-sdk/) for installation instructions. + +## Installing the SDK + +* [Installing the Mapbox Android SDK on Linux](INSTALL_LINUX.md) +* [Installing the Mapbox Android SDK on OS X](INSTALL_OSX.md) + +## Setting up the Android emulator + +The Mapbox Android SDK requires Android 4.0.3+ (API level 15+). + +If you want to run the test app in the emulator, we recommend the x86 build because it will run a lot faster. + +First ensure you have an `MAPBOX_ACCESS_TOKEN` environment variable set, as described below. Then, create an x86 build: + + make android-lib-x86 + +In Android Studio, create an x86 AVD (Android Virtual Device): + +- 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. + +## Running Mapbox GL Native on a hardware Android device + +The Mapbox Android SDK requires Android 4.0.3+ (API level 15+). + +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 up, double check the [Google documentation](http://developer.android.com/tools/device.html). diff --git a/docs/DEVELOP_IOS_OSX.md b/platform/ios/DEVELOPING.md index 9cc27bc581..c8445aade3 100644 --- a/docs/DEVELOP_IOS_OSX.md +++ b/platform/ios/DEVELOPING.md @@ -1,16 +1,14 @@ -# Developing for iOS on OS X +# Contributing to the Mapbox iOS SDK -This process gives you a native iOS app for testing changes to mapbox-gl-native -on a simulator or device. Normally production use of the library is via a -precompiled binary linked into the app target: this process instead compiles -Mapbox GL Native from source along with your application, so it can include -latest development and your own modifications. +This document explains how to build the Mapbox iOS SDK and the osxapp demo application for the purpose of developing the SDK itself. -Developing for iOS implies an OS X host system. +### Requirements + +The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK and require Xcode on a computer running OS X. ### Build -Run +[Install core dependencies](../../INSTALL.md), then run make iproj diff --git a/docs/BUILD_IOS_OSX.md b/platform/ios/INSTALL.md index e605ce7ff0..f3afaea822 100644 --- a/docs/BUILD_IOS_OSX.md +++ b/platform/ios/INSTALL.md @@ -1,9 +1,19 @@ -# Building Mapbox GL Native for iOS +# Integrating the Mapbox iOS SDK into your application -This section is for people contributing to Mapbox GL directly in the context of their own app. +This document explains how to build a development version of Mapbox iOS SDK for the purpose of incorporating it into your own Cocoa Touch application. + +### Requirements + +The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK. They are intended to run on iOS 7.0 and above on the following devices and their simulators: + +* iPhone 4S and above (5, 5c, 5s, 6, 6 Plus) +* iPad 2 and above (3, 4, Mini, Air, Mini 2, Air 2) +* iPod touch 5th generation and above ### Build +1. [Install core dependencies](../../INSTALL.md). + 1. Install [appledoc](http://appledoc.gentlebytes.com/appledoc/) for API docs generation. ``` diff --git a/platform/ios/README.md b/platform/ios/README.md new file mode 100644 index 0000000000..a6752c61e6 --- /dev/null +++ b/platform/ios/README.md @@ -0,0 +1,12 @@ +# [Mapbox iOS SDK](https://www.mapbox.com/ios-sdk/) + +[](https://www.bitrise.io/app/7514e4cf3da2cc57) + +A library based on [Mapbox GL Native](../../README.md) for embedding interactive vector maps into Cocoa Touch applications on iOS 7.0 and above using Objective-C, Swift, or Interface Builder. + +This repository is for day-to-day development of the SDK. Building the SDK yourself requires [a number of dependencies and steps](../../INSTALL.md) that are unnecessary for developing production applications. For production applications, please consider installing an official, prebuilt release instead; see the [Mapbox iOS SDK website](https://www.mapbox.com/ios-sdk/) for installation instructions. + +* [Integrating the Mapbox iOS SDK into your application](INSTALL.md) +* [Contributing to the Mapbox iOS SDK](DEVELOPING.md) + + diff --git a/docs/DEVELOP_LINUX.md b/platform/linux/README.md index 21ed40f07c..55f3e71dba 100644 --- a/docs/DEVELOP_LINUX.md +++ b/platform/linux/README.md @@ -1,5 +1,7 @@ # Linux +A simple map application and test suite for Linux based on [Mapbox GL Native](../../README.md) and [GLFW](https://github.com/glfw/glfw). + We are using Ubuntu for development. While the software should work on other distributions as well, we are not providing explicit build instructions here. This process gives you a Linux desktop app built on a Linux host system. diff --git a/platform/node/DEVELOPING.md b/platform/node/DEVELOPING.md new file mode 100644 index 0000000000..cd03fa6ca3 --- /dev/null +++ b/platform/node/DEVELOPING.md @@ -0,0 +1,29 @@ +# Developing the Mapbox GL Native Node.js module + +This document explains how to build the [Node.js](https://nodejs.org/) bindings for [../../README.md](Mapbox GL Native) for contributing to the development of the bindings themselves. If you just want to use the module, you can simply install it via `npm`; see [README.md](README.md) for installation and usage instructions. + +## Building + +To develop these bindings, you’ll need to build them from source. Building requires [installing all of the basic dependencies needed for Mapbox GL Native](../../INSTALL.md), then running: + + npm install --build-from-source + +From the root directory. This will compile the Node.js bindings and install module dependencies. + +To recompile just the C++ code while developing, run `make node`. + +To create an Xcode project and use a GUI debugger in the case of a crash, run `make xnode`. + +## Testing + +To test the Node.js bindings: + +``` +npm test +``` + +To run the visual render test suite: + +``` +npm run test-suite +``` diff --git a/platform/node/README.md b/platform/node/README.md index 3c935b9b3c..58caec4fda 100644 --- a/platform/node/README.md +++ b/platform/node/README.md @@ -1,6 +1,7 @@ # node-mapbox-gl-native -[](https://npmjs.org/package/mapbox-gl-native) +[](https://npmjs.org/package/mapbox-gl-native) +[](https://travis-ci.org/mapbox/mapbox-gl-native/builds) ## Installing @@ -245,3 +246,7 @@ map.render({}, function(err, image) { }); ``` + +## Contributing + +See [DEVELOPING.md](DEVELOPING.md) for instructions on building this module for development. diff --git a/platform/osx/DEVELOPING.md b/platform/osx/DEVELOPING.md new file mode 100644 index 0000000000..3233b6302c --- /dev/null +++ b/platform/osx/DEVELOPING.md @@ -0,0 +1,23 @@ +# Contributing to the Mapbox OS X SDK + +This document explains how to build the Mapbox OS X SDK for contributing to the development of the SDK itself. + +### Requirements + +The Mapbox OS X SDK and the osxapp demo application run on OS X 10.10.0 and above. + +### Build + +1. [Install core dependencies](../../INSTALL.md). +1. Run `make xproj`. +1. Switch to the osxsdk or osxapp scheme. The former builds just the Cocoa framework, while the latter also builds a Cocoa demo application based on it. + +### Access tokens + +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/). You will be prompted for this access token the first time you launch the demo application. + +### Usage + +Through the OS X SDK, the demo application supports a variety of standard gestures and keyboard shortcuts. For more details, open Mapbox GL Help from the Help menu. + +You can also [integrate the Mapbox OS X SDK into your own Cocoa application](INSTALL.md). diff --git a/docs/BUILD_OSX.md b/platform/osx/INSTALL.md index 0d3c685f41..4016c360c6 100644 --- a/docs/BUILD_OSX.md +++ b/platform/osx/INSTALL.md @@ -1,9 +1,14 @@ -# Building Mapbox GL Native for OS X +# Integrating the Mapbox OS X SDK into your application -This project provides an OS X SDK analogous to the Mapbox iOS SDK. Mapbox does not officially support it to the same extent as the iOS SDK; however, bug reports and pull requests are certainly welcome. This document explains how to build the OS X SDK and integrate it into your own Cocoa application. +This document explains how to build the Mapbox OS X SDK and integrate it into your own Cocoa application. + +### Requirements + +The Mapbox OS X SDK requires the OS X 10.10.0 SDK or above. ### Build +1. [Install core dependencies](../../INSTALL.md). 1. Run `make xpackage`, which produces a `Mapbox.framework` in the `gyp/build/Release/` folder. ### Install @@ -16,6 +21,10 @@ This project provides an OS X SDK analogous to the Mapbox iOS SDK. Mapbox does n 1. In a XIB or storyboard, add a Custom View and set its custom class to `MGLMapView`. If you need to manipulate the map view programmatically, import the `Mapbox` module (Swift) or `Mapbox.h` umbrella header (Objective-C). +## Use + +The [Mapbox iOS SDK’s API documentation](https://www.mapbox.com/ios-sdk/api/3.0.1/) applies to the Mapbox OS X SDK with few differences, mostly around unimplemented features like user location tracking. + ## Troubleshooting You can also try clearing the Xcode cache with `make clear_xcode_cache`. diff --git a/platform/osx/README.md b/platform/osx/README.md new file mode 100644 index 0000000000..d96ae4947f --- /dev/null +++ b/platform/osx/README.md @@ -0,0 +1,10 @@ +# Mapbox OS X SDK + +[](https://www.bitrise.io/app/155ef7da24b38dcd) + +A library based on [Mapbox GL Native](../../README.md) for embedding interactive vector maps into Cocoa applications on OS X 10.10.0 and above using Objective-C, Swift, or Interface Builder. + +This SDK is analogous to the Mapbox iOS SDK, and much of the iOS SDK documentation applies here. Mapbox does not officially support the OS X to the same extent as the iOS SDK; however, bug reports and pull requests are certainly welcome. + +* [Integrating the Mapbox OS X SDK into your application](INSTALL.md) +* [Contributing to the Mapbox OS X SDK](DEVELOPING.md) |