Skip to content

Overview

Most development happens on Linux and macOS. CI tests Windows, but the local Windows setup gets little use and may be broken.

mise manages the toolchain. Install it, then run mise trust and mise bootstrap --yes. On Ubuntu and Fedora, bootstrap also installs the system packages. On other Linux distributions, install the equivalents of the packages in .config/mise.linux.toml. On macOS, install Xcode 26. On Windows, install these first:

Terminal window
winget install --exact --id Git.Git
winget install --exact --id KhronosGroup.VulkanSDK
winget install --exact --id LLVM.LLVM
winget install --exact --id Microsoft.VisualStudio.2022.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --add Microsoft.VisualStudio.Component.VC.Tools.ARM64"

mise run test builds the native library for this machine and runs its C tests. mise run //bindings/<lang>:test tests one binding against that build. Pass a preset name to build for another target, such as linux-gnu-x64-vulkan or macos-arm64-metal. CMakePresets.json lists them.

After you change a header, run mise run bindings:generate. mise run check runs the linters, and mise run fix fixes what it can; the pre-commit hook does the same for staged files. mise run //docs:dev serves this site. mise tasks --all lists everything else.

These SDKs are large, so they’re opt-in. Install one with mise -E android install, -E ohos, or -E emscripten, and pass the same -E to every later command, or set MISE_ENV. After an NDK update, run mise run clean <preset> for each Android preset.

The browser example in examples/browser, which the site serves as its live demo, loads the TypeScript binding’s browser modules. Build them with mise -E emscripten run //bindings/typescript:build emscripten-wasm32-webgl, and again for emscripten-wasm32-webgpu, then serve the example with mise run //examples/browser:dev. The release puts it in the site.

Tests that need a device get one from devices-cli, which mise installs. mise run test boots an emulator or simulator for Android, OpenHarmony, iOS, tvOS, and visionOS, or a virtual machine for FreeBSD, and leaves it running. devices-cli release stops this worktree’s devices. Android emulators need KVM. To test on your own Android device, set ANDROID_SERIAL.

The Windows presets build on Linux. mise -E msvc install downloads the MSVC runtime and the Windows SDK, and accepts Microsoft’s license for them. Install Proton Experimental from Steam, then run tests with mise -E msvc run test windows-x64-vulkan. Proton’s launcher gives the prefix the fonts, ICU, and DXVK that .NET and WPF need. To use another Wine, set WINE to its executable. Wine isn’t Windows: when results differ, Windows CI is right.

On Windows, install MSYS2 and run this in its MINGW64 shell:

Terminal window
pacman -S --needed mingw-w64-x86_64-clang mingw-w64-x86_64-llvm mingw-w64-x86_64-pkgconf

Then run tasks from PowerShell with -E msys2, such as mise -E msys2 run test mingw-x64-wgl. Set MLN_FFI_MSYS2_ROOT if the MINGW64 prefix isn’t C:/msys64/mingw64.

The FreeBSD presets build on Linux, and their tests run in a virtual machine. Install QEMU and OVMF, and make sure you can access /dev/kvm.

These presets build on any Linux host, and their tests run under QEMU. Install Docker, then run bash scripts/setup-qemu.sh to install and register the emulators. Run it again after a reboot.

mise run bench measures what the C API costs its callers: CPU time, allocations, memory, latency, and frame pacing. It runs the cases in benchmarks/, whose comments say what each one times. The first run downloads pinned map data into build/bench/fixtures, and no case uses the network.

mise run bench:compare <ref> compares the working tree with a Git ref, or another build of this repository, such as one with other CMake options. A change gets a verdict only when it’s over 5% and unlikely to be noise. The comparison also reports how much the last frames of the two sides differ, so a side that’s faster because it draws less shows up. mise run bench -- --help and mise run bench:compare -- --help list the options.

Compare on an idle machine. To see how much your machine’s numbers vary, compare a commit with itself, which should give no verdicts. Pass a preset and the same -E as for the tests to run on another target. Emulators and software rasterizers don’t show what a device costs.

Each patch in patches/maplibre-native/ is a change we also send upstream. Start it with why it’s needed and a link to the upstream issue. Once you open the upstream pull request, add Upstream: and its link.

mise deps resets the submodule and applies the patches in filename order. Any edit in the submodule that isn’t in a patch is lost.

To add a patch, commit the patched submodule, make your change, and save the diff:

Terminal window
mise deps
git -C third_party/maplibre-native add -A
git -C third_party/maplibre-native commit -m baseline
# edit third_party/maplibre-native
git -C third_party/maplibre-native diff --ignore-submodules \
> patches/maplibre-native/0067-short-name.patch
# write the header above the diff
mise deps

To edit an existing patch:

  1. Reset the submodule to its pin, and apply only the patches before it with git apply.
  2. Commit, then apply the patch you’re editing.
  3. Make your change, and save the diff over the patch.
  4. Run mise deps to check that the later patches still apply.

Test a patch with upstream’s tests in its test/ tree. Build and run them as the MapLibre Native docs explain, after you initialize the submodules they need, such as googletest, which mise deps skips. CI doesn’t run these tests, so list the ones you ran in the pull request.

Rubberstamp labels each pull request and picks which CI units it runs, from .config/rubberstamp.yml. main runs every unit after merge. To run a unit that a pull request skipped, start a manual run and list it by its name under ci.units:

Terminal window
gh workflow run CI --ref <branch> -f 'units=["mingw-arm64"]'

To debug on a CI runner, use a Blacksmith Testbox. Your Blacksmith account needs access to the MapLibre organization. Run these from the repository root, since the testbox copies the current directory.

Terminal window
blacksmith auth login
blacksmith testbox warmup .github/workflows/blacksmith-testbox-linux-x64.yml --job linux-x64 --ref <branch>
blacksmith testbox run --id <id> "mise run test linux-gnu-x64-egl"

Builds fail on the testbox unless you prefix them with env -u SCCACHE_BUCKET -u SCCACHE_ENDPOINT -u SCCACHE_REGION -u SCCACHE_S3_USE_SSL.

mise run ci:release-version --next prints the next version. To release, push a signed, annotated tag on a main commit whose CI passed. Its message is MapLibre Native FFI <version>, a blank line, and the release notes. The release agent skill can draft the notes.

Kotlin snapshots publish to Maven Central from main daily. To publish one now, run the Publish snapshots workflow. Before a new PyPI distribution’s first release, register its pending trusted publisher on PyPI. npm accepts a trusted publisher only for a package that exists, so publish a new npm package’s first version by hand with a granular token. Then run npm trust github <package> --repo=maplibre/maplibre-native-ffi --file=release.yml --env=npm --allow-publish=true from an interactive npm login session, because npm refuses trust changes from tokens that bypass two-factor authentication.

A release deploys the docs to GitHub Pages and the Go preset modules’ proxy to the go branch of the Cloudflare Pages project. If either deploy didn’t run, run the Deploy release sites workflow on main. Its docs quote the latest release tag’s version. mise run go-native:proxy writes the proxy’s site locally, to build/go-native-proxy.