From 529ed981abb1f6ef6533810e5962b0a4ba3b1c33 Mon Sep 17 00:00:00 2001 From: Yuri Astrakhan Date: Mon, 22 Jul 2024 06:08:14 -0400 Subject: [PATCH] Improve linux build docs (#2639) Co-authored-by: Bart Louwers --- .gitignore | 4 ++ platform/linux/Dockerfile | 34 +++++++-- platform/linux/Dockerfile.dockerignore | 3 + platform/linux/README.md | 96 ++++++++++++++------------ 4 files changed, 89 insertions(+), 48 deletions(-) create mode 100644 platform/linux/Dockerfile.dockerignore diff --git a/.gitignore b/.gitignore index df4ef0fdc..bad82f1a9 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/platform/linux/Dockerfile b/platform/linux/Dockerfile index f7e536647..b55061954 100644 --- a/platform/linux/Dockerfile +++ b/platform/linux/Dockerfile @@ -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 diff --git a/platform/linux/Dockerfile.dockerignore b/platform/linux/Dockerfile.dockerignore new file mode 100644 index 000000000..2ce0f5f39 --- /dev/null +++ b/platform/linux/Dockerfile.dockerignore @@ -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. +* diff --git a/platform/linux/README.md b/platform/linux/README.md index 520a98e1d..7a54a363c 100644 --- a/platform/linux/README.md +++ b/platform/linux/README.md @@ -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. @@ -131,4 +139,4 @@ 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`. \ No newline at end of file +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`.