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