dist/tools: add doxygen as a tool for CI

Makefile

@@ -6,11 +6,11 @@ all: welcome
 	@echo ""
 	@exit 1
 
-doc doc-man doc-latex:
+doc doc-man doc-latex doc-ci:
 	@./dist/tools/features_yaml2mx/features_yaml2mx.py \
 		features.yaml \
 		--output-md doc/doxygen/src/feature_list.md
-	"$(MAKE)" -BC doc/doxygen $@
+	"$(MAKE)" -C doc/doxygen $@
 
 docclean:
 	"$(MAKE)" -BC doc/doxygen clean

dist/tools/doxygen/.gitignore

@@ -0,0 +1,3 @@
+doxygen
+doxygen-*
+doxygen-*/

dist/tools/doxygen/Makefile

@@ -0,0 +1,106 @@
+# This tool package is meant to be used by the `doc-ci` command
+# to download and (if necessary) compile the specified Doxygen version.
+# Depending on the distribution, it is quite difficult to obtain recent
+# package versions.
+#
+# The script will try to download the binary release files for `Linux x86_64`
+# systems and compile from source for every other system.
+#
+# The Doxygen version that will be fetched is saved in the $(PKG_VERSION)
+# environment variable and has to be set by the caller.
+# Accepted values for $(PKG_VERSION) are either version numbers such as
+# `1.13.2` or `latest` to build the latest master source.
+
+PKG_NAME=doxygen
+PKG_LICENSE=GPL-2.0
+
+# optionally add the "clean" target to delete the binary and force a rebuild
+REBUILD=
+
+# the PKG_VERSION is defined by the doc/doxygen/Makefile
+ifeq (,$(filter clean distclean,$(MAKECMDGOALS)))
+  ifeq (,$(PKG_VERSION))
+    $(error Doxygen version undefined!)
+  endif
+
+  # If the requested and installed version mismatch, force a rebuild
+  # by deleting the binary. `latest` will always force a rebuild.
+  ifneq (,$(shell test -f $(CURDIR)/doxygen && echo exists))
+    ifneq ($(PKG_VERSION),$(shell $(CURDIR)/doxygen --version | cut -d ' ' -f1))
+      REBUILD=clean
+    endif
+  endif
+endif
+
+# Try to download the binary if the platform is 'Linux x86_64' to avoid
+# unnecessarily building Doxygen for CI.
+ifeq (Linux x86_64,$(shell uname -m -s))
+  # always build from source for the 'latest' version
+  ifeq (latest,$(PKG_VERSION))
+    BUILD_METHOD=build_source
+  else
+    # The URL has the following format (for version 1.13.2):
+    # https://github.com/doxygen/doxygen/releases/download/Release_1_13_2/
+    # doxygen-1.13.2.linux.bin.tar.gz
+    BIN_PKG_URL=https://github.com/doxygen/doxygen/releases/download/Release_
+    BIN_PKG_EXT=linux.bin.tar.gz
+    BIN_PKG_TAR=$(PKG_NAME)-$(PKG_VERSION).$(BIN_PKG_EXT)
+    BIN_PKG_DOWNLOAD_URL=$(BIN_PKG_URL)$(subst .,_,$(PKG_VERSION))/$(BIN_PKG_TAR)
+
+    BIN_AVAILABLE := $(shell curl --head --silent --fail $(BIN_PKG_DOWNLOAD_URL) \
+                      >/dev/null 2>&1 && echo yes || echo no)
+    ifeq (yes,$(BIN_AVAILABLE))
+      BUILD_METHOD=download_binary
+    else
+      BUILD_METHOD=build_source
+    endif
+  endif
+endif
+
+# fallback to building from source by default
+BUILD_METHOD?=build_source
+
+ifeq (build_source,$(BUILD_METHOD))
+  PKG_URL=https://github.com/doxygen/doxygen
+  PKG_EXT=
+else
+  PKG_URL=$(BIN_PKG_URL)
+  PKG_EXT=$(BIN_PKG_EXT)
+endif
+
+.PHONY: clean distclean
+
+all: $(CURDIR)/doxygen
+
+$(CURDIR)/doxygen: $(REBUILD)
+	@$(MAKE) $(BUILD_METHOD)
+
+download_binary: distclean
+	@echo "[INFO] Downloading Doxygen binary..."
+	@wget -q -O $(CURDIR)/$(BIN_PKG_TAR) $(BIN_PKG_DOWNLOAD_URL) || \
+	  { echo "[ERROR] Failed to download binary"; exit 1; }
+	@echo "[INFO] Unpacking Doxygen..."
+	@tar -xf $(CURDIR)/$(BIN_PKG_TAR)
+	@cp $(CURDIR)/$(PKG_NAME)-$(PKG_VERSION)/bin/doxygen $(CURDIR)
+
+build_source: distclean
+	@echo "[INFO] Cloning and building Doxygen from source..."
+	@if [ "$(PKG_VERSION)" = "latest" ]; then \
+	    git clone --depth=1 $(PKG_URL).git $(CURDIR)/$(PKG_NAME)-$(PKG_VERSION); \
+	else \
+	    git ls-remote --tags $(PKG_URL).git | grep -q "refs/tags/Release_$(subst .,_,$(PKG_VERSION))$$" || \
+	    { echo "[ERROR] Specified version tag 'Release_$(subst .,_,$(PKG_VERSION))'" \
+        "does not exist!"; exit 1; }; \
+	    git clone --branch Release_$(subst .,_,$(PKG_VERSION)) --depth=1 \
+	      $(PKG_URL).git $(CURDIR)/$(PKG_NAME); \
+	fi
+	@cd $(CURDIR)/$(PKG_NAME)-$(PKG_VERSION) && mkdir build && cd build && \
+	cmake -G "Unix Makefiles" .. && \
+	$(MAKE) --no-print-directory && \
+	cp bin/doxygen $(CURDIR)
+
+distclean:: clean
+	@rm -rf $(CURDIR)/$(PKG_NAME)*
+
+clean::
+	@rm -rf $(PKG_NAME)

doc/doxygen/Makefile

@@ -1,5 +1,7 @@
-RIOTBASE  = $(shell git rev-parse --show-toplevel)
+RIOTBASE  ?= $(shell git rev-parse --show-toplevel)
-RIOTMAKE ?= $(RIOTBASE)/makefiles
+RIOTMAKE  ?= $(RIOTBASE)/makefiles
+RIOTTOOLS ?= $(RIOTBASE)/dist/tools
+
 
 # Generate list of quoted absolute include paths. Evaluated in riot.doxyfile.
 export STRIP_FROM_INC_PATH_LIST=$(shell \
@@ -22,11 +24,19 @@ endif
 # Check that the doxygen version is not too old to avoid
 # certain bugs that were fixed in later revisions. Especially
 # Debian-based distributions tend to have very old versions.
-DOXYGEN_MIN_VERSION = 1.14.0
+DOXYGEN_MIN_VERSION = 1.13.2
+
+# Set the Doxygen binary if not already set
+DOXYGEN ?= doxygen
 
 # Strip the commit hash that is sometimes present after the
 # version number.
-DOXYGEN_VERSION = $(shell doxygen --version | cut -d ' ' -f1)
+DOXYGEN_CUR_VERSION = $(shell $(DOXYGEN) --version | cut -d ' ' -f1)
+
+# for the `doc-ci` target, we can choose which Doxygen version should be built.
+# If nothing has been chosen, select the minimum version.
+# Valid options are `latest` and version numbers such as `1.13.2`.
+DOXYGEN_VERSION ?= $(DOXYGEN_MIN_VERSION)
 
 # include color echo macros
 include $(RIOTMAKE)/utils/ansi.mk
@@ -34,27 +44,32 @@ include $(RIOTMAKE)/color.inc.mk
 
 .PHONY: doc doc-man doc-latex
 doc doc-man doc-latex: $(DOCUMENTATION_FORMAT)
-	@if [ "`{ echo "$(DOXYGEN_MIN_VERSION)"; echo "$(DOXYGEN_VERSION)"; } | \
+	@if [ "`{ echo "$(DOXYGEN_MIN_VERSION)"; echo "$(DOXYGEN_CUR_VERSION)"; } | \
 		sort -V | head -n1`" != "$(DOXYGEN_MIN_VERSION)" ]; then \
-		$(COLOR_ECHO) "$(COLOR_RED)Warning: Doxygen version $(DOXYGEN_VERSION) is too old." \
+		$(COLOR_ECHO) "$(COLOR_RED)Warning: Doxygen version $(DOXYGEN_CUR_VERSION) is too old." \
 		"It is recommended to use at least version $(DOXYGEN_MIN_VERSION)" \
 		"to avoid incorrectly formatted output.$(COLOR_RESET)"; \
 	fi
 
+.PHONY: doc-ci
+doc-ci: $(RIOTTOOLS)/doxygen/Makefile
+	@PKG_VERSION=$(DOXYGEN_VERSION) $(MAKE) -C $(RIOTTOOLS)/doxygen all --no-print-directory
+	@$(MAKE) -BC $(CURDIR) DOXYGEN=$(RIOTTOOLS)/doxygen/doxygen doc
+
 # by marking html as phony we force make to re-run Doxygen even if the directory exists.
 .PHONY: html
 html: src/changelog.md src/coc.md src/governance.md
-	( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | doxygen -
+	( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | $(DOXYGEN) -
 	@echo ""
 	@echo "RIOT documentation successfully generated at file://$(RIOTBASE)/doc/doxygen/html/index.html"
 
 .PHONY: check
 check: src/changelog.md src/coc.md src/governance.md
-	( cat riot.doxyfile) | doxygen -
+	( cat riot.doxyfile) | $(DOXYGEN) -
 
 .PHONY: man
 man: src/changelog.md src/coc.md src/governance.md
-	( cat riot.doxyfile ; echo "GENERATE_MAN = yes" ) | doxygen -
+	( cat riot.doxyfile ; echo "GENERATE_MAN = yes" ) | $(DOXYGEN) -
 	@echo ""
 	@echo "RIOT documentation successfully generated at file://$(RIOTBASE)/doc/doxygen/man/man3"
 
@@ -76,9 +91,10 @@ src/governance.md: ../../GOVERNANCE.md
 
 .PHONY:
 latex: src/changelog.md src/coc.md src/governance.md
-	( cat riot.doxyfile ; echo "GENERATE_LATEX= yes" ) | doxygen -
+	( cat riot.doxyfile ; echo "GENERATE_LATEX= yes" ) | $(DOXYGEN) -
 	@echo ""
 	@echo "RIOT documentation successfully generated at file://$(RIOTBASE)/doc/doxygen/latex/index.tex"
 
 clean:
 	-@rm -rf latex man html doxygen_objdb_*.tmp doxygen_entrydb_*.tmp src/changelog.md src/coc.md src/governance.md
+	@$(MAKE) -C $(RIOTTOOLS)/doxygen clean