[libvirt] [PATCHv2 2/2] build: fix VPATH build of docs

Eric Blake eblake at redhat.com
Thu Apr 29 01:37:02 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 (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




More information about the libvir-list mailing list