qemu/docs/devel/build-system.txt

    The QEMU build system architecture
    ==================================

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.

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:

 - VPATH, build artifacts outside of QEMU source tree entirely

     cd ../
     mkdir build
     cd build
     ../qemu/configure
     make

 - VPATH, build artifacts in a subdir of QEMU source tree

     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.

New checks should be added to Meson, which usually comprises the
following tasks:

 - Add a Meson build option to meson_options.txt.

 - Add support to the command line arg parser to handle any new
   --enable-XXX / --disable-XXX flags required by the feature XXX.

 - Add information to the help output message to report on the new
   feature flag.

 - Add code to perform the actual feature check.

 - Add code to include the feature status in config-host.h

 - Add code to print out the feature status in the configure summary
   upon completion.


Taking the probe for SDL as an example, we have the following pieces
in configure:

  # Initial variable state
  sdl=auto

  ..snip..

  # Configure flag processing
  --disable-gnutls) sdl=disabled
  ;;
  --enable-gnutls) sdl=enabled
  ;;

  ..snip..

  # Help output feature message
  sdl             SDL UI

  ..snip..

  # Meson invocation
  -Dsdl=$sdl

In meson_options.txt:

  option('sdl', type : 'feature', value : 'auto')

In meson.build:

  # Detect dependency
  sdl = dependency('sdl2',
                   required: get_option('sdl'),
                   static: enable_static)

  # Create config-host.h
  config_host_data.set('CONFIG_SDL', sdl.found())

  # Summary
  summary_info += {'SDL support':       sdl.found()}



Helper functions
----------------

The configure script provides a variety of helper functions to assist
developers in checking for system features:

 - do_cc $ARGS...

   Attempt to run the system C compiler passing it $ARGS...

 - do_cxx $ARGS...

   Attempt to run the system C++ compiler passing it $ARGS...

 - compile_object $CFLAGS

   Attempt to compile a test program with the system C compiler using
   $CFLAGS. The test program must have been previously written to a file
   called $TMPC.

 - compile_prog $CFLAGS $LDFLAGS

   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.

 - has $COMMAND

   Determine if $COMMAND exists in the current environment, either as a
   shell builtin, or executable binary, returning 0 on success.

 - path_of $COMMAND

   Return the fully qualified path of $COMMAND, printing it to stdout,
   and returning 0 on success.

 - check_define $NAME

   Determine if the macro $NAME is defined by the system C compiler

 - check_include $NAME

   Determine if the include $NAME file is available to the system C
   compiler

 - write_c_skeleton

   Write a minimal C program main() function to the temporary file
   indicated by $TMPC

 - feature_not_found $NAME $REMEDY

   Print a message to stderr that the feature $NAME was not available
   on the system, suggesting the user try $REMEDY to address the
   problem.

 - error_exit $MESSAGE $MORE...

   Print $MESSAGE to stderr, followed by $MORE... and then exit from the
   configure script with non-zero status

 - query_pkg_config $ARGS...

   Run pkg-config passing it $ARGS. If QEMU is doing a static build,
   then --static will be automatically added to $ARGS


Stage 2: Meson
==============

The Meson build system is currently used to describe the build
process for:

1) executables, which include:
   - Tools - qemu-img, qemu-nbd, qga (guest agent), etc
   - System emulators - qemu-system-$ARCH
   - Userspace emulators - qemu-$ARCH
   - Some (but not all) unit tests

2) documentation

3) ROMs, which can be either installed as binary blobs or compiled

4) other data files, such as icons or desktop files

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. The Meson "sourceset" functionality is used
to list the files and their dependency on various configuration  
symbols.

Various subsystems that are common to both tools and emulators have
their own sourceset, for example block_ss for the block device subsystem,
chardev_ss for the character device subsystem, etc.  These sourcesets
are then turned into static libraries as follows:

    libchardev = static_library('chardev', chardev_ss.sources(),
                                name_suffix: 'fa',
                                build_by_default: false)

    chardev = declare_dependency(link_whole: libchardev)

The special ".fa" suffix is needed as long as unit tests are built with
the older Makefile infrastructure, and will go away later.

Files linked into emulator targets there can be split into two distinct groups
of files, those which are independent of the QEMU emulation target and
those which are dependent on the QEMU emulation target.

In the target-independent set lives various general purpose helper code,
such as error handling infrastructure, standard data structures,
platform portability wrapper functions, etc. This code can be compiled
once only and the .o files linked into all output binaries.
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 emulators.

In the target-dependent set lives CPU emulation, device emulation and
much glue code. This sometimes also has to be compiled multiple times,
once for each target being built.

All binaries link with a static library libqemuutil.a, which is then
linked to all the binaries.  libqemuutil.a is built from several
sourcesets; most of them however host generated code, and the only two
of general interest are util_ss and stub_ss.

The separation between these two is purely for documentation purposes.
util_ss contains generic utility files.  Even though this code is only
linked in some binaries, sometimes it requires hooks only in some of
these and depend on other functions that are not fully implemented by
all QEMU binaries.  stub_ss links dummy stubs that will only be linked
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.

The following files concur in the definition of which files are linked
into each emulator:

- default-configs/*.mak

The files under default-configs/ control what emulated hardware is built
into each QEMU system and userspace emulator targets. They merely contain
a list of config variable definitions like the machines that should be
included. For example, default-configs/aarch64-softmmu.mak has:

  include arm-softmmu.mak
  CONFIG_XLNX_ZYNQMP_ARM=y
  CONFIG_XLNX_VERSAL=y

These files rarely need changing unless new devices / hardware need to
be enabled for a particular system/userspace emulation target

- */Kconfig

These files are processed together with default-configs/*.mak and
describe the dependencies between various features, subsystems and
device models.  They are described in kconfig.rst.


Support scripts
---------------

Meson has a special convention for invoking Python scripts: if their
first line is "#! /usr/bin/env python3" and the file is *not* executable,
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.

In case the script is not written in Python, use a "#! /usr/bin/env ..."
line and make the script executable.

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),
should be invoked through the "python" variable in meson.build. For
example:

  test('QAPI schema regression tests', python,
       args: files('test-qapi.py'),
       env: test_env, suite: ['qapi-schema', 'qapi-frontend'])

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.


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.

Tests are also ran by the Makefile with the traditional "make check"
phony target.  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".

The following text is only relevant for unit tests which still have to
be converted to Meson.

All binaries should link to libqemuutil.a, e.g.:

   qemu-img$(EXESUF): qemu-img.o ..snip.. libqemuutil.a

On Windows, all binaries have the suffix '.exe', so all Makefile rules
which create binaries must include the $(EXESUF) variable on the binary
name. e.g.

   qemu-img$(EXESUF): qemu-img.o ..snip..

This expands to '.exe' on Windows, or '' on other platforms.

Variable naming
---------------

The QEMU convention is to define variables to list different groups of
object files. These are named with the convention $PREFIX-obj-y.  The
Meson "chardev" variable in the previous example corresponds to a
variable 'chardev-obj-y'.

Likewise, tests that are executed by "make check-unit" are grouped into
a variable check-unit-y, like this:

  check-unit-y += tests/test-visitor-serialization$(EXESUF)
  check-unit-y += tests/test-iov$(EXESUF)
  check-unit-y += tests/test-bitmap$(EXESUF)

When a test or object file which needs to be conditionally built based
on some characteristic of the host system, the configure script will
define a variable for the conditional. For example, on Windows it will
define $(CONFIG_POSIX) with a value of 'n' and $(CONFIG_WIN32) with a
value of 'y'. It is now possible to use the config variables when
listing object files. For example,

  check-unit-$(CONFIG_POSIX) += tests/test-vmstate$(EXESUF)

On Windows this expands to

  check-unit-n += tests/vmstate.exe

Since the "check-unit" target only runs tests included in "$(check-unit-y)",
POSIX specific tests listed in $(util-obj-n) are ignored on the Windows
platform builds.


CFLAGS / LDFLAGS / LIBS handling
--------------------------------

There are many different binaries being built with differing purposes,
and some of them might even be 3rd party libraries pulled in via git
submodules. As such the use of the global CFLAGS variable is generally
avoided in QEMU, since it would apply to too many build targets.

Flags that are needed by any QEMU code (i.e. everything *except* GIT
submodule projects) are put in $(QEMU_CFLAGS) variable. For linker
flags the $(LIBS) variable is sometimes used, but a couple of more
targeted variables are preferred.

In addition to these variables, it is possible to provide cflags and
libs against individual source code files, by defining variables of the
form $FILENAME-cflags and $FILENAME-libs. For example, the test
test-crypto-tlscredsx509 needs to link to the libtasn1 library,
so tests/Makefile.include defines some variables:

  tests/crypto-tls-x509-helpers.o-cflags := $(TASN1_CFLAGS)
  tests/crypto-tls-x509-helpers.o-libs := $(TASN1_LIBS)

The scope is a little different between the two variables. The libs get
used when linking any target binary that includes the curl.o object
file, while the cflags get used when compiling the curl.c file only.


Important files for the build system
====================================

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.

- Makefile

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.

- Makefile.objs

Defines *-obj-y files corresponding to 

- */meson.build

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.

- rules.mak

This file provides the generic helper rules for invoking build tools, in
particular the compiler and linker.

- tests/Makefile.include

Rules for building the unit tests. This file is included directly by the
top level Makefile, so anything defined in this file will influence the
entire build system. Care needs to be taken when writing rules for tests
to ensure they only apply to the unit test execution / build.

- tests/docker/Makefile.include

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.

- tests/vm/Makefile.include

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.

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.

Built by configure:

- config-host.mak

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
variety of CONFIG_* variables related to optionally enabled features.
This is imported by the top level Makefile and meson.build in order to
tailor the build output.

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.

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...

- $TARGET-NAME/config-target.mak

TARGET-NAME is the name of a system or userspace emulator, for example,
x86_64-softmmu denotes the system emulator for the x86_64 architecture.
This file contains the variables which need to vary on a per-target
basis. For example, it will indicate whether KVM or Xen are enabled for
the target and any other potential custom libraries needed for linking
the target.


Built by Meson:

- ${TARGET-NAME}-config-devices.mak

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.

- config-host.h
- $TARGET-NAME/config-target.h
- $TARGET-NAME/config-devices.h

These files are used by source code to determine what features
are enabled.  They are generated from the contents of the corresponding
*.h files using the scripts/create_config program. This extracts
relevant variables and formats them as C preprocessor macros.

- build.ninja


Built by Makefile:

- Makefile.ninja:

A Makefile conversion of the build rules in build.ninja.  The conversion
is straightforward and, were it necessary to debug the rules produced
by Meson, it should be enough to look at build.ninja.  The conversion
is performed by scripts/ninjatool.py.

- Makefile.mtest:

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.


Useful make targets
===================

- help

  Print a help message for the most common build targets.

- print-VAR

  Print the value of the variable VAR. Useful for debugging the build
  system.