diff options
| author | Minh Nguyễn <mxn@1ec5.org> | 2015-11-22 18:07:06 -0800 |
|---|---|---|
| committer | Minh Nguyễn <mxn@1ec5.org> | 2015-12-13 17:17:35 -0800 |
| commit | 0cab7809eb59675be6c3a87a665a2bf0b9a28d75 (patch) | |
| tree | 490eb9f86113a71be274781f4465c8d32b92dabb /docs | |
| parent | b59f087ea8bd451d7e822bb27d3612974fa5ac77 (diff) | |
| download | qtlocation-mapboxgl-0cab7809eb59675be6c3a87a665a2bf0b9a28d75.tar.gz | |
[osx] Rewrote platform-osx and osxapp
platform-osx now vends a real NSView subclass, MGLMapView, that is readily embedded inside a Cocoa application for OS X. MGLMapView is backed by an NSOpenGLLayer for optimal performance and integration with other layer-backed views. It supports keyboard shortcuts and several gestures and hosts attribution, zooming, and rotation controls as subviews. osxapp is now a bona fide Cocoa application that embeds MGLMapView inside a XIB. osxapp has preferences and a share button for tight integration with custom styles.
Enabling asynchronous rendering would be more consistent with iOS but increases CPU usage so much, even when idle, that it isn’t worth any performance gain. The bigger issue is that VAOs aren’t being used.
make xpackage creates a static library similar to the one created by make ipackage. make clean cleans additional places where build output ends up.
The OS X minimum deployment target has been increased from 10.9 to 10.10. osxapp’s window has a full size content view, which requires 10.10. Lightweight generics require iOS 9+ and OS X 10.11 regardless, because it was only in that release that Foundation collection classes started adopting lightweight generics.
Shuffled files around and refactored annotations so that iOS and OS X share a good chunk of the annotations code, which now takes advantage of polymorphism. MGLMapView can now display annotations but cannot yet select them. In osxapp, a long press drops a pin, and so does the map view’s context menu.
Annotations have NSPopovers as callouts, and their view controllers can be customized. Annotation image alignment rects are respected for hit testing purposes and for positioning the callout anchor. Callouts in osxapp demonstrate the use of bindings to keep callouts in sync with underlying model objects.
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. |