Updated Documentation (#320)

* Update docs

* Added `macOS` build documentation link to README

Author: hummeltech

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,13 @@ 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>`__
+* `macOS </docs/build/building_on_macos.md>`__
+* `Ubuntu </docs/build/building_on_ubuntu.md>`__
 
 Configuration
 -------------
@@ -72,47 +82,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

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`