[libvirt] [PATCH] build: be smarter about building documentation

[Eric Blake]

I'm tired of cryptic reports on IRC from people who build from
git, then type 'make install' and have it fail quite a ways down
the road because the documentation wasn't built.  It's a feature
that documentation is not built during development if the toolchain
is not present (not all git developers build tarballs, and the
tarballs already contain pre-built docs); but this only works as
long as you don't try to install or make a tarball from that
setup.  With this patch in place, and without xhtml1-dtds, I now
get this nice failure:

$ make install
cfg.mk:109: *** ERROR: missing doc toolchain (install xhtml1-dtds and xmllint).  Stop.

and all with no impact to regular 'make' or 'make check'.

Along the way, I tried to discover why 'yum-builddeps libvirt'
doesn't always tell developers to install xhtml1-dtds - my conclusion
was that if the .srpm is unavailable, then yum-builddeps can't
figure out anything that is required.  The spec file already has
a BuildRequires on the doc toolchain (and therefore, the docs shipped
with an rpm are up-to-date, even if the spec file applied patches
that affect the docs).  So thankfully I don't have to make any
spec file changes in this patch.

* cfg.mk: Let 'make install' and 'make dist' error much earlier if
we detect a build from git without doc toolchain.

Signed-off-by: Eric Blake <eblake at redhat.com>
---

Heavily influenced by code in gnulib's GNUMakefile :)

 cfg.mk | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/cfg.mk b/cfg.mk
index e6584e8..7e17b5c 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -88,6 +88,29 @@ else
 distdir: sc_vulnerable_makefile_CVE-2012-3386.z
 endif

+# We intentionally don't require the doc toolchain during 'make' during
+# development, but 'make dist' must ship pre-built docs, and 'make install'
+# from a git build fails if docs weren't built, both with awkward error
+# messages if we let the build run that far.  Therefore, bail loud and
+# early if we detect a git tree but no doc toolchain.
+ifeq ($(MAKELEVEL),0)
+  _is-dist-target ?= $(filter-out %clean, \
+    $(filter maintainer-% dist% alpha beta stable,$(MAKECMDGOALS)))
+  _is-install-target ?= $(filter-out %check, $(filter install%,$(MAKECMDGOALS)))
+  ifneq (,$(_is-dist-target)$(_is-install-target))
+    ifeq ($(shell \
+	if test -e $(srcdir)/.git; then \
+	  if test -x $(XMLLINT) && test -x $(XMLCATALOG) && \
+	    $(XMLCATALOG) '$(XML_CATALOG_FILE)' \
+	    "-//W3C//DTD XHTML 1.0 Strict//EN" >/dev/null; then \
+	    echo works; \
+	  else echo oops; fi;\
+	else echo tarball; fi),oops)
+      $(error ERROR: missing doc toolchain (install xhtml1-dtds and xmllint))
+    endif
+  endif
+endif
+
 # Files that should never cause syntax check failures.
 VC_LIST_ALWAYS_EXCLUDE_REGEX = \
   (^(HACKING|docs/(news\.html\.in|.*\.patch))|\.po)$$
-- 
1.8.3.1