Rust

Install

Add the crate from crates.io. It needs Rust 1.85 or later.

cargo add maplibre-native-ffi

When it builds, the crate downloads the C library for your target and links it statically.

Choose a backend

The crate uses your platform’s default backend. To choose another, enable one feature: opengl, metal, vulkan, or webgpu. A feature on a target-specific dependency applies only to that target:

Cargo.toml

[dependencies]
maplibre-native-ffi = "0.202611.0"

[target.'cfg(target_os = "android")'.dependencies]
maplibre-native-ffi = { version = "0.202611.0", features = ["vulkan"] }

Windows with MinGW

For x86_64-pc-windows-gnu, link with MSYS2’s MINGW64 Clang and LLD (-C link-arg=-fuse-ld=lld), and keep MINGW64’s bin directory on PATH for its runtime DLLs.

Browser

A browser build targets wasm32-unknown-emscripten. It needs nightly Rust to build the standard library with atomics, and link options from the C library. The maplibre-native-ffi-sys docs list them.

Android

Initialize the library once per process, before you create a runtime, with the calling thread’s JNI environment and an Android Context:

src/lib.rs

unsafe { maplibre_native_ffi::init_android(jni_env, context)? };

Use your own build

To link a C library that you built or downloaded, set MAPLIBRE_NATIVE_FFI_LOCAL_BUILD to the absolute path of its install prefix. It must be built for the same target. A Git or path dependency on the crate always needs one.

.cargo/config.toml

[env]
MAPLIBRE_NATIVE_FFI_LOCAL_BUILD = { value = "../maplibre-native-ffi/build/macos-arm64-metal/install", relative = true }

Download from a mirror

If your builds can’t reach GitHub, copy the release’s archives to a server of your own, in a directory named after the release tag, and set MAPLIBRE_NATIVE_FFI_RELEASE_URL to the server’s base URL. The crate still checks each archive against the digest that it pinned at release.