Mapbox-gl-native: Add support for Carthage

[barkoded]

It would be wonderful if Mapbox GL for iOS would support Carthage as an alternative to Cocoapods.

[1ec5]

Carthage support would be great, but Carthage only supports dynamic frameworks at the moment, whereas this project's relatively complex build system puts out a static library. CocoaPods wraps this static library in a framework, which is how we support Swift. So if we can do something like that as part of the build process, we'd be able to support Carthage.

[incanus]

Dynamic framework is tracked in https://github.com/mapbox/mapbox-gl-native/issues/828.

[alec-c4]

carthage support would be great!

[petaren]

+1 on carthage support

[erichoracek]

For anyone interested in a temporary way to include Mapbox via Carthage until #828 is resolved, I've created a mirror using the Rome CocoaPods plugin at https://github.com/erichoracek/Mapbox.

[1ec5]

We’ve begun to publish 3.1.0 prereleases with dynamic frameworks attached. However, there are a couple issues blocking Carthage adoption:

• Carthage insists on a vX.Y.Z tag format, whereas the Mapbox iOS SDK’s tags are formatted ios-vX.Y.Z (with -pre.P appended for prereleases), in order to support independent versioning of the iOS, OS X, and Android SDKs and the Node module. Although we stopped using the vX.Y.Z format to tag the cross-platform mbgl code in this repository months ago, it doesn’t seem right to move iOS releases to that format when non-iOS releases share this repository.
• Carthage looks for release attachments whose names contain “.framework”. It’s also unclear to me whether the existing package structure, which puts the dynamic framework in a dynamic/ folder, is compatible with Carthage.

[1ec5]

It’s also unclear to me whether the existing package structure, which puts the dynamic framework in a dynamic/ folder, is compatible with Carthage.

According to https://github.com/Carthage/Carthage/issues/1056#issuecomment-174293745, the existing structure should be fine. We just need to publish a redundant copy of the “-dynamic.zip” package with “.framework” in the name.

[1ec5]

Apparently Carthage considers _any_ tag that doesn’t strictly conform to semver to meet the requirements specified in the Cartfile: Carthage/Carthage#469. Hopefully we’d get lucky because Android and Node releases have no “.framework” assets.

[friedbunny]

IIRC, Carthage downloaded the Android release when I tried it a few days back (and Android was the most recent).

[maciekish]

+1

[1ec5]

Carthage/Carthage#722 would give us another way forward for this issue.

[cansurmeli]

+1 Carthage

[1ec5]

Carthage fundamentally isn’t compatible with monorepos like this one. We could maintain a separate repository for iOS SDK releases along the lines of https://github.com/mapbox/mapbox-gl-native/issues/1623#issuecomment-161186752, but then why not split the iOS and macOS SDKs’ Objective-C codebase into a separate repo from the core mbgl project, as we originally did in mapbox-gl-cocoa?

[erichoracek]

The most recent version of Carthage (0.19) has added support for binary downloads, e.g.:

binary "https://my.domain.com/release/MyFramework.json"

See the JSON file spec here.

Is this something that could work for MBGL rather than a separate repo with releases?

[friedbunny]

Thanks for the heads-up, @erichoracek — we've added tentative support for Carthage. 🏛

I’ll leave this issue open for now so we can track how well this initial Carthage support works, and also as a reminder to add official documentation.

How to use the Mapbox iOS SDK with Carthage

If you’re new to Carthage, follow these setup instructions.

1. Add this line to your Cartfile:

binary "https://www.mapbox.com/ios-sdk/Mapbox-iOS-SDK.json" ~> 3.4

_There is also a -symbols feed available._

1. Drag Mapbox.framework (located in Carthage/Build/iOS) into Linked Frameworks and Libraries.

2. Add this to your Carthage copy-frameworks build phase:

$(SRCROOT)/Carthage/Build/iOS/Mapbox.framework

Caveats

• Pre-releases are not supported by Carthage yet, even with a specific == operator. Support is a work-in-progress in https://github.com/Carthage/Carthage/pull/1553. (Nonetheless, pre-releases are optimistically included in our feeds.)
• Carthage only supports dynamic frameworks, so that’s all our feeds provide.

[mdiep]

Please be sure to open a Carthage issue if you have any feedback about this feature!

I'm excited to see people adopting this feature. 🤘

[friedbunny]

@mdiep, on behalf of all monorepoists out there, thank you. 😉

[1ec5]

The Mapbox macOS SDK supports Carthage through a setup workflow similar to the one in https://github.com/mapbox/mapbox-gl-native/issues/1623#issuecomment-280175923. Here are the general instructions for a macOS project, and here are the steps for the macOS SDK specifically:

1. Add this binary project specification to your Cartfile:
   binary "https://mapbox.github.io/mapbox-gl-native/macos/Mapbox-macOS-SDK.json" ~> 0.3
   or this one, for debug symbols:
   binary "https://mapbox.github.io/mapbox-gl-native/macos/Mapbox-macOS-SDK-symbols.json" ~> 0.3
2. Drag Mapbox.framework (located in Carthage/Build/Mac) into Linked Frameworks and Libraries.
3. Add this path to the Input Files section of the Run Script build phase that runs carthage copy-frameworks:
   $(SRCROOT)/Carthage/Build/Mac/Mapbox.framework

Note that Carthage doesn’t currently support prereleases, even when you use the == operator. The binary project specification includes prereleases in anticipation of Carthage/Carthage#1553.

Edit: Renamed the binary project specification from “carthage.json” to “Mapbox-macOS-SDK.json”.

[friedbunny]

iOS instructions are live at: https://www.mapbox.com/ios-sdk/

[friedbunny]

Fixed in #8257.