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
