[docs] Make per-platform installation docs self-containedupstream/install.md

I've seen several issues where users followed platform-specific install docs, but were unaware of additional prerequisites spelled out in the top-level INSTALL.md. So let's try making each platform's installation documentation self contained.

9 files changed, 88 insertions, 95 deletions

diff --git a/INSTALL.md b/INSTALL.md
index e5d059e1bb..463d199d10 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,56 +1,15 @@
-# Building & Developing Mapbox GL Native from Source
+# Building & Developing from Source
 
-**Just trying to use Mapbox GL Native? You don't need to read this stuff! We
+**Just trying to use one of the Mapbox Maps SDKs? You don't need to read this stuff! We
 provide [easy-to-install, prebuilt versions of the Mapbox Maps SDKs for iOS and Android
 that you can download instantly and get started with fast](https://www.mapbox.com/install/).**
 
-Still with us? These are the instructions you'll need to build Mapbox GL Native
-from source on a variety of platforms and set up a development environment.
+If you're certain you need to build from source, rather than using a prebuilt SDK, please
+refer to the installation instructions for the platform of interest:
 
-Your journey will start with installing dependencies, then getting the source code, and
-then setting up a development environment, which varies depending on your
-operating system and what platform you want to develop for.
-
-## 1: Installing dependencies
-
-### macOS
-
- 1. Install [Xcode](https://developer.apple.com/xcode/)
- 2. Launch Xcode and install any updates
- 3. Install [Homebrew](http://brew.sh)
- 4. Install [Node.js](https://nodejs.org/), [CMake](https://cmake.org/), and [ccache](https://ccache.samba.org) with `brew install nodejs cmake ccache`
- 5. Install [xcpretty](https://github.com/supermarin/xcpretty) with `[sudo] gem install xcpretty` (optional, used for prettifying command line builds)
-
-### Linux
-
-Install the following:
-
- - `clang++` 3.5 or later or `g++` 4.9 or later
- - [git](https://git-scm.com/)
- - [CMake](https://cmake.org/) 3.1 or later
- - [cURL](https://curl.haxx.se)
- - [Node.js](https://nodejs.org/) 4.2.1 or later
- - [`libcurl`](http://curl.haxx.se/libcurl/) (depends on OpenSSL)
- - [ccache](https://ccache.samba.org) (optional, improves recompilation performance)
-
-## 2: Getting the source
-
- Clone the git repository:
-
-     git clone https://github.com/mapbox/mapbox-gl-native.git
-     cd mapbox-gl-native
-
-## 3: Setting up a development environment & building
-
-See the relevant SDK documentation for next steps:
-
-* [Maps SDK for Android](platform/android/)
-* [Maps SDK for iOS](platform/ios/)
-* [Maps SDK for macOS](platform/macos/)
-* [Maps SDK for Qt](platform/qt/)
-* [Mapbox GL Native on Linux](platform/linux/)
-* [node-mapbox-gl-native](platform/node/)
-
-## 4: Keeping up to date
-
-This repository uses Git submodules, which should be automatically checked out when you first run a `make` command for one of the above platforms. These submodules are not updated automatically and we recommended that you run `git submodule update` after pulling down new commits to this repository.
+* [Mapbox Maps SDK for Android](platform/android/README.md)
+* [Mapbox Maps SDK for iOS](platform/ios/INSTALL.md)
+* [Mapbox Maps SDK for macOS](platform/macos/INSTALL.md)
+* [Mapbox Maps SDK for Qt](platform/qt/README.md)
+* [Mapbox GL Native on Linux](platform/linux/README.md)
+* [node-mapbox-gl-native](platform/node/DEVELOPING.md)
diff --git a/platform/ios/DEVELOPING.md b/platform/ios/DEVELOPING.md
index b407e78e4b..34388c2589 100644
--- a/platform/ios/DEVELOPING.md
+++ b/platform/ios/DEVELOPING.md
@@ -4,14 +4,10 @@ This document explains how to build the Mapbox Maps SDK for iOS from source. It
 
 ## Requirements
 
-The Mapbox Maps SDK for iOS and iosapp demo application require iOS 9.0 or above.
-
-The Mapbox Maps SDK for iOS requires Xcode 9.1 or above to compile from source.
+See the "Requirements" section in [INSTALL.md](INSTALL.md).
 
 ## Building the SDK
 
-Make sure that you have the [core dependencies](../../INSTALL.md) installed.
-
 Create and open an Xcode workspace that includes both the SDK source and some Objective-C test applications by running:
 
 ```bash
diff --git a/platform/ios/INSTALL.md b/platform/ios/INSTALL.md
index f253d3019d..3c79e4dcf8 100644
--- a/platform/ios/INSTALL.md
+++ b/platform/ios/INSTALL.md
@@ -18,16 +18,34 @@ The Mapbox Maps SDK for iOS requires:
 * Xcode 9.1 or higher to compile from source
 * Xcode 8.0 or higher to integrate the compiled framework into an application
 
-### Building the SDK
-
-1. [Install core dependencies](../../INSTALL.md).
+Before building, follow these steps to install prerequisites:
 
+1. Install [Xcode](https://developer.apple.com/xcode/)
+1. Launch Xcode and install any updates
+1. Install [Homebrew](http://brew.sh)
+1. Install [Node.js](https://nodejs.org/), [CMake](https://cmake.org/), and [ccache](https://ccache.samba.org):
+   ```
+   brew install node cmake ccache
+   ```
+1. Install [xcpretty](https://github.com/supermarin/xcpretty) (optional, used for prettifying command line builds):
+   ```
+   [sudo] gem install xcpretty
+   ```
 1. Install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
-
    ```
    [sudo] gem install jazzy
    ```
 
+### Building the SDK
+
+1. Clone the git repository:
+   ```
+   git clone https://github.com/mapbox/mapbox-gl-native.git
+   cd mapbox-gl-native
+   ```
+   Note that this repository uses Git submodules. They'll be automatically checked out when you first run a `make` command,
+   but are not updated automatically. We recommended that you run `git submodule update` after pulling down new commits to
+   this repository.
 1. Run `make iframework BUILDTYPE=Release`. The packaging script will produce a `build/ios/pkg/` folder containing:
   - a `dynamic` folder containing a dynamically-linked fat framework with debug symbols for devices and the iOS Simulator
   - a `documentation` folder with HTML API documentation
diff --git a/platform/linux/README.md b/platform/linux/README.md
index 8b8ac9d089..a8a4d459ee 100644
--- a/platform/linux/README.md
+++ b/platform/linux/README.md
@@ -6,7 +6,7 @@ We are using Ubuntu for development. While the software should work on other dis
 
 This process gives you a Linux desktop app built on a Linux host system.
 
-### Build
+### Prerequisites
 
 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/).
 
@@ -15,9 +15,6 @@ Install GCC 4.9+ if you are running Ubuntu 14.04 or older. Alternatively, you ca
     sudo apt-get install gcc-4.9 g++-4.9
     export CXX=g++-4.9
 
-**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).
-
 Ensure you have git and other build essentials:
 
     sudo apt-get install curl git build-essential zlib1g-dev automake \
@@ -38,6 +35,21 @@ Install glfw3 dependencies:
                          x11proto-xf86vidmode-dev libxxf86vm-dev \
                          libxcursor-dev libxinerama-dev
 
+[Node.js](https://nodejs.org/) 4.2.1 or later is also required.
+
+[ccache](https://ccache.samba.org) is optional, but improves recompilation performance.
+
+## Build
+
+Clone the git repository:
+
+     git clone https://github.com/mapbox/mapbox-gl-native.git
+     cd mapbox-gl-native
+
+Note that this repository uses Git submodules. They'll be automatically checked out when you first run a `make` command,
+but are not updated automatically. We recommended that you run `git submodule update` after pulling down new commits to
+this repository.
+
 Set the environment variable `MAPBOX_ACCESS_TOKEN` to your [Mapbox access token](ACCESS_TOKEN.md):
 
     export MAPBOX_ACCESS_TOKEN=MYTOKEN
diff --git a/platform/macos/DEVELOPING.md b/platform/macos/DEVELOPING.md
index bac5683266..f4d946c527 100644
--- a/platform/macos/DEVELOPING.md
+++ b/platform/macos/DEVELOPING.md
@@ -4,24 +4,10 @@ This document explains how to build the Mapbox Maps SDK for macOS from source. I
 
 ## Requirements
 
-The Mapbox Maps SDK for macOS and the macosapp demo application run on macOS 10.10.0 or above.
-
-The Mapbox Maps SDK for macOS requires Xcode 8.0 or above.
+See the "Requirements" section in [INSTALL.md](INSTALL.md).
 
 ## Building the SDK
 
-1. [Install core dependencies](../../INSTALL.md).
-1. Run `make xproj`.
-1. Switch to the “dynamic” or “macosapp” scheme. The former builds just the Cocoa framework, while the latter also builds a Cocoa demo application based on it.
-
-### Packaging builds
-
-Install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
-
-```bash
-[sudo] gem install jazzy
-```
-
 Build and package the SDK by using one of the following commands:
 
 * `make xpackage` builds a dynamic framework in the Debug configuration, including debug symbols.
diff --git a/platform/macos/INSTALL.md b/platform/macos/INSTALL.md
index c723d3e062..f0fb0278be 100644
--- a/platform/macos/INSTALL.md
+++ b/platform/macos/INSTALL.md
@@ -6,19 +6,41 @@ This document explains how to build a development version of the Mapbox Maps SDK
 
 The Mapbox Maps SDK for macOS requires the macOS 10.10.0 SDK (or above) and Xcode 8.0 (or above). To use this SDK with Xcode 7.3.1, download and use a symbols build from the [releases](https://github.com/mapbox/mapbox-gl-native/releases) page.
 
-### Building the SDK from source
-
-To build the SDK from source:
-
-1. [Install core dependencies](../../INSTALL.md).
+Before building, follow these steps to install prerequisites:
 
+1. Install [Xcode](https://developer.apple.com/xcode/)
+1. Launch Xcode and install any updates
+1. Install [Homebrew](http://brew.sh)
+1. Install [Node.js](https://nodejs.org/), [CMake](https://cmake.org/), and [ccache](https://ccache.samba.org):
+   ```
+   brew install node cmake ccache
+   ```
+1. Install [xcpretty](https://github.com/supermarin/xcpretty) (optional, used for prettifying command line builds):
+   ```
+   [sudo] gem install xcpretty
+   ```
 1. Install [jazzy](https://github.com/realm/jazzy) for generating API documentation:
-
    ```
    [sudo] gem install jazzy
    ```
 
-1. Run `make xpackage`, which produces a `Mapbox.framework` in the `build/macos/pkg/` folder.
+### Building the SDK from source
+
+To build the SDK from source:
+
+1. Clone the git repository:
+   ```
+   git clone https://github.com/mapbox/mapbox-gl-native.git
+   cd mapbox-gl-native
+   ```
+   Note that this repository uses Git submodules. They'll be automatically checked out when you first run a `make` command,
+   but are not updated automatically. We recommended that you run `git submodule update` after pulling down new commits to
+   this repository.
+1. Run:
+   ```
+   make xpackage
+   ```
+   This produces a `Mapbox.framework` in the `build/macos/pkg/` folder.
 
 ### Installation
 
diff --git a/platform/node/DEVELOPING.md b/platform/node/DEVELOPING.md
index b313d75c13..215b06c7bf 100644
--- a/platform/node/DEVELOPING.md
+++ b/platform/node/DEVELOPING.md
@@ -4,11 +4,13 @@ This document explains how to build the [Node.js](https://nodejs.org/) bindings
 
 ## 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:
+To develop these bindings, you’ll need to build them from source. Building requires the prerequisites listed in either 
+the [macOS](../macos/INSTALL.md#requirements) or [Linux](../linux/README.md#prerequisites) install documentation, depending
+on the target platform.
 
-    npm install --build-from-source
+To compile the Node.js bindings and install module dependencies, from the repository root directory, run:
 
-From the root directory. This will compile the Node.js bindings and install module dependencies.
+    npm install --build-from-source
 
 To recompile just the C++ code while developing, run `make node`.
 
diff --git a/platform/node/README.md b/platform/node/README.md
index d19b2a9343..ac5bcd7e8d 100644
--- a/platform/node/README.md
+++ b/platform/node/README.md
@@ -17,7 +17,8 @@ Run:
 npm install @mapbox/mapbox-gl-native
 ```
 
-Other platforms will fall back to a source compile with `make node`; see INSTALL.md in the repository root directory for prequisites.
+Other platforms will fall back to a source compile with `make node`; see [DEVELOPING.md](DEVELOPING.md) for details on
+building from source.
 
 ## Testing
 
diff --git a/platform/qt/README.md b/platform/qt/README.md
index 018f8823b6..f083d4b519 100644
--- a/platform/qt/README.md
+++ b/platform/qt/README.md
@@ -17,9 +17,7 @@ See the Mapbox Qt landing page for more details: https://www.mapbox.com/qt/
 
 #### Linux
 
-For Linux (tested on Ubuntu) desktop, together with these [build
-instructions](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/linux#build),
-you also need:
+For Linux (tested on Ubuntu) desktop, together with these [build instructions](../linux/README.md), you also need:
 
 ```
 $ sudo apt-get install qt5-default
@@ -55,8 +53,7 @@ At runtime, you will also need installed:
 
 ### Build instructions
 
-Public API headers
-can be found in the [platform/qt/include](https://github.com/mapbox/mapbox-gl-native/tree/master/platform/qt/include) directory.
+Public API headers can be found in the [platform/qt/include](qt/include) directory.
 
 #### Linux and macOS