xref: /openbmc/qemu/docs/devel/build-system.rst (revision 7e6055c9)
1==================================
2The QEMU build system architecture
3==================================
4
5This document aims to help developers understand the architecture of the
6QEMU build system. As with projects using GNU autotools, the QEMU build
7system has two stages, first the developer runs the "configure" script
8to determine the local build environment characteristics, then they run
9"make" to build the project. There is about where the similarities with
10GNU autotools end, so try to forget what you know about them.
11
12
13Stage 1: configure
14==================
15
16The QEMU configure script is written directly in shell, and should be
17compatible with any POSIX shell, hence it uses #!/bin/sh. An important
18implication of this is that it is important to avoid using bash-isms on
19development platforms where bash is the primary host.
20
21In contrast to autoconf scripts, QEMU's configure is expected to be
22silent while it is checking for features. It will only display output
23when an error occurs, or to show the final feature enablement summary
24on completion.
25
26Because QEMU uses the Meson build system under the hood, only VPATH
27builds are supported.  There are two general ways to invoke configure &
28perform a build:
29
30 - VPATH, build artifacts outside of QEMU source tree entirely::
31
32     cd ../
33     mkdir build
34     cd build
35     ../qemu/configure
36     make
37
38 - VPATH, build artifacts in a subdir of QEMU source tree::
39
40     mkdir build
41     cd build
42     ../configure
43     make
44
45The configure script automatically recognizes
46command line options for which a same-named Meson option exists;
47dashes in the command line are replaced with underscores.
48
49Many checks on the compilation environment are still found in configure
50rather than ``meson.build``, but new checks should be added directly to
51``meson.build``.
52
53Patches are also welcome to move existing checks from the configure
54phase to ``meson.build``.  When doing so, ensure that ``meson.build`` does
55not use anymore the keys that you have removed from ``config-host.mak``.
56Typically these will be replaced in ``meson.build`` by boolean variables,
57``get_option('optname')`` invocations, or ``dep.found()`` expressions.
58In general, the remaining checks have little or no interdependencies,
59so they can be moved one by one.
60
61Helper functions
62----------------
63
64The configure script provides a variety of helper functions to assist
65developers in checking for system features:
66
67``do_cc $ARGS...``
68   Attempt to run the system C compiler passing it $ARGS...
69
70``do_cxx $ARGS...``
71   Attempt to run the system C++ compiler passing it $ARGS...
72
73``compile_object $CFLAGS``
74   Attempt to compile a test program with the system C compiler using
75   $CFLAGS. The test program must have been previously written to a file
76   called $TMPC.  The replacement in Meson is the compiler object ``cc``,
77   which has methods such as ``cc.compiles()``,
78   ``cc.check_header()``, ``cc.has_function()``.
79
80``compile_prog $CFLAGS $LDFLAGS``
81   Attempt to compile a test program with the system C compiler using
82   $CFLAGS and link it with the system linker using $LDFLAGS. The test
83   program must have been previously written to a file called $TMPC.
84   The replacement in Meson is ``cc.find_library()`` and ``cc.links()``.
85
86``has $COMMAND``
87   Determine if $COMMAND exists in the current environment, either as a
88   shell builtin, or executable binary, returning 0 on success.  The
89   replacement in Meson is ``find_program()``.
90
91``check_define $NAME``
92   Determine if the macro $NAME is defined by the system C compiler
93
94``check_include $NAME``
95   Determine if the include $NAME file is available to the system C
96   compiler.  The replacement in Meson is ``cc.has_header()``.
97
98``write_c_skeleton``
99   Write a minimal C program main() function to the temporary file
100   indicated by $TMPC
101
102``feature_not_found $NAME $REMEDY``
103   Print a message to stderr that the feature $NAME was not available
104   on the system, suggesting the user try $REMEDY to address the
105   problem.
106
107``error_exit $MESSAGE $MORE...``
108   Print $MESSAGE to stderr, followed by $MORE... and then exit from the
109   configure script with non-zero status
110
111``query_pkg_config $ARGS...``
112   Run pkg-config passing it $ARGS. If QEMU is doing a static build,
113   then --static will be automatically added to $ARGS
114
115
116Stage 2: Meson
117==============
118
119The Meson build system is currently used to describe the build
120process for:
121
1221) executables, which include:
123
124   - Tools - qemu-img, qemu-nbd, qga (guest agent), etc
125
126   - System emulators - qemu-system-$ARCH
127
128   - Userspace emulators - qemu-$ARCH
129
130   - Unit tests
131
1322) documentation
133
1343) ROMs, which can be either installed as binary blobs or compiled
135
1364) other data files, such as icons or desktop files
137
138All executables are built by default, except for some ``contrib/``
139binaries that are known to fail to build on some platforms (for example
14032-bit or big-endian platforms).  Tests are also built by default,
141though that might change in the future.
142
143The source code is highly modularized, split across many files to
144facilitate building of all of these components with as little duplicated
145compilation as possible. Using the Meson "sourceset" functionality,
146``meson.build`` files group the source files in rules that are
147enabled according to the available system libraries and to various
148configuration symbols.  Sourcesets belong to one of four groups:
149
150Subsystem sourcesets:
151  Various subsystems that are common to both tools and emulators have
152  their own sourceset, for example ``block_ss`` for the block device subsystem,
153  ``chardev_ss`` for the character device subsystem, etc.  These sourcesets
154  are then turned into static libraries as follows::
155
156    libchardev = static_library('chardev', chardev_ss.sources(),
157                                name_suffix: 'fa',
158                                build_by_default: false)
159
160    chardev = declare_dependency(link_whole: libchardev)
161
162  As of Meson 0.55.1, the special ``.fa`` suffix should be used for everything
163  that is used with ``link_whole``, to ensure that the link flags are placed
164  correctly in the command line.
165
166Target-independent emulator sourcesets:
167  Various general purpose helper code is compiled only once and
168  the .o files are linked into all output binaries that need it.
169  This includes error handling infrastructure, standard data structures,
170  platform portability wrapper functions, etc.
171
172  Target-independent code lives in the ``common_ss``, ``softmmu_ss`` and
173  ``user_ss`` sourcesets.  ``common_ss`` is linked into all emulators,
174  ``softmmu_ss`` only in system emulators, ``user_ss`` only in user-mode
175  emulators.
176
177  Target-independent sourcesets must exercise particular care when using
178  ``if_false`` rules.  The ``if_false`` rule will be used correctly when linking
179  emulator binaries; however, when *compiling* target-independent files
180  into .o files, Meson may need to pick *both* the ``if_true`` and
181  ``if_false`` sides to cater for targets that want either side.  To
182  achieve that, you can add a special rule using the ``CONFIG_ALL``
183  symbol::
184
185    # Some targets have CONFIG_ACPI, some don't, so this is not enough
186    softmmu_ss.add(when: 'CONFIG_ACPI', if_true: files('acpi.c'),
187                                        if_false: files('acpi-stub.c'))
188
189    # This is required as well:
190    softmmu_ss.add(when: 'CONFIG_ALL', if_true: files('acpi-stub.c'))
191
192Target-dependent emulator sourcesets:
193  In the target-dependent set lives CPU emulation, some device emulation and
194  much glue code. This sometimes also has to be compiled multiple times,
195  once for each target being built.  Target-dependent files are included
196  in the ``specific_ss`` sourceset.
197
198  Each emulator also includes sources for files in the ``hw/`` and ``target/``
199  subdirectories.  The subdirectory used for each emulator comes
200  from the target's definition of ``TARGET_BASE_ARCH`` or (if missing)
201  ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``.
202
203  Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary,
204  for example::
205
206    arm_ss = ss.source_set()
207    arm_ss.add(files('boot.c'), fdt)
208    ...
209    hw_arch += {'arm': arm_ss}
210
211  The sourceset is only used for system emulators.
212
213  Each subdirectory in ``target/`` instead should add one sourceset to each
214  of the ``target_arch`` and ``target_softmmu_arch``, which are used respectively
215  for all emulators and for system emulators only.  For example::
216
217    arm_ss = ss.source_set()
218    arm_softmmu_ss = ss.source_set()
219    ...
220    target_arch += {'arm': arm_ss}
221    target_softmmu_arch += {'arm': arm_softmmu_ss}
222
223Module sourcesets:
224  There are two dictionaries for modules: ``modules`` is used for
225  target-independent modules and ``target_modules`` is used for
226  target-dependent modules.  When modules are disabled the ``module``
227  source sets are added to ``softmmu_ss`` and the ``target_modules``
228  source sets are added to ``specific_ss``.
229
230  Both dictionaries are nested.  One dictionary is created per
231  subdirectory, and these per-subdirectory dictionaries are added to
232  the toplevel dictionaries.  For example::
233
234    hw_display_modules = {}
235    qxl_ss = ss.source_set()
236    ...
237    hw_display_modules += { 'qxl': qxl_ss }
238    modules += { 'hw-display': hw_display_modules }
239
240Utility sourcesets:
241  All binaries link with a static library ``libqemuutil.a``.  This library
242  is built from several sourcesets; most of them however host generated
243  code, and the only two of general interest are ``util_ss`` and ``stub_ss``.
244
245  The separation between these two is purely for documentation purposes.
246  ``util_ss`` contains generic utility files.  Even though this code is only
247  linked in some binaries, sometimes it requires hooks only in some of
248  these and depend on other functions that are not fully implemented by
249  all QEMU binaries.  ``stub_ss`` links dummy stubs that will only be linked
250  into the binary if the real implementation is not present.  In a way,
251  the stubs can be thought of as a portable implementation of the weak
252  symbols concept.
253
254
255The following files concur in the definition of which files are linked
256into each emulator:
257
258``default-configs/devices/*.mak``
259  The files under ``default-configs/devices/`` control the boards and devices
260  that are built into each QEMU system emulation targets. They merely contain
261  a list of config variable definitions such as::
262
263    include arm-softmmu.mak
264    CONFIG_XLNX_ZYNQMP_ARM=y
265    CONFIG_XLNX_VERSAL=y
266
267``*/Kconfig``
268  These files are processed together with ``default-configs/devices/*.mak`` and
269  describe the dependencies between various features, subsystems and
270  device models.  They are described in :ref:`kconfig`
271
272``default-configs/targets/*.mak``
273  These files mostly define symbols that appear in the ``*-config-target.h``
274  file for each emulator [#cfgtarget]_.  However, the ``TARGET_ARCH``
275  and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and
276  ``target/`` subdirectories that are compiled into each target.
277
278.. [#cfgtarget] This header is included by ``qemu/osdep.h`` when
279                compiling files from the target-specific sourcesets.
280
281These files rarely need changing unless you are adding a completely
282new target, or enabling new devices or hardware for a particular
283system/userspace emulation target
284
285
286Adding checks
287-------------
288
289New checks should be added to Meson.  Compiler checks can be as simple as
290the following::
291
292  config_host_data.set('HAVE_BTRFS_H', cc.has_header('linux/btrfs.h'))
293
294A more complex task such as adding a new dependency usually
295comprises the following tasks:
296
297 - Add a Meson build option to meson_options.txt.
298
299 - Add code to perform the actual feature check.
300
301 - Add code to include the feature status in ``config-host.h``
302
303 - Add code to print out the feature status in the configure summary
304   upon completion.
305
306Taking the probe for SDL2_Image as an example, we have the following
307in ``meson_options.txt``::
308
309  option('sdl_image', type : 'feature', value : 'auto',
310         description: 'SDL Image support for icons')
311
312Unless the option was given a non-``auto`` value (on the configure
313command line), the detection code must be performed only if the
314dependency will be used::
315
316  sdl_image = not_found
317  if not get_option('sdl_image').auto() or have_system
318    sdl_image = dependency('SDL2_image', required: get_option('sdl_image'),
319                           method: 'pkg-config',
320                           static: enable_static)
321  endif
322
323This avoids warnings on static builds of user-mode emulators, for example.
324Most of the libraries used by system-mode emulators are not available for
325static linking.
326
327The other supporting code is generally simple::
328
329  # Create config-host.h (if applicable)
330  config_host_data.set('CONFIG_SDL_IMAGE', sdl_image.found())
331
332  # Summary
333  summary_info += {'SDL image support': sdl_image.found()}
334
335For the configure script to parse the new option, the
336``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make
337update-buildoptions`` (or just ``make``) will take care of updating it.
338
339
340Support scripts
341---------------
342
343Meson has a special convention for invoking Python scripts: if their
344first line is ``#! /usr/bin/env python3`` and the file is *not* executable,
345find_program() arranges to invoke the script under the same Python
346interpreter that was used to invoke Meson.  This is the most common
347and preferred way to invoke support scripts from Meson build files,
348because it automatically uses the value of configure's --python= option.
349
350In case the script is not written in Python, use a ``#! /usr/bin/env ...``
351line and make the script executable.
352
353Scripts written in Python, where it is desirable to make the script
354executable (for example for test scripts that developers may want to
355invoke from the command line, such as tests/qapi-schema/test-qapi.py),
356should be invoked through the ``python`` variable in meson.build. For
357example::
358
359  test('QAPI schema regression tests', python,
360       args: files('test-qapi.py'),
361       env: test_env, suite: ['qapi-schema', 'qapi-frontend'])
362
363This is needed to obey the --python= option passed to the configure
364script, which may point to something other than the first python3
365binary on the path.
366
367
368Stage 3: makefiles
369==================
370
371The use of GNU make is required with the QEMU build system.
372
373The output of Meson is a build.ninja file, which is used with the Ninja
374build system.  QEMU uses a different approach, where Makefile rules are
375synthesized from the build.ninja file.  The main Makefile includes these
376rules and wraps them so that e.g. submodules are built before QEMU.
377The resulting build system is largely non-recursive in nature, in
378contrast to common practices seen with automake.
379
380Tests are also ran by the Makefile with the traditional ``make check``
381phony target, while benchmarks are run with ``make bench``.  Meson test
382suites such as ``unit`` can be ran with ``make check-unit`` too.  It is also
383possible to run tests defined in meson.build with ``meson test``.
384
385Useful make targets
386-------------------
387
388``help``
389  Print a help message for the most common build targets.
390
391``print-VAR``
392  Print the value of the variable VAR. Useful for debugging the build
393  system.
394
395Important files for the build system
396====================================
397
398Statically defined files
399------------------------
400
401The following key files are statically defined in the source tree, with
402the rules needed to build QEMU. Their behaviour is influenced by a
403number of dynamically created files listed later.
404
405``Makefile``
406  The main entry point used when invoking make to build all the components
407  of QEMU. The default 'all' target will naturally result in the build of
408  every component. Makefile takes care of recursively building submodules
409  directly via a non-recursive set of rules.
410
411``*/meson.build``
412  The meson.build file in the root directory is the main entry point for the
413  Meson build system, and it coordinates the configuration and build of all
414  executables.  Build rules for various subdirectories are included in
415  other meson.build files spread throughout the QEMU source tree.
416
417``tests/Makefile.include``
418  Rules for external test harnesses. These include the TCG tests,
419  ``qemu-iotests`` and the Avocado-based integration tests.
420
421``tests/docker/Makefile.include``
422  Rules for Docker tests. Like tests/Makefile, this file is included
423  directly by the top level Makefile, anything defined in this file will
424  influence the entire build system.
425
426``tests/vm/Makefile.include``
427  Rules for VM-based tests. Like tests/Makefile, this file is included
428  directly by the top level Makefile, anything defined in this file will
429  influence the entire build system.
430
431Dynamically created files
432-------------------------
433
434The following files are generated dynamically by configure in order to
435control the behaviour of the statically defined makefiles. This avoids
436the need for QEMU makefiles to go through any pre-processing as seen
437with autotools, where Makefile.am generates Makefile.in which generates
438Makefile.
439
440Built by configure:
441
442``config-host.mak``
443  When configure has determined the characteristics of the build host it
444  will write a long list of variables to config-host.mak file. This
445  provides the various install directories, compiler / linker flags and a
446  variety of ``CONFIG_*`` variables related to optionally enabled features.
447  This is imported by the top level Makefile and meson.build in order to
448  tailor the build output.
449
450  config-host.mak is also used as a dependency checking mechanism. If make
451  sees that the modification timestamp on configure is newer than that on
452  config-host.mak, then configure will be re-run.
453
454  The variables defined here are those which are applicable to all QEMU
455  build outputs. Variables which are potentially different for each
456  emulator target are defined by the next file...
457
458
459Built by Meson:
460
461``${TARGET-NAME}-config-devices.mak``
462  TARGET-NAME is again the name of a system or userspace emulator. The
463  config-devices.mak file is automatically generated by make using the
464  scripts/make_device_config.sh program, feeding it the
465  default-configs/$TARGET-NAME file as input.
466
467``config-host.h``, ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h``
468  These files are used by source code to determine what features are
469  enabled.  They are generated from the contents of the corresponding
470  ``*.mak`` files using Meson's ``configure_file()`` function.
471
472``build.ninja``
473  The build rules.
474
475
476Built by Makefile:
477
478``Makefile.ninja``
479  A Makefile include that bridges to ninja for the actual build.  The
480  Makefile is mostly a list of targets that Meson included in build.ninja.
481
482``Makefile.mtest``
483  The Makefile definitions that let "make check" run tests defined in
484  meson.build.  The rules are produced from Meson's JSON description of
485  tests (obtained with "meson introspect --tests") through the script
486  scripts/mtest2make.py.
487