Rewrote documentation

Rewrote some copy to provide more context and link to more GL-related repos, including GL JS. Put the various SDKs in a table so we can show the various CI bot status images.

Integrated target list into the relevant documents. Rewrote large portions of iOS and OS X setup documentation to guide normal developers to more friendly places. Combined some Android documentation.

Moved SDK-specific documentation into platform/. Added a temporary readme in ios/ that points to the one in platform/ios/.

13 files changed, 462 insertions, 1 deletions

diff --git a/platform/android/DISTRIBUTE.md b/platform/android/DISTRIBUTE.md
new file mode 100644
index 0000000000..eb21979347
--- /dev/null
+++ b/platform/android/DISTRIBUTE.md
@@ -0,0 +1,3 @@
+# Distributing Mapbox GL Native for Android
+
+Use the `Makefile` target `make apackage` in order to build JNI libraries for all supported ABI's for eventual distribution of the whole package.
diff --git a/platform/android/INSTALL_LINUX.md b/platform/android/INSTALL_LINUX.md
new file mode 100644
index 0000000000..219bb7d0e9
--- /dev/null
+++ b/platform/android/INSTALL_LINUX.md
@@ -0,0 +1,34 @@
+# Developing for Android on Linux
+
+Install a build dependencies:
+
+    apt-get install -y make git build-essential automake \
+    libtool make cmake pkg-config lib32stdc++6 lib32z1
+
+Install [Oracle JDK 7 (requires license agreement)](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html)
+
+    export JAVA_HOME="/dir/to/jdk1.7.0_71"
+
+Install the Android SDK. We recommend doing this by way of [Android Studio](https://developer.android.com/sdk/installing/studio.html).
+
+    export ANDROID_HOME="/dir/to/android-sdk-linux"
+
+In the Android SDK Manager also select and install "Android Support Repository" and "Android Support Library" from "Extras":
+
+![image](https://cloud.githubusercontent.com/assets/98601/9915837/289f398e-5c6e-11e5-9a84-ed4d08d52d1f.png)
+
+## 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 `"MapboxGLAndroidSDKTestApp/src/main/res/values/developer-config.xml` where the app will read it from.
+
+## Building
+
+Run:
+
+    make android
+
+You can then open `android` in Android Studio via "Import project (Eclipse ADT, Gradle, etc.)".
+
+**Next: get your app [running on a hardware Android Device](docs/ANDROID_DEVICE.md) or [simulator](docs/ANDROID_SIMULATOR.md)**
diff --git a/platform/android/INSTALL_OSX.md b/platform/android/INSTALL_OSX.md
new file mode 100644
index 0000000000..f82bb80da0
--- /dev/null
+++ b/platform/android/INSTALL_OSX.md
@@ -0,0 +1,67 @@
+# Installing the Mapbox Android SDK on OS X
+
+Install Oracle JDK 7+ and Android Studio:
+
+    brew tap caskroom/cask
+    brew install brew-cask
+    brew cask install java
+
+    brew cask install android-studio
+
+You can [download Android Studio instead of installing it with Homebrew, but you'll still need to `brew install java`](https://developer.android.com/sdk/index.html)
+for it to work.
+
+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.
+
+## 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`.
+
+## 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](docs/ANDROID_DEVICE.md) or [simulator](docs/ANDROID_SIMULATOR.md)**
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/)
+
+[![Bitrise](https://www.bitrise.io/app/79cdcbdc42de4303.svg?token=_InPF8bII6W7J6kFr-L8QQ&branch=master)](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/platform/ios/DEVELOPING.md b/platform/ios/DEVELOPING.md
new file mode 100644
index 0000000000..c8445aade3
--- /dev/null
+++ b/platform/ios/DEVELOPING.md
@@ -0,0 +1,47 @@
+# Contributing to the Mapbox iOS SDK
+
+This document explains how to build the Mapbox iOS SDK and the osxapp demo application for the purpose of developing the SDK itself.
+
+### 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
+
+[Install core dependencies](../../INSTALL.md), then run
+
+    make iproj
+
+Which will create and open an Xcode project that 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.
+
+### 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/)._
+
+Set up the access token by editing the scheme for the application target, then adding an environment variable with the name `MAPBOX_ACCESS_TOKEN`.
+
+![edit scheme](https://cloud.githubusercontent.com/assets/98601/5460702/c4610262-8519-11e4-873a-8597821da468.png)
+
+![setting access token in Xcode scheme](https://cloud.githubusercontent.com/assets/162976/5349358/0a086f00-7f8c-11e4-8433-bdbaccda2b58.png)
+
+### Test
+
+Run
+
+    make itest
+
+To run the included integration tests on the command line.
+
+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.
+
+### Usage
+
+- Pan to move
+- Pinch to zoom
+- Use two fingers to rotate
+- Double-tap to zoom in one level
+- Two-finger single-tap to zoom out one level
+- Double-tap, long-pressing the second, then pan up and down to "quick zoom" (iPhone only, meant for one-handed use)
+- Use the debug menu to add test annotations, reset position, and cycle through the debug options.
diff --git a/platform/ios/INSTALL.md b/platform/ios/INSTALL.md
new file mode 100644
index 0000000000..f3afaea822
--- /dev/null
+++ b/platform/ios/INSTALL.md
@@ -0,0 +1,101 @@
+# Integrating the Mapbox iOS SDK into your application
+
+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.
+
+   ```
+   curl -L -o appledoc.zip https://github.com/tomaz/appledoc/releases/download/v2.2-963/appledoc.zip
+   unzip appledoc.zip
+   cp appledoc /usr/local/bin
+   cp -Rf Templates/ ~/.appledoc
+   ```
+
+1. Run `make ipackage`. The packaging script will produce the statically-linked `libMapbox.a`, `Mapbox.bundle` for resources, a `Headers` folder, and a `Docs` folder with HTML API documentation.
+
+### 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/)._
+
+Set up the access token by editing the scheme for the application target, then adding an environment variable with the name `MAPBOX_ACCESS_TOKEN`.
+
+![edit scheme](https://cloud.githubusercontent.com/assets/98601/5460702/c4610262-8519-11e4-873a-8597821da468.png)
+
+![setting access token in Xcode scheme](https://cloud.githubusercontent.com/assets/162976/5349358/0a086f00-7f8c-11e4-8433-bdbaccda2b58.png)
+
+### Test
+
+In the context of your own app, you can now either:
+
+#### CocoaPods
+
+Currently, until [#1437](https://github.com/mapbox/mapbox-gl-native/issues/1437) is completed, to install a _development version_ of Mapbox GL using CocoaPods you will need to build it from source manually per above.
+
+1. Zip up the build product.
+
+    ```
+    cd build/ios/pkg/static
+    ZIP=mapbox-ios-sdk.zip
+    rm -f ../${ZIP}
+    zip -r ../${ZIP} *
+    ```
+
+1. Modify a custom `Mapbox-iOS-SDK.podspec` to download this zip file.
+
+    ```rb
+    {...}
+
+    m.source = {
+        :http => "http://{...}/mapbox-ios-sdk.zip",
+        :flatten => true
+    }
+
+    {...}
+    ```
+
+1. Update your app's `Podfile` to point to the `Mapbox-iOS-SDK.podspec`.
+
+    ```rb
+    pod 'Mapbox-iOS-SDK', :podspec => 'http://{...}/Mapbox-iOS-SDK.podspec'
+    ```
+
+1. Run `pod update` to grab the newly-built library.
+
+#### Binary
+
+1. Built from source manually per above.
+
+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.
+   - `Mapbox.bundle` is in your target's *Copy Bundle Resources* build phase.
+   - `libMapbox.a` is in your target's *Link Binary With Libraries* build phase.
+
+1. Add the following Cocoa framework dependencies to your target's *Link Binary With Libraries* build phase:
+
+   - `GLKit.framework`
+   - `ImageIO.framework`
+   - `MobileCoreServices.framework`
+   - `QuartzCore.framework`
+   - `SystemConfiguration.framework`
+   - `libc++.dylib`
+   - `libsqlite3.dylib`
+   - `libz.dylib`
+
+1. Add `-ObjC` to your target's "Other Linker Flags" build setting (`OTHER_LDFLAGS`).
+
+## Troubleshooting
+
+On OS X, you can also try clearing the Xcode cache with `make clear_xcode_cache`.
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/)
+
+[![Bitrise](https://www.bitrise.io/app/7514e4cf3da2cc57.svg?token=OwqZE5rSBR9MVWNr_lf4sA&branch=master)](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)
+
+![](../../ios/screenshot.png)
diff --git a/platform/linux/README.md b/platform/linux/README.md
new file mode 100644
index 0000000000..55f3e71dba
--- /dev/null
+++ b/platform/linux/README.md
@@ -0,0 +1,54 @@
+# 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.
+
+### Build
+
+Install GCC 4.9+ if you are running Ubuntu 14.04 or older. Alternatively, you can also use [Clang 3.5+](http://llvm.org/apt/).
+
+    sudo add-apt-repository --yes ppa:ubuntu-toolchain-r/test
+    sudo apt-get update
+    sudo apt-get install gcc-4.9 g++-4.9
+    export CXX=g++-4.9
+
+Ensure you have git and other build essentials:
+
+    sudo apt-get install curl git build-essential zlib1g-dev automake \
+                         libtool xutils-dev make cmake pkg-config python-pip \
+                         libcurl4-openssl-dev libpng-dev libsqlite3-dev \
+                         libllvm3.4
+
+Install glfw3 dependencies:
+
+    sudo apt-get install libxi-dev libglu1-mesa-dev x11proto-randr-dev \
+                         x11proto-xext-dev libxrandr-dev \
+                         x11proto-xf86vidmode-dev libxxf86vm-dev \
+                         libxcursor-dev libxinerama-dev
+
+Set the environment variable `MAPBOX_ACCESS_TOKEN` to your [Mapbox access token](ACCESS_TOKEN.md):
+
+    export MAPBOX_ACCESS_TOKEN=MYTOKEN
+
+Then, you can then proceed to build the library:
+
+    git submodule update --init
+    make linux
+
+Set an access token as described below, and then run:
+
+    make run-linux
+
+### Test
+
+- `make test-*` Builds and runs all tests. You can specify individual tests by replacing * with their name (e.g. `make test-Sprite.CustomSpriteImages`).
+
+The `zsh` will treat the * in this command as a glob, so you'll need to run
+`make "test-*"` instead.
+
+### Usage
+
+Keyboard shortcuts for testing functionality are logged to the console when the test app is started.
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
 
-[![NPM](https://nodei.co/npm/mapbox-gl-native.png)](https://npmjs.org/package/mapbox-gl-native)
+[![NPM](https://nodei.co/npm/mapbox-gl-native.png)](https://npmjs.org/package/mapbox-gl-native)  
+[![Travis](https://travis-ci.org/mapbox/mapbox-gl-native.svg?branch=master)](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/platform/osx/INSTALL.md b/platform/osx/INSTALL.md
new file mode 100644
index 0000000000..4016c360c6
--- /dev/null
+++ b/platform/osx/INSTALL.md
@@ -0,0 +1,30 @@
+# Integrating the Mapbox OS X SDK into your 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
+
+1. Copy `gyp/build/Release/Mapbox.framework` into your project.
+
+1. In the project editor, select your application target, go to the General tab, and add `Mapbox.framework` to the *Embedded Binaries* section.
+
+1. Mapbox vector tiles require a Mapbox account and API access token. In the project editor, select the application target. In the Info tab, set `MGLMapboxAccessToken` to your access token. You can obtain one from the [Mapbox account page](https://www.mapbox.com/studio/account/tokens/).
+
+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
+
+[![Bitrise](https://www.bitrise.io/app/155ef7da24b38dcd.svg?token=4KSOw_gd6WxTnvGE2rMttg&branch=master)](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)