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