diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BUILD_OSX | 92 | ||||
| -rw-r--r-- | docs/BUILD_OSX.md | 32 | ||||
| -rw-r--r-- | docs/DEVELOP_IOS_OSX.md | 2 | ||||
| -rw-r--r-- | docs/DEVELOP_OSX.md | 12 |
4 files changed, 128 insertions, 10 deletions
diff --git a/docs/BUILD_OSX b/docs/BUILD_OSX new file mode 100644 index 0000000000..6a43025201 --- /dev/null +++ b/docs/BUILD_OSX @@ -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`. + + + + + +### 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/BUILD_OSX.md b/docs/BUILD_OSX.md new file mode 100644 index 0000000000..5b4f6e6327 --- /dev/null +++ b/docs/BUILD_OSX.md @@ -0,0 +1,32 @@ +# Building Mapbox GL Native for OS X + +This project provides an OS X SDK analogous to the Mapbox iOS SDK. Mapbox does not officially support it to the same extent as the iOS SDK; however, bug reports and pull requests are certainly welcome. This document explains how to build the OS X SDK and integrate it into your own Cocoa application. + +### Build + +1. Run `make xpackage`. The packaging script will produce the statically-linked `libMapbox.a`, `Mapbox.bundle` for resources, and a `Headers` folder. + +### Install + +1. Copy the contents of `build/osx/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: + + - `SystemConfiguration.framework` + - `libc++.tbd` + - `libsqlite3.tbd` + - `libz.tbd` + +1. Add `-ObjC` to your target's "Other Linker Flags" build setting (`OTHER_LDFLAGS`). + +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/account/apps/). + +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). + +## Troubleshooting + +You can also try clearing the Xcode cache with `make clear_xcode_cache`. diff --git a/docs/DEVELOP_IOS_OSX.md b/docs/DEVELOP_IOS_OSX.md index 183fd15705..9cc27bc581 100644 --- a/docs/DEVELOP_IOS_OSX.md +++ b/docs/DEVELOP_IOS_OSX.md @@ -14,7 +14,7 @@ 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. +Which will create and open an Xcode project that 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. diff --git a/docs/DEVELOP_OSX.md b/docs/DEVELOP_OSX.md index 02d0865726..3ca96ebf24 100644 --- a/docs/DEVELOP_OSX.md +++ b/docs/DEVELOP_OSX.md @@ -2,7 +2,7 @@ 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 xproj`: Creates an Xcode project with a native OS X application for testing changes to mapbox-gl-native on the desktop. - `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`. @@ -10,14 +10,8 @@ Note that you can't have more than one project in Xcode open at a time because t ### 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/studio/account/tokens/)._ - -Set up the access token by editing the scheme for the application target, then adding an environment variable with the name `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/studio/account/tokens/). You will be prompted for this access token the first time you launch the demo application. ### Usage -Keyboard shortcuts for testing functionality are logged to the console when the test app is started. +Through the OS X SDK, the demo application supports a variety of standard gestures and keyboard shortcuts. For more details, open Mapbox GL Help from the Help menu. |