[docs] Recreate structure of documentation

11 files changed, 357 insertions, 0 deletions

diff --git a/docs/ANDROID_DEVICE.md b/docs/ANDROID_DEVICE.md
new file mode 100644
index 0000000000..c10e2580c0
--- /dev/null
+++ b/docs/ANDROID_DEVICE.md
@@ -0,0 +1,7 @@
+# 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
new file mode 100644
index 0000000000..98959f298c
--- /dev/null
+++ b/docs/ANDROID_SIMULATOR.md
@@ -0,0 +1,21 @@
+# 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/BUILD_IOS_OSX.md b/docs/BUILD_IOS_OSX.md
new file mode 100644
index 0000000000..6a43025201
--- /dev/null
+++ b/docs/BUILD_IOS_OSX.md
@@ -0,0 +1,92 @@
+# Building Mapbox GL Native for iOS
+
+This section is for people contributing to Mapbox GL directly in the context of their own app.
+
+### Build
+
+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/account/apps/)._
+
+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`
+   - `CoreTelephony.framework` (optional, telemetry-only)
+
+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/docs/DEVELOP_ANDROID_DISTRIBUTE.md b/docs/DEVELOP_ANDROID_DISTRIBUTE.md
new file mode 100644
index 0000000000..eb21979347
--- /dev/null
+++ b/docs/DEVELOP_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/docs/DEVELOP_ANDROID_LINUX.md b/docs/DEVELOP_ANDROID_LINUX.md
new file mode 100644
index 0000000000..d39e14c529
--- /dev/null
+++ b/docs/DEVELOP_ANDROID_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/account/apps/)._
+
+gradle will take the value of the `MAPBOX_ACCESS_TOKEN` environ variable and save it to `android/java/MapboxGLAndroidSDKTestApp/src/main/res/raw/token.txt` where the app will read it from.
+
+## Building
+
+Run:
+
+    make android
+
+You can then open `android/java` 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/docs/DEVELOP_ANDROID_OSX.md b/docs/DEVELOP_ANDROID_OSX.md
new file mode 100644
index 0000000000..1a55a1e396
--- /dev/null
+++ b/docs/DEVELOP_ANDROID_OSX.md
@@ -0,0 +1,35 @@
+# Developing for Android on OS X
+
+Install Oracle JDK 7+, the Android SDK, and Android Studio:
+
+    brew cask install java
+    brew install android-sdk
+    brew cask install android-studio
+    android
+
+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)
+
+By default, the SDK will be installed to `/usr/local/opt/android-sdk`. If you open Android Studio at this point, you may get an error message telling you that it can't find a JVM, it's because you installed a custom Java VM from Oracle. Follow [these instructions](http://tools.android.com/recent/androidstudio1rc3_releasecandidate3released) to start Android Studio. You'll wind up setting these environment variables in your .bash_profile or similar:
+
+    echo "export ANDROID_HOME=`brew --prefix android-sdk`" >> .bash_profile
+    echo "export ANDROID_NDK_PATH=`brew --cellar android-ndk`/r10e" >> .bash_profile
+    # Replace <path> with something like /Library/Java/JavaVirtualMachines/jdk1.8.0_31.jdk/Contents/Home
+    echo "export JAVA_HOME=<path>" >> .bash_profile
+    echo "export STUDIO_JDK=$JAVA_HOME" >> .bash_profile
+
+## 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/account/apps/)._
+
+gradle will take the value of the `MAPBOX_ACCESS_TOKEN` environ variable and save it to `android/java/MapboxGLAndroidSDKTestApp/src/main/res/raw/token.txt` where the app will read it from.
+
+Run:
+
+    make android
+    open -a Android\ Studio
+
+You can then open `android/java` 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/docs/DEVELOP_IOS_OSX.md b/docs/DEVELOP_IOS_OSX.md
new file mode 100644
index 0000000000..dbdb43cd0e
--- /dev/null
+++ b/docs/DEVELOP_IOS_OSX.md
@@ -0,0 +1,49 @@
+# Developing for iOS on OS X
+
+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.
+
+Developing for iOS implies an OS X host system.
+
+### Build
+
+Run
+
+    make iproj
+
+Which which will create and open an Xcode project which 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/account/apps/)._
+
+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 toggle debug info.
diff --git a/docs/DEVELOP_LINUX.md b/docs/DEVELOP_LINUX.md
new file mode 100644
index 0000000000..57f5592cd4
--- /dev/null
+++ b/docs/DEVELOP_LINUX.md
@@ -0,0 +1,58 @@
+# Linux
+
+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.
+
+The `zsh` will treat the * in this command as a glob, so you'll need to run
+`make "test-*"` instead.
+
+### Usage
+
+- Press `S` to cycle through bundled styles
+- Press `X` to reset the transform
+- Press `N` to reset north
+- Press `Tab` to toggle debug information
+- Press `C` to toggle symbol collision debug boxes
+- Press `Esc` to quit
+- Press `1` through `6` to add increasing numbers of point annotations for testing
diff --git a/docs/DEVELOP_NODE.md b/docs/DEVELOP_NODE.md
new file mode 100644
index 0000000000..7422a40a08
--- /dev/null
+++ b/docs/DEVELOP_NODE.md
@@ -0,0 +1,34 @@
+# 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
new file mode 100644
index 0000000000..6440014921
--- /dev/null
+++ b/docs/DEVELOP_OSX.md
@@ -0,0 +1,19 @@
+# Developing on OS X
+
+To create projects, you can run:
+
+- `make xproj`: Creates an Xcode project with OS X-specific handlers for HTTP downloads and settings storage. It uses [GLFW](http://www.glfw.org) for window handling.
+- `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 project.
+
+### 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/account/apps/)._
+
+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)
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 0000000000..9832b5da0a
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,5 @@
+# Troubleshooting
+
+To trigger a complete rebuild, run `make clean`.
+
+If you are having trouble getting the dependencies right, you can blow away the `mason_packages` directory, or run `make distclean`. This means the `Makefile` and configure script will automatically install the dependencies again on the next try.