Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure for gtkdocs

[Anthony Liguori]

On 12/15/2011 03:37 AM, Avi Kivity wrote:
> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
> > By convention, documented headers now go in include/
>
> Dislike.

I've been planning on doing this for a while.  I think it's a useful way to help 
improve internal modularity.  It provides a consistent way to indicate which 
headers represent "public" internal interfaces (like the memory API) verses 
things that are really private headers specific to a submodule (say block_int.h).

We have a real problem internally with headers too.  It's almost surprising how 
many lack guards, don't have proper #includes, etc.  By moving all public 
headers to include/, it gives us a systematic way to go through, clean up 
various headers, and have an idea of how much work is left to be done.

> > +include $(SRC_PATH)/Makefile.docs
> > +
> >   $(common-obj-y): $(GENERATED_HEADERS)
> >   subdir-libcacard: $(oslib-obj-y) $(trace-obj-y) qemu-timer-common.o
> >
> > @@ -113,6 +115,8 @@ QEMU_CFLAGS+=$(CURL_CFLAGS)
> >
> >   QEMU_CFLAGS+=$(GLIB_CFLAGS)
> >
> > +QEMU_CFLAGS+=$(SRC_PATH)/include
> > +
> >   ui/cocoa.o: ui/cocoa.m
>
> Documentation should be built by default, so that errors in the format
> are detected (and break the build).

I agree, but since we now are dealing with a fork of a common tool, I didn't 
want to add a hard build dependency until I can get some feedback on whether 
upstream is willing to consider our patch.

> > +
> > +gtkdoc: html/index.html
> > +
> > +html/index.html: $(DOC_SRC)
> > +       gtkdoc-scan --module=QEMU --source-dir=$(SRC_PATH)/include&&  \
> > +        cp $(SRC_PATH)/QEMU-docs.xml .&&  \
> > +       gtkdoc-mkdb --module=QEMU --output-format=xml 
> > --source-dir=$(SRC_PATH)/include&&  \
> > +       mkdir -p html&&  \
> > +        (cd html&&  gtkdoc-mkhtml QEMU ../QEMU-docs.xml&&  cd ..)&&  \
> > +       gtkdoc-fixxref --module=QEMU --module-dir=html
> > +
>
> Does this thing not support incremental builds?

As best as I can tell, no.  Every other tool I've looked as suffers from the 
same problem.

Regards,

Anthony Liguori

> > +++ b/QEMU-docs.xml
> > @@ -0,0 +1,31 @@
> > +<?xml version="1.0"?>
> > +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
> > +               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
> > +[
> > +<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 
> > 'http://www.w3.org/2003/XInclude'">
> > +]>
> > +<book id="index">
> > +<bookinfo>
> > +<title>QEMU Reference Manual</title>
> > +<releaseinfo>
> > +      for QEMU 1.0.
>
> 1.1.