docs/devel/build-system.rst

2 The QEMU build system architecture
6 QEMU build system. As with projects using GNU autotools, the QEMU build
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.
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,
49    the build, and possibly install packages into it from PyPI
52    configuration step for the emulator build
58 Almost all QEMU developers that need to modify the build system will
125 Python virtual environments and the build process
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
182 Python packages that are **mandatory** dependencies to build QEMU,
196 The Meson build system describes the build and install process for:
216 binaries that are known to fail to build on some platforms (for example
223 ``meson.build`` files group the source files in rules that are
354  - Add a Meson build option to meson_options.txt.
403 and preferred way to invoke support scripts from Meson build files,
412 should be invoked through the ``python`` variable in meson.build. For
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
454 respectively to build emulators and run tests defined in meson.build.
462   Print a help message for the most common build targets.
465   Print the value of the variable VAR. Useful for debugging the build
469 Important files for the build system
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
488   other meson.build files spread throughout the QEMU source tree.
501   file will influence the entire build system.
506   file will influence the entire build system.
519   When configure has determined the characteristics of the build host it
521   and to a smaller extent ``meson.build``.
541   A set of Makefile dependencies that order the build and execution of
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
560   Used by C code to determine the properties of the build environment
561   and the set of enabled features for the entire build.
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