tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Linux docs, add to Developer Documentation (#3451)

Browse Source 
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Bart Louwers
2025-05-13 14:09:43 +02:00
committed by GitHub
parent 6e9189d3ba
commit c43c00d492
8 changed files with 189 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
CMakePresets.json
View File

@@ -76,16 +76,31 @@
} }
}, },
{ {
"name": "linux-opengl", "name": "linux",
"binaryDir": "${sourceDir}/build-linux-opengl", "hidden": true,
"generator": "Ninja", "generator": "Ninja",
"cacheVariables": { "cacheVariables": {
"CMAKE_SYSTEM_NAME": "Linux", "CMAKE_SYSTEM_NAME": "Linux",
"CMAKE_CXX_COMPILER_LAUNCHER": "ccache", "CMAKE_CXX_COMPILER_LAUNCHER": "ccache",
"MLN_WITH_METAL": "OFF", "MLN_WITH_METAL": "OFF",
"MLN_WITH_OPENGL": "ON", "MLN_WITH_OPENGL": "OFF",
"MLN_WITH_VULKAN": "OFF",
"CMAKE_C_COMPILER": "clang", "CMAKE_C_COMPILER": "clang",
"CMAKE_CXX_COMPILER": "clang++" "CMAKE_CXX_COMPILER": "clang++",
"CMAKE_BUILD_WITH_INSTALL_RPATH": "ON",
"CMAKE_BUILD_TYPE": "RelWithDebInfo",
"MLN_WITH_CLANG_TIDY": "OFF",
"MLN_WITH_WAYLAND": "ON",
"MLN_WITH_X11": "OFF"
}
},
{
"name": "linux-opengl",
"binaryDir": "${sourceDir}/build-linux-opengl",
"generator": "Ninja",
"inherits": "linux",
"cacheVariables": {
"MLN_WITH_OPENGL": "ON"
} }
}, },
{ {
@@ -98,11 +113,11 @@
{ {
"name": "linux-vulkan", "name": "linux-vulkan",
"binaryDir": "${sourceDir}/build-linux-vulkan", "binaryDir": "${sourceDir}/build-linux-vulkan",
"generator": "Ninja", "inherits": "linux",
"inherits": "linux-opengl",
"cacheVariables": { "cacheVariables": {
"MLN_WITH_OPENGL": "OFF", "MLN_WITH_VULKAN": "ON",
"MLN_WITH_VULKAN": "ON" "MLN_WITH_WAYLAND": "OFF",
"MLN_WITH_X11": "ON"
} }
}, },
{ {

42
docker/README.md
View File

@@ -1,43 +1,3 @@
# Building with Docker # Building with Docker
These steps will allow you to compile code as described [platform/linux/README.md](../platform/linux/README.md) using a Docker container. All the steps should be executed from the root of the repository. Refer to the guide in the [MapLibre Developer Documentation](https://maplibre.org/maplibre-native/docs/book/platforms/linux/using-docker.html) to learn how to build MapLibre Native inside a Docker container.
> [!IMPORTANT]
> Not all platform builds are currently supported. Docker builds are a work in progress.
> [!IMPORTANT]
> You cannot build MapLibre native using both Docker and host methods at the same time. If you want to switch, you need to clean the repository first, e.g. by using this command:
>
> ```bash
> git clean -dxfi -e .idea -e .clwb -e .vscode
> ```
### Build Docker Image
You must build your own Docker image, specific with your user and group IDs to ensure file permissions stay correct.
```bash
# Build docker image from the repo __root__
# Specifying USER_UID and USER_GID allows container to create files with the same owner as the host user,
# and avoids having to pass -u $(id -u):$(id -g) to docker run.
docker build \
-t maplibre-native-image \
--build-arg USER_UID=$(id -u) \
--build-arg USER_GID=$(id -g) \
-f docker/Dockerfile \
docker
```
## Run Docker Container
```bash
# Run all build commands using the docker container.
# You can also execute build commands from inside the docker container by starting it without the build command.
docker run --rm -it -v "$PWD:/app/" -v "$PWD/docker/.cache:/home/ubuntu/.cache" maplibre-native-image
```
You can also use the container to run just one specific commands, e.g. `cmake` or `bazel`. Any downloaded dependencies will be cached in the `docker/.cache` directory.
```bash
docker run --rm -it -v "$PWD:/app/" -v "$PWD/docker/.cache:/home/ubuntu/.cache" maplibre-native-image cmake ...
```

2
docs/mdbook/src/SUMMARY.md
View File

@@ -14,6 +14,8 @@
- [Release](./platforms/ios/release.md) - [Release](./platforms/ios/release.md)
- [Development Apps](./platforms/ios/dev-apps.md) - [Development Apps](./platforms/ios/dev-apps.md)
- [macOS](./platforms/macos/README.md) - [macOS](./platforms/macos/README.md)
- [Linux](./platforms/linux/README.md)
- [Using Docker](./platforms/linux/using-docker.md)
- [Release Policy](./release-policy.md) - [Release Policy](./release-policy.md)

119
docs/mdbook/src/platforms/linux/README.md Normal file
View File

@@ -0,0 +1,119 @@
# Linux
This guide explains how to get started building and running MapLibre Native on Linux. The guide focusses on a Ubuntu 22.04 or later. 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
```bash
# Install build tools
apt install build-essential 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` (when not found will use SQLite as vendored dependency).
When using Wayland (now default for `linux-opengl` preset): `libegl1-mesa-dev`.
## Build with CMake
```bash
cmake --preset linux-opengl
cmake --build build-linux-opengl --target mbgl-render
```
## 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/).
![Sample image of world from mbgl-render command](images/sample-maplibre-style-mbgl-render-out.png)
```bash
./build-linux-opengl/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png
xdg-open out.png
```
### Headless rendering
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-linux-opengl/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-linux-opengl/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.
![Sample image of world from mbgl-render command](images/sample-barebones-mbgl-render-out.png)
### Running the render tests
> [!TIP]
> For more information on the render tests see the [dedicated Render Tests article](../../render-tests.md).
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-linux-opengl/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json
```
Or a single test with:
```
./build-linux-opengl/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`.

0
misc/sample-barebones-mbgl-render-out.png → docs/mdbook/src/platforms/linux/images/sample-barebones-mbgl-render-out.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 39 KiB

0
misc/sample-maplibre-style-mbgl-render-out.png → docs/mdbook/src/platforms/linux/images/sample-maplibre-style-mbgl-render-out.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 100 KiB

After

Width:  |  Height:  |  Size: 100 KiB

43
docs/mdbook/src/platforms/linux/using-docker.md Normal file
View File

@@ -0,0 +1,43 @@
# Building with Docker
These steps will allow you to compile code as described [here](./README.md) using a Docker container. All the steps should be executed from the root of the repository.
> [!IMPORTANT]
> Not all platform builds are currently supported. Docker builds are a work in progress.
> [!IMPORTANT]
> You cannot build MapLibre native using both Docker and host methods at the same time. If you want to switch, you need to clean the repository first, e.g. by using this command:
>
> ```bash
> git clean -dxfi -e .idea -e .clwb -e .vscode
> ```
### Build Docker Image
You must build your own Docker image, specific with your user and group IDs to ensure file permissions stay correct.
```bash
# Build docker image from the repo __root__
# Specifying USER_UID and USER_GID allows container to create files with the same owner as the host user,
# and avoids having to pass -u $(id -u):$(id -g) to docker run.
docker build \
-t maplibre-native-image \
--build-arg USER_UID=$(id -u) \
--build-arg USER_GID=$(id -g) \
-f docker/Dockerfile \
docker
```
## Run Docker Container
```bash
# Run all build commands using the docker container.
# You can also execute build commands from inside the docker container by starting it without the build command.
docker run --rm -it -v "$PWD:/app/" -v "$PWD/docker/.cache:/home/ubuntu/.cache" maplibre-native-image
```
You can also use the container to run just one specific commands, e.g. `cmake` or `bazel`. Any downloaded dependencies will be cached in the `docker/.cache` directory.
```bash
docker run --rm -it -v "$PWD:/app/" -v "$PWD/docker/.cache:/home/ubuntu/.cache" maplibre-native-image cmake ...
```

121
platform/linux/README.md
View File

@@ -1,122 +1,3 @@
# Linux # 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. Refer to the guide in the [MapLibre Native Developer Documentation](https://maplibre.org/maplibre-native/docs/book/platforms/linux/index.html) to get started with developing MapLibre Native on Linux.
## 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 build-essential 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
See instructions in [docker/README.md](../../docker/README.md) to build in a docker container.
## 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 -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/).
![Sample image of world from mbgl-render command](/misc/sample-maplibre-style-mbgl-render-out.png)
```bash
./build/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png
xdg-open out.png
```
### Headless rendering
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.
![Sample image of world from mbgl-render command](/misc/sample-barebones-mbgl-render-out.png)
### 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`.