@@ -187,21 +187,23 @@ process for:
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.
-
All executables are built by default, except for some `contrib/`
binaries that are known to fail to build on some platforms (for example
32-bit or big-endian platforms). Tests are also built by default,
though that might change in the future.
-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::
+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. Using the Meson "sourceset" functionality,
+`meson.build` files group the source files in rules that are
+enabled according to the available system libraries and to various
+configuration symbols. Sourcesets belong to one of four groups:
+
+Subsystem sourcesets:
+ 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',
@@ -209,61 +211,111 @@ are then turned into static libraries as follows::
chardev = declare_dependency(link_whole: libchardev)
-As of Meson 0.55.1, the special `.fa` suffix should be used for everything
-that is used with `link_whole`, to ensure that the link flags are placed
-correctly in the command line.
-
-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. Target-dependent files are included
-in the `specific_ss` sourceset.
-
-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.
+ As of Meson 0.55.1, the special `.fa` suffix should be used for everything
+ that is used with `link_whole`, to ensure that the link flags are placed
+ correctly in the command line.
+
+Target-independent emulator sourcesets:
+ Various general purpose helper code is compiled only once and
+ the .o files are linked into all output binaries that need it.
+ This includes error handling infrastructure, standard data structures,
+ platform portability wrapper functions, etc.
+
+ 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.
+
+ Target-independent sourcesets must exercise particular care when using
+ `if_false` rules. The `if_false` rule will be used correctly when linking
+ emulator binaries; however, when *compiling* target-independent files
+ into .o files, Meson needs to pick *both* the `if_true` and
+ `if_false` sides to cater for targets that need either side. For
+ that reason, you need to add a special rule using the ``CONFIG_ALL``
+ symbol::
+
+ # This is not enough
+ softmmu_ss.add(when: 'CONFIG_ACPI`, if_true: files('acpi.c'),
+ if_false: files('acpi-stub.c'))
+
+ # This is required as well:
+ softmmu_ss.add(when: 'CONFIG_ALL`, if_true: files('acpi-stub.c'))
+
+Target-dependent emulator sourcesets:
+ In the target-dependent set lives CPU emulation, some device emulation and
+ much glue code. This sometimes also has to be compiled multiple times,
+ once for each target being built. Target-dependent files are included
+ in the `specific_ss` sourceset.
+
+ Each emulator also includes sources for files in the `hw/` and `target/`
+ subdirectories. The subdirectory used for each emulator comes
+ from the target's definition of ``TARGET_BASE_ARCH`` or (if missing)
+ ``TARGET_ARCH``, as found in `default-configs/targets/*.mak`.
+
+ Each subdirectory in `hw/` adds one sourceset to the `hw_arch` dictionary,
+ for example::
+
+ arm_ss = ss.source_set()
+ arm_ss.add(files('boot.c'), fdt)
+ ...
+ hw_arch += {'arm': arm_ss}
+
+ The sourceset is only used for system emulators.
+
+ Each subdirectory in `target/` instead should add one sourceset to each
+ of the `target_arch` and `target_softmmu_arch`, which are used respectively
+ for all emulators and for system emulators only. For example::
+
+ arm_ss = ss.source_set()
+ arm_softmmu_ss = ss.source_set()
+ ...
+ target_arch += {'arm': arm_ss}
+ target_softmmu_arch += {'arm': arm_softmmu_ss}
+
+Utility sourcesets:
+ All binaries link with a static library `libqemuutil.a`. This library
+ 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::
+`default-configs/devices/*.mak`
+ The files under `default-configs/devices/` control the boards and devices
+ that are built into each QEMU system emulation targets. They merely contain
+ a list of config variable definitions such as::
include arm-softmmu.mak
CONFIG_XLNX_ZYNQMP_ARM=y
CONFIG_XLNX_VERSAL=y
`*/Kconfig`
- These files are processed together with `default-configs/*.mak` and
+ These files are processed together with `default-configs/devices/*.mak` and
describe the dependencies between various features, subsystems and
- device models. They are described in kconfig.rst.
+ device models. They are described in :ref:`kconfig`
+
+`default-configs/targets/*.mak`
+ These files mostly define symbols that appear in the `*-config-target.h`
+ file for each emulator[#cfgtarget]_. However, the ``TARGET_ARCH``
+ and ``TARGET_BASE_ARCH`` will also be used to select the `hw/` and
+ `target/` subdirectories that are compiled into each target.
+
+.. [#cfgtarget] This header is included by `qemu/osdep.h` when
+ compiling files from the target-specific sourcesets.
-These files rarely need changing unless new devices / hardware need to
-be enabled for a particular system/userspace emulation target
+These files rarely need changing unless you are adding a completely
+new target, or enabling new devices or hardware for a particular
+system/userspace emulation target
Support scripts
@@ -1,3 +1,5 @@
+.. _kconfig:
+
================
QEMU and Kconfig
================
@@ -11,3 +11,4 @@ softmmu_ss.add(when: 'CONFIG_TCG', if_true: files(
'replay-random.c',
'replay-debugging.c',
), if_false: files('stubs-system.c'))
+softmmu_ss.add(when: 'CONFIG_ALL', if_true: files('stubs-system.c'))
Expand on the usage of sourcesets and describe the CONFIG_ALL symbol. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> --- docs/devel/build-system.rst | 158 ++++++++++++++++++++++++------------ docs/devel/kconfig.rst | 2 + replay/meson.build | 1 + 3 files changed, 108 insertions(+), 53 deletions(-)