[libvirt] [PATCHv2 2/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 (EXTRA_DIST): Remove redundant listing of xml files. ($(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. (libvirt-api.xml, libvirt-refs.xml): ...longhand. (api, web, html/index.html, maintainer-clean-local): (html/index.html, %.html.tmp, %.html): Update location. (dot_html_in, patches): Massage wildcard correctly. * docs/apibuild.py (docBuilder.serialize): Put output in srcdir. (docBuilder.serialize_xrefs_references): Update location. (rebuild): Look for built libvirt.h in builddir. * .gitignore: Ignore 'make distcheck' crumbs. --- This patch replaces 2/2 of v1 of the series (1/2 of the original series is already pushed). It took me a lot longer than originally anticipated, because the docs/Makefile.am was playing quite fast and loose when it came to builddir vs. srcdir. This is my first time ever writing a patch that involves python source. But as stated in the commit message, I proved to myself that it works by doing 'make distcheck' from a VPATH build. .gitignore | 1 + docs/Makefile.am | 52 +++++++++++++++++++++++++++++++--------------------- docs/apibuild.py | 18 +++++++++++++----- 3 files changed, 45 insertions(+), 26 deletions(-) diff --git a/.gitignore b/.gitignore index 8c275f4..76c8986 100644 --- a/.gitignore +++ b/.gitignore @@ -33,6 +33,7 @@ cscope.files cscope.out gnulib/ libtool +/libvirt-[0-9]* libvirt-*.tar.gz libvirt.pc libvirt.spec diff --git a/docs/Makefile.am b/docs/Makefile.am index a18821b..91ae13e 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 < $< > $@ @@ -99,7 +100,7 @@ ChangeLog.html.in: ChangeLog.xml ChangeLog.xsl %.png: %.fig convert -rotate 90 $< $@ -%.html.tmp: %.html.in site.xsl page.xsl sitemap.html.in +%.html.tmp: $(srcdir)/%.html.in site.xsl page.xsl sitemap.html.in @(if [ -x $(XSLTPROC) ] ; then \ echo "Generating $@"; \ name=`echo $@ | sed -e 's/.tmp//'`; \ @@ -107,16 +108,20 @@ ChangeLog.html.in: ChangeLog.xml ChangeLog.xsl %.html: %.html.tmp @(if test -x $(XMLLINT) && test -x $(XMLCATALOG) ; then \ - if $(XMLCATALOG) /etc/xml/catalog "-//W3C//DTD XHTML 1.0 Strict//EN" > /dev/null ; then \ + if $(XMLCATALOG) /etc/xml/catalog \ + "-//W3C//DTD XHTML 1.0 Strict//EN" > /dev/null ; then \ echo "Validating $@" ; \ - $(XMLLINT) --nonet --format --valid $< > $@ || (rm $@ && exit 1) ; \ + $(XMLLINT) --nonet --format --valid $< > $@ \ + || (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 $(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" \ @@ -124,25 +129,30 @@ 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) +$(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 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.6.6.1