docs/devel/build-system.rst

2 The QEMU build system architecture
6 QEMU build system. As with projects using GNU autotools, the QEMU build
7 system has two stages; first the developer runs the "configure" script
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
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.
101    Attempt to compile a test program with the system C compiler using
106    Attempt to compile a test program with the system C compiler using
107    $CFLAGS and link it with the system linker using $LDFLAGS. The test
111    Determine if the macro $NAME is defined by the system C compiler.
115    does not use flags passed via options such as ``--extra-cflags``, and
116    therefore can be used to check for cross compilers.  However, most
118    ``cc-option`` macro in ``pc-bios/option-rom/Makefile``).
126 -------------------------------------------------
130 comes from the ``--python`` command line option, the ``$PYTHON`` variable
131 from the environment, or the system PATH, in this order.  The venv resides
137 look for ``meson``, ``sphinx-build`` or ``avocado`` binaries in the PATH;
138 likewise, there are no options such as ``--meson`` or ``--sphinx-build``.
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 -----------------------
189 22.04 and openSUSE Leap).
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
221 32-bit or big-endian platforms).  Tests are also built by default,
228 enabled according to the available system libraries and to various
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
273   The sourceset is only used for system emulators.
277   for all emulators and for system emulators only.  For example::
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 }
322   that are built into each QEMU system emulation targets. They merely contain
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.
345 system/userspace emulation target
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 ---------------
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),
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',
449 these sub-Makefiles, the resulting build is largely non-recursive.
452 Makefile with the traditional ``make check`` phony target, while benchmarks
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``
470   system.
473 Important files for the build system
477 ------------------------
490   Meson build system, and it coordinates the configuration and build of all
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``
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``
542   inspected manually to check the contents of the environment.
550 ``pc-bios/*/config.mak``, ``tests/tcg/config-host.mak``, ``tests/tcg/*/config-target.mak``
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``
594   The Makefile definitions that let "make check" run tests defined in
596   tests (obtained with "meson introspect --tests") through the script