docs/devel/build-system.rst

2 The QEMU build system architecture
6 QEMU build system. As with projects using GNU autotools, the QEMU build
8 to determine the local build environment characteristics, then they run
9 "make" to build the project.  This is about where the similarities with
12 The two general ways to perform a build are as follows:
14  - build artifacts outside of QEMU source tree entirely::
17      mkdir build
18      cd build
22  - build artifacts in a subdir of QEMU source tree::
24      mkdir build
25      cd build
29 Most of the actual build process uses Meson under the hood, therefore
30 build artifacts cannot be placed in the source tree itself.
38  - detect the host architecture
40  - list the targets for which to build emulators; the list of
41    targets also affects which firmware binaries and tests to build
43  - find the compilers (native and cross) used to build executables,
45    fragments (``config-host.mak``) or a Meson machine file
46    (``config-meson.cross``)
48  - create a virtual environment in which all Python code runs during
49    the build, and possibly install packages into it from PyPI
51  - invoke Meson in the virtual environment, to perform the actual
52    configuration step for the emulator build
55 which a same-named Meson option exists; dashes in the command line are
58 Almost all QEMU developers that need to modify the build system will
64 -----------------------
68 using bash-isms to avoid breaking development platforms where bash is
77    configure script with non-zero status.
86   ``$CPU-softmmu``, ``$CPU-linux-user``, ``$CPU-bsd-user``).  If a working
88   ``$target_ar``, etc. to non-empty values.
115    does not use flags passed via options such as ``--extra-cflags``, and
118    ``cc-option`` macro in ``pc-bios/option-rom/Makefile``).
125 Python virtual environments and the build process
126 -------------------------------------------------
130 comes from the ``--python`` command line option, the ``$PYTHON`` variable
132 in the ``pyvenv`` directory in the build tree, and provides consistency
133 in how the build process runs Python code.
136 about QEMU's build dependencies.  Note that the build process does  *not*
137 look for ``meson``, ``sphinx-build`` or ``avocado`` binaries in the PATH;
138 likewise, there are no options such as ``--meson`` or ``--sphinx-build``.
141 by the user during the build process.  On the other hand, it introduces
144 was installed in the ``site-packages`` directory of another interpreter,
152 ``--disable-download``; and anyway, it only happens when a ``configure``
153 option (currently, only ``--enable-docs``) is explicitly enabled but
159               Currently, in all cases it would be possible to use ``python -m``
167 .. [#pip] ``pip`` might also be used when running ``make check-avocado``
184 -----------------------
186 Python packages that are **mandatory** dependencies to build QEMU,
200 The Meson build system describes the build and install process for:
204    - Tools - ``qemu-img``, ``qemu-nbd``, ``qemu-ga`` (guest agent), etc
206    - System emulators - ``qemu-system-$ARCH``
208    - Userspace emulators - ``qemu-$ARCH``
210    - Unit tests
219 All executables are built by default, except for some ``contrib/``
220 binaries that are known to fail to build on some platforms (for example
221 32-bit or big-endian platforms).  Tests are also built by default,
227 ``meson.build`` files group the source files in rules that are
243 Target-independent emulator sourcesets:
249   Target-independent code lives in the ``common_ss``, ``system_ss`` and
251   ``system_ss`` only in system emulators, ``user_ss`` only in user-mode
254 Target-dependent emulator sourcesets:
255   In the target-dependent set lives CPU emulation, some device emulation and
257   once for each target being built.  Target-dependent files are included
287   target-independent modules and ``target_modules`` is used for
288   target-dependent modules.  When modules are disabled the ``module``
293   subdirectory, and these per-subdirectory dictionaries are added to
300     modules += { 'hw-display': hw_display_modules }
309   linked in some binaries, sometimes it requires hooks only in some of
325     include arm-softmmu.mak
335   These files mostly define symbols that appear in the ``*-config-target.h``
341                 compiling files from the target-specific sourcesets.
349 -------------
358  - Add a Meson build option to meson_options.txt.
360  - Add code to perform the actual feature check.
362  - Add code to include the feature status in ``config-host.h``
364  - Add code to print out the feature status in the configure summary
373 Unless the option was given a non-``auto`` value (on the configure
380                            method: 'pkg-config')
383 This avoids warnings on static builds of user-mode emulators, for example.
384 Most of the libraries used by system-mode emulators are not available for
389   # Create config-host.h (if applicable)
396 ``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make
397 update-buildoptions`` (or just ``make``) will take care of updating it.
401 ---------------
407 and preferred way to invoke support scripts from Meson build files,
408 because it automatically uses the value of configure's --python= option.
415 invoke from the command line, such as tests/qapi-schema/test-qapi.py),
416 should be invoked through the ``python`` variable in meson.build. For
420        args: files('test-qapi.py'),
421        env: test_env, suite: ['qapi-schema', 'qapi-frontend'])
423 This is needed to obey the --python= option passed to the configure
433        fs.parent(python.full_path()) / 'sphinx-build',
441 to build QEMU, and may be installed as ``gmake`` on some hosts.
443 The output of Meson is a ``build.ninja`` file, which is used with the
444 Ninja build tool.  However, QEMU's build comprises other components than
447 the smaller build systems for firmware and tests; it also takes care of
449 these sub-Makefiles, the resulting build is largely non-recursive.
451 Tests, whether defined in ``meson.build`` or not, are also ran by the
454 with ``make check-unit``, and ``make check-tcg`` builds and runs "non-Meson"
458 respectively to build emulators and run tests defined in meson.build.
459 The main difference is that ``make`` needs the ``-jN`` flag in order to
463 -------------------
466   Print a help message for the most common build targets.
468 ``print-VAR``
469   Print the value of the variable VAR. Useful for debugging the build
473 Important files for the build system
477 ------------------------
480 the rules needed to build QEMU. Their behaviour is influenced by a
484   The main entry point used when invoking make to build all the components
485   of QEMU. The default 'all' target will naturally result in the build of
488 ``*/meson.build``
489   The meson.build file in the root directory is the main entry point for the
490   Meson build system, and it coordinates the configuration and build of all
491   executables.  Build rules for various subdirectories are included in
492   other meson.build files spread throughout the QEMU source tree.
501   and the Avocado-based integration tests.
506   file will influence the entire build system.
509   Rules for VM-based tests. Like ``tests/Makefile.include``, this file is
511   file will influence the entire build system.
514 -------------------------
516 The following files are generated at run-time in order to control the
518 go through any pre-processing as seen with autotools, where configure
523 ``config-host.mak``
524   When configure has determined the characteristics of the build host it
526   and to a smaller extent ``meson.build``.
528   ``config-host.mak`` is also used as a dependency checking mechanism. If make
530   ``config-host.mak``, then configure will be re-run.
532 ``config-meson.cross``
546   A set of Makefile dependencies that order the build and execution of
550 ``pc-bios/*/config.mak``, ``tests/tcg/config-host.mak``, ``tests/tcg/*/config-target.mak``
552   Configuration variables used to build the firmware and TCG tests,
558   during the build.  Using a virtual environment ensures that even code
559   that is run via ``sphinx-build``, ``meson`` etc. uses the same interpreter
564 ``config-host.h``
565   Used by C code to determine the properties of the build environment
566   and the set of enabled features for the entire build.
568 ``${TARGET-NAME}-config-devices.mak``
569   TARGET-NAME is the name of a system emulator. The file is
572 ``${TARGET-NAME}-config-target.mak``
573   TARGET-NAME is the name of a system or usermode emulator. The file is
576 ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h``
583 ``build.ninja``
584   The build rules.
590   A Makefile include that bridges to ninja for the actual build.  The
591   Makefile is mostly a list of targets that Meson included in build.ninja.
595   meson.build.  The rules are produced from Meson's JSON description of
596   tests (obtained with "meson introspect --tests") through the script