This library fully supports Qt 6.5 and newer. Qt 5.15 is fully supported only on desktop platforms, previous Qt 5 versions down to 5.6 only support widgets but not Qt Location.
Build basics
MapLibre Native for Qt uses CMake as its build system. Both the core and the bindings build in the same step. To speed-up the build, ninja and ccache are recommended. For Qt 6 using the qt-cmake wrapper instead of plain cmake makes building non-desktop platforms easier.
Note
To ensure that the git submodules are up to date first run:
git submodule update --init --recursive
Note
To make sure a correct version of Qt 6 is used, use the provided toolchain file with -DCMAKE_TOOLCHAIN_FILE="<path-to-qt>/lib/cmake/Qt6/qt.toolchain.cmake"
It is recommended to use CMake workflows as they are always up-to-date and cover all supported platforms.
Using CMake workflows
CMake workflow presets are provided for all supported platforms. Run the following command in the root directory to use a preset:
cmake --workflow --preset <preset>
for example
cmake --workflow --preset macOS-ccache
will run the macOS build with ccache enabled.
It is recommended to set QT_ROOT_DIR environment variable as the path to the Qt installation to be used, mainly for mobile platforms to use the correct Qt version.
For Android, the ANDROID_ABI environment variable should be set.
Supported release workflows
Platform
Qt6
Qt6 with ccache
Qt5
Qt5 with ccache
Linux
Linux
Linux-ccache
Linux-legacy
Linux-legacy-ccache
macOS
macOS
macOS-ccache
macOS-legacy
macOS-legacy-ccache
Windows
Windows
Windows-ccache
Windows-legacy
Windows-legacy-ccache
iOS
iOS
iOS-ccache
Android
Android
Android-ccache
WASM
WASM
WASM-ccache
Special workflows
Platform
Workflow
Description
Linux
Linux-coverage
Linux build with Qt6, ccache and code coverage
Linux
Linux-internal-icu
Linux build with Qt6 and internal ICU library (also with -ccache)
Linux
Linux-CI
Linux build with Qt6 and ccache for CI
Linux
Linux-legacy-CI
Linux build with Qt5 and ccache for CI
macOS
macOS-clang-tidy
macOS build with Qt6, ccache and clang-tidy
Platform specific build instructions
Linux
Installing Qt6 prerequisites
Alpine
sudo apk add \
ccache \
cmake \
g++ \
icu-dev \
ninja-build \
qt6-qtbase-dev \
qt6-qtlocation-dev \
samurai
Archlinux & Manjaro
sudo pacman -S \
ccache \
cmake \
gcc \
icu \
ninja \
qt6-base \
qt6-location
Fedora
sudo dnf install \
ccache \
cmake \
gcc-c++ \
libicu-devel \
ninja-build \
qt6-qtbase-devel \
qt6-qtlocation-devel
openSUSE
sudo zypper in \
ccache \
cmake \
gcc-c++ \
libicu-devel \
ninja \
qt6-base-private-devel \
qt6-location-private-devel \
qt6-quicktest-private-devel
Debian / Ubuntu
Debian 13 Trixie / Ubuntu 24.10 Oracular or newer: These releases have the minimum required Qt version pre-packaged, which can be used directly, but the qt6-location-dev package does not include the private headers and there is no qt6-location-private-dev package, which needs a workaround:
sudo apt update && sudo apt install -y \
build-essential \
ccache \
cmake \
g++ \
libicu-dev \
libxcb-xkb-dev \
ninja-build \
qt6-base-dev \
qt6-base-private-dev \
qt6-location-dev \
Install the private headers from the apropriate source files:
On Linux distribution versions where the minimum required Qt version is not met, or the private headers are not packaged the aqt tool can be used to install the right version of Qt with the needed private headers, but first the distribution specific package manager needs to be used to resolve dependencies of Qt.
Installing Qt dependencies
Debian 12 Bookworm / Linux Mint 22.1 Xia / Ubuntu 24.04 Noble or older:
Release binaries are build with -DCMAKE_BUILD_TYPE="Release".
Note that when using the standalone Qt installation the system version of the ICU library is still used. You should make sure that the system ICU is not too new as it may prevent your app from running on older versions of Linux. Alternatively you can use internally bundled ICU with the -DMLN_QT_WITH_INTERNAL_ICU=ON CMake option.
To replicate run:
mkdir build && cd build
cmake ../maplibre-native-qt -G Ninja \
-DCMAKE_BUILD_TYPE="Release" \
-DCMAKE_C_COMPILER_LAUNCHER="ccache" \
-DCMAKE_CXX_COMPILER_LAUNCHER="ccache" \
-DCMAKE_INSTALL_PREFIX="../install"
ninja
ninja install
macOS
Release binaries contain debug symbols. Additionally both Intel and ARM versions are supported and included. OS deployment target version is set to 12.0 for Qt 6 and 10.13 for Qt 5.
To replicate run:
mkdir build && cd build
cmake ../maplibre-native-qt -G Ninja \
-DCMAKE_BUILD_TYPE="RelWithDebInfo" \
-DCMAKE_C_COMPILER_LAUNCHER="ccache" \
-DCMAKE_CXX_COMPILER_LAUNCHER="ccache" \
-DCMAKE_INSTALL_PREFIX="../install" \
-DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" \
-DCMAKE_OSX_DEPLOYMENT_TARGET="12.0"
ninja
ninja install
Windows
Two separate release binaries are provided, one with release build and one with debug build. To achieve that Ninja Multi-Config generator is used.
Two separate release binaries are provided, one with release build and one with debug build. To achieve that Ninja Multi-Config generator is used. Both device and simulator builds are supported. OS deployment target version is set to 16.0.
Release binaries contain debug symbols. Each ABI is built separately.
To replicate, run:
mkdir build && cd build
cmake ../maplibre-native-qt -G Ninja \
-DCMAKE_BUILD_TYPE="RelWithDebInfo" \
-DCMAKE_C_COMPILER_LAUNCHER="ccache" \
-DCMAKE_CXX_COMPILER_LAUNCHER="ccache" \
-DCMAKE_INSTALL_PREFIX="../install" \
-DANDROID_ABI="arm64-v8a"
ninja
ninja install
WebAssembly (WASM)
No official binaries are provided for WebAssembly. You can build it yourself using the Emscripten toolchain. The Qt Location module has to be disabled as it is not supported.
