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

8 files changed, 78 insertions, 44 deletions

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