README.md 8.66 KB
Newer Older
Petr Pridal's avatar
Petr Pridal committed
1
# MapLibre GL Native - Open-Source Mapbox GL Native
Petr Pokorny's avatar
Petr Pokorny committed
2

Petr Pridal's avatar
Petr Pridal committed
3
SDK for iOS, Android and other platforms
Petr Pokorny's avatar
Petr Pokorny committed
4

Petr Pokorny's avatar
Petr Pokorny committed
5
6
7
8
9
10
11
12
13
14
MapLibre GL Native is a community led fork derived from [mapbox-gl-native](https://github.com/mapbox/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](https://github.com/mapbox/mapbox-gl-native-ios)) and Android SDK (forked from [mapbox-gl-native-android](https://github.com/mapbox/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.

Petr Pokorny's avatar
Petr Pokorny committed
15
> The mapbox-gl-native was forked from [d60fd30 - mgbl 1.6.0](https://github.com/mapbox/mapbox-gl-native/tree/d60fd302b1f6563e7d16952f8855122fdcc85f73), mapbox-gl-native-ios from [a139216](https://github.com/mapbox/mapbox-gl-native-ios/commit/a139216) and mapbox-gl-native-android from [4c12fb2](https://github.com/mapbox/mapbox-gl-native-android/commit/4c12fb2c)
Petr Pokorny's avatar
Petr Pokorny committed
16
17
18
19
## Build Status

| SDK                                                           | Build   | Build status                                                                                                                                                                                  |
|---------------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
Petr Pridal's avatar
Petr Pridal committed
20
21
22
23
| [Maps SDK for iOS](platform/ios/) | CI      | [![GitHub Action build status](https://github.com/maplibre/maplibre-gl-native/workflows/ios-ci/badge.svg)](https://github.com/maplibre/maplibre-gl-native/workflows/ios-ci)                   |
| [Maps SDK for iOS](platform/ios/) | Release | [![GitHub Action build status](https://github.com/maplibre/maplibre-gl-native/workflows/ios-release/badge.svg)](https://github.com/maplibre/maplibre-gl-native/workflows/ios-release)         |
| [Maps SDK for Android](platform/android/)      | CI      | [![GitHub Action build status](https://github.com/maplibre/maplibre-gl-native/workflows/android-ci/badge.svg)](https://github.com/maplibre/maplibre-gl-native/workflows/android-ci)           |
| [Maps SDK for Android](platform/android/)     | Release | [![GitHub Action build status](https://github.com/maplibre/maplibre-gl-native/workflows/android-release/badge.svg)](https://github.com/maplibre/maplibre-gl-native/workflows/android-release) |
Petr Pokorny's avatar
Petr Pokorny committed
24

Oliver Wipfli's avatar
Oliver Wipfli committed
25
26
27
28
29

## Sponsors

We thank everyone who supported us financially in the past and special thanks to the people and organizations who support us with recurring dontations:  

Oliver Wipfli's avatar
Oliver Wipfli committed
30
[MIERUNE Inc.](https://www.mierune.co.jp/?lang=en) [@MIERUNE](https://github.com/MIERUNE), [@jawg](https://github.com/jawg), [@nekoyasan](https://github.com/nekoyasan), [@atierian](https://github.com/atierian), [@photoprism](https://github.com/photoprism), [@kaplanlior](https://github.com/kaplanlior), [@francois2metz](https://github.com/francois2metz), [@Schneider-Geo](https://github.com/Schneider-Geo), [@serghov](https://github.com/serghov), [@ambientlight](https://github.com/ambientlight), [@joschi77](https://github.com/joschi77), [@geoffhill](https://github.com/geoffhill), [@jasongode](https://github.com/jasongode)
Oliver Wipfli's avatar
Oliver Wipfli committed
31

32
33
34
35
36
37
## Documentation

The Android API documentation is available at https://maplibre.org/maplibre-gl-native/android/api/

The iOS API documentation is available at https://maplibre.org/maplibre-gl-native/ios/api/

Petr Pokorny's avatar
Petr Pokorny committed
38
39
40
41
## Installation

### Android

42
1. Add bintray maven repositories to your build.gradle at project level so that you can access MapLibre packages for Android:
Petr Pokorny's avatar
Petr Pokorny committed
43
44
45
46
47

    ```gradle
        allprojects {
            repositories {
                ...
Petr Pokorny's avatar
Petr Pokorny committed
48
                mavenCentral()                
Petr Pokorny's avatar
Petr Pokorny committed
49
50
51
52
            }
        }
    ```

Petr Pokorny's avatar
Petr Pokorny committed
53
54
   > Note: [Bintray was turn off May 1st, 2021](https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/) so we migrated all packages to maven central.

Petr Pokorny's avatar
Petr Pokorny committed
55
56
57
58
59
2. Add the library as a dependency into your module build.gradle

    ```gradle
        dependencies {
            ...
60
            implementation 'org.maplibre.gl:android-sdk:<version>'
Petr Pokorny's avatar
Petr Pokorny committed
61
62
63
64
65
66
            ...
        }
    ```

3. Sync gradle and rebuild your app

67
68
69
70
71
72
73
*Note: MapLibre by default ships with the proprietary Google Play Location Services. If you want to avoid pulling proprietary dependencies into your project, you can exclude Google Play Location Services as follows:*
```gradle
    implementation ('org.maplibre.gl:android-sdk:<version>') {
        exclude group: 'com.google.android.gms'
    }
```

Petr Pokorny's avatar
Petr Pokorny committed
74
75
76
77
### 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.

78
2. Either add MapLibre GitHub distribution URL (https://github.com/maplibre/maplibre-gl-native-distribution) or search for `maplibre-gl-native` package.
Petr Pokorny's avatar
Petr Pokorny committed
79
80
81
82
83
84
85
86
87
88
89
90

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

```bash
91
git clone --recurse-submodules https://github.com/maplibre/maplibre-gl-native.git
Petr Pokorny's avatar
Petr Pokorny committed
92
93
```

RobLabs.com's avatar
RobLabs.com committed
94
## Build
Petr Pokorny's avatar
Petr Pokorny committed
95

Rob | Labs's avatar
Rob | Labs committed
96
97
98
99
100
101
102
103
104
105
MapLibre uses tags for its Android & iOS releases based on [SemVer](https://semver.org) 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

```bash
# 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.4.2
RobLabs.com's avatar
RobLabs.com committed
106
107
# TAG=android-v9.5.2
TAG=ios-v5.12.0
Rob | Labs's avatar
Rob | Labs committed
108
109
110
111
112
113
114
115
116
# 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`
```

RobLabs.com's avatar
RobLabs.com committed
117
118
119
120
121
122
123
124
125
126
127
128
### Android

---

<details open><summary>macOS Build Environment:  Android Studio + NDK</summary>
<ul>
<li>Environment:  Android Studio + NDK<ul>
<li><code style="font-family: Menlo, Consolas, &quot;DejaVu Sans Mono&quot;, monospace;">JAVA_HOME=/Applications/Android Studio.app/Contents/jre/Contents/Home</code></li>
<li><code style="font-family: Menlo, Consolas, &quot;DejaVu Sans Mono&quot;, monospace;">ANDROID_SDK_ROOT=~/Library/Android/sdk</code></li>
<li><code style="font-family: Menlo, Consolas, &quot;DejaVu Sans Mono&quot;, monospace;">~/Library/Android/sdk/tools/bin/sdkmanager --install ndk;major.minor.build</code></li>
</ul>
</details>
Petr Pokorny's avatar
Petr Pokorny committed
129
130
131


```bash
132
cd platform/android
RobLabs.com's avatar
RobLabs.com committed
133
134
BUILDTYPE=Debug make apackage
#BUILDTYPE=Release make apackage
Petr Pokorny's avatar
Petr Pokorny committed
135
136
```

RobLabs.com's avatar
RobLabs.com committed
137
Binaries are produced in `platform/android/MapboxGLAndroidSDK/build/outputs/aar/MapboxGLAndroidSDK-<BUILDTYPE>.aar`
138
Please refer to [Mapbox Maps SDK for Android](platform/android/) for detailed instructions.
Petr Pokorny's avatar
Petr Pokorny committed
139

RobLabs.com's avatar
RobLabs.com committed
140
### iOS
Petr Pokorny's avatar
Petr Pokorny committed
141

Rob Labs's avatar
Rob Labs committed
142
143
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.

Petr Pokorny's avatar
Petr Pokorny committed
144
```bash
145
cd platform/ios
Rob Labs's avatar
Rob Labs committed
146
147
148
149
150
151
152
153

# make and open the Xcode workspace
make iproj

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

# Make Frameworks
Petr Pokorny's avatar
Petr Pokorny committed
154
make xcframework BUILDTYPE=Release
Rob Labs's avatar
Rob Labs committed
155
156
157
158
159
160
161

# test
make ios-test

# UITests
#   You can review uitest results:  $(IOS_OUTPUT_PATH)/Logs/Test
 make ios-uitest
Petr Pokorny's avatar
Petr Pokorny committed
162
163
```

164
The packaging script will produce a `Mapbox.xcframework` in the  `platform/ios/build/ios/pkg/dynamic` folder.
165
Please refer to [Mapbox Maps SDK for iOS](platform/ios/platform/ios/) for detailed instructions.
Petr Pokorny's avatar
Petr Pokorny committed
166
167
168
169
170


#### MacOS

```bash
171
cd platform/ios
Petr Pokorny's avatar
Petr Pokorny committed
172
173
174
make xpackage
```

175
This produces a `Mapbox.framework` in the `platform/ios/build/macos/pkg/` folder.
Jiří Komárek's avatar
typo    
Jiří Komárek committed
176
Please refer to [Mapbox Maps SDK for macos](platform/ios/platform/macos/) for detailed instructions.
Daniel Woznicki's avatar
Daniel Woznicki committed
177
178
179
180

#### Linux

See [the Linux platform build section](platform/linux/) for instructions.