Re: [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" \            > /dev/null ; then \ @@ -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))