update readme

[skip ci]

1 files changed, 69 insertions, 58 deletions

diff --git a/README.md b/README.md
index ee9d1bacb0..b9a22d249a 100644
--- a/README.md
+++ b/README.md
@@ -6,114 +6,125 @@ implemented in C++11, currently targeting iOS, OS X, and Ubuntu Linux.
 # Depends
 
  - Modern C++ compiler that supports `-std=c++11` (On OS X clang++, on Linux g++-4.8 or g++-4.9)
- - Boost headers
- - `libpng`
- - `libuv`
- - `glfw3`
- - `libcurl` (depends on OpenSSL; Linux only)
+ - [Boost headers](http://boost.org/)
+ - [`zlib`](http://www.zlib.net/)
+ - [`libpng`](http://www.libpng.org/pub/png/libpng.html)
+ - [`libuv 0.10+`](https://github.com/joyent/libuv)
+ - [`glfw 3.1+`](http://www.glfw.org/)
+ - [`libcurl`](http://curl.haxx.se/libcurl/) (depends on OpenSSL; Linux only)
  - `libboost_regex` (Linux only)
  - Apple Command Line Tools (for build on OS X; available at [Apple Developer](https://developer.apple.com/downloads))
+ - `pkg-config` (for build only)
  - [Homebrew](http://brew.sh) (for build on OS X)
  - Python 2.x (for build only)
  - Node.js (for build only)
 
 # Build instructions
 
-We use [mapnik-packaging](https://github.com/mapnik/mapnik-packaging) to build static libraries of
-dependencies.
+We try to link to as many system-provided libraries as possible. When these are unavailable or too outdated, we run a thin build-script layer called [Mason](https://github.com/mapbox/mason) to automate builds, and load precompiled binary packages when possible.
 
-First off: if you hit problems during development try:
+## OS X
 
-    make clean
+On OS X, we are using `zlib`, `SQLite3`, `libcurl` and `libpng` provided by the operating system. In addition to that, you need to have the Boost headers installed. To install all prerequisites, use [Homebrew](http://brew.sh/) and type `brew install pkg-config boost`.
 
-This will clear cached build data and update to the latest versions of dependencies.
+To create projects, you can run:
 
-### Mapbox API access tokens
+- `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`.
+- `make linux run-linux`: Builds and runs the Linux application with `make`.
 
-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/). 
+Note that you can't have more than one project in Xcode open at a time since they the static library project is shared across the OS X, Linux and iOS project.
 
-For iOS and OS X use of the demo apps in Xcode, setup the access token by editing the scheme for the application target, then adding an environment variable with the name `MAPBOX_ACCESS_TOKEN`. 
+Target OS: 10.9+
 
-![edit scheme](https://cloud.githubusercontent.com/assets/98601/3647749/30f74f26-1102-11e4-84af-f1be853b4e38.png)
 
-![setting access token in Xcode scheme](https://cloud.githubusercontent.com/assets/52399/3543326/9e7cfbb8-0860-11e4-8def-3684a9028b61.png)
+## iOS
 
-## OS X
+iOS makes use of a Cocoa-specific API called [`mapbox-gl-cocoa`](https://github.com/mapbox/mapbox-gl-cocoa). If you are just interested in running Mapbox GL on iOS and not developing with it, head to that project and you can use this library as a pre-built static library instead. A `UIView` interface to the map view and bundle resources are provided there.
 
-Run:
+If you intend to develop here, `mapbox-gl-cocoa` is included as a submodule of the overall build setup.
 
-    make setup
+To pull down the submodule(s), run:
 
-This downloads all required dependencies, builds them and creates universal libraries that can be used on both OS X and iOS.
+    git submodule init
+    git submodule update
 
-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 linux`: Builds the Linux GLFW application with `make`.
+Then, you can run `make iproj` to create and open an Xcode project with an iOS-specific view controller housing. This will automatically install required dependencies as well.
 
-Note that if you are doing iOS development as well, to toggle from iOS back to OS X, you will need to `make xproj` again. 
+Note that if you are doing OS X development as well, to toggle from OS X back to iOS, you will need to `make iproj` again.
 
-Target OS: 10.9+
+Target devices: iPhone 4S and above (5, 5c, 5s, 6, 6 Plus) and iPad 2 and above (3, 4, Mini , Air, Mini 2, Air 2).
 
-## iOS
+Target OS: 7.0+
 
-iOS makes use of a Cocoa-specific API called [`mapbox-gl-cocoa`](https://github.com/mapbox/mapbox-gl-cocoa). If you are just interested in running Mapbox GL on iOS and not developing with it, head to that project and you can use this library as a pre-built static library instead. A `UIView` interface to the map view and bundle resources are provided there. 
+## Linux
 
-If you intend to develop here, `mapbox-gl-cocoa` is included as a submodule of the overall build setup. 
+We are using Ubuntu for development. While the software should work on other distributions as well, we are not providing explicit build instructions here.
 
-First, pull down the submodule(s): 
+Install GCC 4.8+ if you are running Ubuntu 13.10 or older. Alternatively, you can also use Clang 3.4+.
 
-    git submodule init
-    git submodule update
+	sudo add-apt-repository --yes ppa:ubuntu-toolchain-r/test
+	sudo apt-get update
+	sudo apt-get install gcc-4.8 g++-4.8
 
-Then run:
+Ensure you have git and other build essentials:
 
-    make setup
+    sudo apt-get install git build-essential zlib1g-dev automake \
+                         libtool xutils-dev make cmake pkg-config python-pip \
+                         libcurl4-openssl-dev libpng-dev libsqlite3-dev
 
-This downloads all required dependencies, builds them and creates universal libraries that can be used on both OS X and iOS.
+Install glfw3 dependencies:
 
-Lastly, `make iproj` to create and open an Xcode project with an iOS-specific view controller housing. 
+    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
 
-Note that if you are doing OS X development as well, to toggle from OS X back to iOS, you will need to `make iproj` again. 
+Finally, install Boost. If you're running Ubuntu 12.04 or older, you need to install a backport PPA since the version provided by APT doesn't contain Boost Geometry:
 
-Target devices: iPhone 4 and above (4S, 5, 5c, 5s) and iPad 2 and above (3, 4, mini and/or retina).
+	sudo add-apt-repository --yes ppa:boost-latest/ppa
+	sudo apt-get update
+	sudo apt-get install libboost1.55-dev libboost-regex1.55-dev
 
-Target OS: 7.0+
+Otherwise, you can just install
 
-## Ubuntu
+	sudo apt-get install libboost-dev libboost-regex-dev
 
-Set the environment variable `MAPBOX_ACCESS_TOKEN` to your token.
+Once you're done installing the build dependencies, you can get started by running
 
-Ensure you have git and other build essentials:
+	./configure
 
-    sudo apt-get update
-    sudo apt-get install git build-essential zlib1g-dev automake libtool xutils-dev make cmake pkg-config nodejs-legacy curl libuv-dev
+which downloads all other dependencies that we need to build manually with [Mason](https://github.com/mapbox/mason). There's a good chance that there already are binary files and that you don't need to compile anything.
 
-If you are running Ubuntu 13.10 or older, install a `-std=c++11` capable compiler:
+Then, you can then proceed to build the library like:
 
-    sudo add-apt-repository --yes ppa:ubuntu-toolchain-r/test
-    sudo apt-get update
-    sudo apt-get install gcc-4.8 g++-4.8
+    make mbgl
 
-Install glfw3 dependencies:
+Or proceed to building the debug application with:
 
-    sudo apt-get install libxi-dev libglu1-mesa-dev x11proto-randr-dev x11proto-xext-dev libxrandr-dev x11proto-xf86vidmode-dev libxxf86vm-dev libxcursor-dev
+	make linux
 
-Then run:
 
-    make setup
+# Troubleshooting
 
-This downloads all required dependencies, builds them and creates universal libraries that can be used on both OS X and iOS.
+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.
 
-You can then proceed to build the library like:
+# Mapbox API 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/).
+
+For iOS and OS X use of the demo apps in Xcode, setup 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/3647749/30f74f26-1102-11e4-84af-f1be853b4e38.png)
+
+![setting access token in Xcode scheme](https://cloud.githubusercontent.com/assets/52399/3543326/9e7cfbb8-0860-11e4-8def-3684a9028b61.png)
 
-    make linux
+For Linux, set the environment variable `MAPBOX_ACCESS_TOKEN` to your token.
 
 # Style
 
-Some styles in JSON format are included at `./styles`. See the [style spec](https://github.com/mapbox/mapbox-gl-style-spec) for more details. 
+Some styles in JSON format are included at `./styles`. See the [style spec](https://github.com/mapbox/mapbox-gl-style-spec) for more details.
 
 # Usage
 
@@ -136,4 +147,4 @@ Some styles in JSON format are included at `./styles`. See the [style spec](http
 
 # Other notes
 
-Under early development, this project was called LLMR (Low-Level Map Renderer), in case you see any lingering references to it. 
+Under early development, this project was called LLMR (Low-Level Map Renderer), in case you see any lingering references to it.