10:30 a.m.
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
-@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 \
+ $(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