2020-08-11 18:34:40 +02:00
|
|
|
==================================
|
|
|
|
The QEMU build system architecture
|
|
|
|
==================================
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
This document aims to help developers understand the architecture of the
|
|
|
|
QEMU build system. As with projects using GNU autotools, the QEMU build
|
|
|
|
system has two stages, first the developer runs the "configure" script
|
|
|
|
to determine the local build environment characteristics, then they run
|
|
|
|
"make" to build the project. There is about where the similarities with
|
|
|
|
GNU autotools end, so try to forget what you know about them.
|
|
|
|
|
|
|
|
|
|
|
|
Stage 1: configure
|
|
|
|
==================
|
|
|
|
|
|
|
|
The QEMU configure script is written directly in shell, and should be
|
|
|
|
compatible with any POSIX shell, hence it uses #!/bin/sh. An important
|
|
|
|
implication of this is that it is important to avoid using bash-isms on
|
|
|
|
development platforms where bash is the primary host.
|
|
|
|
|
|
|
|
In contrast to autoconf scripts, QEMU's configure is expected to be
|
|
|
|
silent while it is checking for features. It will only display output
|
|
|
|
when an error occurs, or to show the final feature enablement summary
|
|
|
|
on completion.
|
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
Because QEMU uses the Meson build system under the hood, only VPATH
|
|
|
|
builds are supported. There are two general ways to invoke configure &
|
|
|
|
perform a build:
|
|
|
|
|
2020-08-11 18:34:40 +02:00
|
|
|
- VPATH, build artifacts outside of QEMU source tree entirely::
|
2020-02-04 11:43:54 +01:00
|
|
|
|
|
|
|
cd ../
|
|
|
|
mkdir build
|
|
|
|
cd build
|
|
|
|
../qemu/configure
|
|
|
|
make
|
|
|
|
|
2020-08-11 18:34:40 +02:00
|
|
|
- VPATH, build artifacts in a subdir of QEMU source tree::
|
2020-02-04 11:43:54 +01:00
|
|
|
|
|
|
|
mkdir build
|
|
|
|
cd build
|
|
|
|
../configure
|
|
|
|
make
|
|
|
|
|
|
|
|
For now, checks on the compilation environment are found in configure
|
|
|
|
rather than meson.build, though this is expected to change. The command
|
|
|
|
line is parsed in the configure script and, whenever needed, converted
|
|
|
|
into the appropriate options to Meson.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
New checks should be added to Meson, which usually comprises the
|
|
|
|
following tasks:
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
- Add a Meson build option to meson_options.txt.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
- Add support to the command line arg parser to handle any new
|
2021-07-26 16:23:29 +02:00
|
|
|
``--enable-XXX``/``--disable-XXX`` flags required by the feature.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
- Add information to the help output message to report on the new
|
|
|
|
feature flag.
|
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
- Add code to perform the actual feature check.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
- Add code to include the feature status in ``config-host.h``
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
- Add code to print out the feature status in the configure summary
|
|
|
|
upon completion.
|
|
|
|
|
|
|
|
|
2020-08-31 12:27:00 +02:00
|
|
|
Taking the probe for SDL2_Image as an example, we have the following pieces
|
2020-08-11 18:34:40 +02:00
|
|
|
in configure::
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
# Initial variable state
|
2020-08-31 12:27:00 +02:00
|
|
|
sdl_image=auto
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
..snip..
|
|
|
|
|
|
|
|
# Configure flag processing
|
2020-08-31 12:27:00 +02:00
|
|
|
--disable-sdl-image) sdl_image=disabled
|
2015-09-24 15:41:38 +02:00
|
|
|
;;
|
2020-08-31 12:27:00 +02:00
|
|
|
--enable-sdl-image) sdl_image=enabled
|
2015-09-24 15:41:38 +02:00
|
|
|
;;
|
|
|
|
|
|
|
|
..snip..
|
|
|
|
|
|
|
|
# Help output feature message
|
2020-08-31 12:27:00 +02:00
|
|
|
sdl-image SDL Image support for icons
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
..snip..
|
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
# Meson invocation
|
2020-08-31 12:27:00 +02:00
|
|
|
-Dsdl_image=$sdl_image
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-08-11 18:34:40 +02:00
|
|
|
In meson_options.txt::
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-08-31 12:27:00 +02:00
|
|
|
option('sdl', type : 'feature', value : 'auto',
|
|
|
|
description: 'SDL Image support for icons')
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-08-11 18:34:40 +02:00
|
|
|
In meson.build::
|
2020-02-04 11:43:54 +01:00
|
|
|
|
|
|
|
# Detect dependency
|
2020-08-31 12:27:00 +02:00
|
|
|
sdl_image = dependency('SDL2_image', required: get_option('sdl_image'),
|
|
|
|
method: 'pkg-config',
|
2021-01-26 11:15:33 +01:00
|
|
|
kwargs: static_kwargs)
|
2020-02-04 11:43:54 +01:00
|
|
|
|
2020-08-31 12:27:00 +02:00
|
|
|
# Create config-host.h (if applicable)
|
|
|
|
config_host_data.set('CONFIG_SDL_IMAGE', sdl_image.found())
|
2020-02-04 11:43:54 +01:00
|
|
|
|
|
|
|
# Summary
|
2020-08-31 12:27:00 +02:00
|
|
|
summary_info += {'SDL image support': sdl_image.found()}
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Helper functions
|
|
|
|
----------------
|
|
|
|
|
|
|
|
The configure script provides a variety of helper functions to assist
|
|
|
|
developers in checking for system features:
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``do_cc $ARGS...``
|
2015-09-24 15:41:38 +02:00
|
|
|
Attempt to run the system C compiler passing it $ARGS...
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``do_cxx $ARGS...``
|
2015-09-24 15:41:38 +02:00
|
|
|
Attempt to run the system C++ compiler passing it $ARGS...
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``compile_object $CFLAGS``
|
2015-09-24 15:41:38 +02:00
|
|
|
Attempt to compile a test program with the system C compiler using
|
|
|
|
$CFLAGS. The test program must have been previously written to a file
|
2021-07-26 16:23:29 +02:00
|
|
|
called $TMPC. The replacement in Meson is the compiler object ``cc``,
|
|
|
|
which has methods such as ``cc.compiles()``,
|
|
|
|
``cc.check_header()``, ``cc.has_function()``.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``compile_prog $CFLAGS $LDFLAGS``
|
2015-09-24 15:41:38 +02:00
|
|
|
Attempt to compile a test program with the system C compiler using
|
|
|
|
$CFLAGS and link it with the system linker using $LDFLAGS. The test
|
|
|
|
program must have been previously written to a file called $TMPC.
|
2021-07-26 16:23:29 +02:00
|
|
|
The replacement in Meson is ``cc.find_library()`` and ``cc.links()``.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``has $COMMAND``
|
2015-09-24 15:41:38 +02:00
|
|
|
Determine if $COMMAND exists in the current environment, either as a
|
2020-09-01 12:38:25 +02:00
|
|
|
shell builtin, or executable binary, returning 0 on success. The
|
2021-07-26 16:23:29 +02:00
|
|
|
replacement in Meson is ``find_program()``.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``check_define $NAME``
|
2015-09-24 15:41:38 +02:00
|
|
|
Determine if the macro $NAME is defined by the system C compiler
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``check_include $NAME``
|
2015-09-24 15:41:38 +02:00
|
|
|
Determine if the include $NAME file is available to the system C
|
2021-07-26 16:23:29 +02:00
|
|
|
compiler. The replacement in Meson is ``cc.has_header()``.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``write_c_skeleton``
|
2015-09-24 15:41:38 +02:00
|
|
|
Write a minimal C program main() function to the temporary file
|
|
|
|
indicated by $TMPC
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``feature_not_found $NAME $REMEDY``
|
2015-09-24 15:41:38 +02:00
|
|
|
Print a message to stderr that the feature $NAME was not available
|
|
|
|
on the system, suggesting the user try $REMEDY to address the
|
|
|
|
problem.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``error_exit $MESSAGE $MORE...``
|
2015-09-24 15:41:38 +02:00
|
|
|
Print $MESSAGE to stderr, followed by $MORE... and then exit from the
|
|
|
|
configure script with non-zero status
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``query_pkg_config $ARGS...``
|
2015-09-24 15:41:38 +02:00
|
|
|
Run pkg-config passing it $ARGS. If QEMU is doing a static build,
|
|
|
|
then --static will be automatically added to $ARGS
|
|
|
|
|
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
Stage 2: Meson
|
|
|
|
==============
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
The Meson build system is currently used to describe the build
|
|
|
|
process for:
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
1) executables, which include:
|
2020-08-11 18:34:40 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
- Tools - qemu-img, qemu-nbd, qga (guest agent), etc
|
2020-08-11 18:34:40 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
- System emulators - qemu-system-$ARCH
|
2020-08-11 18:34:40 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
- Userspace emulators - qemu-$ARCH
|
2020-08-11 18:34:40 +02:00
|
|
|
|
2020-09-07 18:39:13 +02:00
|
|
|
- Unit tests
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
2) documentation
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
3) ROMs, which can be either installed as binary blobs or compiled
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
4) other data files, such as icons or desktop files
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
All executables are built by default, except for some ``contrib/``
|
2020-09-11 13:12:11 +02:00
|
|
|
binaries that are known to fail to build on some platforms (for example
|
|
|
|
32-bit or big-endian platforms). Tests are also built by default,
|
|
|
|
though that might change in the future.
|
|
|
|
|
2020-10-29 13:06:09 +01:00
|
|
|
The source code is highly modularized, split across many files to
|
|
|
|
facilitate building of all of these components with as little duplicated
|
|
|
|
compilation as possible. Using the Meson "sourceset" functionality,
|
2021-07-26 16:23:29 +02:00
|
|
|
``meson.build`` files group the source files in rules that are
|
2020-10-29 13:06:09 +01:00
|
|
|
enabled according to the available system libraries and to various
|
|
|
|
configuration symbols. Sourcesets belong to one of four groups:
|
|
|
|
|
|
|
|
Subsystem sourcesets:
|
|
|
|
Various subsystems that are common to both tools and emulators have
|
2021-07-26 16:23:29 +02:00
|
|
|
their own sourceset, for example ``block_ss`` for the block device subsystem,
|
|
|
|
``chardev_ss`` for the character device subsystem, etc. These sourcesets
|
2020-10-29 13:06:09 +01:00
|
|
|
are then turned into static libraries as follows::
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
libchardev = static_library('chardev', chardev_ss.sources(),
|
|
|
|
name_suffix: 'fa',
|
|
|
|
build_by_default: false)
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
chardev = declare_dependency(link_whole: libchardev)
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
As of Meson 0.55.1, the special ``.fa`` suffix should be used for everything
|
|
|
|
that is used with ``link_whole``, to ensure that the link flags are placed
|
2020-10-29 13:06:09 +01:00
|
|
|
correctly in the command line.
|
|
|
|
|
|
|
|
Target-independent emulator sourcesets:
|
|
|
|
Various general purpose helper code is compiled only once and
|
|
|
|
the .o files are linked into all output binaries that need it.
|
|
|
|
This includes error handling infrastructure, standard data structures,
|
|
|
|
platform portability wrapper functions, etc.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
Target-independent code lives in the ``common_ss``, ``softmmu_ss`` and
|
|
|
|
``user_ss`` sourcesets. ``common_ss`` is linked into all emulators,
|
|
|
|
``softmmu_ss`` only in system emulators, ``user_ss`` only in user-mode
|
2020-10-29 13:06:09 +01:00
|
|
|
emulators.
|
|
|
|
|
|
|
|
Target-independent sourcesets must exercise particular care when using
|
2021-07-26 16:23:29 +02:00
|
|
|
``if_false`` rules. The ``if_false`` rule will be used correctly when linking
|
2020-10-29 13:06:09 +01:00
|
|
|
emulator binaries; however, when *compiling* target-independent files
|
2021-07-26 16:23:29 +02:00
|
|
|
into .o files, Meson may need to pick *both* the ``if_true`` and
|
|
|
|
``if_false`` sides to cater for targets that want either side. To
|
2020-10-29 13:06:09 +01:00
|
|
|
achieve that, you can add a special rule using the ``CONFIG_ALL``
|
|
|
|
symbol::
|
|
|
|
|
|
|
|
# Some targets have CONFIG_ACPI, some don't, so this is not enough
|
2021-07-26 16:23:30 +02:00
|
|
|
softmmu_ss.add(when: 'CONFIG_ACPI', if_true: files('acpi.c'),
|
2020-10-29 13:06:09 +01:00
|
|
|
if_false: files('acpi-stub.c'))
|
|
|
|
|
|
|
|
# This is required as well:
|
2021-07-26 16:23:30 +02:00
|
|
|
softmmu_ss.add(when: 'CONFIG_ALL', if_true: files('acpi-stub.c'))
|
2020-10-29 13:06:09 +01:00
|
|
|
|
|
|
|
Target-dependent emulator sourcesets:
|
|
|
|
In the target-dependent set lives CPU emulation, some device emulation and
|
|
|
|
much glue code. This sometimes also has to be compiled multiple times,
|
|
|
|
once for each target being built. Target-dependent files are included
|
2021-07-26 16:23:29 +02:00
|
|
|
in the ``specific_ss`` sourceset.
|
2020-10-29 13:06:09 +01:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
Each emulator also includes sources for files in the ``hw/`` and ``target/``
|
2020-10-29 13:06:09 +01:00
|
|
|
subdirectories. The subdirectory used for each emulator comes
|
|
|
|
from the target's definition of ``TARGET_BASE_ARCH`` or (if missing)
|
2021-07-26 16:23:29 +02:00
|
|
|
``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``.
|
2020-10-29 13:06:09 +01:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary,
|
2020-10-29 13:06:09 +01:00
|
|
|
for example::
|
|
|
|
|
|
|
|
arm_ss = ss.source_set()
|
|
|
|
arm_ss.add(files('boot.c'), fdt)
|
|
|
|
...
|
|
|
|
hw_arch += {'arm': arm_ss}
|
|
|
|
|
|
|
|
The sourceset is only used for system emulators.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
Each subdirectory in ``target/`` instead should add one sourceset to each
|
|
|
|
of the ``target_arch`` and ``target_softmmu_arch``, which are used respectively
|
2020-10-29 13:06:09 +01:00
|
|
|
for all emulators and for system emulators only. For example::
|
|
|
|
|
|
|
|
arm_ss = ss.source_set()
|
|
|
|
arm_softmmu_ss = ss.source_set()
|
|
|
|
...
|
|
|
|
target_arch += {'arm': arm_ss}
|
|
|
|
target_softmmu_arch += {'arm': arm_softmmu_ss}
|
|
|
|
|
2021-06-24 12:38:23 +02:00
|
|
|
Module sourcesets:
|
2021-07-26 16:23:29 +02:00
|
|
|
There are two dictionaries for modules: ``modules`` is used for
|
|
|
|
target-independent modules and ``target_modules`` is used for
|
|
|
|
target-dependent modules. When modules are disabled the ``module``
|
|
|
|
source sets are added to ``softmmu_ss`` and the ``target_modules``
|
|
|
|
source sets are added to ``specific_ss``.
|
2021-06-24 12:38:23 +02:00
|
|
|
|
|
|
|
Both dictionaries are nested. One dictionary is created per
|
|
|
|
subdirectory, and these per-subdirectory dictionaries are added to
|
|
|
|
the toplevel dictionaries. For example::
|
|
|
|
|
|
|
|
hw_display_modules = {}
|
|
|
|
qxl_ss = ss.source_set()
|
|
|
|
...
|
|
|
|
hw_display_modules += { 'qxl': qxl_ss }
|
|
|
|
modules += { 'hw-display': hw_display_modules }
|
|
|
|
|
2020-10-29 13:06:09 +01:00
|
|
|
Utility sourcesets:
|
2021-07-26 16:23:29 +02:00
|
|
|
All binaries link with a static library ``libqemuutil.a``. This library
|
2020-10-29 13:06:09 +01:00
|
|
|
is built from several sourcesets; most of them however host generated
|
2021-07-26 16:23:29 +02:00
|
|
|
code, and the only two of general interest are ``util_ss`` and ``stub_ss``.
|
2020-10-29 13:06:09 +01:00
|
|
|
|
|
|
|
The separation between these two is purely for documentation purposes.
|
2021-07-26 16:23:29 +02:00
|
|
|
``util_ss`` contains generic utility files. Even though this code is only
|
2020-10-29 13:06:09 +01:00
|
|
|
linked in some binaries, sometimes it requires hooks only in some of
|
|
|
|
these and depend on other functions that are not fully implemented by
|
2021-07-26 16:23:29 +02:00
|
|
|
all QEMU binaries. ``stub_ss`` links dummy stubs that will only be linked
|
2020-10-29 13:06:09 +01:00
|
|
|
into the binary if the real implementation is not present. In a way,
|
|
|
|
the stubs can be thought of as a portable implementation of the weak
|
|
|
|
symbols concept.
|
|
|
|
|
2017-09-19 16:20:31 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
The following files concur in the definition of which files are linked
|
|
|
|
into each emulator:
|
2017-09-19 16:20:31 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``default-configs/devices/*.mak``
|
|
|
|
The files under ``default-configs/devices/`` control the boards and devices
|
2020-10-29 13:06:09 +01:00
|
|
|
that are built into each QEMU system emulation targets. They merely contain
|
|
|
|
a list of config variable definitions such as::
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-08-11 18:34:40 +02:00
|
|
|
include arm-softmmu.mak
|
|
|
|
CONFIG_XLNX_ZYNQMP_ARM=y
|
|
|
|
CONFIG_XLNX_VERSAL=y
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``*/Kconfig``
|
|
|
|
These files are processed together with ``default-configs/devices/*.mak`` and
|
2020-08-11 18:34:40 +02:00
|
|
|
describe the dependencies between various features, subsystems and
|
2020-10-29 13:06:09 +01:00
|
|
|
device models. They are described in :ref:`kconfig`
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``default-configs/targets/*.mak``
|
|
|
|
These files mostly define symbols that appear in the ``*-config-target.h``
|
2020-10-29 13:06:09 +01:00
|
|
|
file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH``
|
2021-07-26 16:23:29 +02:00
|
|
|
and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and
|
|
|
|
``target/`` subdirectories that are compiled into each target.
|
2020-10-29 13:06:09 +01:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
.. [#cfgtarget] This header is included by ``qemu/osdep.h`` when
|
2020-10-29 13:06:09 +01:00
|
|
|
compiling files from the target-specific sourcesets.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-10-29 13:06:09 +01:00
|
|
|
These files rarely need changing unless you are adding a completely
|
|
|
|
new target, or enabling new devices or hardware for a particular
|
|
|
|
system/userspace emulation target
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
|
|
|
|
Support scripts
|
|
|
|
---------------
|
|
|
|
|
|
|
|
Meson has a special convention for invoking Python scripts: if their
|
2021-07-26 16:23:29 +02:00
|
|
|
first line is ``#! /usr/bin/env python3`` and the file is *not* executable,
|
2020-02-04 11:43:54 +01:00
|
|
|
find_program() arranges to invoke the script under the same Python
|
|
|
|
interpreter that was used to invoke Meson. This is the most common
|
|
|
|
and preferred way to invoke support scripts from Meson build files,
|
|
|
|
because it automatically uses the value of configure's --python= option.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
In case the script is not written in Python, use a ``#! /usr/bin/env ...``
|
2020-02-04 11:43:54 +01:00
|
|
|
line and make the script executable.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
Scripts written in Python, where it is desirable to make the script
|
|
|
|
executable (for example for test scripts that developers may want to
|
|
|
|
invoke from the command line, such as tests/qapi-schema/test-qapi.py),
|
2021-07-26 16:23:29 +02:00
|
|
|
should be invoked through the ``python`` variable in meson.build. For
|
2020-08-11 18:34:40 +02:00
|
|
|
example::
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
test('QAPI schema regression tests', python,
|
|
|
|
args: files('test-qapi.py'),
|
|
|
|
env: test_env, suite: ['qapi-schema', 'qapi-frontend'])
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
This is needed to obey the --python= option passed to the configure
|
|
|
|
script, which may point to something other than the first python3
|
|
|
|
binary on the path.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
Stage 3: makefiles
|
|
|
|
==================
|
|
|
|
|
|
|
|
The use of GNU make is required with the QEMU build system.
|
|
|
|
|
|
|
|
The output of Meson is a build.ninja file, which is used with the Ninja
|
|
|
|
build system. QEMU uses a different approach, where Makefile rules are
|
|
|
|
synthesized from the build.ninja file. The main Makefile includes these
|
|
|
|
rules and wraps them so that e.g. submodules are built before QEMU.
|
|
|
|
The resulting build system is largely non-recursive in nature, in
|
|
|
|
contrast to common practices seen with automake.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
Tests are also ran by the Makefile with the traditional ``make check``
|
|
|
|
phony target, while benchmarks are run with ``make bench``. Meson test
|
|
|
|
suites such as ``unit`` can be ran with ``make check-unit`` too. It is also
|
|
|
|
possible to run tests defined in meson.build with ``meson test``.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
Important files for the build system
|
|
|
|
====================================
|
|
|
|
|
2015-09-24 15:41:38 +02:00
|
|
|
Statically defined files
|
|
|
|
------------------------
|
|
|
|
|
|
|
|
The following key files are statically defined in the source tree, with
|
|
|
|
the rules needed to build QEMU. Their behaviour is influenced by a
|
|
|
|
number of dynamically created files listed later.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``Makefile``
|
2020-08-11 18:34:40 +02:00
|
|
|
The main entry point used when invoking make to build all the components
|
|
|
|
of QEMU. The default 'all' target will naturally result in the build of
|
|
|
|
every component. Makefile takes care of recursively building submodules
|
|
|
|
directly via a non-recursive set of rules.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``*/meson.build``
|
2020-08-11 18:34:40 +02:00
|
|
|
The meson.build file in the root directory is the main entry point for the
|
|
|
|
Meson build system, and it coordinates the configuration and build of all
|
|
|
|
executables. Build rules for various subdirectories are included in
|
|
|
|
other meson.build files spread throughout the QEMU source tree.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``tests/Makefile.include``
|
2020-09-07 18:39:13 +02:00
|
|
|
Rules for external test harnesses. These include the TCG tests,
|
2021-07-26 16:23:29 +02:00
|
|
|
``qemu-iotests`` and the Avocado-based acceptance tests.
|
2020-08-11 18:34:40 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``tests/docker/Makefile.include``
|
2020-08-11 18:34:40 +02:00
|
|
|
Rules for Docker tests. Like tests/Makefile, this file is included
|
|
|
|
directly by the top level Makefile, anything defined in this file will
|
|
|
|
influence the entire build system.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``tests/vm/Makefile.include``
|
2020-08-11 18:34:40 +02:00
|
|
|
Rules for VM-based tests. Like tests/Makefile, this file is included
|
|
|
|
directly by the top level Makefile, anything defined in this file will
|
|
|
|
influence the entire build system.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
Dynamically created files
|
|
|
|
-------------------------
|
|
|
|
|
|
|
|
The following files are generated dynamically by configure in order to
|
|
|
|
control the behaviour of the statically defined makefiles. This avoids
|
|
|
|
the need for QEMU makefiles to go through any pre-processing as seen
|
|
|
|
with autotools, where Makefile.am generates Makefile.in which generates
|
|
|
|
Makefile.
|
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
Built by configure:
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``config-host.mak``
|
2020-08-11 18:34:40 +02:00
|
|
|
When configure has determined the characteristics of the build host it
|
|
|
|
will write a long list of variables to config-host.mak file. This
|
|
|
|
provides the various install directories, compiler / linker flags and a
|
2021-07-26 16:23:29 +02:00
|
|
|
variety of ``CONFIG_*`` variables related to optionally enabled features.
|
2020-08-11 18:34:40 +02:00
|
|
|
This is imported by the top level Makefile and meson.build in order to
|
|
|
|
tailor the build output.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-08-11 18:34:40 +02:00
|
|
|
config-host.mak is also used as a dependency checking mechanism. If make
|
|
|
|
sees that the modification timestamp on configure is newer than that on
|
|
|
|
config-host.mak, then configure will be re-run.
|
2015-09-24 15:41:38 +02:00
|
|
|
|
2020-08-11 18:34:40 +02:00
|
|
|
The variables defined here are those which are applicable to all QEMU
|
|
|
|
build outputs. Variables which are potentially different for each
|
|
|
|
emulator target are defined by the next file...
|
2015-09-24 15:41:38 +02:00
|
|
|
|
|
|
|
|
2020-02-04 11:43:54 +01:00
|
|
|
Built by Meson:
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``${TARGET-NAME}-config-devices.mak``
|
2020-08-11 18:34:40 +02:00
|
|
|
TARGET-NAME is again the name of a system or userspace emulator. The
|
|
|
|
config-devices.mak file is automatically generated by make using the
|
|
|
|
scripts/make_device_config.sh program, feeding it the
|
|
|
|
default-configs/$TARGET-NAME file as input.
|
2020-02-04 11:43:54 +01:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``config-host.h``, ``$TARGET-NAME/config-target.h``, ``$TARGET-NAME/config-devices.h``
|
2020-08-11 18:34:40 +02:00
|
|
|
These files are used by source code to determine what features
|
|
|
|
are enabled. They are generated from the contents of the corresponding
|
2021-07-26 16:23:29 +02:00
|
|
|
``*.h`` files using the scripts/create_config program. This extracts
|
2020-08-11 18:34:40 +02:00
|
|
|
relevant variables and formats them as C preprocessor macros.
|
2020-02-04 11:43:54 +01:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``build.ninja``
|
2020-08-11 18:34:40 +02:00
|
|
|
The build rules.
|
2020-02-04 11:43:54 +01:00
|
|
|
|
|
|
|
|
|
|
|
Built by Makefile:
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``Makefile.ninja``
|
2020-08-13 15:28:11 +02:00
|
|
|
A Makefile include that bridges to ninja for the actual build. The
|
|
|
|
Makefile is mostly a list of targets that Meson included in build.ninja.
|
2020-02-04 11:43:54 +01:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``Makefile.mtest``
|
2020-08-11 18:34:40 +02:00
|
|
|
The Makefile definitions that let "make check" run tests defined in
|
|
|
|
meson.build. The rules are produced from Meson's JSON description of
|
|
|
|
tests (obtained with "meson introspect --tests") through the script
|
|
|
|
scripts/mtest2make.py.
|
2018-01-04 17:05:08 +01:00
|
|
|
|
|
|
|
|
|
|
|
Useful make targets
|
2020-08-11 18:34:40 +02:00
|
|
|
-------------------
|
2018-01-04 17:05:08 +01:00
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``help``
|
2018-01-04 17:05:08 +01:00
|
|
|
Print a help message for the most common build targets.
|
|
|
|
|
2021-07-26 16:23:29 +02:00
|
|
|
``print-VAR``
|
2018-01-04 17:05:08 +01:00
|
|
|
Print the value of the variable VAR. Useful for debugging the build
|
|
|
|
system.
|