[ios] Strip Simulator content when archiving

Copied strip-frameworks.sh from realm/realm-cocoa@7cc31db631c323bb649aec1e311693a599a37f05 for realm/realm-cocoa#2759. This script, which is embedded in the dynamic framework, strips out content for invalid architectures from any embedded framework and specifically strips out Simulator content when archiving to work around an App Store bug.

Rewrote the iOS setup documentation. In particular, the MAPBOX_ACCESS_TOKEN environment variable is only for use with the iosapp demo application and doesn’t work in third-party applications.

7 files changed, 41 insertions, 16 deletions

diff --git a/platform/android/README.md b/platform/android/README.md
index 891fe74a53..135eb87a93 100644
--- a/platform/android/README.md
+++ b/platform/android/README.md
@@ -2,7 +2,7 @@
 
 [![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.
+A library based on [Mapbox GL Native](../../README.md) for embedding interactive map views with scalable, customizable 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.
 
diff --git a/platform/ios/DEVELOPING.md b/platform/ios/DEVELOPING.md
index c8445aade3..75ad15fdd5 100644
--- a/platform/ios/DEVELOPING.md
+++ b/platform/ios/DEVELOPING.md
@@ -1,6 +1,6 @@
 # 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.
+This document explains how to build the Mapbox iOS SDK from source. It is intended for advanced developers who wish to contribute to Mapbox GL and the Mapbox iOS SDK.
 
 ### Requirements
 
diff --git a/platform/ios/INSTALL.md b/platform/ios/INSTALL.md
index f77fc26e59..55f2f6b4c3 100644
--- a/platform/ios/INSTALL.md
+++ b/platform/ios/INSTALL.md
@@ -20,7 +20,11 @@ The Mapbox iOS SDK and iosapp demo application build against the iOS 7.0 SDK. Th
    [sudo] gem install jazzy
    ```
 
-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.
+1. Run `make ipackage`. The packaging script will produce a `build/ios/pkg/` folder containing:
+  - a `dynamic` folder containing a dynamically-linked fat framework
+  - a `static` folder containing a statically-linked framework
+  - a `documentation` folder with HTML API documentation
+  - an example `Settings.bundle` for providing the required Mapbox Metrics opt-out setting
 
 ### Install
 
@@ -33,13 +37,13 @@ Currently, until [#1437](https://github.com/mapbox/mapbox-gl-native/issues/1437)
 1. Zip up the build product.
 
     ```
-    cd build/ios/pkg/static
+    cd build/ios/pkg/
     ZIP=mapbox-ios-sdk.zip
     rm -f ../${ZIP}
     zip -r ../${ZIP} *
     ```
 
-1. Modify a custom `Mapbox-iOS-SDK.podspec` to download this zip file.
+1. Customize [`Mapbox-iOS-SDK.podspec`](../ios/Mapbox-iOS-SDK.podspec) to download this zip file.
 
     ```rb
     {...}
@@ -60,17 +64,31 @@ Currently, until [#1437](https://github.com/mapbox/mapbox-gl-native/issues/1437)
 
 1. Run `pod update` to grab the newly-built library.
 
-#### Binary
+#### Dynamic framework
 
-1. Built from source manually per above.
+This is the recommended workflow for manually integrating the SDK into an application targeting iOS 8 and above:
 
-1. Copy the contents of `build/ios/pkg/static` into your project. It should happen automatically, but ensure that:
+1. Build from source manually per above.
 
-   - `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. Open the project editor and select your application target. Drag `build/ios/pkg/dynamic/Mapbox.framework` into the “Embedded Binaries” section of the General tab. In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.
 
-1. Add the following Cocoa framework dependencies to your target's *Link Binary With Libraries* build phase:
+1. In the Build Phases tab, click the + button at the top and select “New Run Script Phase”. Enter the following code into the script text field:
+
+```bash
+bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Mapbox.framework/strip-frameworks.sh"
+```
+
+(The last step, courtesy of [Realm](https://github.com/realm/realm-cocoa/), is required for working around an [iOS App Store bug](http://www.openradar.me/radar?id=6409498411401216) when archiving universal binaries.)
+
+#### Static framework
+
+If your application targets iOS 7.x, you’ll need to install the static framework instead:
+
+1. Build from source manually per above.
+
+1. Open the project editor and select your application target. Drag `build/ios/pkg/static/Mapbox.framework` into the “Embedded Binaries” section of the General tab. In the sheet that appears, make sure “Copy items if needed” is checked, then click Finish.
+
+1. Add the following Cocoa Touch frameworks and libraries to the “Linked Frameworks and Libraries” section:
 
    - `GLKit.framework`
    - `ImageIO.framework`
@@ -81,7 +99,13 @@ Currently, until [#1437](https://github.com/mapbox/mapbox-gl-native/issues/1437)
    - `libsqlite3.dylib`
    - `libz.dylib`
 
-1. Add `-ObjC` to your target's "Other Linker Flags" build setting (`OTHER_LDFLAGS`).
+1. In the Build Settings tab, add `-ObjC` to the “Other Linker Flags” (`OTHER_LDFLAGS`) build setting.
+
+### Use
+
+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
 
diff --git a/platform/ios/README.md b/platform/ios/README.md
index a6752c61e6..2ca32fde97 100644
--- a/platform/ios/README.md
+++ b/platform/ios/README.md
@@ -2,7 +2,7 @@
 
 [![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.
+A library based on [Mapbox GL Native](../../README.md) for embedding interactive map views with scalable, customizable 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.
 
diff --git a/platform/ios/scripts/package.sh b/platform/ios/scripts/package.sh
index 0d5808aea3..24726207af 100755
--- a/platform/ios/scripts/package.sh
+++ b/platform/ios/scripts/package.sh
@@ -165,6 +165,7 @@ cp -pv ios/framework/Info.plist "${OUTPUT}/static/${NAME}.framework/Info.plist"
 perl -pi -e "s/(?<=<string>)0(?=<\/string>)/${PROJ_VERSION}/g" "${OUTPUT}/static/${NAME}.framework/Info.plist"
 mkdir "${OUTPUT}/static/${NAME}.framework/Modules"
 cp -pv ios/framework/modulemap "${OUTPUT}/static/${NAME}.framework/Modules/module.modulemap"
+cp -pv ios/framework/strip-frameworks.sh "${OUTPUT}/dynamic/${NAME}.framework/strip-frameworks.sh"
 
 step "Generating API documentation…"
 if [ -z `which jazzy` ]; then
diff --git a/platform/osx/DEVELOPING.md b/platform/osx/DEVELOPING.md
index 3233b6302c..f75fa86db3 100644
--- a/platform/osx/DEVELOPING.md
+++ b/platform/osx/DEVELOPING.md
@@ -1,6 +1,6 @@
 # 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.
+This document explains how to build the Mapbox OS X SDK from source. It is intended for advanced developers who wish to contribute to Mapbox GL and the Mapbox iOS SDK.
 
 ### Requirements
 
diff --git a/platform/osx/README.md b/platform/osx/README.md
index d96ae4947f..8a21897f64 100644
--- a/platform/osx/README.md
+++ b/platform/osx/README.md
@@ -2,7 +2,7 @@
 
 [![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.
+A library based on [Mapbox GL Native](../../README.md) for embedding interactive map views with scalable, customizable 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.