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`` or ``sphinx-build`` 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``
168 ``pythondeps.toml``.  The format is custom to QEMU, but it is documented
171 by QEMU's supported distros.
180 -----------------------
182 Python packages that are **mandatory** dependencies to build QEMU,
184 QEMU sources.  The only one is currently Meson (outdated in Ubuntu
196 The Meson build system describes the build and install process for:
200    - Tools - ``qemu-img``, ``qemu-nbd``, ``qemu-ga`` (guest agent), etc
202    - System emulators - ``qemu-system-$ARCH``
204    - Userspace emulators - ``qemu-$ARCH``
206    - Unit tests
210 3) ROMs, whether provided as binary blobs in the QEMU distributions
217 32-bit or big-endian platforms).  Tests are also built by default,
224 enabled according to the available system libraries and to various
239 Target-independent emulator sourcesets:
245   Target-independent code lives in the ``common_ss``, ``system_ss`` and
247   ``system_ss`` only in system emulators, ``user_ss`` only in user-mode
250 Target-dependent emulator sourcesets:
251   In the target-dependent set lives CPU emulation, some device emulation and
253   once for each target being built.  Target-dependent files are included
269   The sourceset is only used for system emulators.
273   for all emulators and for system emulators only.  For example::
283   target-independent modules and ``target_modules`` is used for
284   target-dependent modules.  When modules are disabled the ``module``
289   subdirectory, and these per-subdirectory dictionaries are added to
296     modules += { 'hw-display': hw_display_modules }
307   all QEMU binaries.  ``stub_ss`` links dummy stubs that will only be linked
318   that are built into each QEMU system emulation targets. They merely contain
321     include arm-softmmu.mak
331   These files mostly define symbols that appear in the ``*-config-target.h``
336 .. [#cfgtarget] This header is included by ``qemu/osdep.h`` when
337                 compiling files from the target-specific sourcesets.
341 system/userspace emulation target
345 -------------
354  - Add a Meson build option to meson_options.txt.
356  - Add code to perform the actual feature check.
358  - Add code to include the feature status in ``config-host.h``
360  - Add code to print out the feature status in the configure summary
369 Unless the option was given a non-``auto`` value (on the configure
376                            method: 'pkg-config')
379 This avoids warnings on static builds of user-mode emulators, for example.
380 Most of the libraries used by system-mode emulators are not available for
385   # Create config-host.h (if applicable)
392 ``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make
393 update-buildoptions`` (or just ``make``) will take care of updating it.
397 ---------------
404 because it automatically uses the value of configure's --python= option.
411 invoke from the command line, such as tests/qapi-schema/test-qapi.py),
416        args: files('test-qapi.py'),
417        env: test_env, suite: ['qapi-schema', 'qapi-frontend'])
419 This is needed to obey the --python= option passed to the configure
429        fs.parent(python.full_path()) / 'sphinx-build',
436 The next step in building QEMU is to invoke make.  GNU Make is required
437 to build QEMU, and may be installed as ``gmake`` on some hosts.
440 Ninja build tool.  However, QEMU's build comprises other components than
442 need different cross compilers.  The QEMU Makefile wraps both Ninja and
445 these sub-Makefiles, the resulting build is largely non-recursive.
450 with ``make check-unit``, and ``make check-tcg`` builds and runs "non-Meson"
455 The main difference is that ``make`` needs the ``-jN`` flag in order to
459 -------------------
464 ``print-VAR``
466   system.
469 Important files for the build system
473 ------------------------
476 the rules needed to build QEMU. Their behaviour is influenced by a
481   of QEMU. The default 'all' target will naturally result in the build of
486   Meson build system, and it coordinates the configuration and build of all
488   other meson.build files spread throughout the QEMU source tree.
501   file will influence the entire build system.
504   Rules for VM-based tests. Like ``tests/Makefile.include``, this file is
506   file will influence the entire build system.
509 -------------------------
511 The following files are generated at run-time in order to control the
512 behaviour of the Makefiles. This avoids the need for QEMU makefiles to
513 go through any pre-processing as seen with autotools, where configure
518 ``config-host.mak``
523   ``config-host.mak`` is also used as a dependency checking mechanism. If make
525   ``config-host.mak``, then configure will be re-run.
527 ``config-meson.cross``
545 ``pc-bios/*/config.mak``, ``tests/tcg/config-host.mak``, ``tests/tcg/*/config-target.mak``
554   that is run via ``sphinx-build``, ``meson`` etc. uses the same interpreter
559 ``config-host.h``
563 ``${TARGET-NAME}-config-devices.mak``
564   TARGET-NAME is the name of a system emulator. The file is
567 ``${TARGET-NAME}-config-target.mak``
568   TARGET-NAME is the name of a system or usermode emulator. The file is
571 ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h``
591   tests (obtained with "meson introspect --tests") through the script