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
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list