MapLibre GL Native - Open-Source Mapbox GL Native

SDK for iOS, Android and other platforms

MapLibre GL Native is a community led fork derived from mapbox-gl-native prior to their switch to a non-OSS license. The fork also includes Maps SDK for iOS and MacOS (forked from mapbox-gl-native-ios) and Android SDK (forked from mapbox-gl-native-android). These platform-specific SDKs were merged under platform directory and they reference mapbox-gl-native directly, not as a submodule.

Beside merging in platform specific SDKs, the following changes were made compared to original mapbox projects:

• The code was upgraded so that it can be built using latest clang compiler / Xcode 12.
• CI/CD was migrated from CircleCI to GitHub Actions.
• Along with GitHub releases, binaries are distributed as follows:
  • The iOS binaries distribution was upgraded from fat packages to Swift package containing XCFramework.
  • The Android binaries are distributed to GitHub maven package repository.

The mapbox-gl-native was forked from d60fd30 - mgbl 1.6.0, mapbox-gl-native-ios from a139216 and mapbox-gl-native-android from 4c12fb2

Build Status

| SDK | Build | Build status | |---------------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Maps SDK for iOS | CI | | | Maps SDK for iOS | Release | | | Maps SDK for Android | CI | | | Maps SDK for Android | Release | |

Installation

Android

1. Add bintray maven repositories to your build.gradle at project level so that you can access MapLibre packages for Android:

       allprojects {
           repositories {
               ...
               mavenCentral()                
           }
       }

   Note: Bintray was turn off May 1st, 2021 so we migrated all packages to maven central.

2. Add the library as a dependency into your module build.gradle

       dependencies {
           ...
           implementation 'org.maplibre.gl:android-sdk:9.4.0'
           ...
       }

3. Sync gradle and rebuild your app

iOS

1. To add a package dependency to your Xcode project, select File > Swift Packages > Add Package Dependency and enter its repository URL. You can also navigate to your target’s General pane, and in the “Frameworks, Libraries, and Embedded Content” section, click the + button, select Add Other, and choose Add Package Dependency.

2. Either add MapLibre GitHub distribution URL (https://github.com/maplibre/maplibre-gl-native-distribution) or search for maplibre-gl-native package.

3. Choose "next". Xcode should clone the distribution repository and download the binaries.

Alternative installation

You can also download pre-build from releases in this repository.

How to create your own build

Source code checkout

git clone --recurse-submodules https://github.com/maplibre/maplibre-gl-native.git

Build

MapLibre uses tags for its Android & iOS releases based on SemVer versioning. This is useful for checking out a particular released version for feature enhancments or debugging.

You can list available tags by issuing the command git tag, then use the result

# 1. Obtain a list of tags, which matches to release versions
git tag

# 2.  Set a convenience variable with the desired TAG
# TAG=android-v9.2.1
# TAG=android-v9.4.2
TAG=ios-v5.11.0
# TAG=ios-v5.12.0-pre.1

# 3.  Check out a particular TAG
git checkout tags/$TAG -b $TAG

# 4. build, debug or enhance features based on the tag
# clean, if you need to troubleshoot build dependencies by using `make clean`

Android

Make sure you have set Android SDK path in platform/android/local.properties, variable sdk.dir

cd platform/android
BUILDTYPE=Release make apackage

Binaries are produced in platform/android/MapboxGLAndroidSDK/build/outputs/aar/MapboxGLAndroidSDK-release.aar Please refer to Mapbox Maps SDK for Android for detailed instructions.

iOS

You can run automated test on a Simulator or Device by changing to the Scheme iosapp and choosing Product > Test (or use ⌘-U). Use ⌘-9 to navigate to Reports to see results and browse through screenshots. This method of testing should work well with CI tools such as GitHub Actions, Xcode Server Bots, & AWS Device Farm.

cd platform/ios

# make and open the Xcode workspace
make iproj

# make Xcode workspace, but run in headless mode
make iproj CI=1

# Make Frameworks
make xcframework BUILDTYPE=Release

# test
make ios-test

# UITests
#   You can review uitest results:  $(IOS_OUTPUT_PATH)/Logs/Test
 make ios-uitest

The packaging script will produce a Mapbox.xcframework in the platform/ios/build/ios/pkg/dynamic folder. Please refer to Mapbox Maps SDK for iOS for detailed instructions.

MacOS

cd platform/ios
make xpackage

This produces a Mapbox.framework in the platform/ios/build/macos/pkg/ folder. Please refer to Mapbox Maps SDK for macos for detailed instructions.