Zig

Install

Add the package from a release. It needs Zig 0.17.

zig fetch --save https://github.com/maplibre/maplibre-native-ffi/releases/download/v0.202611.0/maplibre-native-ffi-zig.tar.gz

build.zig

const maplibre = b.dependency("maplibre_native_ffi", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("maplibre_native_ffi", maplibre.module("maplibre_native_ffi"));

When it builds, the package downloads the C library for your target.

Your executable loads the library at run time, from its own directory on Windows, and from ../lib elsewhere. Install the shared libraries from the package’s prefix there:

build.zig

const libraries = if (target.result.os.tag == .windows) "bin" else "lib";
b.installDirectory(.{
    .source_dir = maplibre.namedLazyPath("prefix").path(b, libraries),
    .install_dir = .{ .custom = libraries },
    .install_subdir = "",
    .include_extensions = &.{ ".dll", ".so", ".dylib" },
});

Choose a backend

The package uses your platform’s default backend. To choose another, pass .backend to the dependency: .opengl, .metal, or .vulkan.

build.zig

const maplibre = b.dependency("maplibre_native_ffi", .{
    .target = target,
    .optimize = optimize,
    .backend = .opengl,
});

Windows

Zig targets MinGW on Windows by default. To use MSVC instead, build with -Dtarget=x86_64-windows-msvc.

Mac Catalyst

Mac Catalyst builds target aarch64-maccatalyst.

Android

Zig has no libc for Android, so an Android build uses the NDK’s. Pass the dependency .@"system-root" as the NDK’s sysroot directory, and .@"target-libc" as a libc file in the format that zig libc prints. The file names usr/include and its target subdirectory as the include directories, and the target’s usr/lib/<target>/<API level> as both crt_dir and cc_dir. Call setLibCFile with the same file on each artifact that imports the module. Ship libmaplibre-native-c.so in the app’s lib/<abi> directory.

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

src/main.zig

try maplibre.initAndroid(jni_env, context, null);

Use your own build

To link a C library that you built, pass its install prefix to the dependency as local-build. It must be built for the same target. A path from the command line must be absolute. A Git dependency on the package always needs one.

build.zig

const maplibre = b.dependency("maplibre_native_ffi", .{
    .target = target,
    .optimize = optimize,
    .@"local-build" = b.option(std.Build.LazyPath, "local-build", "MapLibre Native C library build"),
});