build: document makefile and prepare for out-of-tree builds

This documents the structure of `Makefile` as well as its supported
targets. Furthermore, we add support for SRCDIR and BUILDDIR so we can
use this makefile to ultimately deploy generated documentation to our
website and more.

This commit does not convert all of the makefile to honor SRCDIR. It
merely sets up the infrastructure to support SRCDIR. Follow-ups will
improve the different targets.

Makefile

@@ -1,6 +1,96 @@
-VERSION := $(shell python3 setup.py --version)
-NEXT_VERSION := $(shell expr "$(VERSION)" + 1)
-COMMIT=$(shell git rev-parse HEAD)
+#
+# Maintenance Helpers
+#
+# This makefile contains targets used for development, as well as helpers to
+# aid automatization of maintenance. Unless a target is documented in
+# `make help`, it is not supported and is only meant to be used by developers
+# to aid their daily development work.
+#
+# All supported targets honor the `SRCDIR` variable to find the source-tree.
+# For most unsupported targets, you are expected to have the source-tree as
+# your working directory. To specify a different source-tree, simply override
+# the variable via `SRCDIR=<path>` on the commandline. While you can also
+# override `BUILDDIR`, you are usually expected to have the build output
+# directory as working directory.
+#
+
+BUILDDIR ?= .
+SRCDIR ?= .
+
+#
+# Automatic Variables
+#
+# This section contains a bunch of automatic variables used all over the place.
+# They mostly try to fetch information from the repository sources to avoid
+# hard-coding them in this makefile.
+#
+# Most of the variables here are pre-fetched so they will only ever be
+# evaluated once. This, however, means they are always executed regardless of
+# which target is run.
+#
+#     VERSION:
+#         This evaluates the `version` field of `setup.py`. Therefore, it will
+#         be set to the latest version number of this repository without any
+#         prefix (just a plain number).
+#
+#     COMMIT:
+#         This evaluates to the latest git commit sha. This will not work if
+#         the source is not a git checkout. Hence, this variable is not
+#         pre-fetched but evaluated at time of use.
+#
+
+VERSION := $(shell (cd "$(SRCDIR)" && python3 setup.py --version))
+COMMIT = $(shell (cd "$(SRCDIR)" && git rev-parse HEAD))
+
+#
+# Generic Targets
+#
+# The following is a set of generic targets used across the makefile. The
+# following targets are defined:
+#
+#     help
+#         This target prints all supported targets. It is meant as
+#         documentation of targets we support and might use outside of this
+#         repository.
+#         This is also the default target.
+#
+#     $(BUILDDIR)/
+#     $(BUILDDIR)/%/
+#         This target simply creates the specified directory. It is limited to
+#         the build-dir as a safety measure. Note that this requires you to use
+#         a trailing slash after the directory to not mix it up with regular
+#         files. Lastly, you mostly want this as order-only dependency, since
+#         timestamps on directories do not affect their content.
+#
+
+.PHONY: help
+help:
+	@echo "make [TARGETS...]"
+	@echo
+	@echo "This is the maintenance makefile of osbuild. The following"
+	@echo "targets are available:"
+	@echo
+	@echo "    help:               Print this usage information."
+	@echo "    man:                Generate all man-pages"
+
+$(BUILDDIR)/:
+	mkdir -p "$@"
+
+$(BUILDDIR)/%/:
+	mkdir -p "$@"
+
+#
+# Documentation
+#
+# The following targets build the included documentation. This includes the
+# packaged man-pages, but also all other kinds of documentation that needs to
+# be generated. Note that these targets are relied upon by automatic
+# deployments to our website, as well as package manager scripts.
+#
+
+.PHONY: man
+man:
+	rst2man docs/osbuild.1.rst osbuild.1
 
 #
 # Building packages
@@ -41,11 +131,10 @@ rpm: $(RPM_SPECFILE) $(RPM_TARBALL)
 # Releasing
 #
 
+NEXT_VERSION := $(shell expr "$(VERSION)" + 1)
+
 .PHONY: bump-version
 bump-version:
 	sed -i "s|Version:\(\s*\)$(VERSION)|Version:\1$(NEXT_VERSION)|" osbuild.spec
 	sed -i "s|Release:\(\s*\)[[:digit:]]\+|Release:\11|" osbuild.spec
 	sed -i "s|version=\"$(VERSION)\"|version=\"$(NEXT_VERSION)\"|" setup.py
-
-man:
-	rst2man docs/osbuild.1.rst osbuild.1