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
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.
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``).
125 Python virtual environments and the build process
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
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`` or ``sphinx-build`` 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``
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
216 binaries that are known to fail to build on some platforms (for example
217 32-bit or big-endian platforms).  Tests are also built by default,
223 ``meson.build`` files group the source files in rules that are
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 }
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``
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 ---------------
403 and preferred way to invoke support scripts from Meson build files,
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),
412 should be invoked through the ``python`` variable in meson.build. For
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',
437 to build QEMU, and may be installed as ``gmake`` on some hosts.
439 The output of Meson is a ``build.ninja`` file, which is used with the
440 Ninja build tool.  However, QEMU's build comprises other components than
443 the smaller build systems for firmware and tests; it also takes care of
445 these sub-Makefiles, the resulting build is largely non-recursive.
447 Tests, whether defined in ``meson.build`` or not, are also ran by the
450 with ``make check-unit``, and ``make check-tcg`` builds and runs "non-Meson"
454 respectively to build emulators and run tests defined in meson.build.
455 The main difference is that ``make`` needs the ``-jN`` flag in order to
459 -------------------
462   Print a help message for the most common build targets.
464 ``print-VAR``
465   Print the value of the variable VAR. Useful for debugging the build
466   system.
469 Important files for the build system
473 ------------------------
476 the rules needed to build QEMU. Their behaviour is influenced by a
480   The main entry point used when invoking make to build all the components
481   of QEMU. The default 'all' target will naturally result in the build of
484 ``*/meson.build``
485   The meson.build file in the root directory is the main entry point for the
486   Meson build system, and it coordinates the configuration and build of all
487   executables.  Build rules for various subdirectories are included in
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
513 go through any pre-processing as seen with autotools, where configure
518 ``config-host.mak``
519   When configure has determined the characteristics of the build host it
521   and to a smaller extent ``meson.build``.
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``
541   A set of Makefile dependencies that order the build and execution of
545 ``pc-bios/*/config.mak``, ``tests/tcg/config-host.mak``, ``tests/tcg/*/config-target.mak``
547   Configuration variables used to build the firmware and TCG tests,
553   during the build.  Using a virtual environment ensures that even code
554   that is run via ``sphinx-build``, ``meson`` etc. uses the same interpreter
559 ``config-host.h``
560   Used by C code to determine the properties of the build environment
561   and the set of enabled features for the entire build.
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``
578 ``build.ninja``
579   The build rules.
585   A Makefile include that bridges to ninja for the actual build.  The
586   Makefile is mostly a list of targets that Meson included in build.ninja.
590   meson.build.  The rules are produced from Meson's JSON description of
591   tests (obtained with "meson introspect --tests") through the script