From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:38354) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RbBOd-0003ZR-2u for qemu-devel@nongnu.org; Thu, 15 Dec 2011 08:30:54 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RbBOT-0004j2-C2 for qemu-devel@nongnu.org; Thu, 15 Dec 2011 08:30:51 -0500 Received: from mail-iy0-f173.google.com ([209.85.210.173]:51654) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RbBOT-0004iw-6t for qemu-devel@nongnu.org; Thu, 15 Dec 2011 08:30:41 -0500 Received: by iagj37 with SMTP id j37so3211596iag.4 for ; Thu, 15 Dec 2011 05:30:40 -0800 (PST) Message-ID: <4EE9F67B.3060302@codemonkey.ws> Date: Thu, 15 Dec 2011 07:30:35 -0600 From: Anthony Liguori 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: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Avi Kivity Cc: qemu-devel@nongnu.org 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 @@ >> + >> +> + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" >> +[ >> + >> +]> >> + >> + >> +QEMU Reference Manual >> + >> + for QEMU 1.0. > > 1.1. >