Overview
Set up
Section titled “Set up”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:
winget install --exact --id Git.Gitwinget install --exact --id KhronosGroup.VulkanSDKwinget install --exact --id LLVM.LLVMwinget install --exact --id Microsoft.VisualStudio.2022.BuildTools --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --add Microsoft.VisualStudio.Component.VC.Tools.ARM64"Everyday commands
Section titled “Everyday commands”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.
Other targets
Section titled “Other targets”Android, OpenHarmony, and Emscripten
Section titled “Android, OpenHarmony, and Emscripten”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.
Emulators and simulators
Section titled “Emulators and simulators”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.
Windows from Linux
Section titled “Windows from Linux”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:
pacman -S --needed mingw-w64-x86_64-clang mingw-w64-x86_64-llvm mingw-w64-x86_64-pkgconfThen 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.
FreeBSD
Section titled “FreeBSD”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.
RISC-V and LoongArch
Section titled “RISC-V and LoongArch”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.
Benchmarks
Section titled “Benchmarks”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.
Change the engine
Section titled “Change the engine”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:
mise depsgit -C third_party/maplibre-native add -Agit -C third_party/maplibre-native commit -m baseline# edit third_party/maplibre-nativegit -C third_party/maplibre-native diff --ignore-submodules \ > patches/maplibre-native/0067-short-name.patch# write the header above the diffmise depsTo edit an existing patch:
- Reset the submodule to its pin, and apply only the patches before it with
git apply. - Commit, then apply the patch you’re editing.
- Make your change, and save the diff over the patch.
- Run
mise depsto 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:
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.
blacksmith auth loginblacksmith 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.
Releases
Section titled “Releases”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.