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

[Matthias Bolte]

2010/6/3 Eric Blake <eblake at redhat.com>:
> 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
>        - 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 \

I think we need to add   -o $(srcdir)/  here too otherwise the files
will be put into the $(builddir), but they should be in $(srcdir)
because they are distributed.

> -         $(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))
>

Without this patch a normal in-tree build created lines like this

  <reference name='LIBVIR_VERSION_NUMBER'
href='html/libvirt-libvirt.html#LIBVIR_VERSION_NUMBER'/>

in docs/libvirt-refs.xml.

With you're patches and running autobulild.sh creates lines link this

  <reference name='LIBVIR_VERSION_NUMBER'
href='../../docs/html/libvirt-libvirt.html#LIBVIR_VERSION_NUMBER'/>

in docs/libvirt-refs.xml, referencing a docs directory above the $(top_srcdir).

Also, I wonder why you changed the path generation for the
libvirt-refs.xml file when neither the libvirt-refs.xml nor the
referenced html files get placed into the build directory.

Matthias