From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54546) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZeTXN-0004n6-HB for qemu-devel@nongnu.org; Tue, 22 Sep 2015 15:47:38 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZeTXI-0000eF-Gk for qemu-devel@nongnu.org; Tue, 22 Sep 2015 15:47:37 -0400 Received: from mail-wi0-x236.google.com ([2a00:1450:400c:c05::236]:35423) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZeTXI-0000e5-6G for qemu-devel@nongnu.org; Tue, 22 Sep 2015 15:47:32 -0400 Received: by wicge5 with SMTP id ge5so177282089wic.0 for ; Tue, 22 Sep 2015 12:47:31 -0700 (PDT) Sender: Paolo Bonzini References: <1442939759-9862-1-git-send-email-berrange@redhat.com> <560199E7.6020401@redhat.com> From: Paolo Bonzini Message-ID: <5601B04E.20205@redhat.com> Date: Tue, 22 Sep 2015 21:47:26 +0200 MIME-Version: 1.0 In-Reply-To: <560199E7.6020401@redhat.com> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit Subject: Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: John Snow , "Daniel P. Berrange" , qemu-devel@nongnu.org On 22/09/2015 20:11, John Snow wrote: >> +such as error handling infrastructure, standard data structures, >> +platform portability wrapper functions, etc. This code can be compiled >> +once only and the .o files linked into all output binaries. >> + >> +In the target dependant set lives CPU emulation, device emulation and >> +much glue code. This code is generally compiled multiple times, once for s/is generally compiled/sometimes also has to be compiled/ >> +each target architecture being built. ... while in other cases can be compiled once for each architecture. Do not use "target architecture", since you're using "target" to mean a Makefile target, i.e. binary. >> +The target independant code that is used by all binaries is built into a s/The target independant/Utlity/ >> +static archive called libqemuutil.a, which is then linked to all the >> +binaries. Due to ongoing incomplete refactoring, some of the code in s/Due to ongoing incomplete refactoring/In order to provide hooks that are only needed by some of the binaries/ >> +libqemuutil.a depends on other functions that are not available in all s/available in/fully implemented by/ >> +QEMU binaries. To deal with this there is a second library called >> +libqemustub.a which provide dummy stubs for all these functions. These >> +will get lazy linked into the binary if the real implementation is not >> +present. Thus any time a binary links to libqemuutil.a, it should also >> +be made to link libqemustub.a. eg >> + >> + qemu-img$(EXESUF): qemu-img.o ..snip.. libqemuutil.a libqemustub.a Really all binaries should link libqemustub.a. Perhaps add a note that libqemustub symbols effectively work as weak symbols, but a static library is more portable? >> + >> +Windows platform portability >> +---------------------------- >> + >> +On Windows all binaries have a .exe suffix, so all the Makefile rules > > I guess you pronounce the 'dot' :) > >> +which create binaries must include the $(EXESUF) variable on the binary >> +name. eg > > 'e.g.' here and everywhere subsequent. > >> + >> + qemu-img$(EXESUF): qemu-img.o ..snip.. >> + >> +This expands to '.exe' on Windows, or '' on other platforms. >> + >> +A further complication for the system and userspace emulator binaries is >> +that two separate binaries need to be generated. >> + >> +The main binary (eg qemu-system-x86_64.exe) is linked against the >> +Windows console runtime subsystem. These are expected to be run from a >> +command prompt window, and so will print stderr to the console that >> +launched them. >> + >> +The second binary generated has a 'w' on the end of its name (eg >> +qemu-system-x86_64w.exe) and is linked against the Windows graphical >> +runtime subsystem. These are expected to be run directly from the >> +desktop and will open up a dedicated console window for stderr output. >> + >> +The Makefile.target will generate the binary for the graphical subsystem >> +first, and then use objcopy to relink it against the console subsystem >> +to generate the second binary. >> + >> + >> +Object variable naming >> +---------------------- >> + >> +The QEMU convention is to define variables to list different groups of >> +object files. These are named with the convention $PREFIX-y. For example $PREFIX-obj-y >> +the libqemuutil.a file will be linked with all objects listed in a >> +variable 'util-y'. util-obj-y. >> +- */Makefile.objs >> + >> +Since the source code is spread across multiple directories, the rules >> +for each file are similarly modularized. Thus each subdirectory >> +containing .c files will usually also contain a Makefile.objs file. >> +These files are not directly invoked by a recursive make, but instead >> +they are imported by the top level Makefile and/or Makefile.target >> + >> +Each Makefile.objs usually just declares a set of variables listing the >> +.o files that need building from the source files in the directory. They >> +will also define any custom linker or compiler flags. For example in >> +block/Makefile.objs >> + >> + block-obj-$(CONFIG_LIBISCSI) += iscsi.o >> + block-obj-$(CONFIG_CURL) += curl.o >> + >> + ..snip... >> + >> + iscsi.o-cflags := $(LIBISCSI_CFLAGS) >> + iscsi.o-libs := $(LIBISCSI_LIBS) >> + curl.o-cflags := $(CURL_CFLAGS) >> + curl.o-libs := $(CURL_LIBS) You may want to mention that rules in */Makefile.objs should use $(obj) as a prefix to the target, for example: $(obj)/generated-tcg-tracers.h: $(obj)/generated-tcg-tracers.h-timestamp I'll join the choir: awesome job. Paolo