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::
19      ../qemu/configure
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.
85   Detect a cross compiler and cross tools for the QEMU target $TARGET (e.g.,
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
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
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``.
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``
172 ``pythondeps.toml``.  The format is custom to QEMU, but it is documented
184 -----------------------
186 Python packages that are **mandatory** dependencies to build QEMU,
188 QEMU sources.  The only one is currently Meson (outdated in Ubuntu
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
214 3) ROMs, whether provided as binary blobs in the QEMU distributions
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 }
311   all QEMU binaries.  ``stub_ss`` links dummy stubs that will only be linked
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``
340 .. [#cfgtarget] This header is included by ``qemu/osdep.h`` when
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',
440 The next step in building QEMU is to invoke make.  GNU Make is required
441 to build QEMU, and may be installed as ``gmake`` on some hosts.
444 Ninja build tool.  However, QEMU's build comprises other components than
446 need different cross compilers.  The QEMU Makefile wraps both Ninja and
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``
470   system.
473 Important files for the build system
477 ------------------------
480 the rules needed to build QEMU. Their behaviour is influenced by a
485   of QEMU. The default 'all' target will naturally result in the build of
490   Meson build system, and it coordinates the configuration and build of all
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
517 behaviour of the Makefiles. This avoids the need for QEMU makefiles to
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``
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``
596   tests (obtained with "meson introspect --tests") through the script