From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([140.186.70.92]:41658)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <sw@weilnetz.de>) id 1Rb8Db-00059b-DN
	for qemu-devel@nongnu.org; Thu, 15 Dec 2011 05:07:21 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <sw@weilnetz.de>) id 1Rb8DW-0001wI-G2
	for qemu-devel@nongnu.org; Thu, 15 Dec 2011 05:07:15 -0500
Received: from v220110690675601.yourvserver.net ([78.47.199.172]:53791)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <sw@weilnetz.de>) id 1Rb8DW-0001w2-9V
	for qemu-devel@nongnu.org; Thu, 15 Dec 2011 05:07:10 -0500
Message-ID: <4EE9C6A2.1060502@weilnetz.de>
Date: Thu, 15 Dec 2011 11:06:26 +0100
From: Stefan Weil <sw@weilnetz.de>
MIME-Version: 1.0
References: <1323879637-16901-1-git-send-email-aliguori@us.ibm.com>	<1323879637-16901-3-git-send-email-aliguori@us.ibm.com>
	<4EE9BFD9.3040108@redhat.com>
In-Reply-To: <4EE9BFD9.3040108@redhat.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [Qemu-devel] [PATCH 2/4] docs: add build infrastructure
	for	gtkdocs
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: Avi Kivity <avi@redhat.com>
Cc: Anthony Liguori <aliguori@us.ibm.com>, qemu-devel@nongnu.org

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