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`` 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``
180 -----------------------
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
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 }
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 ---------------
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',
445 these sub-Makefiles, the resulting build is largely non-recursive.
448 Makefile with the traditional ``make check`` phony target, while benchmarks
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 ------------------------
486   Meson build system, and it coordinates the configuration and build of all
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``
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``
537   inspected manually to check the contents of the environment.
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``
589   The Makefile definitions that let "make check" run tests defined in
591   tests (obtained with "meson introspect --tests") through the script