diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/devel/blkverify.txt | 4 | ||||
| -rw-r--r-- | docs/devel/build-system.rst | 500 | ||||
| -rw-r--r-- | docs/devel/build-system.txt | 519 | ||||
| -rw-r--r-- | docs/devel/index.rst | 1 | ||||
| -rw-r--r-- | docs/devel/testing.rst | 11 | ||||
| -rw-r--r-- | docs/devel/tracing.txt | 2 | ||||
| -rw-r--r-- | docs/index.html.in | 4 | ||||
| -rw-r--r-- | docs/interop/live-block-operations.rst | 4 | ||||
| -rw-r--r-- | docs/interop/qemu-ga-ref.texi | 2 | ||||
| -rw-r--r-- | docs/interop/qemu-qmp-ref.texi | 2 | ||||
| -rw-r--r-- | docs/meson.build | 73 | ||||
| -rw-r--r-- | docs/sphinx/depfile.py | 51 |
13 files changed, 640 insertions, 535 deletions
diff --git a/docs/conf.py b/docs/conf.py index d6e173ef77..0dbd90dc11 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -67,7 +67,7 @@ needs_sphinx = '1.6' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'qmp_lexer', 'hxtool'] +extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/devel/blkverify.txt b/docs/devel/blkverify.txt index d556dc4e6d..aca826c51c 100644 --- a/docs/devel/blkverify.txt +++ b/docs/devel/blkverify.txt @@ -62,8 +62,8 @@ A more realistic scenario is verifying the installation of a guest OS: $ ./qemu-img create raw.img 16G $ ./qemu-img create -f qcow2 test.qcow2 16G - $ x86_64-softmmu/qemu-system-x86_64 -cdrom debian.iso \ - -drive file=blkverify:raw.img:test.qcow2 + $ ./qemu-system-x86_64 -cdrom debian.iso \ + -drive file=blkverify:raw.img:test.qcow2 If the installation is aborted when blkverify detects corruption, use qemu-io to explore the contents of the disk image at the sector in question. diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst new file mode 100644 index 0000000000..58bf392430 --- /dev/null +++ b/docs/devel/build-system.rst @@ -0,0 +1,500 @@ +================================== +The QEMU build system architecture +================================== + +This document aims to help developers understand the architecture of the +QEMU build system. As with projects using GNU autotools, the QEMU build +system has two stages, first the developer runs the "configure" script +to determine the local build environment characteristics, then they run +"make" to build the project. There is about where the similarities with +GNU autotools end, so try to forget what you know about them. + + +Stage 1: configure +================== + +The QEMU configure script is written directly in shell, and should be +compatible with any POSIX shell, hence it uses #!/bin/sh. An important +implication of this is that it is important to avoid using bash-isms on +development platforms where bash is the primary host. + +In contrast to autoconf scripts, QEMU's configure is expected to be +silent while it is checking for features. It will only display output +when an error occurs, or to show the final feature enablement summary +on completion. + +Because QEMU uses the Meson build system under the hood, only VPATH +builds are supported. There are two general ways to invoke configure & +perform a build: + + - VPATH, build artifacts outside of QEMU source tree entirely:: + + cd ../ + mkdir build + cd build + ../qemu/configure + make + + - VPATH, build artifacts in a subdir of QEMU source tree:: + + mkdir build + cd build + ../configure + make + +For now, checks on the compilation environment are found in configure +rather than meson.build, though this is expected to change. The command +line is parsed in the configure script and, whenever needed, converted +into the appropriate options to Meson. + +New checks should be added to Meson, which usually comprises the +following tasks: + + - Add a Meson build option to meson_options.txt. + + - Add support to the command line arg parser to handle any new + `--enable-XXX`/`--disable-XXX` flags required by the feature. + + - Add information to the help output message to report on the new + feature flag. + + - Add code to perform the actual feature check. + + - Add code to include the feature status in `config-host.h` + + - Add code to print out the feature status in the configure summary + upon completion. + + +Taking the probe for SDL as an example, we have the following pieces +in configure:: + + # Initial variable state + sdl=auto + + ..snip.. + + # Configure flag processing + --disable-gnutls) sdl=disabled + ;; + --enable-gnutls) sdl=enabled + ;; + + ..snip.. + + # Help output feature message + sdl SDL UI + + ..snip.. + + # Meson invocation + -Dsdl=$sdl + +In meson_options.txt:: + + option('sdl', type : 'feature', value : 'auto') + +In meson.build:: + + # Detect dependency + sdl = dependency('sdl2', + required: get_option('sdl'), + static: enable_static) + + # Create config-host.h + config_host_data.set('CONFIG_SDL', sdl.found()) + + # Summary + summary_info += {'SDL support': sdl.found()} + + + +Helper functions +---------------- + +The configure script provides a variety of helper functions to assist +developers in checking for system features: + +`do_cc $ARGS...` + Attempt to run the system C compiler passing it $ARGS... + +`do_cxx $ARGS...` + Attempt to run the system C++ compiler passing it $ARGS... + +`compile_object $CFLAGS` + Attempt to compile a test program with the system C compiler using + $CFLAGS. The test program must have been previously written to a file + called $TMPC. + +`compile_prog $CFLAGS $LDFLAGS` + Attempt to compile a test program with the system C compiler using + $CFLAGS and link it with the system linker using $LDFLAGS. The test + program must have been previously written to a file called $TMPC. + +`has $COMMAND` + Determine if $COMMAND exists in the current environment, either as a + shell builtin, or executable binary, returning 0 on success. + +`path_of $COMMAND` + Return the fully qualified path of $COMMAND, printing it to stdout, + and returning 0 on success. + +`check_define $NAME` + Determine if the macro $NAME is defined by the system C compiler + +`check_include $NAME` + Determine if the include $NAME file is available to the system C + compiler + +`write_c_skeleton` + Write a minimal C program main() function to the temporary file + indicated by $TMPC + +`feature_not_found $NAME $REMEDY` + Print a message to stderr that the feature $NAME was not available + on the system, suggesting the user try $REMEDY to address the + problem. + +`error_exit $MESSAGE $MORE...` + Print $MESSAGE to stderr, followed by $MORE... and then exit from the + configure script with non-zero status + +`query_pkg_config $ARGS...` + Run pkg-config passing it $ARGS. If QEMU is doing a static build, + then --static will be automatically added to $ARGS + + +Stage 2: Meson +============== + +The Meson build system is currently used to describe the build +process for: + +1) executables, which include: + + - Tools - qemu-img, qemu-nbd, qga (guest agent), etc + + - System emulators - qemu-system-$ARCH + + - Userspace emulators - qemu-$ARCH + + - Some (but not all) unit tests + +2) documentation + +3) ROMs, which can be either installed as binary blobs or compiled + +4) other data files, such as icons or desktop files + +The source code is highly modularized, split across many files to +facilitate building of all of these components with as little duplicated +compilation as possible. The Meson "sourceset" functionality is used +to list the files and their dependency on various configuration +symbols. + +Various subsystems that are common to both tools and emulators have +their own sourceset, for example `block_ss` for the block device subsystem, +`chardev_ss` for the character device subsystem, etc. These sourcesets +are then turned into static libraries as follows:: + + libchardev = static_library('chardev', chardev_ss.sources(), + name_suffix: 'fa', + build_by_default: false) + + chardev = declare_dependency(link_whole: libchardev) + +The special `.fa` suffix is needed as long as unit tests are built with +the older Makefile infrastructure, and will go away later. + +Files linked into emulator targets there can be split into two distinct groups +of files, those which are independent of the QEMU emulation target and +those which are dependent on the QEMU emulation target. + +In the target-independent set lives various general purpose helper code, +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. +Target-independent code lives in the `common_ss`, `softmmu_ss` and +`user_ss` sourcesets. `common_ss` is linked into all emulators, `softmmu_ss` +only in system emulators, `user_ss` only in user-mode emulators. + +In the target-dependent set lives CPU emulation, device emulation and +much glue code. This sometimes also has to be compiled multiple times, +once for each target being built. + +All binaries link with a static library `libqemuutil.a`, which is then +linked to all the binaries. `libqemuutil.a` is built from several +sourcesets; most of them however host generated code, and the only two +of general interest are `util_ss` and `stub_ss`. + +The separation between these two is purely for documentation purposes. +`util_ss` contains generic utility files. Even though this code is only +linked in some binaries, sometimes it requires hooks only in some of +these and depend on other functions that are not fully implemented by +all QEMU binaries. `stub_ss` links dummy stubs that will only be linked +into the binary if the real implementation is not present. In a way, +the stubs can be thought of as a portable implementation of the weak +symbols concept. + +The following files concur in the definition of which files are linked +into each emulator: + +`default-configs/*.mak` + The files under default-configs/ control what emulated hardware is built + into each QEMU system and userspace emulator targets. They merely contain + a list of config variable definitions like the machines that should be + included. For example, default-configs/aarch64-softmmu.mak has:: + + include arm-softmmu.mak + CONFIG_XLNX_ZYNQMP_ARM=y + CONFIG_XLNX_VERSAL=y + +`*/Kconfig` + These files are processed together with `default-configs/*.mak` and + describe the dependencies between various features, subsystems and + device models. They are described in kconfig.rst. + +These files rarely need changing unless new devices / hardware need to +be enabled for a particular system/userspace emulation target + + +Support scripts +--------------- + +Meson has a special convention for invoking Python scripts: if their +first line is `#! /usr/bin/env python3` and the file is *not* executable, +find_program() arranges to invoke the script under the same Python +interpreter that was used to invoke Meson. This is the most common +and preferred way to invoke support scripts from Meson build files, +because it automatically uses the value of configure's --python= option. + +In case the script is not written in Python, use a `#! /usr/bin/env ...` +line and make the script executable. + +Scripts written in Python, where it is desirable to make the script +executable (for example for test scripts that developers may want to +invoke from the command line, such as tests/qapi-schema/test-qapi.py), +should be invoked through the `python` variable in meson.build. For +example:: + + test('QAPI schema regression tests', python, + args: files('test-qapi.py'), + env: test_env, suite: ['qapi-schema', 'qapi-frontend']) + +This is needed to obey the --python= option passed to the configure +script, which may point to something other than the first python3 +binary on the path. + + +Stage 3: makefiles +================== + +The use of GNU make is required with the QEMU build system. + +The output of Meson is a build.ninja file, which is used with the Ninja +build system. QEMU uses a different approach, where Makefile rules are +synthesized from the build.ninja file. The main Makefile includes these +rules and wraps them so that e.g. submodules are built before QEMU. +The resulting build system is largely non-recursive in nature, in +contrast to common practices seen with automake. + +Tests are also ran by the Makefile with the traditional `make check` +phony target. Meson test suites such as `unit` can be ran with `make +check-unit` too. It is also possible to run tests defined in meson.build +with `meson test`. + +The following text is only relevant for unit tests which still have to +be converted to Meson. + +All binaries should link to `libqemuutil.a`, e.g.: + + qemu-img$(EXESUF): qemu-img.o ..snip.. libqemuutil.a + +On Windows, all binaries have the suffix `.exe`, so all Makefile rules +which create binaries must include the $(EXESUF) variable on the binary +name. e.g. + + qemu-img$(EXESUF): qemu-img.o ..snip.. + +This expands to `.exe` on Windows, or an empty string on other platforms. + +Variable naming +--------------- + +The QEMU convention is to define variables to list different groups of +object files. These are named with the convention $PREFIX-obj-y. The +Meson `chardev` variable in the previous example corresponds to a +variable 'chardev-obj-y'. + +Likewise, tests that are executed by `make check-unit` are grouped into +a variable check-unit-y, like this: + + check-unit-y += tests/test-visitor-serialization$(EXESUF) + check-unit-y += tests/test-iov$(EXESUF) + check-unit-y += tests/test-bitmap$(EXESUF) + +When a test or object file which needs to be conditionally built based +on some characteristic of the host system, the configure script will +define a variable for the conditional. For example, on Windows it will +define $(CONFIG_POSIX) with a value of 'n' and $(CONFIG_WIN32) with a +value of 'y'. It is now possible to use the config variables when +listing object files. For example, + + check-unit-$(CONFIG_POSIX) += tests/test-vmstate$(EXESUF) + +On Windows this expands to + + check-unit-n += tests/vmstate.exe + +Since the `check-unit` target only runs tests included in `$(check-unit-y)`, +POSIX specific tests listed in `$(util-obj-n)` are ignored on the Windows +platform builds. + + +CFLAGS / LDFLAGS / LIBS handling +-------------------------------- + +There are many different binaries being built with differing purposes, +and some of them might even be 3rd party libraries pulled in via git +submodules. As such the use of the global CFLAGS variable is generally +avoided in QEMU, since it would apply to too many build targets. + +Flags that are needed by any QEMU code (i.e. everything *except* GIT +submodule projects) are put in $(QEMU_CFLAGS) variable. For linker +flags the $(LIBS) variable is sometimes used, but a couple of more +targeted variables are preferred. + +In addition to these variables, it is possible to provide cflags and +libs against individual source code files, by defining variables of the +form $FILENAME-cflags and $FILENAME-libs. For example, the test +test-crypto-tlscredsx509 needs to link to the libtasn1 library, +so tests/Makefile.include defines some variables: + + tests/crypto-tls-x509-helpers.o-cflags := $(TASN1_CFLAGS) + tests/crypto-tls-x509-helpers.o-libs := $(TASN1_LIBS) + +The scope is a little different between the two variables. The libs get +used when linking any target binary that includes the curl.o object +file, while the cflags get used when compiling the curl.c file only. + + +Important files for the build system +==================================== + +Statically defined files +------------------------ + +The following key files are statically defined in the source tree, with +the rules needed to build QEMU. Their behaviour is influenced by a +number of dynamically created files listed later. + +`Makefile` + The main entry point used when invoking make to build all the components + of QEMU. The default 'all' target will naturally result in the build of + every component. Makefile takes care of recursively building submodules + directly via a non-recursive set of rules. + +`*/meson.build` + The meson.build file in the root directory is the main entry point for the + Meson build system, and it coordinates the configuration and build of all + executables. Build rules for various subdirectories are included in + other meson.build files spread throughout the QEMU source tree. + +`rules.mak` + This file provides the generic helper rules for invoking build tools, in + particular the compiler and linker. + +`tests/Makefile.include` + Rules for building the unit tests. This file is included directly by the + top level Makefile, so anything defined in this file will influence the + entire build system. Care needs to be taken when writing rules for tests + to ensure they only apply to the unit test execution / build. + +`tests/docker/Makefile.include` + Rules for Docker tests. Like tests/Makefile, this file is included + directly by the top level Makefile, anything defined in this file will + influence the entire build system. + +`tests/vm/Makefile.include` + Rules for VM-based tests. Like tests/Makefile, this file is included + directly by the top level Makefile, anything defined in this file will + influence the entire build system. + +Dynamically created files +------------------------- + +The following files are generated dynamically by configure in order to +control the behaviour of the statically defined makefiles. This avoids +the need for QEMU makefiles to go through any pre-processing as seen +with autotools, where Makefile.am generates Makefile.in which generates +Makefile. + +Built by configure: + +`config-host.mak` + When configure has determined the characteristics of the build host it + will write a long list of variables to config-host.mak file. This + provides the various install directories, compiler / linker flags and a + variety of `CONFIG_*` variables related to optionally enabled features. + This is imported by the top level Makefile and meson.build in order to + tailor the build output. + + config-host.mak is also used as a dependency checking mechanism. If make + sees that the modification timestamp on configure is newer than that on + config-host.mak, then configure will be re-run. + + The variables defined here are those which are applicable to all QEMU + build outputs. Variables which are potentially different for each + emulator target are defined by the next file... + +`$TARGET-NAME/config-target.mak` + TARGET-NAME is the name of a system or userspace emulator, for example, + x86_64-softmmu denotes the system emulator for the x86_64 architecture. + This file contains the variables which need to vary on a per-target + basis. For example, it will indicate whether KVM or Xen are enabled for + the target and any other potential custom libraries needed for linking + the target. + + +Built by Meson: + +`${TARGET-NAME}-config-devices.mak` + TARGET-NAME is again the name of a system or userspace emulator. The + config-devices.mak file is automatically generated by make using the + scripts/make_device_config.sh program, feeding it the + default-configs/$TARGET-NAME file as input. + +`config-host.h`, `$TARGET-NAME/config-target.h`, `$TARGET-NAME/config-devices.h` + These files are used by source code to determine what features + are enabled. They are generated from the contents of the corresponding + `*.h` files using the scripts/create_config program. This extracts + relevant variables and formats them as C preprocessor macros. + +`build.ninja` + The build rules. + + +Built by Makefile: + +`Makefile.ninja` + A Makefile conversion of the build rules in build.ninja. The conversion + is straightforward and, were it necessary to debug the rules produced + by Meson, it should be enough to look at build.ninja. The conversion + is performed by scripts/ninjatool.py. + +`Makefile.mtest` + The Makefile definitions that let "make check" run tests defined in + meson.build. The rules are produced from Meson's JSON description of + tests (obtained with "meson introspect --tests") through the script + scripts/mtest2make.py. + + +Useful make targets +------------------- + +`help` + Print a help message for the most common build targets. + +`print-VAR` + Print the value of the variable VAR. Useful for debugging the build + system. diff --git a/docs/devel/build-system.txt b/docs/devel/build-system.txt deleted file mode 100644 index 41bd08ea3a..0000000000 --- a/docs/devel/build-system.txt +++ /dev/null @@ -1,519 +0,0 @@ - The QEMU build system architecture - ================================== - -This document aims to help developers understand the architecture of the -QEMU build system. As with projects using GNU autotools, the QEMU build -system has two stages, first the developer runs the "configure" script -to determine the local build environment characteristics, then they run -"make" to build the project. There is about where the similarities with -GNU autotools end, so try to forget what you know about them. - - -Stage 1: configure -================== - -The QEMU configure script is written directly in shell, and should be -compatible with any POSIX shell, hence it uses #!/bin/sh. An important -implication of this is that it is important to avoid using bash-isms on -development platforms where bash is the primary host. - -In contrast to autoconf scripts, QEMU's configure is expected to be -silent while it is checking for features. It will only display output -when an error occurs, or to show the final feature enablement summary -on completion. - -Adding new checks to the configure script usually comprises the -following tasks: - - - Initialize one or more variables with the default feature state. - - Ideally features should auto-detect whether they are present, - so try to avoid hardcoding the initial state to either enabled - or disabled, as that forces the user to pass a --enable-XXX - / --disable-XXX flag on every invocation of configure. - - - Add support to the command line arg parser to handle any new - --enable-XXX / --disable-XXX flags required by the feature XXX. - - - Add information to the help output message to report on the new - feature flag. - - - Add code to perform the actual feature check. As noted above, try to - be fully dynamic in checking enablement/disablement. - - - Add code to print out the feature status in the configure summary - upon completion. - - - Add any new makefile variables to $config_host_mak on completion. - - -Taking (a simplified version of) the probe for gnutls from configure, -we have the following pieces: - - # Initial variable state - gnutls="" - - ..snip.. - - # Configure flag processing - --disable-gnutls) gnutls="no" - ;; - --enable-gnutls) gnutls="yes" - ;; - - ..snip.. - - # Help output feature message - gnutls GNUTLS cryptography support - - ..snip.. - - # Test for gnutls - if test "$gnutls" != "no"; then - if ! $pkg_config --exists "gnutls"; then - gnutls_cflags=`$pkg_config --cflags gnutls` - gnutls_libs=`$pkg_config --libs gnutls` - libs_softmmu="$gnutls_libs $libs_softmmu" - libs_tools="$gnutls_libs $libs_tools" - QEMU_CFLAGS="$QEMU_CFLAGS $gnutls_cflags" - gnutls="yes" - elif test "$gnutls" = "yes"; then - feature_not_found "gnutls" "Install gnutls devel" - else - gnutls="no" - fi - fi - - ..snip.. - - # Completion feature summary - echo "GNUTLS support $gnutls" - - ..snip.. - - # Define make variables - if test "$gnutls" = "yes" ; then - echo "CONFIG_GNUTLS=y" >> $config_host_mak - fi - - -Helper functions ----------------- - -The configure script provides a variety of helper functions to assist -developers in checking for system features: - - - do_cc $ARGS... - - Attempt to run the system C compiler passing it $ARGS... - - - do_cxx $ARGS... - - Attempt to run the system C++ compiler passing it $ARGS... - - - compile_object $CFLAGS - - Attempt to compile a test program with the system C compiler using - $CFLAGS. The test program must have been previously written to a file - called $TMPC. - - - compile_prog $CFLAGS $LDFLAGS - - Attempt to compile a test program with the system C compiler using - $CFLAGS and link it with the system linker using $LDFLAGS. The test - program must have been previously written to a file called $TMPC. - - - has $COMMAND - - Determine if $COMMAND exists in the current environment, either as a - shell builtin, or executable binary, returning 0 on success. - - - path_of $COMMAND - - Return the fully qualified path of $COMMAND, printing it to stdout, - and returning 0 on success. - - - check_define $NAME - - Determine if the macro $NAME is defined by the system C compiler - - - check_include $NAME - - Determine if the include $NAME file is available to the system C - compiler - - - write_c_skeleton - - Write a minimal C program main() function to the temporary file - indicated by $TMPC - - - feature_not_found $NAME $REMEDY - - Print a message to stderr that the feature $NAME was not available - on the system, suggesting the user try $REMEDY to address the - problem. - - - error_exit $MESSAGE $MORE... - - Print $MESSAGE to stderr, followed by $MORE... and then exit from the - configure script with non-zero status - - - query_pkg_config $ARGS... - - Run pkg-config passing it $ARGS. If QEMU is doing a static build, - then --static will be automatically added to $ARGS - - -Stage 2: makefiles -================== - -The use of GNU make is required with the QEMU build system. - -Although the source code is spread across multiple subdirectories, the -build system should be considered largely non-recursive in nature, in -contrast to common practices seen with automake. There is some recursive -invocation of make, but this is related to the things being built, -rather than the source directory structure. - -QEMU currently supports both VPATH and non-VPATH builds, so there are -three general ways to invoke configure & perform a build. - - - VPATH, build artifacts outside of QEMU source tree entirely - - cd ../ - mkdir build - cd build - ../qemu/configure - make - - - VPATH, build artifacts in a subdir of QEMU source tree - - mkdir build - cd build - ../configure - make - - - non-VPATH, build artifacts everywhere - - ./configure - make - -The QEMU maintainers generally recommend that a VPATH build is used by -developers. Patches to QEMU are expected to ensure VPATH build still -works. - - -Module structure ----------------- - -There are a number of key outputs of the QEMU build system: - - - Tools - qemu-img, qemu-nbd, qga (guest agent), etc - - System emulators - qemu-system-$ARCH - - Userspace emulators - qemu-$ARCH - - Unit tests - -The source code is highly modularized, split across many files to -facilitate building of all of these components with as little duplicated -compilation as possible. There can be considered to be two distinct -groups of files, those which are independent of the QEMU emulation -target and those which are dependent on the QEMU emulation target. - -In the target-independent set lives various general purpose helper code, -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-dependent set lives CPU emulation, device emulation and -much glue code. This sometimes also has to be compiled multiple times, -once for each target being built. - -The utility code that is used by all binaries is built into a -static archive called libqemuutil.a, which is then linked to all the -binaries. In order to provide hooks that are only needed by some of the -binaries, code in libqemuutil.a may depend on other functions that are -not fully implemented by all QEMU binaries. Dummy stubs for all these -functions are also provided by this library, and will only be linked -into the binary if the real implementation is not present. In a way, -the stubs can be thought of as a portable implementation of the weak -symbols concept. - -All binaries should link to libqemuutil.a, e.g.: - - qemu-img$(EXESUF): qemu-img.o ..snip.. libqemuutil.a - - -Windows platform portability ----------------------------- - -On Windows, all binaries have the suffix '.exe', so all Makefile rules -which create binaries must include the $(EXESUF) variable on the binary -name. e.g. - - qemu-img$(EXESUF): qemu-img.o ..snip.. - -This expands to '.exe' on Windows, or '' on other platforms. - -A further complication for the system emulator binaries is that -two separate binaries need to be generated. - -The main binary (e.g. 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 (e.g. -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-obj-y. For -example the libqemuutil.a file will be linked with all objects listed -in a variable 'util-obj-y'. So, for example, util/Makefile.obj will -contain a set of definitions looking like - - util-obj-y += bitmap.o bitops.o hbitmap.o - util-obj-y += fifo8.o - util-obj-y += acl.o - util-obj-y += error.o qemu-error.o - -When there is an object file which needs to be conditionally built based -on some characteristic of the host system, the configure script will -define a variable for the conditional. For example, on Windows it will -define $(CONFIG_POSIX) with a value of 'n' and $(CONFIG_WIN32) with a -value of 'y'. It is now possible to use the config variables when -listing object files. For example, - - util-obj-$(CONFIG_WIN32) += oslib-win32.o qemu-thread-win32.o - util-obj-$(CONFIG_POSIX) += oslib-posix.o qemu-thread-posix.o - -On Windows this expands to - - util-obj-y += oslib-win32.o qemu-thread-win32.o - util-obj-n += oslib-posix.o qemu-thread-posix.o - -Since libqemutil.a links in $(util-obj-y), the POSIX specific files -listed against $(util-obj-n) are ignored on the Windows platform builds. - - -CFLAGS / LDFLAGS / LIBS handling --------------------------------- - -There are many different binaries being built with differing purposes, -and some of them might even be 3rd party libraries pulled in via git -submodules. As such the use of the global CFLAGS variable is generally -avoided in QEMU, since it would apply to too many build targets. - -Flags that are needed by any QEMU code (i.e. everything *except* GIT -submodule projects) are put in $(QEMU_CFLAGS) variable. For linker -flags the $(LIBS) variable is sometimes used, but a couple of more -targeted variables are preferred. $(libs_softmmu) is used for -libraries that must be linked to system emulator targets, $(LIBS_TOOLS) -is used for tools like qemu-img, qemu-nbd, etc and $(LIBS_QGA) is used -for the QEMU guest agent. There is currently no specific variable for -the userspace emulator targets as the global $(LIBS), or more targeted -variables shown below, are sufficient. - -In addition to these variables, it is possible to provide cflags and -libs against individual source code files, by defining variables of the -form $FILENAME-cflags and $FILENAME-libs. For example, the curl block -driver needs to link to the libcurl library, so block/Makefile defines -some variables: - - curl.o-cflags := $(CURL_CFLAGS) - curl.o-libs := $(CURL_LIBS) - -The scope is a little different between the two variables. The libs get -used when linking any target binary that includes the curl.o object -file, while the cflags get used when compiling the curl.c file only. - - -Statically defined files ------------------------- - -The following key files are statically defined in the source tree, with -the rules needed to build QEMU. Their behaviour is influenced by a -number of dynamically created files listed later. - -- Makefile - -The main entry point used when invoking make to build all the components -of QEMU. The default 'all' target will naturally result in the build of -every component. The various tools and helper binaries are built -directly via a non-recursive set of rules. - -Each system/userspace emulation target needs to have a slightly -different set of make rules / variables. Thus, make will be recursively -invoked for each of the emulation targets. - -The recursive invocation will end up processing the toplevel -Makefile.target file (more on that later). - - -- */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) - -If there are any rules defined in the Makefile.objs file, they should -all use $(obj) as a prefix to the target, e.g. - - $(obj)/generated-tcg-tracers.h: $(obj)/generated-tcg-tracers.h-timestamp - - -- Makefile.target - -This file provides the entry point used to build each individual system -or userspace emulator target. Each enabled target has its own -subdirectory. For example if configure is run with the argument -'--target-list=x86_64-softmmu', then a sub-directory 'x86_64-softmmu' -will be created, containing a 'Makefile' which symlinks back to -Makefile.target - -So when the recursive '$(MAKE) -C x86_64-softmmu' is invoked, it ends up -using Makefile.target for the build rules. - - -- rules.mak - -This file provides the generic helper rules for invoking build tools, in -particular the compiler and linker. This also contains the magic (hairy) -'unnest-vars' function which is used to merge the variable definitions -from all Makefile.objs in the source tree down into the main Makefile -context. - - -- default-configs/*.mak - -The files under default-configs/ control what emulated hardware is built -into each QEMU system and userspace emulator targets. They merely contain -a list of config variable definitions like the machines that should be -included. For example, default-configs/aarch64-softmmu.mak has: - - include arm-softmmu.mak - CONFIG_XLNX_ZYNQMP_ARM=y - CONFIG_XLNX_VERSAL=y - -These files rarely need changing unless new devices / hardware need to -be enabled for a particular system/userspace emulation target - - -- tests/Makefile - -Rules for building the unit tests. This file is included directly by the -top level Makefile, so anything defined in this file will influence the -entire build system. Care needs to be taken when writing rules for tests -to ensure they only apply to the unit test execution / build. - -- tests/docker/Makefile.include - -Rules for Docker tests. Like tests/Makefile, this file is included -directly by the top level Makefile, anything defined in this file will -influence the entire build system. - -- po/Makefile - -Rules for building and installing the binary message catalogs from the -text .po file sources. This almost never needs changing for any reason. - - -Dynamically created files -------------------------- - -The following files are generated dynamically by configure in order to -control the behaviour of the statically defined makefiles. This avoids -the need for QEMU makefiles to go through any pre-processing as seen -with autotools, where Makefile.am generates Makefile.in which generates -Makefile. - - -- config-host.mak - -When configure has determined the characteristics of the build host it -will write a long list of variables to config-host.mak file. This -provides the various install directories, compiler / linker flags and a -variety of CONFIG_* variables related to optionally enabled features. -This is imported by the top level Makefile in order to tailor the build -output. - -The variables defined here are those which are applicable to all QEMU -build outputs. Variables which are potentially different for each -emulator target are defined by the next file... - -It is also used as a dependency checking mechanism. If make sees that -the modification timestamp on configure is newer than that on -config-host.mak, then configure will be re-run. - - -- config-host.h - -The config-host.h file is used by source code to determine what features -are enabled. It is generated from the contents of config-host.mak using -the scripts/create_config program. This extracts all the CONFIG_* variables, -most of the HOST_* variables and a few other misc variables from -config-host.mak, formatting them as C preprocessor macros. - - -- $TARGET-NAME/config-target.mak - -TARGET-NAME is the name of a system or userspace emulator, for example, -x86_64-softmmu denotes the system emulator for the x86_64 architecture. -This file contains the variables which need to vary on a per-target -basis. For example, it will indicate whether KVM or Xen are enabled for -the target and any other potential custom libraries needed for linking -the target. - - -- $TARGET-NAME/config-devices.mak - -TARGET-NAME is again the name of a system or userspace emulator. The -config-devices.mak file is automatically generated by make using the -scripts/make_device_config.sh program, feeding it the -default-configs/$TARGET-NAME file as input. - - -- $TARGET-NAME/Makefile - -This is the entrypoint used when make recurses to build a single system -or userspace emulator target. It is merely a symlink back to the -Makefile.target in the top level. - - -Useful make targets -=================== - -- help - - Print a help message for the most common build targets. - -- print-VAR - - Print the value of the variable VAR. Useful for debugging the build - system. diff --git a/docs/devel/index.rst b/docs/devel/index.rst index ae6eac7c9c..04773ce076 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -13,6 +13,7 @@ Contents: .. toctree:: :maxdepth: 2 + build-system kconfig loads-stores memory diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index c1ff24370b..196e3bc35e 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -164,13 +164,12 @@ instrumenting the tested code. To use it, configure QEMU with ``--enable-gcov`` option and build. Then run ``make check`` as usual. If you want to gather coverage information on a single test the ``make -clean-coverage`` target can be used to delete any existing coverage +clean-gcda`` target can be used to delete any existing coverage information before running a single test. You can generate a HTML coverage report by executing ``make -coverage-report`` which will create -./reports/coverage/coverage-report.html. If you want to create it -elsewhere simply execute ``make /foo/bar/baz/coverage-report.html``. +coverage-html`` which will create +``meson-logs/coveragereport/index.html``. Further analysis can be conducted by running the ``gcov`` command directly on the various .gcda output files. Please read the ``gcov`` @@ -820,7 +819,7 @@ the following approaches: 1) Set ``qemu_bin``, and use the given binary 2) Do not set ``qemu_bin``, and use a QEMU binary named like - "${arch}-softmmu/qemu-system-${arch}", either in the current + "qemu-system-${arch}", either in the current working directory, or in the current source tree. The resulting ``qemu_bin`` value will be preserved in the @@ -887,7 +886,7 @@ like the following: .. code:: - PARAMS (key=qemu_bin, path=*, default=x86_64-softmmu/qemu-system-x86_64) => 'x86_64-softmmu/qemu-system-x86_64 + PARAMS (key=qemu_bin, path=*, default=./qemu-system-x86_64) => './qemu-system-x86_64 arch ~~~~ diff --git a/docs/devel/tracing.txt b/docs/devel/tracing.txt index cb5f685de9..6144d9921b 100644 --- a/docs/devel/tracing.txt +++ b/docs/devel/tracing.txt @@ -60,7 +60,7 @@ general. It is strongly preferred that all events be declared directly in the sub-directory that uses them. The only exception is where there are some shared trace events defined in the top level directory trace-events file. The top level directory generates trace files with a filename prefix of -"trace-root" instead of just "trace". This is to avoid ambiguity between +"trace/trace-root" instead of just "trace". This is to avoid ambiguity between a trace.h in the current directory, vs the top level directory. === Using trace events === diff --git a/docs/index.html.in b/docs/index.html.in index 6736fa4360..ca28047881 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -2,10 +2,10 @@ <html lang="en"> <head> <meta charset="UTF-8"> - <title>QEMU @@VERSION@@ Documentation</title> + <title>QEMU @VERSION@ Documentation</title> </head> <body> - <h1>QEMU @@VERSION@@ Documentation</h1> + <h1>QEMU @VERSION@ Documentation</h1> <ul> <li><a href="system/index.html">System Emulation User's Guide</a></li> <li><a href="user/index.html">User Mode Emulation User's Guide</a></li> diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst index 48afdc7927..e13f5a21f8 100644 --- a/docs/interop/live-block-operations.rst +++ b/docs/interop/live-block-operations.rst @@ -129,7 +129,7 @@ To show some example invocations of command-line, we will use the following invocation of QEMU, with a QMP server running over UNIX socket:: - $ ./x86_64-softmmu/qemu-system-x86_64 -display none -no-user-config \ + $ ./qemu-system-x86_64 -display none -no-user-config \ -M q35 -nodefaults -m 512 \ -blockdev node-name=node-A,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./a.qcow2 \ -device virtio-blk,drive=node-A,id=virtio0 \ @@ -694,7 +694,7 @@ instance, with the following invocation. (As noted earlier, for simplicity's sake, the destination QEMU is started on the same host, but it could be located elsewhere):: - $ ./x86_64-softmmu/qemu-system-x86_64 -display none -no-user-config \ + $ ./qemu-system-x86_64 -display none -no-user-config \ -M q35 -nodefaults -m 512 \ -blockdev node-name=node-TargetDisk,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./target-disk.qcow2 \ -device virtio-blk,drive=node-TargetDisk,id=virtio0 \ diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi index ddb76ce1c2..a23cc2ed7f 100644 --- a/docs/interop/qemu-ga-ref.texi +++ b/docs/interop/qemu-ga-ref.texi @@ -65,7 +65,7 @@ along with this manual. If not, see http://www.gnu.org/licenses/. @c for texi2pod: @c man begin DESCRIPTION -@include qemu-ga-qapi.texi +@include qga/qga-qapi-doc.texi @c man end diff --git a/docs/interop/qemu-qmp-ref.texi b/docs/interop/qemu-qmp-ref.texi index bb25758bd0..ea1d7fe6c2 100644 --- a/docs/interop/qemu-qmp-ref.texi +++ b/docs/interop/qemu-qmp-ref.texi @@ -65,7 +65,7 @@ along with this manual. If not, see http://www.gnu.org/licenses/. @c for texi2pod: @c man begin DESCRIPTION -@include qemu-qmp-qapi.texi +@include qapi/qapi-doc.texi @c man end diff --git a/docs/meson.build b/docs/meson.build new file mode 100644 index 0000000000..8b059a8e39 --- /dev/null +++ b/docs/meson.build @@ -0,0 +1,73 @@ +SPHINX_ARGS = [config_host['SPHINX_BUILD'], + '-Dversion=' + meson.project_version(), + '-Drelease=' + config_host['PKGVERSION']] + +if get_option('werror') + SPHINX_ARGS += [ '-W' ] +endif + +if build_docs + configure_file(output: 'index.html', + input: files('index.html.in'), + configuration: {'VERSION': meson.project_version()}, + install_dir: config_host['qemu_docdir']) + manuals = [ 'devel', 'interop', 'tools', 'specs', 'system', 'user' ] + man_pages = { + 'interop' : { + 'qemu-ga.8': (have_tools ? 'man8' : ''), + }, + 'tools': { + 'qemu-img.1': (have_tools ? 'man1' : ''), + 'qemu-nbd.8': (have_tools ? 'man8' : ''), + 'qemu-trace-stap.1': (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''), + 'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''), + 'virtiofsd.1': (have_virtiofsd ? 'man1' : ''), + }, + 'system': { + 'qemu.1': 'man1', + 'qemu-block-drivers.7': 'man7', + 'qemu-cpu-models.7': 'man7' + }, + } + + sphinxdocs = [] + sphinxmans = [] + foreach manual : manuals + private_dir = meson.current_build_dir() / (manual + '.p') + output_dir = meson.current_build_dir() / manual + input_dir = meson.current_source_dir() / manual + + this_manual = custom_target(manual + ' manual', + build_by_default: build_docs, + output: [manual + '.stamp'], + input: [files('conf.py'), files(manual / 'conf.py')], + depfile: manual + '.d', + command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@', + '-Ddepfile_stamp=@OUTPUT0@', + '-b', 'html', '-d', private_dir, + input_dir, output_dir]) + sphinxdocs += this_manual + if build_docs and manual != 'devel' + install_subdir(output_dir, install_dir: config_host['qemu_docdir']) + endif + + these_man_pages = [] + install_dirs = [] + foreach page, section : man_pages.get(manual, {}) + these_man_pages += page + install_dirs += section == '' ? false : get_option('mandir') / section + endforeach + if these_man_pages.length() > 0 + sphinxmans += custom_target(manual + ' man pages', + build_by_default: build_docs, + output: these_man_pages, + input: this_manual, + install: build_docs, + install_dir: install_dirs, + command: [SPHINX_ARGS, '-b', 'man', '-d', private_dir, + input_dir, meson.current_build_dir()]) + endif + endforeach + alias_target('sphinxdocs', sphinxdocs) + alias_target('man', sphinxmans) +endif diff --git a/docs/sphinx/depfile.py b/docs/sphinx/depfile.py new file mode 100644 index 0000000000..277fdf0f56 --- /dev/null +++ b/docs/sphinx/depfile.py @@ -0,0 +1,51 @@ +# coding=utf-8 +# +# QEMU depfile generation extension +# +# Copyright (c) 2020 Red Hat, Inc. +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. + +"""depfile is a Sphinx extension that writes a dependency file for + an external build system""" + +import os +import sphinx + +__version__ = '1.0' + +def get_infiles(env): + for x in env.found_docs: + yield env.doc2path(x) + yield from ((os.path.join(env.srcdir, dep) + for dep in env.dependencies[x])) + +def write_depfile(app, env): + if not env.config.depfile: + return + + # Using a directory as the output file does not work great because + # its timestamp does not necessarily change when the contents change. + # So create a timestamp file. + if env.config.depfile_stamp: + with open(env.config.depfile_stamp, 'w') as f: + pass + + with open(env.config.depfile, 'w') as f: + print((env.config.depfile_stamp or app.outdir) + ": \\", file=f) + print(*get_infiles(env), file=f) + for x in get_infiles(env): + print(x + ":", file=f) + + +def setup(app): + app.add_config_value('depfile', None, 'env') + app.add_config_value('depfile_stamp', None, 'env') + app.connect('env-updated', write_depfile) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) |