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

[Stefan Weil]

Am 15.12.2011 10:37, schrieb Avi Kivity:
> On 12/14/2011 06:20 PM, Anthony Liguori wrote:
> > By convention, documented headers now go in include/
>
> Dislike.
> > +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. It is built by default today, and there is a configure option
to disable this default behavior.

> > +
> > +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?

I don't know the answer for gtkdoc, but at least for doxygen incremental 
builds
are not useful if you want to use advanced features like cross reference 
listings:
bidirectional references must parse all files (or would need rather 
complicated
dependency lists).

Parsing of the QEMU code and generation of advanced html output (which
includes style sheets and graphics) with doxygen takes about 4 min on my 
server
and creates 70 MB of data.

If only some public interfaces are analyzed (like memory.h), this takes 
of course
much less time. Keeping those public interfaces in one place (in 
directory 'include',
for example) supports this approach.

Regards,
Stefan Weil