Update docs

openstreetmap · Jun 4, 2023 · 5ff933d · 5ff933d
1 parent f521540
commit 5ff933d
Show file tree

Hide file tree

Showing 19 changed files with 563 additions and 376 deletions.
diff --git a/.github/actions/cmake/build/action.yml b/.github/actions/cmake/build/action.yml
@@ -11,11 +11,11 @@ runs:
 
     - name: Prepare `build` directory
       run: |
-        cmake -S . -B build \
+        cmake -B build -S . \
           -LA \
-          -DCMAKE_BUILD_TYPE=${BUILD_TYPE:-Debug} \
-          -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX:-/usr/local} \
-          -DENABLE_TESTS=1
+          -DCMAKE_BUILD_TYPE:STRING=${BUILD_TYPE:-Debug} \
+          -DCMAKE_INSTALL_PREFIX:PATH=${INSTALL_PREFIX:-/usr/local} \
+          -DENABLE_TESTS:BOOL=ON
       shell: bash --noprofile --norc -euxo pipefail {0}
 
     - name: Build `mod_tile`

diff --git a/.github/actions/cmake/install/action.yml b/.github/actions/cmake/install/action.yml
@@ -3,5 +3,5 @@ runs:
   using: composite
   steps:
     - name: Install `mod_tile`
-      run: cmake --install build
+      run: ${{ !matrix.image && 'sudo' || '' }} cmake --install build
       shell: bash --noprofile --norc -euxo pipefail {0}
diff --git a/.github/actions/cmake/test/action.yml b/.github/actions/cmake/test/action.yml
@@ -29,7 +29,7 @@ runs:
     - name: Archive test artifacts on failure
       if: failure()
       run: |
-        TAR_FILENAME=${{ matrix.image }}-${{ matrix.compiler }}.tar.gz
+        TAR_FILENAME=${{ matrix.image || matrix.os }}-${{ matrix.compiler }}.tar.gz
         TAR_FILENAME=$(echo "${TAR_FILENAME}" | sed 's/:/-/g')
         tar -zcf /tmp/${TAR_FILENAME} tests
       shell: bash --noprofile --norc -euxo pipefail {0}

diff --git a/.github/actions/dependencies/build-and-install/mapnik/latest/action.yml b/.github/actions/dependencies/build-and-install/mapnik/latest/action.yml
@@ -25,7 +25,7 @@ runs:
         cmake -S mapnik-src -B mapnik-build \
           -DBUILD_DEMO_VIEWER:BOOL=OFF \
           -DBUILD_TESTING:BOOL=OFF \
-          -DCMAKE_BUILD_TYPE=Release \
+          -DCMAKE_BUILD_TYPE:STRING=Release \
           -DCMAKE_INSTALL_PREFIX:PATH=/usr
         cmake --build mapnik-build
       shell: bash --noprofile --norc -euxo pipefail {0}

diff --git a/.github/actions/dependencies/install/action.yml b/.github/actions/dependencies/install/action.yml
@@ -55,6 +55,7 @@ inputs:
       iniparser
       libmemcached
       mapnik
+      pkg-config
   macos-test-dependencies:
     default: >-
       coreutils
@@ -78,7 +79,7 @@ inputs:
       gdal-devel
       harfbuzz-devel
       libicu-devel
-      libjpeg-turbo-devel
+      libjpeg-devel
       libpng-devel
       libtiff-devel
       libwebp-devel

diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml
@@ -20,8 +20,8 @@ jobs:
           - 'debian:10'
           - 'debian:11'
           - 'debian:testing'
-          - 'fedora:36'
           - 'fedora:37'
+          - 'fedora:38'
           - 'fedora:rawhide'
           - 'ubuntu:20.04'
         build_system:
@@ -90,24 +90,25 @@ jobs:
       CFLAGS: -Wno-implicit-function-declaration
       LDFLAGS: -undefined dynamic_lookup
       LIBRARY_PATH: /usr/local/lib
-    name: ${{ matrix.image }} (${{ matrix.build_system }}) (${{ matrix.compiler }})
-    runs-on: ${{ matrix.image }}
+    name: ${{ matrix.os }} (${{ matrix.build_system }}) (${{ matrix.compiler }})
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        image:
+        os:
           - macos-11
+          - macos-12
         build_system:
           - CMake
         compiler:
           - LLVM
         on_default_branch:
           - ${{ contains(github.ref, 'master') || contains(github.ref, 'develop') }}
         include:
-          - image: macos-12
+          - os: macos-13
             build_system: Autotools
             compiler: LLVM
-          - image: macos-12
+          - os: macos-13
             build_system: CMake
             compiler: LLVM
         exclude:

diff --git a/README.rst b/README.rst
@@ -8,7 +8,7 @@ This software contains two main pieces:
 2) ``renderd``: A daemon that renders map tiles using mapnik.
 
 .. figure:: ./screenshot.jpg
-   :alt: Image shoing example slippy map and OSM layer
+   :alt: Image showing example slippy map and OSM layer
 
 Together they efficiently render and serve raster map tiles for example
 to use within a slippy map. The two consist of the classic raster tile
@@ -21,15 +21,22 @@ 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>`__
-* `Memcached library (optional) <https://libmemcached.org/>`__
-* `RADOS library (optional) <https://docs.ceph.com/en/latest/rados/api/librados/>`__
+* `Supported Operating Systems`
+    * `GNU/Linux` (works best on Debian or Ubuntu)
+    * `FreeBSD`
+    * `macOS`
+* `Supported Build Systems`
+    * `GNU Autotools <https://www.gnu.org/software/software.html>`__
+    * `CMake <https://cmake.org/>`__
+* `Runtime/Build Dependencies`
+    * `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>`__
+    * `Memcached library (optional) <https://libmemcached.org/>`__
+    * `RADOS library (optional) <https://docs.ceph.com/en/latest/rados/api/librados/>`__
 
 Installation
 ------------
@@ -58,10 +65,12 @@ when using it on an operating system this is not being packaged for.
 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)
-* `Debian 12 </docs/build/building_on_debian_12.md>`__
+* `CentOS </docs/build/building_on_centos.md>`__
+* `CentOS Stream </docs/build/building_on_centos_stream.md>`__
+* `Debian </docs/build/building_on_debian.md>`__
+* `Fedora </docs/build/building_on_fedora.md>`__
+* `FreeBSD </docs/build/building_on_freebsd.md>`__
+* `Ubuntu </docs/build/building_on_ubuntu.md>`__
 
 Configuration
 -------------
@@ -72,47 +81,63 @@ 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 ``utils/example-map``
-directory. For a simple test copy it over to ``/var/www/example-map``.
+directory.
 
-Copy the configuration files to their place, too:
+For a simple test copy it over to ``/usr/share/renderd/example-map``:
 
 ::
 
-    $ cp etc/renderd/renderd.conf /etc/renderd.conf
-    $ cp etc/apache2/renderd.conf /etc/apache2/conf-available/renderd.conf
-    $ cp etc/apache2/renderd-example-map.conf /etc/apache2/conf-available/renderd-example-map.conf
+    $ sudo mkdir -p /usr/share/renderd
+    $ sudo cp -av utils/example-map /usr/share/renderd/
 
-Enable the configuration:
+Copy the apache configuration file to its place, too:
 
 ::
 
-    $ sudo a2enmod tile
-    $ sudo a2enconf renderd
-    $ sudo a2enconf renderd-example-map
+    $ sudo cp -av etc/apache2/renderd-example-map.conf /etc/apache2/sites-available/renderd-example-map.conf
 
-Restart apache2:
+Add a map configuration for example-map to ``/etc/renderd.conf`:
 
 ::
 
-    $ sudo a2enmod tile
-    $ sudo a2enconf renderd
+    $ printf '
+    [example-map]
+    URI=/tiles/renderd-example
+    XML=/usr/share/renderd/example-map/mapnik.xml
+    ' | sudo tee -a /etc/renderd.conf
 
+Start the rendering daemon
+
+::
 
-And run the rendering daemon
+    $ sudo renderd
+
+Enable the apache module and site:
 
 ::
 
-    $ renderd -f
+    $ sudo a2enmod tile
+    $ sudo a2ensite renderd-example-map
+
+Restart apache:
+
+::
+
+    $ sudo apache2ctl restart
+
+Now visit the renderd example map in your browser, e.g.:
+
+::
 
-Make sure the ``/var/cache/renderd/tiles`` directory is writable by
-the user running the renderd process.
+    http://localhost/renderd-example-map
 
-Try loading a tile in your browser, e.g.
+Or try loading a single tile, e.g:
 
 ::
 
-    http://localhost/renderd-example/tiles/0/0/0.png
+    http://localhost:8081/tiles/renderd-example/0/0/0.png
 
+*Note: the above commands and paths may differ based on your OS/distribution.*
 
 You may edit ``/etc/renderd.conf`` to indicate the location of different
 mapnik style sheets (up to ten) and the endpoints you wish to use to access

diff --git a/docs/build/building_on_centos.md b/docs/build/building_on_centos.md
@@ -0,0 +1,72 @@
+# Building on CentOS
+
+This document provides users with step-by-step instructions on how to compile and use`mod_tile` and `renderd`.
+
+Please see our [Continuous Integration script](/.github/workflows/build-and-test.yml) for more details.
+
+_CentOS does not provide a `mapnik`/`mapnik-devel` package, so it will first need to be built & installed, which is beyond the scope of this document, please visit the project's [installation document on GitHub](https://github.com/mapnik/mapnik/blob/master/INSTALL.md) or our [Continuous Integration script](/.github/actions/dependencies/build-and-install/mapnik/action.yml) for more information._
+
+## CentOS 7
+```shell
+#!/usr/bin/env bash
+
+# Update installed packages
+sudo yum --assumeyes update
+
+# Install build dependencies
+# (libmemcached-devel & librados2-devel are optional)
+sudo yum --assumeyes install epel-release
+sudo yum --assumeyes --setopt=install_weak_deps=False install \
+  boost169-devel \
+  cairo-devel \
+  cmake3 \
+  gcc \
+  gcc-c++ \
+  gdal \
+  git \
+  glib2-devel \
+  harfbuzz-devel \
+  httpd-devel \
+  iniparser-devel \
+  libcurl-devel \
+  libicu-devel \
+  libjpeg \
+  libmemcached-devel \
+  librados2-devel \
+  libtiff \
+  libwebp \
+  make \
+  proj
+
+# Download, Build, Test & Install `mod_tile`
+export CMAKE_BUILD_PARALLEL_LEVEL=$(nproc)
+rm -rf /tmp/mod_tile_src /tmp/mod_tile_build
+mkdir /tmp/mod_tile_src /tmp/mod_tile_build
+cd /tmp/mod_tile_src
+git clone --depth 1 https://github.com/openstreetmap/mod_tile.git .
+cd /tmp/mod_tile_build
+cmake3 -B . -S /tmp/mod_tile_src \
+  -DCMAKE_BUILD_TYPE:STRING=Release \
+  -DCMAKE_CXX_FLAGS:STRING="-I/usr/include/boost169" \
+  -DCMAKE_C_FLAGS:STRING="-I/usr/include/boost169" \
+  -DENABLE_TESTS:BOOL=ON
+cmake3 --build .
+ctest3
+sudo cmake --install . --prefix /usr --strip
+
+# Create /usr/share/renderd directory
+sudo mkdir --parents /usr/share/renderd
+
+# Copy files of example map
+sudo cp -av /tmp/mod_tile_src/utils/example-map /usr/share/renderd/example-map
+
+# Add configuration
+sudo cp -av /tmp/mod_tile_src/etc/apache2/renderd-example-map.conf /etc/httpd/conf.d/renderd-example-map.conf
+printf '\n[example-map]\nURI=/tiles/renderd-example\nXML=/usr/share/renderd/example-map/mapnik.xml\n' | sudo tee -a /etc/renderd.conf
+
+# Start services
+sudo httpd
+sudo renderd -f
+```
+
+Then you can visit: `http://localhost:8081/renderd-example-map`