This is been rewritten to include:
- How to build for the platforms we support.
- Acceptance criteria for code contributions (style, static asserts)
- How to run the unit tests.
- How to run the benchmarks.
- How to rebaseline baselines metrics.
- How to use GL Native as a 3rd party library in your project.
To check that the output of the rendering is correct, we compare actual rendered PNGs for simple styles with expected PNGs. The content of the tests is stored in the MapLibre GL JS submodule which means that GL JS and Native are in fact quasi pixel-identical in their rendering.
The directory sturcture of the render tests looks like:
maplibre-gl-js/
test/
integration/
render-tests/
<name-of-style-spec-feature>/
<name-of-feature-value>/
expected.png
style.json
After the render test run, the folder will also contain an actual.png
file and a diff.png
which is the difference between the expected and the actual image. There is a pixel difference threshold value which is used to decide if a render test passed or failed.
Run the following on linux to build the render test runner:
git submodule update --init --recursive --depth 1
sudo apt update
sudo apt install ccache cmake ninja-build pkg-config xvfb libcurl4-openssl-dev libglfw3-dev libuv1-dev g++-10 libc++-9-dev libc++abi-9-dev libpng-dev libgl1-mesa-dev libgl1-mesa-dri libjpeg-turbo8 libicu66 libjpeg-dev
cmake . -B build -G Ninja -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10
cmake --build build -j $(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null)
On linux, run all render tests with:
./build/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json
Or a single test with:
./build/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json --filter "render-tests/fill-visibility/visible"
On macOS, run all render tests with:
./build/mbgl-render-test-runner --manifestPath metrics/macos-xcode11-release-style.json
The render test results are summarized in a HTML website located next to the manifest file. For example, running metrics/linux-clang8-release-style.json
produces a summary at metrics/linux-clang8-release-style.html
.
MapLibre makes use of a common set of C++ files for iOS, macOS, Android, Linux & QT. See platform/default/src/mbgl/
,
or any of the platform make files:
platform/android/android.cmake
platform/ios/ios.cmake
platform/linux/linux.cmake
platform/macos/macos.cmake
platform/qt/qt.cmake
- Android developers can use Android Studio or
ndk-gdb
- iOS developers can use Xcode. See also Advanced Debugging with Xcode and LLDB.
- Android developers can review NDK logging at developer.android.com/ndk/reference/group/logging.
- iOS developers can review Logging at developer.apple.com/documentation/os/logging.
Add this to your header.
#include <iostream>
#include <sstream>
#define LOG_TAG "# MapLibre "
#ifdef __ANDROID__
#include <android/log.h>
#endif
Then you can use this sample code which compiles for both Android & Xcode.
std::stringstream message;
// Set your message to log.
message << LOG_TAG << __FUNCTION__ << " req->resource.url = " << req->resource.url << std::endl;
// Logs to Xcode console.
std::cout << message.str();
#ifdef __ANDROID__
// Logs to Android Logcat.
__android_log_print(ANDROID_LOG_DEBUG, LOG_TAG, "%s", message.str().c_str());
#endif
Which will log the following samples.
com.mapbox.mapboxsdk.testapp D/# MapLibre: online_file_source.cpp: # MapLibre: online_file_source.cpp activateRequest req->resource.url = https://api.maptiler.com/tiles/v3/tiles.json
MapLibre: online_file_source.cpp activateRequest req->resource.url = https://demotiles.maplibre.org/style.json
MapLibre makes use of several command line tools for local and cloud builds.
To see what targets exist you have to review the Makefile
, which can be tedious.
There is a better way with the Zsh. While in a folder with a Makefile
, you can type make
followed by hitting <tab>
twice.
cd platform/android
make android # <tab><tab>
# Example, Android make targets starting with `ap`
# apackage aproj
# ----
cd platform/ios
make ios # <tab><tab>
# Example, iOS make targets starting with `ios`
# ios ios-lint ios-sanitize ios-test
make macos # <tab><tab>
# Example, macOS make targets starting with `macos`
# macos macos-lint macos-test
To add this feature add the following to your zsh.
# open ~/.zprofile
# Autocomplete for `make` when in a directory
zstyle ':completion:*:*:make:*' tag-order 'targets'
autoload -Uz compinit && compinit
We are moving the Android SDK to Kotlin, which is backward compatible with Java, but if you need a Java version of the Android SDK there is a before-kotlin-port
tag available.