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