Added compilation instructions for several distros

Author: Felix Delattre

.github/actions/apt/provision/action.yml

@@ -7,8 +7,6 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Update installed packages
-      uses: ./.github/actions/apt/update
     - name: Install package(s)
       uses: ./.github/actions/apt/install
       with:

.github/actions/apt/update/action.yml

@@ -12,8 +12,6 @@ inputs:
 runs:
   using: composite
   steps:
-    - name: Update installed packages
-      uses: ./.github/actions/yum/update
     - name: Install group(s)
       uses: ./.github/actions/yum/groups-install
       with:

.github/actions/yum/provision/action.yml

@@ -2,10 +2,10 @@
 name: Build & Test (CentOS 7)
 
 on:
-  pull_request:
   push:
     branches:
-      - centos7
+      - master
+      - distros/centos-7
 
 env:
   build-dependencies: >-

.github/actions/yum/update/action.yml

@@ -7,6 +7,7 @@ on:
     branches:
       - master
       - develop
+      - distros/fedora-34
 
 env:
   build-group-dependencies: >-

.github/workflows/build-and-test-centos-7.yml

@@ -1,12 +1,13 @@
 ---
-name: Build & Test (Ubuntu Latest)
+name: Build & Test (Ubuntu 20.04)
 
 on:
   pull_request:
   push:
     branches:
       - master
       - develop
+      - distros/ubuntu-20-04
 
 env:
   build-dependencies: >-
@@ -22,7 +23,7 @@ env:
 jobs:
   build-and-test:
     name: Build & Test
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     steps:
       - name: Checkout code
         uses: actions/checkout@v2

.github/workflows/build-and-test-fedora-34.yml

@@ -27,11 +27,11 @@ bin_PROGRAMS = \
 noinst_PROGRAMS = gen_tile_test
 
 man_MANS = \
-	docs/renderd.1 \
-	docs/render_expired.1 \
-	docs/render_list.1 \
-	docs/render_old.1 \
-	docs/render_speedtest.1
+	docs/man/renderd.1 \
+	docs/man/render_expired.1 \
+	docs/man/render_list.1 \
+	docs/man/render_old.1 \
+	docs/man/render_speedtest.1
 
 renderddir = $(sysconfdir)
 

…rkflows/build-and-test-ubuntu-latest.yml …orkflows/build-and-test-ubuntu-20-04.yml.github/workflows/build-and-test-ubuntu-latest.yml renamed to .github/workflows/build-and-test-ubuntu-20-04.yml .github/workflows/build-and-test-ubuntu-latest.yml renamed to .github/workflows/build-and-test-ubuntu-20-04.yml

@@ -18,6 +18,17 @@ As an alternative to ``renderd`` its drop-in replacement
 `Tirex <https://github.com/openstreetmap/tirex>`__ can be used in
 combination with ``mod_tile``.
 
+Dependencies
+------------
+
+* `GNU/Linux` Operating System (works best on Debian or Ubuntu)
+* `Apache 2 HTTP webserver <https://httpd.apache.org/>`__
+* `Mapnik <https://mapnik.org/>`__
+* `Cairo 2D graphics library  <https://cairographics.org/>`__
+* `Curl library (SSL variant) <https://curl.haxx.se/>`__
+* `Iniparser library <https://github.com/ndevilla/iniparser>`__
+* `GLib library <https://gitlab.gnome.org/GNOME/glib>`__
+
 Installation
 ------------
 
@@ -36,53 +47,18 @@ These packages for **Debian** and **Ubuntu** are being maintained by
 the `Debian GIS Team <https://wiki.debian.org/DebianGis>`__ in the respective
 `repository <https://salsa.debian.org/debian-gis-team/libapache2-mod-tile>`__.
 
-Dependencies
-------------
-
-* `GNU/Linux` Operating System (works best on Debian or Ubuntu)
-* `Apache 2 HTTP webserver <https://httpd.apache.org/>`__
-* `Mapnik <https://mapnik.org/>`__
-* `Cairo 2D graphics library  <https://cairographics.org/>`__
-* `Curl library (SSL variant) <https://curl.haxx.se/>`__
-* `Iniparser library <https://github.com/ndevilla/iniparser>`__
-* `GLib library <https://gitlab.gnome.org/GNOME/glib>`__
-
 Compilation
 -----------
 
-You may want to compile this software for developing on it or when using
-on operating systems this is not being packaged for. On Debian or Ubuntu
-systems the following packages are needed to start compiling. On other systems
-the name of the libary might differ slightly.
-
-::
-
-    $ apt install build-essential \
-        autoconf \
-        apache2-dev \
-        libcairo2-dev \
-        libcurl4-gnutls-dev \
-        libglib2.0-dev \
-        libiniparser-dev \
-        libmapnik-dev
-
-*(You may install more and optional dependencies in order to add
-functionality to renderd)*
-
-Once the dependencies are installed you can compile and install
-mod_tile and renderd:
-
-::
-
-    $ ./autogen.sh
-    $ ./configure
-    $ make
-    $ sudo make install
-    $ sudo make install-mod_tile
+You may want to compile this software yourself. Either for developing on it or
+when using it on an operating system this is not being packaged for.
 
-Be aware that you have to add configuration files that are adjusted to your
-environment before you can run it all.
+We prepared instructions for you on how to build the software on the following
+distributions:
 
+* `CentOS 7 <docs/build/building_on_centos_7.md>`__
+* `Fedora 34 </docs/build/building_on_fedora_34.md>`__
+* `Ubuntu 20.04 </docs/build/building_on_ubuntu_20_04.md>`__ (this should work as well for Debian 10 and later)
 
 Configuration
 -------------
@@ -92,7 +68,7 @@ yourself, you can continue with the configuration. For your convenience
 example configuration files are distributed with the software packages and
 located in the ``etc`` directory of this repository.
 
-A very basic example-map and data can be found in the ``example-map``
+A very basic example-map and data can be found in the ``utils/example-map``
 directory. For a simple test copy it over to ``/var/www/example-map``.
 
 Copy the configuration files to their place, too:

Makefile.am

@@ -0,0 +1,116 @@
+# Building on CentOS 7
+
+This documents step by step on how to compile and put into use the software `mod_tile` and `renderd`.
+Please see our [Continous Integration script](../../.github/workflows/build-and-test-centos-7.yml) for more detail.
+
+As `CentOS 7` does not provide any `mapnik`/`mapnik-devel` packages in the official repository (nor are any available from `EPEL`,) it must therefore be built and installed before `mod_tile` can be built. Although `boost-devel` is present in the official repository, the version available there (`1.53.0`) is not in [mapnik's recommended dependency list](https://github.com/mapnik/mapnik/blob/v3.0.24/INSTALL.md#depends), so the `boost169-devel` package from `EPEL` should probably be used instead.
+
+```shell
+#!/usr/bin/env bash
+export LD_LIBRARY_PATH=/usr/local/lib
+export MAPNIK_VERSION=3.0.24
+
+# Install `EPEL` yum repository
+sudo yum --assumeyes install epel-release
+
+# Update installed packages
+sudo yum --assumeyes update
+
+# Install "Development Tools" group
+sudo yum --assumeyes groups install \
+  "Development Tools"
+
+# Install build dependencies
+sudo yum --assumeyes install \
+  boost169-devel \
+  cairo-devel \
+  freetype-devel \
+  gdal-devel \
+  glib2-devel \
+  harfbuzz-devel \
+  httpd-devel \
+  iniparser-devel \
+  libcurl-devel \
+  libicu-devel \
+  libjpeg-turbo-devel \
+  libmemcached-devel \
+  libpng-devel \
+  librados2-devel \
+  libtiff-devel \
+  libwebp-devel \
+  libxml2-devel \
+  postgresql-devel \
+  proj-devel \
+  sqlite-devel \
+  zlib-devel
+
+# Export `GDAL_DATA` & `PROJ_LIB` variables and create directories (if needed)
+export GDAL_DATA=$(gdal-config --datadir)
+export PROJ_LIB=/usr/share/proj
+sudo --preserve-env mkdir -p ${GDAL_DATA} ${PROJ_LIB}
+
+# Download, Build & Install `Mapnik`
+sudo mkdir -p /usr/local/src/mapnik-${MAPNIK_VERSION}
+cd /usr/local/src/mapnik-${MAPNIK_VERSION}
+sudo curl --silent --location https://github.com/mapnik/mapnik/releases/download/v${MAPNIK_VERSION}/mapnik-v${MAPNIK_VERSION}.tar.bz2 \
+  | sudo tar --verbose --extract --bzip2 --strip-components=1 --file=-
+sudo --preserve-env ./configure BOOST_INCLUDES=/usr/include/boost169 BOOST_LIBS=/usr/lib64/boost169
+sudo --preserve-env JOBS=$(nproc) make
+sudo --preserve-env make install
+
+# Fix issue with `iniparser.h` from `iniparser-devel` not being in the expected location
+sudo mkdir /usr/include/iniparser
+sudo ln -s /usr/include/iniparser.h /usr/include/iniparser/iniparser.h
+
+# Download and build
+sudo git clone https://github.com/openstreetmap/mod_tile.git /usr/local/src/mod_tile
+cd /usr/local/src/mod_tile
+sudo --preserve-env ./autogen.sh
+sudo --preserve-env ./configure
+sudo --preserve-env make
+
+# Create tiles directory
+sudo mkdir --parents /run/renderd /var/cache/renderd/tiles
+
+# Move files of example map
+sudo cp -r "utils/example-map" /var/www/example-map
+
+# Install leaflet
+sudo curl --silent \
+  "https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.7.1/leaflet.js" \
+  > /var/www/example-map/leaflet/leaflet.min.js
+sudo curl --silent \
+  "https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.7.1/leaflet.css" \
+  > /var/www/example-map/leaflet/leaflet.css
+
+# Add configuration
+sudo cp "etc/renderd/renderd.conf.examples" /etc/renderd.conf
+sudo cp "etc/apache2/renderd.conf" /etc/httpd/conf.d/renderd.conf
+sudo cp "apache2/renderd-example-map.conf" \
+  /etc/httpd/conf.d/renderd-example-map.conf
+
+# Apply CentOS specific changes to configuration files
+sudo sed --in-place \
+  "s#/usr/lib/mapnik/3.0/input#/usr/lib64/mapnik/input#g" \
+  /etc/renderd.conf
+sudo sed --in-place \
+  "s#/usr/share/fonts/truetype#/usr/share/fonts#g" \
+  /etc/renderd.conf
+
+# Add and activate mod_tile for Apache
+echo "LoadModule tile_module /usr/lib64/httpd/modules/mod_tile.so" \
+  | sudo tee --append /etc/httpd/conf.modules.d/11-mod_tile.conf
+
+# Make example map the new main page of Apache
+sudo rm --force /etc/httpd/conf.d/welcome.conf
+
+# Install software
+sudo make install
+sudo make install-mod_tile
+
+# Start services
+sudo httpd
+sudo renderd -f
+```
+
+Then you can visit: `http://localhost/example-map`