Adopt Apple Generic Versioning

[1ec5]

The iOS and macOS Xcode projects should adopt the Apple Generic Versioning system to replace the incomplete, ad-hoc system we’re currently using.

Background

Frameworks and applications are supposed to set the CURRENT_PROJECT_VERSION and CURRENT_SHORT_VERSION build settings to something meaningful. These settings are used in several ways, such as to display the application version in Finder (handy for debugging purposes) or to query a framework’s version at runtime (an additional layer of safety when weak-linking a framework).

We currently rely on the two package.sh scripts to fill in the iOS and macOS map SDKs’ CURRENT_PROJECT_VERSION and CURRENT_SHORT_VERSION build settings:

https://github.com/mapbox/mapbox-gl-native-ios/blob/69ddd885126a9650dbe1d20f4b7cee73aa7fc946/platform/ios/scripts/package.sh#L68-L69 https://github.com/mapbox/mapbox-gl-native-ios/blob/69ddd885126a9650dbe1d20f4b7cee73aa7fc946/platform/ios/scripts/package.sh#L88-L89 https://github.com/mapbox/mapbox-gl-native-ios/blob/69ddd885126a9650dbe1d20f4b7cee73aa7fc946/platform/macos/scripts/package.sh#L36-L37

The values are automatically calculated based on Git commit history and tags.

Problem

The build scripts only set CURRENT_PROJECT_VERSION, not DYLIB_CURRENT_VERSION, which is the setting that matters more for dynamic libraries. (It’s what you see when running otool -L.) By default, DYLIB_CURRENT_VERSION is supposed to be based on CURRENT_PROJECT_VERSION, but we’ve hard-coded it as 1.

CURRENT_PROJECT_VERSION and CURRENT_SHORT_VERSION only get filled in when building from the command line, not when debugging in Xcode as we normally do.

Moreover, for a time, we also used the scripts to fill in macosapp’s build settings:

https://github.com/mapbox/mapbox-gl-native-ios/blob/69ddd885126a9650dbe1d20f4b7cee73aa7fc946/platform/macos/scripts/package.sh#L60-L61

However, ever since we’ve had to notarize macosapp, I’ve been manually archiving it inside Xcode. Once complete, mapbox/mapbox-gl-native#14754 #204 would automate notarization, allowing us to rely on the script to archive the application again. In the meantime, the version remains at 0.1.0.

Proposed solution

To adopt Apple Generic Versioning, we would set the CURRENT_PROJECT_VERSION and VERSIONING_SYSTEM build settings as described in this documentation.

Then we would add the following step to the release process, to be run manually at the same time that we increment the version in the CocoaPods podspecs, so the results would be committed to the repository:

agvtool bump -all
agvtool new-marketing-version $( git describe --tags --match=ios-v*.*.* --abbrev=0 | sed 's/^ios-v//' )

A simple script could run these commands and modify the podspecs.

Rationale

Apple Generic Versioning is a more-or-less preferred way to manage the build artifacts’ versions. We can continue to calculate the versions the same way, but we’d specify them in a way that applies within Xcode too.

Mapbox’s iOS navigation SDK and Swift service libraries all use Apple Generic Versioning, invoking agvtool manually at release time.

/cc @mapbox/maps-ios

[1ec5]

git describe --tags would return the previous release tag if we run this step as part of putting together the release PR. I think it’d be fine to require the releaser to pass the version number in explicitly when invoking make agvtool or ./platform/ios/scripts/update-versions.sh.

[1ec5]

263 adopts AGV on macOS. I’ll leave this issue open to track the same change on iOS.