143 lines
5.9 KiB
Markdown
143 lines
5.9 KiB
Markdown
# Linux
|
|
|
|
This guide explains how to get started building and running MapLibre Native on Linux. The guide focusses on a Ubuntu 22.04. The build process should give you a set of `.a` files that you can use to include MapLibre Native in other C++ projects, as well as a set of executables that you can run to render map tile images and test the project.
|
|
|
|
## Clone the repo
|
|
|
|
First, clone the repository. This repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), that are required to build the project.
|
|
|
|
```bash
|
|
git clone --recurse-submodules -j8 https://github.com/maplibre/maplibre-native.git
|
|
cd maplibre-native
|
|
```
|
|
|
|
## Requirements
|
|
### Building without Docker
|
|
|
|
```bash
|
|
# Install build tools
|
|
apt install clang cmake ccache ninja-build pkg-config
|
|
|
|
# Install system dependencies
|
|
apt install libcurl4-openssl-dev libglfw3-dev libuv1-dev libpng-dev libicu-dev libjpeg-turbo8-dev libwebp-dev xvfb
|
|
```
|
|
|
|
Optional: `libsqlite3-dev` (also available as vendored dependency).
|
|
|
|
### Building with Docker
|
|
|
|
You can use a Docker container to build MapLibre Native. A `Dockerfile` that installes the required dependencies when the image is built is provided in this directory.
|
|
|
|
```bash
|
|
# Build docker image from the repo root
|
|
docker build -t maplibre-native-image -f platform/linux/Dockerfile .
|
|
|
|
# Run docker image as the current user.
|
|
# This ensures that the files created in the container are owned by the current user.
|
|
docker run --rm -it -v "$PWD:/code/" -u $(id -u):$(id -g) maplibre-native-image
|
|
```
|
|
|
|
You can safely ignore this type of message and a missing username. It happens if your linux user was not the first one created on the system.
|
|
|
|
```
|
|
groups: cannot find name for group ID ....
|
|
I have no name!@...:/root$ `
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
# Run from the root of the project to init the build
|
|
cmake -B build -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=RelWithDebInfo -DMLN_WITH_CLANG_TIDY=OFF -DMLN_WITH_COVERAGE=OFF -DMLN_DRAWABLE_RENDERER=ON -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON
|
|
|
|
# Build mbgl-render using all available CPUs
|
|
cmake --build build --target mbgl-render -j $(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null)
|
|
```
|
|
|
|
|
|
## Running `mbgl-render`
|
|
Running `mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json` should produce a map tile image with the default MapLibre styling from [the MapLibre demo](https://maplibre.org/).
|
|
|
|
|
|
|
|
### Outside of Docker
|
|
|
|
Render output image using default MapLibre demo tiles server. You can run this binary on your host machine even if you built it inside a Docker container.
|
|
|
|
```bash
|
|
./build/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png
|
|
xdg-open out.png
|
|
```
|
|
|
|
### Inside Docker
|
|
|
|
If you run `mbgl-render` inside a Docker or on a remote headless server, you will likely get this error because there is no X server running in the container.
|
|
|
|
> `Error: Failed to open X display.`
|
|
|
|
You'll need to simulate an X server to do any rendering. Install `xvfb` and `xauth` and run the following command:
|
|
|
|
```bash
|
|
xvfb-run -a ./build/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png
|
|
```
|
|
|
|
### Using your own style/tiles
|
|
|
|
You can also use the `mbgl-render` command to render images from your own style or tile set. To do so, you will need a data source and a style JSON file.
|
|
|
|
For the purposes of this exercise, you can use the `zurich_switzerland.mbtiles` from [here](https://github.com/acalcutt/tileserver-gl/releases/download/test_data/zurich_switzerland.mbtiles), and [this](https://gist.github.com/louwers/d7607270cbd6e3faa05222a09bcb8f7d) following `style.json` file. Download both by running the commands below.
|
|
|
|
```
|
|
wget https://github.com/acalcutt/tileserver-gl/releases/download/test_data/zurich_switzerland.mbtiles
|
|
wget https://gist.githubusercontent.com/louwers/d7607270cbd6e3faa05222a09bcb8f7d/raw/4e9532e1760717865df8aeff08f9bcf100f9e8c4/style.json
|
|
```
|
|
|
|
Note that this style is totally inadequate for any real use beyond testing your custom setup. Replace the source URL `mbtiles:///path/to/zurich_switzerland.mbtiles` with the actual path to your `.mbtiles` file. You can use this command if you downloaded both files to the working directory:
|
|
|
|
```bash
|
|
sed -i "s#/path/to#$PWD#" style.json
|
|
```
|
|
|
|
Next, run the following command.
|
|
|
|
```bash
|
|
./build/bin/mbgl-render --style style.json --output out.png
|
|
```
|
|
|
|
This should produce an `out.png` image in your current directory with a barebones image of the world.
|
|
|
|
|
|
|
|
### Running the render tests
|
|
|
|
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 used to be stored in the MapLibre GL JS repository, which means that GL JS and Native are mostly pixel-identical in their rendering.
|
|
|
|
The directory structure of the render tests looks like:
|
|
|
|
```
|
|
metrics/
|
|
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 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"
|
|
```
|
|
|
|
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`.
|