diff --git a/platform/linux/README.md b/platform/linux/README.md index f755d3d49..9f42948a3 100644 --- a/platform/linux/README.md +++ b/platform/linux/README.md @@ -1,51 +1,44 @@ # Linux -A simple executable and test suite for Linux based on [MapLibre Native](../../README.md). - -This guide focuses on Debian and Ubuntu distributions. - -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. +This guide explains how to get started building and running MapLibre Native on Linux. The guide focusses on **Debian 11**, but should be adaptible to other distributions. 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. ## Prerequisites -The following dependencies are required to build MapLibre Native on Debian 11. +The following system libraries need to be installed. ```bash -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 +apt install libcurl4-openssl-dev libglfw3-dev libuv1-dev libpng-dev libicu-dev libjpeg62-turbo ``` -There are two required packages that are not available in the standard Debian package repository: `libjpeg-turbo8` and `libicu66`. You can install them by downloading and installing the `.deb` packages. +Optional: `libsqlite3-dev` (also available as vendored dependency). + +### Build tools + +The following tools need to be available. ```bash -wget http://archive.ubuntu.com/ubuntu/pool/main/libj/libjpeg-turbo/libjpeg-turbo8_2.0.3-0ubuntu1_amd64.deb -apt install ./libjpeg-turbo8_2.0.3-0ubuntu1_amd64.deb -wget http://archive.ubuntu.com/ubuntu/pool/main/i/icu/libicu66_66.1-2ubuntu2_amd64.deb -apt install ./libicu66_66.1-2ubuntu2_amd64.deb -``` - -On an Ubuntu based distribution, you may be able to install these using `apt`. - -```bash -apt install libjpeg-turbo8 libicu66 +apt install g++ git cmake ccache ninja-build pkg-config ``` ## Build -First, clone the repository. This repository uses git submodules, which are also required to build the project. +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 ``` -To create the build, run the following commands. +To create the build, run the following commands from the root of the project. ```bash -cmake . -B build -G Ninja -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_C_COMPILER=gcc-10 -DCMAKE_CXX_COMPILER=g++-10 +cmake -S . -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) ``` -If all went well, there should now be a `maplibre-native/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. +## `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. ```bash ./build/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png @@ -53,7 +46,7 @@ If all went well, there should now be a `maplibre-native/build/bin/mbgl-render` > I get an error `Error: Failed to open X display.` when I run this command. -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. +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: ```bash xvfb-run -a ./build/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png @@ -67,96 +60,25 @@ This should produce an `out.png` map tile image with the default MapLibre stylin 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 the following `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. -```json -{ - "version": 8, - "name": "Test style", - "center": [ - 8.54806714892635, - 47.37180823552663 - ], - "sources": { - "test": { - "type": "vector", - "url": "mbtiles:///path/to/zurich_switzerland.mbtiles" - } - }, - "layers": [ - { - "id": "background", - "type": "background", - "paint": { - "background-color": "hsl(47, 26%, 88%)" - } - }, - { - "id": "water", - "type": "fill", - "source": "test", - "source-layer": "water", - "filter": [ - "==", - "$type", - "Polygon" - ], - "paint": { - "fill-color": "hsl(205, 56%, 73%)" - } - }, - { - "id": "admin_country", - "type": "line", - "source": "test", - "source-layer": "boundary", - "filter": [ - "all", - [ - "<=", - "admin_level", - 2 - ], - [ - "==", - "$type", - "LineString" - ] - ], - "layout": { - "line-cap": "round", - "line-join": "round" - }, - "paint": { - "line-color": "hsla(0, 8%, 22%, 0.51)", - "line-width": { - "base": 1.3, - "stops": [ - [ - 3, - 0.5 - ], - [ - 22, - 15 - ] - ] - } - } - } - ] -} +``` +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. Don't forget to replace the source URL `"mbtiles:///path/to/zurich_switzerland.mbtiles"` with the actual path to your mbtiles file. - -From your `maplibre-native/` dir, run the following command. +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 -./build/bin/mbgl-render --style /path/to/style.json --output out.png +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) - +![Sample image of world from mbgl-render command](/misc/sample-barebones-mbgl-render-out.png) \ No newline at end of file