@maplibre/maplibre-gl-native 5.1.1 → 5.2.0-pre.1

package/README.md

@@ -1,300 +1,79 @@
-# MapLibre GL Native - Open-Source Mapbox GL Native
+[![MapLibre Logo](https://maplibre.org/img/maplibre-logo-big.svg)](https://maplibre.org/)
 
-SDK for iOS, Android and other platforms
+# MapLibre GL Native
 
-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.
+MapLibre GL Native is a free and open-source library for publishing maps in your apps and desktop applications on various platforms. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering.
 
-Beside merging in platform specific SDKs, the following changes were made compared to original mapbox projects:
+This project originated as a fork of Mapbox GL Native, before their switch to a non-OSS license in December 2020. For more information, see: [`FORK.md`](./FORK.md).
 
-* 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.
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/649392/211550776-8779041a-7c12-4bed-a7bd-c2ec80af2b29.png" alt="Android device with MapLibre" width="24%">   <img src="https://user-images.githubusercontent.com/649392/211550762-0f42ebc9-05ab-4d89-bd59-c306453ea9af.png" alt="iOS device with MapLibre" width="25%">
+</p>
 
-> 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)
+## Getting Started
 
-**Call for Bounties💰** If you have ideas for new features in MapLibre, you can now nominate them for the MapLibre Bounty Program at https://maplibre.org/news/2022-10-16-call-for-bounties/
-
-## Build Status
-
-| SDK                                                           | Build   | Build status                                                                                                                                                                                  |
-|---------------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [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) |
-
-
-## Sponsors
-
-We thank everyone who supported us financially in the past and special thanks to the people and organizations who support us with recurring donations!
-
-Read more about the MapLibre Sponsorship Program at [https://maplibre.org/sponsors/](https://maplibre.org/sponsors/).
-
-Platinum:
-
-<img src="https://maplibre.org/img/aws-logo.svg" alt="Logo AWS" width="25%"/>
-
-
-Silver:
-
-<img src="https://maplibre.org/img/meta-logo.svg" alt="Logo Meta" width="50%"/>
-
-Stone:
-
-[MIERUNE Inc.](https://www.mierune.co.jp/?lang=en)
-
-Backers and Supporters:
-
-<a href="https://opencollective.com/maplibre/backer/0/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/0/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/1/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/1/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/2/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/2/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/3/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/3/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/4/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/4/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/5/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/5/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/6/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/6/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/7/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/7/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/8/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/8/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/9/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/9/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/10/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/10/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/11/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/11/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/12/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/12/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/13/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/13/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/14/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/14/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/15/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/15/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/16/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/16/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/17/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/17/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/18/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/18/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/19/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/19/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/20/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/20/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/21/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/21/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/22/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/22/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/23/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/23/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/24/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/24/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/25/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/25/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/26/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/26/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/27/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/27/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/28/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/28/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/29/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/29/avatar.svg?requireActive=false"></a>
-<a href="https://opencollective.com/maplibre/backer/30/website?requireActive=false" target="_blank"><img src="https://opencollective.com/maplibre/backer/30/avatar.svg?requireActive=false"></a>
+To get started with MapLibre GL Native, go to your platform below.
 
 ## 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/
-
-Architecture: https://maplibre.org/maplibre-gl-native/docs/book/
-
-## Installation
-
-### Android
-
-1. Add bintray maven repositories to your build.gradle at project level so that you can access MapLibre packages for Android:
-
-    ```gradle
-        allprojects {
-            repositories {
-                ...
-                mavenCentral()                
-            }
-        }
-    ```
-
-   > 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.
-
-2. Add the library as a dependency into your module build.gradle
-
-    ```gradle
-        dependencies {
-            ...
-            implementation 'org.maplibre.gl:android-sdk:<version>'
-            ...
-        }
-    ```
-
-3. Sync gradle and rebuild your app
-
-*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'
-    }
-```
-
-### 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
+The documentation of MapLibre GL Native is a work in progress. To get an architectural overview and to learn about the current state of the project and its path forward read the [MapLibre GL Native Markdown Book](https://maplibre.org/maplibre-gl-native/docs/book/). See below for platform-specific documentation.
 
-You can also download pre-build from releases in this repository.
+## Platforms
 
-## How to create your own build
+- [⭐️ Android](platform/android/README.md) 
+- [⭐️ iOS](platform/ios/platform/ios/README.md)
+- [GLFW](platform/glfw)
+- [Linux](platform/linux/README.md)
+- [Node.js](platform/node/README.md)
+- [Qt](platform/qt/README.md)
+- [Windows](platform/windows/README.md)
+- [macOS](platform/ios/platform/macos/README.md)
 
-### Source code checkout
+Platforms with a ⭐️ are **MapLibre Core Projects** and have a substantial amount of financial resources allocated to them. Learn about the different [project tiers](https://github.com/maplibre/maplibre/blob/main/PROJECT_TIERS.md#project-tiers).
 
-```bash
-git clone --recurse-submodules https://github.com/maplibre/maplibre-gl-native.git
-```
+## Renderer Modularization & Metal
 
-## Build
+![image-metal](https://user-images.githubusercontent.com/53421382/214308933-66cd4efb-b5a5-4de3-b4b4-7ed59045a1c3.png)
 
-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.
+MapLibre GL Native is being actively developed. Our big goal for 2023 is to modularize the OpenGL renderer and implement a Metal graphics backend (https://developer.apple.com/metal/). This will improve the performance and yield lower power consumption on iOS devices. At the same time, the Metal preparations will help us in the implementation of a Vulkan graphics backend.
 
-You can list available tags by issuing the command `git tag`, then use the result
+Your help in preparing the codebase for the latest graphics backends is more than welcome. Feel free to reach out if you are interested in joining the effort!
 
-```bash
-# 1. Obtain a list of tags, which matches to release versions
-git tag
+- Check out the [news](https://maplibre.org/news/) on MapLibre's website.
+- See the [Design Proposals](https://github.com/louwers/maplibre-gl-native/tree/main/design-proposals) that have been accepted and are being worked on, the most recent ones being the [Rendering Modularization Design Proposal](design-proposals/2022-10-27-rendering-modularization.md) and the [Metal Port Design Proposal](design-proposals/2022-11-29-metal-port.md).
 
-# 2.  Set a convenience variable with the desired TAG
-# TAG=android-v9.4.2
-# TAG=android-v9.5.2
-TAG=ios-v5.12.0
-# TAG=ios-v5.12.0-pre.1
+## Contributing
 
-# 3.  Check out a particular TAG
-git checkout tags/$TAG -b $TAG
+To contribute to MapLibre GL Native, see [`CONTRIBUTING.md`](CONTRIBUTING.md) and (if applicable) the specific instructions for the platform you want to contribute to.
 
-# 4. build, debug or enhance features based on the tag
-# clean, if you need to troubleshoot build dependencies by using `make clean`
-```
+### Getting Involved
 
-### Build using Bazel
+Join the `#maplibre-native` Slack channel at OSMUS. Get an invite at https://slack.openstreetmap.us/ 
 
-[Bazel](https://bazel.build) is also supported as a build option for getting a packaged release of the xcframework compiled for either static or dynamic linking.
 
-Firstly you will have to ensure that Bazel is installed
-
-`brew install baselisk`
-
-From there you can use the script in platform/ios/platform/ios/scripts/package-bazel.sh
-
-#### There are 4 options:
-
-`cd platform/ios/platform/ios/scripts`
-
-Static xcframework compiled for release (this is default if no parameters are provided):
-`./bazel-package.sh --static --release`
-
-Static xcframework compiled for debug:
-`./bazel-package.sh --static --debug`
-
-Dynamic xcframework compiled for release:
-`./bazel-package.sh --dynamic --release`
-
-Dynamic xcframework compiled for debug:
-`./bazel-package.sh --dynamic --debug`
-
-All compiled frameworks will end up in the `bazel-bin/platform/ios/` path from the root of the repo.
-
-Also you can use the link option to ensure that the framework is able to link.
-
-`./bazel-package.sh --link`
-
-#### Bazel build files are placed in a few places throughout the project:
-
-`BUILD.bazel`
-- Covering the base cpp in the root `src` directory.
-
-`vendor/BUILD.bazel`
-- Covering the submodule dependencies of Maplibre.
-
-`platform/default/BUILD.bazel`
-- Covering the cpp dependencies in default.
-
-`platform/darwin/BUILD.bazel`
-- Covering the cpp source in platform/default.
-
-`platform/ios/platform/ios/vendor/`
-- Covering the iOS specific dependencies.
-
-`platform/ios/BUILD.bazel`
-- Covering the source in `platform/ios/platform/ios/src` and `platform/ios/platform/darwin/src` as well as defining all the other BUILD.bazel files and defining the xcframework targets.
-
-#### There are also some other areas that make bazel work:
-
-`WORKSPACE`
-- Defines the "repo" and the different modules that are loaded in order to compile for Apple.
-
-`.bazelversion`
-- Defines the version of bazel used, important for specific support for Apple targets.
-
-`bazel/flags.bzl`
-- Defines some compilation flags that are used between the different build files. 
-
-### 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>
-
-
-```bash
-cd platform/android
-BUILDTYPE=Debug make apackage
-#BUILDTYPE=Release make apackage
-```
-
-Binaries are produced in `platform/android/MapboxGLAndroidSDK/build/outputs/aar/MapboxGLAndroidSDK-<BUILDTYPE>.aar`
-Please refer to [Mapbox Maps SDK for Android](platform/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.
-
-```bash
-cd platform/ios
+## Sponsors
 
-# make and open the Xcode workspace
-make iproj
+We thank everyone who supported us financially in the past and special thanks to the people and organizations who support us with recurring donations!
 
-# make Xcode workspace, but run in headless mode
-make iproj CI=1
+Read more about the MapLibre Sponsorship Program at [https://maplibre.org/sponsors/](https://maplibre.org/sponsors/).
 
-# Make Frameworks
-make xcframework BUILDTYPE=Release
+Platinum:
 
-# test
-make ios-test
+<img src="https://maplibre.org/img/aws-logo.svg" alt="Logo AWS" width="25%"/>
 
-# 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](platform/ios/platform/ios/) for detailed instructions.
+Silver:
 
+<img src="https://maplibre.org/img/meta-logo.svg" alt="Logo Meta" width="50%"/>
 
-#### MacOS
+Stone:
 
-```bash
-cd platform/ios
-# open macOS project in Xcode
-make xproj
+[MIERUNE Inc.](https://www.mierune.co.jp/?lang=en)
 
-# build or test from the command line
-make xpackage
-make macos-test
-```
+Backers and Supporters:
 
-This produces a `Mapbox.framework` in the `platform/ios/build/macos/pkg/` folder.
-Please refer to [Mapbox Maps SDK for macos](platform/ios/platform/macos/) for detailed instructions.
+[![](https://opencollective.com/maplibre/backers.svg?avatarHeight=50&width=600)](https://opencollective.com/maplibre)
 
-#### Linux
+## License
 
-See [the Linux platform build section](platform/linux/) for instructions.
+**MapLibre GL Native** is licensed under the [BSD 2-Clause License](./LICENSE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maplibre/maplibre-gl-native",
-  "version": "5.1.1",
+  "version": "5.2.0-pre.1",
   "description": "Renders map tiles with Maplibre GL",
   "keywords": [
     "maplibre",
@@ -10,27 +10,28 @@
     "lib": "lib"
   },
   "files": [
-    "lib"
+    "lib",
+    "platform/node/index.d.ts"
   ],
   "main": "platform/node/index.js",
+  "types": "platform/node/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/maplibre/maplibre-gl-native.git"
   },
   "license": "BSD-2-Clause",
   "dependencies": {
-    "@mapbox/cmake-node-module": "^1.2.0",
     "@acalcutt/node-pre-gyp": "^1.0.11",
     "@acalcutt/node-pre-gyp-github": "1.4.8",
-    "minimatch": "^5.1.0",
+    "minimatch": "^7.2.0",
     "npm-run-all": "^4.0.2"
   },
   "devDependencies": {
     "@mapbox/flow-remove-types": "^2.0.0",
     "@mapbox/mvt-fixtures": "3.10.0",
-    "@octokit/plugin-retry": "^3.0.9",
-    "@octokit/rest": "^19.0.5",
-    "aws-sdk": "^2.1277.0",
+    "@octokit/plugin-retry": "^4.1.2",
+    "@octokit/rest": "^19.0.7",
+    "aws-sdk": "^2.1318.0",
     "csscolorparser": "~1.0.2",
     "d3-queue": "3.0.7",
     "diff": "5.1.0",
@@ -38,18 +39,18 @@
     "esm": "~3.2.25",
     "express": "^4.18.2",
     "json-stringify-pretty-compact": "^4.0.0",
-    "jsonwebtoken": "^8.3.0",
+    "jsonwebtoken": "^9.0.0",
     "lodash": "^4.16.4",
     "lodash.template": "4.5.0",
     "mapbox-gl-styles": "2.0.2",
     "pixelmatch": "^5.3.0",
     "pngjs": "^6.0.0",
-    "pretty-bytes": "^6.0.0",
+    "pretty-bytes": "^6.1.0",
     "request": "^2.88.0",
     "semver": "^7.3.8",
     "shuffle-seed": "1.1.6",
     "st": "3.0.0",
-    "tape": "^5.6.1",
+    "tape": "^5.6.3",
     "xcode": "^3.0.1"
   },
   "engines": {

package/platform/node/README.md

@@ -0,0 +1,204 @@
+# @maplibre/maplibre-gl-native
+
+[![Version](https://img.shields.io/npm/v/@maplibre/maplibre-gl-native?style=flat)](https://www.npmjs.com/package/@maplibre/maplibre-gl-native)
+[![node-ci](https://github.com/maplibre/maplibre-gl-native/actions/workflows/node-ci.yml/badge.svg)](https://github.com/maplibre/maplibre-gl-native/actions/workflows/node-ci.yml)
+
+## Installing
+
+Binaries are available and downloaded during install for the following platforms:
+
+- Operating systems:
+  - Ubuntu 20.04 (amd64/arm64)
+  - macOS 12 (amd64/arm64)
+  - Windows (amd64)
+- Node.js 14, 16, 18
+
+Run:
+
+```
+npm install @maplibre/maplibre-gl-native
+```
+
+Further platforms might work [with additional libraries installed](https://github.com/maplibre/maplibre-gl-native/tree/main/platform/linux#prerequisites).
+
+## Testing
+
+```
+npm test
+npm run test-suite
+```
+
+## Rendering a map tile
+
+```js
+var fs = require('fs');
+var path = require('path');
+var mbgl = require('@maplibre/maplibre-gl-native');
+var sharp = require('sharp');
+
+var options = {
+  request: function(req, callback) {
+    fs.readFile(path.join(__dirname, 'test', req.url), function(err, data) {
+      callback(err, { data: data });
+    });
+  },
+  ratio: 1
+};
+
+var map = new mbgl.Map(options);
+
+map.load(require('./test/fixtures/style.json'));
+
+map.render({zoom: 0}, function(err, buffer) {
+    if (err) throw err;
+
+    map.release();
+
+    var image = sharp(buffer, {
+        raw: {
+            width: 512,
+            height: 512,
+            channels: 4
+        }
+    });
+
+    // Convert raw image buffer to PNG
+    image.toFile('image.png', function(err) {
+        if (err) throw err;
+    });
+});
+```
+
+The first argument passed to `map.render` is an options object, all keys are optional:
+
+```js
+{
+    zoom: {zoom}, // number, defaults to 0
+    width: {width}, // number (px), defaults to 512
+    height: {height}, // number (px), defaults to 512
+    center: [{longitude}, {latitude}], // array of numbers (coordinates), defaults to [0,0]
+    bearing: {bearing}, // number (in degrees, counter-clockwise from north), defaults to 0
+    pitch: {pitch}, // number (in degrees, arcing towards the horizon), defaults to 0
+    classes: {classes} // array of strings
+}
+```
+
+When you are finished using a map object, you can call `map.release()` to permanently dispose the internal map resources. This is not necessary, but can be helpful to optimize resource usage (memory, file sockets) on a more granular level than V8's garbage collector. Calling `map.release()` will prevent a map object from being used for any further render calls, but can be safely called as soon as the `map.render()` callback returns, as the returned pixel buffer will always be retained for the scope of the callback.
+
+## Implementing a file source
+
+When creating a `Map`, you must pass an options object (with a required `request` method and optional 'ratio' number) as the first parameter.
+
+```js
+var map = new mbgl.Map({
+    request: function(req) {
+        // TODO
+    },
+    ratio: 2.0
+});
+```
+
+The `request()` method handles a request for a resource. The `ratio` sets the scale at which the map will render tiles, such as `2.0` for rendering images for high pixel density displays. The `req` parameter has two properties:
+
+```json
+{
+    "url": "http://example.com",
+    "kind": 1
+}
+```
+
+The `kind` is an enum and defined in [`mbgl.Resource`](https://github.com/maplibre/maplibre-gl-native/blob/main/include/mbgl/storage/resource.hpp):
+
+```json
+{
+    "Unknown": 0,
+    "Style": 1,
+    "Source": 2,
+    "Tile": 3,
+    "Glyphs": 4,
+    "SpriteImage": 5,
+    "SpriteJSON": 6
+}
+```
+
+The `kind` enum has no significance for anything but serves as a hint to your implemention as to what sort of resource to expect. E.g., your implementation could choose caching strategies based on the expected file type.
+
+The `request` implementation should pass uncompressed data to `callback`. If you are downloading assets from a source that applies gzip transport encoding, the implementation must decompress the results before passing them on.
+
+A sample implementation that reads files from disk would look like the following:
+
+```js
+var map = new mbgl.Map({
+    request: function(req, callback) {
+        fs.readFile(path.join('base/path', req.url), function(err, data) {
+            callback(err, { data: data });
+        });
+    }
+});
+```
+
+This is a very barebones implementation and you'll probably want a better implementation. E.g. it passes the url verbatim to the file system, but you'd want add some logic that normalizes `http` URLs. You'll notice that once your implementation has obtained the requested file, you have to deliver it to the requestee by calling `callback()`, which takes either an error object or `null` and an object with several keys:
+
+```js
+{
+    modified: new Date(),
+    expires: new Date(),
+    etag: "string",
+    data: new Buffer()
+}
+```
+
+A sample implementation that uses [`request`](https://github.com/request/request) to fetch data from a remote source:
+
+```js
+var mbgl = require('@maplibre/maplibre-gl-native');
+var request = require('request');
+
+var map = new mbgl.Map({
+    request: function(req, callback) {
+        request({
+            url: req.url,
+            encoding: null,
+            gzip: true
+        }, function (err, res, body) {
+            if (err) {
+                callback(err);
+            } else if (res.statusCode == 200) {
+                var response = {};
+
+                if (res.headers.modified) { response.modified = new Date(res.headers.modified); }
+                if (res.headers.expires) { response.expires = new Date(res.headers.expires); }
+                if (res.headers.etag) { response.etag = res.headers.etag; }
+
+                response.data = body;
+
+                callback(null, response);
+            } else if (res.statusCode == 204) {
+                callback();
+            } else {
+                callback(new Error(JSON.parse(body).message));
+            }
+        });
+    }
+});
+```
+
+Stylesheets are free to use any protocols, but your implementation of `request` must support these; e.g. you could use `s3://` to indicate that files are supposed to be loaded from S3.
+
+## Listening for log events
+
+The module imported with `require('maplibre-gl-native')` inherits from [`EventEmitter`](https://nodejs.org/api/events.html), and the `NodeLogObserver` will push log events to this. Log messages can have [`class`](https://github.com/maplibre/maplibre-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L43-L60), [`severity`](https://github.com/maplibre/maplibre-gl-native/blob/node-v2.1.0/include/mbgl/platform/event.hpp#L17-L23), `code` ([HTTP status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html)), and `text` parameters.
+
+```js
+var mbgl = require('@maplibre/maplibre-gl-native');
+mbgl.on('message', function(msg) {
+    t.ok(msg, 'emits error');
+    t.equal(msg.class, 'Style');
+    t.equal(msg.severity, 'ERROR');
+    t.ok(msg.text.match(/Failed to load/), 'error text matches');
+});
+```
+
+## Contributing
+
+See [DEVELOPING.md](DEVELOPING.md) for instructions on building this module for development.

package/platform/node/index.d.ts

@@ -0,0 +1,226 @@
+declare module '@maplibre/maplibre-gl-native' {
+  const enum ResourceKind {
+    Unknown = 0,
+    Style = 1,
+    Source = 2,
+    Tile = 3,
+    Glyphs = 4,
+    SpriteImage = 5,
+    SpriteJSON = 6,
+  }
+
+  /**
+   * Response expected by a request call during render
+   */
+  type RequestResponse = {
+    data: Uint8Array;
+    modified?: Date;
+    expires?: Date;
+    etag?: string;
+  };
+
+  const enum MapMode {
+    /**
+     * Render all tiles in map view
+     */
+    Static = 'static',
+
+    /**
+     * Render and request only a single tile
+     */
+    Tile = 'tile',
+  }
+
+  type MapOptions = {
+    /**
+     * Will be used during a `Map.render` call to request all necessary map resources (tiles, fonts...)
+     */
+    request: (
+      request: { url: string; kind: ResourceKind },
+      callback: (error?: Error, response?: RequestResponse) => void,
+    ) => void;
+
+    /**
+     * Pixel ratio at which to render images
+     *
+     * @default 1
+     */
+    ratio?: number;
+
+    /**
+     * Mode in which map view will be rendered
+     *
+     * @default MapMode.Static
+     */
+    mode?: MapMode;
+  };
+
+  /**
+   * Defines the map view to render and the resulting image
+   */
+  type RenderOptions = {
+    /**
+     * Zoom level
+     *
+     * @default 0
+     */
+    zoom?: number;
+
+    /**
+     * Width of image in pixel
+     *
+     * @default 512
+     */
+    width?: number;
+
+    /**
+     * Height of image in pixel
+     *
+     * @default 512
+     */
+    height?: number;
+
+    /**
+     * Coordinates [longitude, latitude]
+     *
+     * @default [0, 0]
+     */
+    center?: [number, number];
+
+    /**
+     * Bearing of map view in degrees, counter-clockwise from north
+     *
+     * @default 0
+     */
+    bearing?: number;
+
+    /**
+     * Pitch of map view in degrees, arcing towards the horizon
+     *
+     * @default 0
+     */
+    pitch?: number;
+
+    /**
+     * @default []
+     */
+    classes?: string[];
+  };
+
+  /**
+   * A `Map` instance is used to render images from map views
+   */
+  class Map {
+    constructor(mapOptions: MapOptions);
+
+    /**
+     * Load a style into a map
+     */
+    load: (style: any) => void;
+
+    /**
+     * Render a specific map view to an image with previously loaded map styles with render options.
+     */
+    render(renderOptions: RenderOptions, callback: (...args: [error: Error, buffer: undefined] | [error: undefined, buffer: Uint8Array]) => void): void;
+
+    /**
+     * Render a specific map view to an image with previously loaded map styles without render options.
+     */
+    render(callback: (...args: [error: Error, buffer: undefined] | [error: undefined, buffer: Uint8Array]) => void): void;
+
+    /**
+     * Call to permanently dispose the internal map resources, instance can't be used for further render calls
+     */
+    release: () => void;
+
+    /**
+     * Add source to map's style
+     */
+    addSource: (sourceId: string, source: object) => void;
+
+    /**
+     * Remove source from map's style
+     */
+    removeSource: (sourceId: string) => void;
+
+    /**
+     * Add layer to map's style
+     */
+    addLayer: (layer: object, beforeId?: string) => void;
+
+    /**
+     * Remove layer from map's style
+     */
+    removeLayer: (layerId: string) => void;
+
+    /**
+     * Add image to map's style
+     */
+    addImage: (imageId: string, image: any) => void;
+
+    /**
+     * Remove image from map's style
+     */
+    removeImage: (imageId: string) => void;
+
+    /**
+     * Set the extent of the zoom for a specified layer
+     */
+    setLayerZoomRange: (layerId: string, minZoom: number, maxZoom: number) => void;
+
+    /**
+     * Set the value for a layer's property
+     */
+    setLayoutProperty: (layerId: string, name: string, value: string) => void;
+
+    /**
+     * Set filter for specified style layer
+     */
+    setFilter: (layerId: string, filter: [] | null | undefined) => void;
+
+    /**
+     * Set size of the tile
+     */
+    setSize: (size: [number, number]) => void;
+
+    /**
+     * Set the center of the map
+     */
+    setCenter: (center: [number, number]) => void;
+
+    /**
+     * Set zoom of the map
+     */
+    setZoom: (zoom: number) => void;
+
+    /**
+     * Set bearing (rotation) of map
+     */
+    setBearing: (bearing: number) => void;
+
+    /**
+     * Set pitch (tilt angle) of map
+     */
+    setPitch: (pitch: number) => void;
+
+    /**
+     * Set light value of map
+     */
+    setLight: (light: any) => void;
+
+    /**
+     * Set axonometric view of map
+     */
+    setAxonometric: (state: boolean) => void;
+
+    /**
+     * Set X skew of map
+     */
+    setXSkew: (x: number) => void;
+
+    /**
+     * Set Y skew of map
+     */
+    setYSkew: (y: number) => void;
+  }
+}