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. ---
Should we be distributing a pre-built libvirt-api.xml and libvirt-override-api.xml?
I doubt we've documented the criteria libvirt uses for deciding whether to distribute generated files. However, one good reason to distribute such files (generated by python scripts) is to be able to provide the API xml files even to people who lack python support and to those who choose to configure --without-python.
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" \ > /dev/null ; then \ @@ -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