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

Improve linux build docs (#2639)

Browse Source 
Co-authored-by: Bart Louwers <bart.louwers@gmail.com>
This commit is contained in:
Yuri Astrakhan
2024-07-22 06:08:14 -04:00
committed by GitHub
parent d15de92158
commit 529ed981ab
4 changed files with 89 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -51,3 +51,7 @@ __generated__
/metrics/integration/query-tests/**/actual.json
/metrics/integration/render-tests/**/actual.png
/metrics/integration/render-tests/**/diff.png
cache.sqlite
cache.sqlite-journal
out.png

34
platform/linux/Dockerfile
View File

@@ -1,7 +1,33 @@
FROM ubuntu:22.04
RUN apt-get update && \
DEBIAN_FRONTEND=noninteractive apt-get install -y libcurl4-openssl-dev libglfw3-dev libuv1-dev libpng-dev libicu-dev libjpeg-turbo8-dev libwebp-dev xvfb clang git cmake ccache ninja-build pkg-config && \
rm -rf /var/lib/apt/lists/*
# When running docker with -u flag, the user should exist in the container to avoid various warnings
RUN groupadd -f user && useradd -m -g user user
WORKDIR /root
# Install build tools and dependencies
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y \
apt-transport-https \
curl \
gnupg \
&& curl -fsSL https://bazel.build/bazel-release.pub.gpg | gpg --dearmor >bazel-archive-keyring.gpg \
&& mv bazel-archive-keyring.gpg /usr/share/keyrings \
&& echo "deb [arch=amd64 signed-by=/usr/share/keyrings/bazel-archive-keyring.gpg] https://storage.googleapis.com/bazel-apt stable jdk1.8" | tee /etc/apt/sources.list.d/bazel.list \
&& apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y \
bazel \
libcurl4-openssl-dev \
libglfw3-dev \
libuv1-dev \
libpng-dev \
libicu-dev \
libjpeg-turbo8-dev \
libwebp-dev \
xvfb \
clang \
git \
cmake \
ccache \
ninja-build \
pkg-config
WORKDIR /code

3
platform/linux/Dockerfile.dockerignore Normal file
View File

@@ -0,0 +1,3 @@
# Exclude everything because we expect users to mount this dir as a volume,
# so none of this repos' content should be part of the docker build context.
*

94
platform/linux/README.md
View File

@@ -2,39 +2,7 @@
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.
## Requirements
The following system libraries need to be installed.
```bash
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).
The following tools need to be available.
```bash
apt install clang git cmake ccache ninja-build pkg-config
```
## 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.
Build image with:
```bash
# in platform/linux
docker build -t maplibre-native-image .
```
Run image with:
```bash
# in repo root directory
docker run --rm -it -v "$(pwd)":/root/ maplibre-native-image
```
## Build
## 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.
@@ -43,36 +11,76 @@ git clone --recurse-submodules -j8 https://github.com/maplibre/maplibre-native.g
cd maplibre-native
```
To create the build, run the following commands from the root of the project:
## Requirements
### Building without Docker
```bash
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
# 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)
```
## `mbgl-render`
If all went well, there should now be a `./build/bin/mbgl-render` binary that you can run to generate map tile images. To test that it is working properly, run the following command.
## 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)
### 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
```
> I get an error `Error: Failed to open X display.` when I run this command.
### Inside Docker
If you're setting up MapLibre Native on a headless server (i.e. one without a display), you'll need to simulate an X server to do any rendering. Install `xvfb` and `xauth` and run the following command:
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
```
This should produce an `out.png` 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)
### 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.