[libvirt] [PATCHv3 1/2] build: fix VPATH build of docs

The rule of thumb for generated files: If they are distributed, they should be generated in $(srcdir); otherwise, they should be built by the end user in $(builddir). Since our .xml docs are built with python, and we want them available even to end users that don't build with python, we want them distributed; hence, they must live in $(srcdir). Tested with 'make distcheck' in both an in-tree build and a VPATH build. * docs/Makefile.am (dot_html_in, patches): Massage wildcard correctly. (EXTRA_DIST): Remove redundant listing of xml files. (api, web, maintainer-clean-local): Update location. (html/index.html): Likewise, and dump all generated files in correct location. ($(devhelphtml)): Since we distribute .xml, build it in srcdir. (html/%-%.html, html/%-virterror.html, %-api.xml, %-refs.xml): Rewrite with... (python_generated_files): ...new macro. * docs/apibuild.py (srcPref): Define. (docBuilder.serialize): Put output in srcdir. (docBuilder.serialize_xrefs_references): Update location. (rebuild): Look for built libvirt.h in builddir. --- It took me a while to figure out that xsltproc needs the '-o dir' option to guarantee that generated files will end up in the right place. That's the biggest difference from v1 and v2 patches posted earlier, but it's been long enough that this patch is worth reviewing in entirety rather than looking at interdiffs. docs/Makefile.am | 46 +++++++++++++++++++++++++++------------------- docs/apibuild.py | 18 +++++++++++++----- 2 files changed, 40 insertions(+), 24 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 41068c6..4b1c99a 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -53,10 +53,10 @@ gif = \ architecture.gif \ node.gif -dot_html_in = $(wildcard *.html.in) +dot_html_in = $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/*.html.in)) dot_html = $(dot_html_in:%.html.in=%.html) -patches = $(wildcard api_extension/*.patch) +patches = $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/api_extension/*.patch)) xml = \ libvirt-api.xml \ @@ -70,8 +70,8 @@ fig = \ libvirt-object-model.fig EXTRA_DIST= \ - libvirt-api.xml libvirt-refs.xml apibuild.py \ - site.xsl newapi.xsl news.xsl page.xsl ChangeLog.xsl \ + apibuild.py \ + site.xsl newapi.xsl news.xsl page.xsl ChangeLog.xsl \ $(dot_html) $(dot_html_in) $(gif) $(apihtml) $(apipng) \ $(devhelphtml) $(devhelppng) $(devhelpcss) $(devhelpxsl) \ $(xml) $(fig) $(png) \ @@ -83,9 +83,10 @@ MAINTAINERCLEANFILES = $(dot_html) $(apihtml) $(devhelphtml) all: web -api: libvirt-api.xml libvirt-refs.xml +api: $(srcdir)/libvirt-api.xml $(srcdir)/libvirt-refs.xml -web: $(dot_html) html/index.html devhelp/index.html +web: $(srcdir)/$(dot_html) $(srcdir)/html/index.html \ + $(srcdir)/devhelp/index.html ChangeLog.xml: ../ChangeLog ChangeLog.awk awk -f ChangeLog.awk < $< > $@ @@ -117,11 +118,13 @@ ChangeLog.html.in: ChangeLog.xml ChangeLog.xsl || { rm $@ && exit 1; }; \ else echo "missing XHTML1 DTD" ; fi ; fi - -html/index.html: libvirt-api.xml newapi.xsl page.xsl sitemap.html.in +$(srcdir)/html/index.html: $(srcdir)/libvirt-api.xml newapi.xsl page.xsl \ + sitemap.html.in -@if [ -x $(XSLTPROC) ] ; then \ echo "Rebuilding the HTML pages from the XML API" ; \ - $(XSLTPROC) --nonet $(srcdir)/newapi.xsl libvirt-api.xml ; fi + $(XSLTPROC) --nonet -o $(srcdir)/ \ + $(srcdir)/newapi.xsl $(srcdir)/libvirt-api.xml; \ + fi -@if test -x $(XMLLINT) && test -x $(XMLCATALOG) ; then \ if $(XMLCATALOG) /etc/xml/catalog "-//W3C//DTD XHTML 1.0 Strict//EN" \ @@ -129,19 +132,24 @@ html/index.html: libvirt-api.xml newapi.xsl page.xsl sitemap.html.in $(XMLLINT) --nonet --valid --noout html/*.html ; \ else echo "missing XHTML1 DTD" ; fi ; fi -$(devhelphtml): libvirt-api.xml $(devhelpxsl) +$(addprefix $(srcdir)/,$(devhelphtml)): $(srcdir)/libvirt-api.xml $(devhelpxsl) -@echo Rebuilding devhelp files -@if [ -x $(XSLTPROC) ] ; then \ $(XSLTPROC) --nonet -o devhelp/libvirt.devhelp \ - $(top_srcdir)/docs/devhelp/devhelp.xsl libvirt-api.xml ; fi - -html/%-%.html html/%-virterror.html %-api.xml %-refs.xml: $(srcdir)/apibuild.py - -srcdir=$(srcdir) $(srcdir)/apibuild.py - -html/%-%.html html/%-virterror.html %-api.xml %-refs.xml: \ - $(srcdir)/../include/%/*.h \ - $(srcdir)/../src/%.c \ + $(top_srcdir)/docs/devhelp/devhelp.xsl $(srcdir)/libvirt-api.xml ; \ + fi + +python_generated_files = \ + $(srcdir)/html/libvirt-libvirt.html \ + $(srcdir)/html/libvirt-virterror.html \ + $(srcdir)/libvirt-api.xml \ + $(srcdir)/libvirt-refs.xml + +$(python_generated_files): $(srcdir)/apibuild.py \ + $(srcdir)/../include/libvirt/*.h \ + $(srcdir)/../src/libvirt.c \ $(srcdir)/../src/util/virterror.c + -srcdir=$(srcdir) $(srcdir)/apibuild.py check-local: all @@ -149,7 +157,7 @@ clean-local: rm -f *~ *.bak *.hierarchy *.signals *-unused.txt maintainer-clean-local: clean-local - rm -rf libvirt-api.xml libvirt-refs.xml + rm -rf $(srcdir)/libvirt-api.xml $(srcdir)/libvirt-refs.xml rebuild: api all diff --git a/docs/apibuild.py b/docs/apibuild.py index 2dda4df..da50afb 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -11,6 +11,13 @@ import os, sys import string import glob +if __name__ == "__main__": + # launched as a script + srcPref = os.path.dirname(sys.argv[0]) +else: + # imported + srcPref = os.path.dirname(__file__) + debug=0 debugsym=None @@ -1983,7 +1990,7 @@ class docBuilder: idf = self.idx.identifiers[id] module = idf.header output.write(" <reference name='%s' href='%s'/>\n" % (id, - 'html/' + self.basename + '-' + + srcPref + '/html/' + self.basename + '-' + self.modulename_file(module) + '.html#' + id)) @@ -2057,7 +2064,7 @@ class docBuilder: def serialize(self): filename = "%s-api.xml" % self.name print "Saving XML description %s" % (filename) - output = open(filename, "w") + output = open(os.path.join(srcPref,filename), "w") output.write('<?xml version="1.0" encoding="ISO-8859-1"?>\n') output.write("<api name='%s'>\n" % self.name) output.write(" <files>\n") @@ -2093,7 +2100,7 @@ class docBuilder: filename = "%s-refs.xml" % self.name print "Saving XML Cross References %s" % (filename) - output = open(filename, "w") + output = open(os.path.join(srcPref,filename), "w") output.write('<?xml version="1.0" encoding="ISO-8859-1"?>\n') output.write("<apirefs name='%s'>\n" % self.name) self.serialize_xrefs(output) @@ -2109,10 +2116,11 @@ def rebuild(): builder = docBuilder("libvirt", [srcdir + "/../src", srcdir + "/../src/util", - srcdir + "/../include/libvirt"], + srcdir + "/../include/libvirt", + "../include/libvirt"], []) elif glob.glob("src/libvirt.c") != [] : - print "Rebuilding API description for libvir" + print "Rebuilding API description for libvirt" builder = docBuilder("libvirt", ["src", "src/util", "include/libvirt"], []) else: -- 1.7.0.1