feat(linux): vendor static deps for portable shared libraries

[jamesarich]

Description

Add a new MLN_LINUX_STATIC_DEPS CMake option that vendors zlib, libpng, libjpeg-turbo, libwebp, libuv, and bzip2 as static libraries built from source. When enabled, these are amalgamated into mbgl-core via armerge, producing a self-contained shared library with no runtime dependency on distro-specific library versions.

Problem

Published Linux shared libraries (e.g. JNI .so for maplibre-compose) dynamically link against system libraries at build time. When users run on a different distro or version, symbol mismatches cause UnsatisfiedLinkError crashes — particularly ICU (version-mangled C++ symbols), libpng, and zlib. This is the blocker described in maplibre/maplibre-compose#627.

Approach

• FetchContent for zlib 1.3.1, libpng 1.6.44, libwebp 1.5.0, libuv 1.50.0
• FetchContent_Populate + manual build for bzip2 1.0.8 (no CMakeLists.txt)
• ExternalProject for libjpeg-turbo 3.1.0 (blocks add_subdirectory())
• System curl kept dynamic (stable ABI, complex dependency tree)
• Builtin ICU forced on when vendoring (maplibre-native already has a vendored ICU)
• -Wl,--exclude-libs,ALL hides vendored symbols from the final .so exports
• FreeType PNG/BZip2 features disabled when vendoring to prevent system lib leakage

All vendored deps inherit CMAKE_POSITION_INDEPENDENT_CODE=ON from the root CMakeLists.txt. The existing system-deps path (MLN_LINUX_STATIC_DEPS=OFF, the default) is completely unchanged.

Files changed

• CMakeLists.txt — Added option(MLN_LINUX_STATIC_DEPS) declaration
• platform/linux/cmake/vendored_deps.cmake — New: downloads, builds, and configures all vendored deps with license metadata
• platform/linux/linux.cmake — Conditional paths for vendored vs system deps, armerge enforcement, amalgamation
• vendor/freetype.cmake — Disable PNG/BZip2 when vendoring (gated behind CMAKE_SYSTEM_NAME STREQUAL "Linux" AND MLN_LINUX_STATIC_DEPS)
• CHANGELOG.md — Added entry

Test plan

Linux (Ubuntu 25.04, GCC 15.2, CMake 4.2.3):

• MLN_LINUX_STATIC_DEPS=ON: full build succeeds, .so has no dynamic deps on vendored libs (ldd clean), no leaked vendored symbols (nm -D clean)
• MLN_LINUX_STATIC_DEPS=OFF: CMake configure succeeds, system-deps path unchanged
• Built .so loads and renders map tiles in a Compose Desktop app

Cross-platform:

• No changes to macOS/Windows/iOS/Android build paths (all gated behind MLN_LINUX_STATIC_DEPS)
• vendor/freetype.cmake change additionally gated behind CMAKE_SYSTEM_NAME STREQUAL "Linux"

Requirements

When MLN_LINUX_STATIC_DEPS=ON:

• armerge must be installed (cargo install armerge) — clear FATAL_ERROR if missing
• Clang compiler recommended (consistent with existing Linux presets)

Breaking changes

None. The option defaults to OFF, preserving existing behavior.

[jamesarich]

Hi @sargunv - we (Meshtastic) are interested in potentially leveraging maplibre in our KMP projects. I'd like to help unblock Desktop JVM maps parity - let me know how we can assist!

[jamesarich]

Closing — this should target maplibre/maplibre-native instead. Re-opening there.

[sargunv]

I'd like to help unblock Desktop JVM maps parity - let me know how we can assist!

Hey, I'd love some help on this front. Are you on the OSMUS slack workspace?

The main issue for the desktop JVM parity is the native core integration -- I'm somewhat amateur at modern C++ and very amateur at C++ <> JVM integration and OpenGL/Vulkan/Metal, just figuring it all out as I go. If you have skills/experience there, that's would be extremely helpful.

Some immediate issues, off the top of my head:

• I think some of the ways I'm doing memory management across the JVM / C++ boundary are unsound; would love a review or improvements there
• Linux support right now is broken with a segfault (and my main workstation these days is Linux). I haven't tracked down this particular bug yet
• Related to your recent PRs: would be nice to build MapLibre Compose on MapLibre Native's prebuilt binaries, so the dev ex is a bit easier
• Most of the missing parity work is in style support. Implementing all the layer/source/image/etc adapters I think is mostly mechanical work and not directly blocked by any of the foundational stuff above (I expect recent frontier LLMs can probably do this part well enough)

(It's been a few months since I worked on desktop stuff though, so my memory might be wrong on some things)

But the long term goal is to make the MapLibre Compose <> native core integration stable and complete enough that it becomes the path for Android and iOS targets too, rather than the platform-specific SDKs we integrate with today.

[jamesarich]

Are you on the OSMUS slack workspace

Nope, but you can find me on the Meshtastic Discord @olm3c

Most of the missing parity work is in style support. Implementing all the layer/source/image/etc adapters I think is mostly mechanical work and not directly blocked by any of the foundational stuff above (I expect recent frontier LLMs can probably do this part well enough)

I'll take a poke around, thanks for the response!