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

Eric Blake eblake at redhat.com
Fri Jun 25 15:30:47 UTC 2010


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.
---

No change from https://www.redhat.com/archives/libvir-list/2010-June/msg00051.html.

However, testing reveals that this fixes the dependency issue
described by Matthias on IRC:

[17:20]	  <photron>   eblake_out: i can reproduce a depedency problem here
[17:20]	  <photron>   steps to reproduce
[17:20]	  <photron>   change include/libvirt.h.in, e.g. a a new item to an enum
[17:20]	  <photron>   run make
[17:20]	  <photron>   include/libvirt.h gets regerenated, as expected
[17:20]	  <photron>   docs/libvirt-api.xml doesn't list the new item, but it should
[17:24]	  <photron>   eblake_out: i can fix that by reverting a79fb1c491197a91094cd2345c3d7bbba40da2fd partly
[17:25]	  <photron>   then chnaging the input files for apibuild.py triggers a regeneration of libvirt-api.xml again

Commit a79fb1c4 is part of 0.8.0, which explains why 0.8.1-10.el6 did not
pick up VIR_DOMAIN_START_PAUSED (the api docs were not regenerated
correctly, due to the missing dependency).  The addition of
$(python_generated_files) and better spelling of their dependencies
in the patch below serves as the partial reversion of a79fb1c that
is sufficient to resolve the problem in BZ 589465.

 docs/Makefile.am |   48 ++++++++++++++++++++++++++++--------------------
 docs/apibuild.py |   18 +++++++++++++-----
 2 files changed, 41 insertions(+), 25 deletions(-)

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 41068c6..57979e2 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
 	- at 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
 	- at 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)
 	- at echo Rebuilding devhelp files
 	- at 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 \
+	  $(XSLTPROC) --nonet -o $(srcdir)/devhelp/ \
+	  $(srcdir)/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..990451c 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 + '-' +
+			 '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




More information about the libvir-list mailing list