1================================== 2The QEMU build system architecture 3================================== 4 5This document aims to help developers understand the architecture of the 6QEMU build system. As with projects using GNU autotools, the QEMU build 7system has two stages, first the developer runs the "configure" script 8to determine the local build environment characteristics, then they run 9"make" to build the project. There is about where the similarities with 10GNU autotools end, so try to forget what you know about them. 11 12 13Stage 1: configure 14================== 15 16The QEMU configure script is written directly in shell, and should be 17compatible with any POSIX shell, hence it uses #!/bin/sh. An important 18implication of this is that it is important to avoid using bash-isms on 19development platforms where bash is the primary host. 20 21In contrast to autoconf scripts, QEMU's configure is expected to be 22silent while it is checking for features. It will only display output 23when an error occurs, or to show the final feature enablement summary 24on completion. 25 26Because QEMU uses the Meson build system under the hood, only VPATH 27builds are supported. There are two general ways to invoke configure & 28perform a build: 29 30 - VPATH, build artifacts outside of QEMU source tree entirely:: 31 32 cd ../ 33 mkdir build 34 cd build 35 ../qemu/configure 36 make 37 38 - VPATH, build artifacts in a subdir of QEMU source tree:: 39 40 mkdir build 41 cd build 42 ../configure 43 make 44 45The configure script automatically recognizes 46command line options for which a same-named Meson option exists; 47dashes in the command line are replaced with underscores. 48 49Many checks on the compilation environment are still found in configure 50rather than ``meson.build``, but new checks should be added directly to 51``meson.build``. 52 53Patches are also welcome to move existing checks from the configure 54phase to ``meson.build``. When doing so, ensure that ``meson.build`` does 55not use anymore the keys that you have removed from ``config-host.mak``. 56Typically these will be replaced in ``meson.build`` by boolean variables, 57``get_option('optname')`` invocations, or ``dep.found()`` expressions. 58In general, the remaining checks have little or no interdependencies, 59so they can be moved one by one. 60 61Helper functions 62---------------- 63 64The configure script provides a variety of helper functions to assist 65developers in checking for system features: 66 67``do_cc $ARGS...`` 68 Attempt to run the system C compiler passing it $ARGS... 69 70``do_cxx $ARGS...`` 71 Attempt to run the system C++ compiler passing it $ARGS... 72 73``compile_object $CFLAGS`` 74 Attempt to compile a test program with the system C compiler using 75 $CFLAGS. The test program must have been previously written to a file 76 called $TMPC. The replacement in Meson is the compiler object ``cc``, 77 which has methods such as ``cc.compiles()``, 78 ``cc.check_header()``, ``cc.has_function()``. 79 80``compile_prog $CFLAGS $LDFLAGS`` 81 Attempt to compile a test program with the system C compiler using 82 $CFLAGS and link it with the system linker using $LDFLAGS. The test 83 program must have been previously written to a file called $TMPC. 84 The replacement in Meson is ``cc.find_library()`` and ``cc.links()``. 85 86``has $COMMAND`` 87 Determine if $COMMAND exists in the current environment, either as a 88 shell builtin, or executable binary, returning 0 on success. The 89 replacement in Meson is ``find_program()``. 90 91``check_define $NAME`` 92 Determine if the macro $NAME is defined by the system C compiler 93 94``write_c_skeleton`` 95 Write a minimal C program main() function to the temporary file 96 indicated by $TMPC 97 98``error_exit $MESSAGE $MORE...`` 99 Print $MESSAGE to stderr, followed by $MORE... and then exit from the 100 configure script with non-zero status 101 102 103Stage 2: Meson 104============== 105 106The Meson build system is currently used to describe the build 107process for: 108 1091) executables, which include: 110 111 - Tools - ``qemu-img``, ``qemu-nbd``, ``qga`` (guest agent), etc 112 113 - System emulators - ``qemu-system-$ARCH`` 114 115 - Userspace emulators - ``qemu-$ARCH`` 116 117 - Unit tests 118 1192) documentation 120 1213) ROMs, which can be either installed as binary blobs or compiled 122 1234) other data files, such as icons or desktop files 124 125All executables are built by default, except for some ``contrib/`` 126binaries that are known to fail to build on some platforms (for example 12732-bit or big-endian platforms). Tests are also built by default, 128though that might change in the future. 129 130The source code is highly modularized, split across many files to 131facilitate building of all of these components with as little duplicated 132compilation as possible. Using the Meson "sourceset" functionality, 133``meson.build`` files group the source files in rules that are 134enabled according to the available system libraries and to various 135configuration symbols. Sourcesets belong to one of four groups: 136 137Subsystem sourcesets: 138 Various subsystems that are common to both tools and emulators have 139 their own sourceset, for example ``block_ss`` for the block device subsystem, 140 ``chardev_ss`` for the character device subsystem, etc. These sourcesets 141 are then turned into static libraries as follows:: 142 143 libchardev = static_library('chardev', chardev_ss.sources(), 144 name_suffix: 'fa', 145 build_by_default: false) 146 147 chardev = declare_dependency(link_whole: libchardev) 148 149 As of Meson 0.55.1, the special ``.fa`` suffix should be used for everything 150 that is used with ``link_whole``, to ensure that the link flags are placed 151 correctly in the command line. 152 153Target-independent emulator sourcesets: 154 Various general purpose helper code is compiled only once and 155 the .o files are linked into all output binaries that need it. 156 This includes error handling infrastructure, standard data structures, 157 platform portability wrapper functions, etc. 158 159 Target-independent code lives in the ``common_ss``, ``softmmu_ss`` and 160 ``user_ss`` sourcesets. ``common_ss`` is linked into all emulators, 161 ``softmmu_ss`` only in system emulators, ``user_ss`` only in user-mode 162 emulators. 163 164 Target-independent sourcesets must exercise particular care when using 165 ``if_false`` rules. The ``if_false`` rule will be used correctly when linking 166 emulator binaries; however, when *compiling* target-independent files 167 into .o files, Meson may need to pick *both* the ``if_true`` and 168 ``if_false`` sides to cater for targets that want either side. To 169 achieve that, you can add a special rule using the ``CONFIG_ALL`` 170 symbol:: 171 172 # Some targets have CONFIG_ACPI, some don't, so this is not enough 173 softmmu_ss.add(when: 'CONFIG_ACPI', if_true: files('acpi.c'), 174 if_false: files('acpi-stub.c')) 175 176 # This is required as well: 177 softmmu_ss.add(when: 'CONFIG_ALL', if_true: files('acpi-stub.c')) 178 179Target-dependent emulator sourcesets: 180 In the target-dependent set lives CPU emulation, some device emulation and 181 much glue code. This sometimes also has to be compiled multiple times, 182 once for each target being built. Target-dependent files are included 183 in the ``specific_ss`` sourceset. 184 185 Each emulator also includes sources for files in the ``hw/`` and ``target/`` 186 subdirectories. The subdirectory used for each emulator comes 187 from the target's definition of ``TARGET_BASE_ARCH`` or (if missing) 188 ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``. 189 190 Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary, 191 for example:: 192 193 arm_ss = ss.source_set() 194 arm_ss.add(files('boot.c'), fdt) 195 ... 196 hw_arch += {'arm': arm_ss} 197 198 The sourceset is only used for system emulators. 199 200 Each subdirectory in ``target/`` instead should add one sourceset to each 201 of the ``target_arch`` and ``target_softmmu_arch``, which are used respectively 202 for all emulators and for system emulators only. For example:: 203 204 arm_ss = ss.source_set() 205 arm_softmmu_ss = ss.source_set() 206 ... 207 target_arch += {'arm': arm_ss} 208 target_softmmu_arch += {'arm': arm_softmmu_ss} 209 210Module sourcesets: 211 There are two dictionaries for modules: ``modules`` is used for 212 target-independent modules and ``target_modules`` is used for 213 target-dependent modules. When modules are disabled the ``module`` 214 source sets are added to ``softmmu_ss`` and the ``target_modules`` 215 source sets are added to ``specific_ss``. 216 217 Both dictionaries are nested. One dictionary is created per 218 subdirectory, and these per-subdirectory dictionaries are added to 219 the toplevel dictionaries. For example:: 220 221 hw_display_modules = {} 222 qxl_ss = ss.source_set() 223 ... 224 hw_display_modules += { 'qxl': qxl_ss } 225 modules += { 'hw-display': hw_display_modules } 226 227Utility sourcesets: 228 All binaries link with a static library ``libqemuutil.a``. This library 229 is built from several sourcesets; most of them however host generated 230 code, and the only two of general interest are ``util_ss`` and ``stub_ss``. 231 232 The separation between these two is purely for documentation purposes. 233 ``util_ss`` contains generic utility files. Even though this code is only 234 linked in some binaries, sometimes it requires hooks only in some of 235 these and depend on other functions that are not fully implemented by 236 all QEMU binaries. ``stub_ss`` links dummy stubs that will only be linked 237 into the binary if the real implementation is not present. In a way, 238 the stubs can be thought of as a portable implementation of the weak 239 symbols concept. 240 241 242The following files concur in the definition of which files are linked 243into each emulator: 244 245``default-configs/devices/*.mak`` 246 The files under ``default-configs/devices/`` control the boards and devices 247 that are built into each QEMU system emulation targets. They merely contain 248 a list of config variable definitions such as:: 249 250 include arm-softmmu.mak 251 CONFIG_XLNX_ZYNQMP_ARM=y 252 CONFIG_XLNX_VERSAL=y 253 254``*/Kconfig`` 255 These files are processed together with ``default-configs/devices/*.mak`` and 256 describe the dependencies between various features, subsystems and 257 device models. They are described in :ref:`kconfig` 258 259``default-configs/targets/*.mak`` 260 These files mostly define symbols that appear in the ``*-config-target.h`` 261 file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH`` 262 and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and 263 ``target/`` subdirectories that are compiled into each target. 264 265.. [#cfgtarget] This header is included by ``qemu/osdep.h`` when 266 compiling files from the target-specific sourcesets. 267 268These files rarely need changing unless you are adding a completely 269new target, or enabling new devices or hardware for a particular 270system/userspace emulation target 271 272 273Adding checks 274------------- 275 276New checks should be added to Meson. Compiler checks can be as simple as 277the following:: 278 279 config_host_data.set('HAVE_BTRFS_H', cc.has_header('linux/btrfs.h')) 280 281A more complex task such as adding a new dependency usually 282comprises the following tasks: 283 284 - Add a Meson build option to meson_options.txt. 285 286 - Add code to perform the actual feature check. 287 288 - Add code to include the feature status in ``config-host.h`` 289 290 - Add code to print out the feature status in the configure summary 291 upon completion. 292 293Taking the probe for SDL2_Image as an example, we have the following 294in ``meson_options.txt``:: 295 296 option('sdl_image', type : 'feature', value : 'auto', 297 description: 'SDL Image support for icons') 298 299Unless the option was given a non-``auto`` value (on the configure 300command line), the detection code must be performed only if the 301dependency will be used:: 302 303 sdl_image = not_found 304 if not get_option('sdl_image').auto() or have_system 305 sdl_image = dependency('SDL2_image', required: get_option('sdl_image'), 306 method: 'pkg-config') 307 endif 308 309This avoids warnings on static builds of user-mode emulators, for example. 310Most of the libraries used by system-mode emulators are not available for 311static linking. 312 313The other supporting code is generally simple:: 314 315 # Create config-host.h (if applicable) 316 config_host_data.set('CONFIG_SDL_IMAGE', sdl_image.found()) 317 318 # Summary 319 summary_info += {'SDL image support': sdl_image.found()} 320 321For the configure script to parse the new option, the 322``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make 323update-buildoptions`` (or just ``make``) will take care of updating it. 324 325 326Support scripts 327--------------- 328 329Meson has a special convention for invoking Python scripts: if their 330first line is ``#! /usr/bin/env python3`` and the file is *not* executable, 331find_program() arranges to invoke the script under the same Python 332interpreter that was used to invoke Meson. This is the most common 333and preferred way to invoke support scripts from Meson build files, 334because it automatically uses the value of configure's --python= option. 335 336In case the script is not written in Python, use a ``#! /usr/bin/env ...`` 337line and make the script executable. 338 339Scripts written in Python, where it is desirable to make the script 340executable (for example for test scripts that developers may want to 341invoke from the command line, such as tests/qapi-schema/test-qapi.py), 342should be invoked through the ``python`` variable in meson.build. For 343example:: 344 345 test('QAPI schema regression tests', python, 346 args: files('test-qapi.py'), 347 env: test_env, suite: ['qapi-schema', 'qapi-frontend']) 348 349This is needed to obey the --python= option passed to the configure 350script, which may point to something other than the first python3 351binary on the path. 352 353 354Stage 3: makefiles 355================== 356 357The use of GNU make is required with the QEMU build system. 358 359The output of Meson is a build.ninja file, which is used with the Ninja 360build system. QEMU uses a different approach, where Makefile rules are 361synthesized from the build.ninja file. The main Makefile includes these 362rules and wraps them so that e.g. submodules are built before QEMU. 363The resulting build system is largely non-recursive in nature, in 364contrast to common practices seen with automake. 365 366Tests are also ran by the Makefile with the traditional ``make check`` 367phony target, while benchmarks are run with ``make bench``. Meson test 368suites such as ``unit`` can be ran with ``make check-unit`` too. It is also 369possible to run tests defined in meson.build with ``meson test``. 370 371Useful make targets 372------------------- 373 374``help`` 375 Print a help message for the most common build targets. 376 377``print-VAR`` 378 Print the value of the variable VAR. Useful for debugging the build 379 system. 380 381Important files for the build system 382==================================== 383 384Statically defined files 385------------------------ 386 387The following key files are statically defined in the source tree, with 388the rules needed to build QEMU. Their behaviour is influenced by a 389number of dynamically created files listed later. 390 391``Makefile`` 392 The main entry point used when invoking make to build all the components 393 of QEMU. The default 'all' target will naturally result in the build of 394 every component. Makefile takes care of recursively building submodules 395 directly via a non-recursive set of rules. 396 397``*/meson.build`` 398 The meson.build file in the root directory is the main entry point for the 399 Meson build system, and it coordinates the configuration and build of all 400 executables. Build rules for various subdirectories are included in 401 other meson.build files spread throughout the QEMU source tree. 402 403``tests/Makefile.include`` 404 Rules for external test harnesses. These include the TCG tests, 405 ``qemu-iotests`` and the Avocado-based integration tests. 406 407``tests/docker/Makefile.include`` 408 Rules for Docker tests. Like tests/Makefile, this file is included 409 directly by the top level Makefile, anything defined in this file will 410 influence the entire build system. 411 412``tests/vm/Makefile.include`` 413 Rules for VM-based tests. Like tests/Makefile, this file is included 414 directly by the top level Makefile, anything defined in this file will 415 influence the entire build system. 416 417Dynamically created files 418------------------------- 419 420The following files are generated dynamically by configure in order to 421control the behaviour of the statically defined makefiles. This avoids 422the need for QEMU makefiles to go through any pre-processing as seen 423with autotools, where Makefile.am generates Makefile.in which generates 424Makefile. 425 426Built by configure: 427 428``config-host.mak`` 429 When configure has determined the characteristics of the build host it 430 will write a long list of variables to config-host.mak file. This 431 provides the various install directories, compiler / linker flags and a 432 variety of ``CONFIG_*`` variables related to optionally enabled features. 433 This is imported by the top level Makefile and meson.build in order to 434 tailor the build output. 435 436 config-host.mak is also used as a dependency checking mechanism. If make 437 sees that the modification timestamp on configure is newer than that on 438 config-host.mak, then configure will be re-run. 439 440 The variables defined here are those which are applicable to all QEMU 441 build outputs. Variables which are potentially different for each 442 emulator target are defined by the next file... 443 444 445Built by Meson: 446 447``${TARGET-NAME}-config-devices.mak`` 448 TARGET-NAME is again the name of a system or userspace emulator. The 449 config-devices.mak file is automatically generated by make using the 450 scripts/make_device_config.sh program, feeding it the 451 default-configs/$TARGET-NAME file as input. 452 453``config-host.h``, ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h`` 454 These files are used by source code to determine what features are 455 enabled. They are generated from the contents of the corresponding 456 ``*.mak`` files using Meson's ``configure_file()`` function. 457 458``build.ninja`` 459 The build rules. 460 461 462Built by Makefile: 463 464``Makefile.ninja`` 465 A Makefile include that bridges to ninja for the actual build. The 466 Makefile is mostly a list of targets that Meson included in build.ninja. 467 468``Makefile.mtest`` 469 The Makefile definitions that let "make check" run tests defined in 470 meson.build. The rules are produced from Meson's JSON description of 471 tests (obtained with "meson introspect --tests") through the script 472 scripts/mtest2make.py. 473