Re: [Qemu-devel] [PATCH] docs: describe the QEMU build system structure / design

[Paolo Bonzini]

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