docs/devel/build-system.rst

14  - build artifacts outside of QEMU source tree entirely::
22  - build artifacts in a subdir of QEMU source tree::
38  - detect the host architecture
40  - list the targets for which to build emulators; the list of
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
51  - invoke Meson in the virtual environment, to perform the actual
55 which a same-named Meson option exists; dashes in the command line are
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 -------------------------------------------------
128 An important step in ``configure`` is to create a Python virtual
129 environment (venv) during the configuration phase.  The Python interpreter
130 comes from the ``--python`` command line option, the ``$PYTHON`` variable
133 in how the build process runs Python code.
135 At this stage, ``configure`` also queries the chosen Python interpreter
137 look for ``meson``, ``sphinx-build`` or ``avocado`` binaries in the PATH;
138 likewise, there are no options such as ``--meson`` or ``--sphinx-build``.
140 PATH might operate in a different Python environment than the one chosen
144 was installed in the ``site-packages`` directory of another interpreter,
150 virtual environment with ``pip``, either from wheels in ``python/wheels``
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``
164               because the Python Packaging Authority provides a package
167 .. [#pip] ``pip`` might also be used when running ``make check-avocado``
183 Bundled Python packages
184 -----------------------
186 Python packages that are **mandatory** dependencies to build QEMU,
192 ``python/scripts/vendor.py`` script.  The script embeds the
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
221 32-bit or big-endian platforms).  Tests are also built by default,
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 }
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 ---------------
403 Meson has a special convention for invoking Python scripts: if their
405 find_program() arranges to invoke the script under the same Python
408 because it automatically uses the value of configure's --python= option.
410 In case the script is not written in Python, use a ``#! /usr/bin/env ...``
413 Scripts written in Python, where it is desirable to make the script
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
419   test('QAPI schema regression tests', python,
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
427 By the time Meson runs, Python dependencies are available in the virtual
433        fs.parent(python.full_path()) / 'sphinx-build',
449 these sub-Makefiles, the resulting build is largely non-recursive.
454 with ``make check-unit``, and ``make check-tcg`` builds and runs "non-Meson"
459 The main difference is that ``make`` needs the ``-jN`` flag in order to
463 -------------------
468 ``print-VAR``
477 ------------------------
494 ``python/scripts/mkvenv.py``
495   A wrapper for the Python ``venv`` and ``distlib.scripts`` packages.
501   and the Avocado-based integration tests.
509   Rules for VM-based tests. Like ``tests/Makefile.include``, this file is
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``
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``
547   firmware and tests after the container images and emulators that they
550 ``pc-bios/*/config.mak``, ``tests/tcg/config-host.mak``, ``tests/tcg/*/config-target.mak``
557   A Python virtual environment that is used for all Python code running
559   that is run via ``sphinx-build``, ``meson`` etc. uses the same interpreter
564 ``config-host.h``
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``
596   tests (obtained with "meson introspect --tests") through the script