[M] Change in flashrom[main]: Makefile,meson.build: Add support for Sphinx versions prior to 4.x

[Anastasia Klimchuk (Code Review)]

Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/77778?usp=email )

Change subject: Makefile,meson.build: Add support for Sphinx versions prior to 4.x
......................................................................

Makefile,meson.build: Add support for Sphinx versions prior to 4.x

As of version 3.x, `sphinx-build` outputs man pages to "8" directory
instead of "man8" expected by Makefile and doc/meson.build. See:
    https://github.com/sphinx-doc/sphinx/issues/7996
    https://github.com/sphinx-doc/sphinx/issues/9217

Current solution is to rename "8" to "man8" after documentation build.
That enables successful build and installation, as well as dependency
tracking at build-system level, but not on `sphinx-build` own level
upon which `meson` build blindly relies.

Change-Id: I9cd280551a1ba4d17edb2e857d56f80431b61e1b
Signed-off-by: Anton Samsonov 
Reviewed-on: https://review.coreboot.org/c/flashrom/+/77778
Tested-by: build bot (Jenkins) 
Reviewed-by: Anastasia Klimchuk 
Reviewed-by: Peter Marheine 
---
M Makefile
M doc/meson.build
A doc/sphinx-wrapper.sh
3 files changed, 51 insertions(+), 2 deletions(-)

Approvals:
  Anastasia Klimchuk: Looks good to me, approved
  build bot (Jenkins): Verified
  Peter Marheine: Looks good to me, approved

diff --git a/Makefile b/Makefile
index 7b1312d..a36e575 100644
--- a/Makefile
+++ b/Makefile
@@ -228,6 +228,10 @@
 CONFIG_LIBPCI_CFLAGS       := $(call dependency_cflags, libpci)
 CONFIG_LIBPCI_LDFLAGS      := $(call dependency_ldflags, libpci)

+CONFIG_SPHINXBUILD_VERSION :=
+CONFIG_SPHINXBUILD_MAJOR   := 0
+
+
 # Determine the destination OS, architecture and endian
 # IMPORTANT: The following lines must be placed before TARGET_OS, ARCH or ENDIAN
 # is ever used (of course), but should come after any lines setting CC because
@@ -958,6 +962,11 @@

OBJS = $(CHIP_OBJS) $(PROGRAMMER_OBJS) $(LIB_OBJS)

+ifeq ($(HAS_SPHINXBUILD), yes)
+override CONFIG_SPHINXBUILD_VERSION := $(shell $(SPHINXBUILD) --version | cut -d' ' -f2 )
+override CONFIG_SPHINXBUILD_MAJOR   := $(shell echo "$(CONFIG_SPHINXBUILD_VERSION)" | cut -d'.' -f1 )
+endif
+

all: $(PROGRAM)$(EXEC_SUFFIX) $(call has_dependency, $(HAS_SPHINXBUILD), man8/$(PROGRAM).8)
 ifeq ($(ARCH), x86)
@@ -1022,7 +1031,7 @@
    	echo "The following features are unavailable on your machine: $(UNSUPPORTED_FEATURES)" \
    	exit 1;								\
    fi
-	@echo "Checking for program "sphinx-build": $(HAS_SPHINXBUILD)"
+	@echo "Checking for program "sphinx-build": $(HAS_SPHINXBUILD) $(CONFIG_SPHINXBUILD_VERSION)"

%.o: %.c | config
    $(CC) -MMD $(CFLAGS) $(CPPFLAGS) $(FLASHROM_CFLAGS) $(FEATURE_FLAGS) -D'FLASHROM_VERSION=$(VERSION)'  -o $@ -c $<
@@ -1035,8 +1044,18 @@
    $(RANLIB) $@

man8/$(PROGRAM).8: doc/*
+#	When using sphinx-build prior to version 4.x, man pages are output
+#	to a directory named "8" instead of expected "man8". We fix that
+#	by renaming "8" to "man8" and creating symlink "8" pointing to "man8".
    @if [ "$(HAS_SPHINXBUILD)" = "yes" ]; then			\
    	$(SPHINXBUILD) -Drelease=$(VERSION) -b man doc .;	\
+		if [ "$(CONFIG_SPHINXBUILD_MAJOR)" -lt 4 ]; then	\
+			if [ -d 8 -a ! -L 8 ]; then			\
+				rm -rf man8;				\
+				mv 8 man8;				\
+				ln -s man8 8;				\
+			fi						\
+		fi							\
    else								\
    	echo "$(SPHINXBUILD) not found. Can't build man-page";	\
    	exit 1;							\
diff --git a/doc/meson.build b/doc/meson.build
index aca73d8..5bc57b9 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -1,5 +1,6 @@

sphinx = find_program('sphinx-build', native : true, required : get_option('man-pages').enabled() or get_option('documentation').enabled())
+sphinx_wrapper = meson.current_source_dir() / 'sphinx-wrapper.sh'

man_pages = [
   'flashrom.8'
@@ -14,7 +15,7 @@

custom_target(
       'man-pages',
-      command : [sphinx, '-b', 'man', '-q', '-d', '@PRIVATE_DIR@', '-Drelease=' + flashrom_version,'@CURRENT_SOURCE_DIR@', '@OUTDIR@'],
+      command : [sphinx_wrapper, '@OUTDIR@', ' '.join(man_outputs), sphinx, '-b', 'man', '-q', '-d', '@PRIVATE_DIR@', '-Drelease=' + flashrom_version, '@CURRENT_SOURCE_DIR@', '@OUTDIR@'],
       build_always_stale : true, # sphinx handles rebuilds
       output  : man_outputs,
       install : true,
diff --git a/doc/sphinx-wrapper.sh b/doc/sphinx-wrapper.sh
new file mode 100755
index 0000000..5569638
--- /dev/null
+++ b/doc/sphinx-wrapper.sh
@@ -0,0 +1,29 @@
+#!/bin/sh
+
+OUTPUT_HOME="$1"
+MAN_OUTPUTS="$2"
+SPHINXBUILD="$3"
+shift 3
+
+"${SPHINXBUILD}" "$@" || exit $?
+
+SPHINXBUILD_MAJOR="$("${SPHINXBUILD}" --version | cut -d' ' -f2 | cut -d'.' -f1)"
+if [ "${SPHINXBUILD_MAJOR}" -ge 4 ]; then
+	exit 0
+fi
+
+# sphinx-build 3.x outputs man pages to "8" directory instead of expected "man8".
+# The following block checks for "man8" (and other output paths in ${MAN_OUTPUTS})
+# and, if that is missing, but "8" dir exists instead, it renames "8" to "man8"
+# and creates a symlink named "8" that points to "man8", so that anyone is happy
+# during the rest of current build and subsequent builds as well.
+
+for MAN_OUTPUT in ${MAN_OUTPUTS}; do
+	PATH_TARGET="${OUTPUT_HOME}/${MAN_OUTPUT}"
+	PATH_ACTUAL="${OUTPUT_HOME}/${MAN_OUTPUT#man}"
+	if [ -d "${PATH_ACTUAL}" -a ! -L "${PATH_ACTUAL}" ]; then
+		rm -rf "${PATH_TARGET}"
+		mv "${PATH_ACTUAL}" "${PATH_TARGET}"
+		ln -s "${MAN_OUTPUT}" "${PATH_ACTUAL}"
+	fi
+done