blob: 431caba7aa06e807354bf4e9445d8f31a0f41f13 [file] [log] [blame]
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +02001==================================
2The QEMU build system architecture
3==================================
Daniel P. Berrange717171b2015-09-24 14:41:38 +01004
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
Paolo Bonzini77d27b92020-02-04 11:43:54 +010026Because 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
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +020030 - VPATH, build artifacts outside of QEMU source tree entirely::
Paolo Bonzini77d27b92020-02-04 11:43:54 +010031
32 cd ../
33 mkdir build
34 cd build
35 ../qemu/configure
36 make
37
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +020038 - VPATH, build artifacts in a subdir of QEMU source tree::
Paolo Bonzini77d27b92020-02-04 11:43:54 +010039
40 mkdir build
41 cd build
42 ../configure
43 make
44
Paolo Bonzini3b4da132021-10-07 15:08:29 +020045The configure script automatically recognizes
46command line options for which a same-named Meson option exists;
47dashes in the command line are replaced with underscores.
Paolo Bonzini77d27b92020-02-04 11:43:54 +010048
Paolo Bonzini3b4da132021-10-07 15:08:29 +020049Many checks on the compilation environment are still found in configure
John Snowca0a0d12021-10-04 17:52:37 -040050rather than ``meson.build``, but new checks should be added directly to
51``meson.build``.
Daniel P. Berrange717171b2015-09-24 14:41:38 +010052
Paolo Bonzini3b4da132021-10-07 15:08:29 +020053Patches are also welcome to move existing checks from the configure
John Snowca0a0d12021-10-04 17:52:37 -040054phase 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.
Paolo Bonzini3b4da132021-10-07 15:08:29 +020058In general, the remaining checks have little or no interdependencies,
59so they can be moved one by one.
Daniel P. Berrange717171b2015-09-24 14:41:38 +010060
61Helper functions
62----------------
63
64The configure script provides a variety of helper functions to assist
65developers in checking for system features:
66
Peter Maydell35a4ca42021-07-26 15:23:29 +010067``do_cc $ARGS...``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010068 Attempt to run the system C compiler passing it $ARGS...
69
Peter Maydell35a4ca42021-07-26 15:23:29 +010070``do_cxx $ARGS...``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010071 Attempt to run the system C++ compiler passing it $ARGS...
72
Peter Maydell35a4ca42021-07-26 15:23:29 +010073``compile_object $CFLAGS``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010074 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
Peter Maydell35a4ca42021-07-26 15:23:29 +010076 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()``.
Daniel P. Berrange717171b2015-09-24 14:41:38 +010079
Peter Maydell35a4ca42021-07-26 15:23:29 +010080``compile_prog $CFLAGS $LDFLAGS``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010081 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.
Peter Maydell35a4ca42021-07-26 15:23:29 +010084 The replacement in Meson is ``cc.find_library()`` and ``cc.links()``.
Daniel P. Berrange717171b2015-09-24 14:41:38 +010085
Peter Maydell35a4ca42021-07-26 15:23:29 +010086``has $COMMAND``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010087 Determine if $COMMAND exists in the current environment, either as a
Paolo Bonzini738aa602020-09-01 06:38:25 -040088 shell builtin, or executable binary, returning 0 on success. The
Peter Maydell35a4ca42021-07-26 15:23:29 +010089 replacement in Meson is ``find_program()``.
Daniel P. Berrange717171b2015-09-24 14:41:38 +010090
Peter Maydell35a4ca42021-07-26 15:23:29 +010091``check_define $NAME``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010092 Determine if the macro $NAME is defined by the system C compiler
93
Peter Maydell35a4ca42021-07-26 15:23:29 +010094``check_include $NAME``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010095 Determine if the include $NAME file is available to the system C
Peter Maydell35a4ca42021-07-26 15:23:29 +010096 compiler. The replacement in Meson is ``cc.has_header()``.
Daniel P. Berrange717171b2015-09-24 14:41:38 +010097
Peter Maydell35a4ca42021-07-26 15:23:29 +010098``write_c_skeleton``
Daniel P. Berrange717171b2015-09-24 14:41:38 +010099 Write a minimal C program main() function to the temporary file
100 indicated by $TMPC
101
Peter Maydell35a4ca42021-07-26 15:23:29 +0100102``feature_not_found $NAME $REMEDY``
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100103 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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100107``error_exit $MESSAGE $MORE...``
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100108 Print $MESSAGE to stderr, followed by $MORE... and then exit from the
109 configure script with non-zero status
110
Peter Maydell35a4ca42021-07-26 15:23:29 +0100111``query_pkg_config $ARGS...``
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100112 Run pkg-config passing it $ARGS. If QEMU is doing a static build,
113 then --static will be automatically added to $ARGS
114
115
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100116Stage 2: Meson
117==============
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100118
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100119The Meson build system is currently used to describe the build
120process for:
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100121
Paolo Bonzini77d27b92020-02-04 11:43:54 +01001221) executables, which include:
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200123
Philippe Mathieu-Daudéc5ba6212021-11-18 20:27:44 +0100124 - Tools - ``qemu-img``, ``qemu-nbd``, ``qga`` (guest agent), etc
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200125
Philippe Mathieu-Daudéc5ba6212021-11-18 20:27:44 +0100126 - System emulators - ``qemu-system-$ARCH``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200127
Philippe Mathieu-Daudéc5ba6212021-11-18 20:27:44 +0100128 - Userspace emulators - ``qemu-$ARCH``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200129
Paolo Bonzinief6a0d62020-09-07 18:39:13 +0200130 - Unit tests
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100131
Paolo Bonzini77d27b92020-02-04 11:43:54 +01001322) documentation
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100133
Paolo Bonzini77d27b92020-02-04 11:43:54 +01001343) ROMs, which can be either installed as binary blobs or compiled
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100135
Paolo Bonzini77d27b92020-02-04 11:43:54 +01001364) other data files, such as icons or desktop files
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100137
Peter Maydell35a4ca42021-07-26 15:23:29 +0100138All executables are built by default, except for some ``contrib/``
Paolo Bonzini27d551c2020-09-11 13:12:11 +0200139binaries 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
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100143The 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,
Peter Maydell35a4ca42021-07-26 15:23:29 +0100146``meson.build`` files group the source files in rules that are
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100147enabled 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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100152 their own sourceset, for example ``block_ss`` for the block device subsystem,
153 ``chardev_ss`` for the character device subsystem, etc. These sourcesets
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100154 are then turned into static libraries as follows::
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100155
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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100162 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
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100164 correctly in the command line.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100165
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100166Target-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.
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100171
Peter Maydell35a4ca42021-07-26 15:23:29 +0100172 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
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100175 emulators.
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100176
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100177 Target-independent sourcesets must exercise particular care when using
Peter Maydell35a4ca42021-07-26 15:23:29 +0100178 ``if_false`` rules. The ``if_false`` rule will be used correctly when linking
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100179 emulator binaries; however, when *compiling* target-independent files
Peter Maydell35a4ca42021-07-26 15:23:29 +0100180 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
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100182 achieve that, you can add a special rule using the ``CONFIG_ALL``
183 symbol::
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100184
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100185 # Some targets have CONFIG_ACPI, some don't, so this is not enough
Peter Maydelld463f3c2021-07-26 15:23:30 +0100186 softmmu_ss.add(when: 'CONFIG_ACPI', if_true: files('acpi.c'),
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100187 if_false: files('acpi-stub.c'))
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100188
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100189 # This is required as well:
Peter Maydelld463f3c2021-07-26 15:23:30 +0100190 softmmu_ss.add(when: 'CONFIG_ALL', if_true: files('acpi-stub.c'))
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100191
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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100196 in the ``specific_ss`` sourceset.
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100197
Peter Maydell35a4ca42021-07-26 15:23:29 +0100198 Each emulator also includes sources for files in the ``hw/`` and ``target/``
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100199 subdirectories. The subdirectory used for each emulator comes
200 from the target's definition of ``TARGET_BASE_ARCH`` or (if missing)
Peter Maydell35a4ca42021-07-26 15:23:29 +0100201 ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``.
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100202
Peter Maydell35a4ca42021-07-26 15:23:29 +0100203 Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary,
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100204 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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100213 Each subdirectory in ``target/`` instead should add one sourceset to each
214 of the ``target_arch`` and ``target_softmmu_arch``, which are used respectively
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100215 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
Gerd Hoffmann964711c2021-06-24 12:38:23 +0200223Module sourcesets:
Peter Maydell35a4ca42021-07-26 15:23:29 +0100224 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``.
Gerd Hoffmann964711c2021-06-24 12:38:23 +0200229
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
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100240Utility sourcesets:
Peter Maydell35a4ca42021-07-26 15:23:29 +0100241 All binaries link with a static library ``libqemuutil.a``. This library
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100242 is built from several sourcesets; most of them however host generated
Peter Maydell35a4ca42021-07-26 15:23:29 +0100243 code, and the only two of general interest are ``util_ss`` and ``stub_ss``.
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100244
245 The separation between these two is purely for documentation purposes.
Peter Maydell35a4ca42021-07-26 15:23:29 +0100246 ``util_ss`` contains generic utility files. Even though this code is only
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100247 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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100249 all QEMU binaries. ``stub_ss`` links dummy stubs that will only be linked
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100250 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
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100254
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100255The following files concur in the definition of which files are linked
256into each emulator:
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100257
Peter Maydell35a4ca42021-07-26 15:23:29 +0100258``default-configs/devices/*.mak``
259 The files under ``default-configs/devices/`` control the boards and devices
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100260 that are built into each QEMU system emulation targets. They merely contain
261 a list of config variable definitions such as::
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100262
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200263 include arm-softmmu.mak
264 CONFIG_XLNX_ZYNQMP_ARM=y
265 CONFIG_XLNX_VERSAL=y
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100266
Peter Maydell35a4ca42021-07-26 15:23:29 +0100267``*/Kconfig``
268 These files are processed together with ``default-configs/devices/*.mak`` and
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200269 describe the dependencies between various features, subsystems and
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100270 device models. They are described in :ref:`kconfig`
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100271
Peter Maydell35a4ca42021-07-26 15:23:29 +0100272``default-configs/targets/*.mak``
273 These files mostly define symbols that appear in the ``*-config-target.h``
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100274 file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH``
Peter Maydell35a4ca42021-07-26 15:23:29 +0100275 and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and
276 ``target/`` subdirectories that are compiled into each target.
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100277
Peter Maydell35a4ca42021-07-26 15:23:29 +0100278.. [#cfgtarget] This header is included by ``qemu/osdep.h`` when
Paolo Bonzini2eba4272020-10-29 13:06:09 +0100279 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
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100284
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100285
Paolo Bonzini3b4da132021-10-07 15:08:29 +0200286Adding 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
John Snowca0a0d12021-10-04 17:52:37 -0400301 - Add code to include the feature status in ``config-host.h``
Paolo Bonzini3b4da132021-10-07 15:08:29 +0200302
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
John Snowca0a0d12021-10-04 17:52:37 -0400337update-buildoptions`` (or just ``make``) will take care of updating it.
Paolo Bonzini3b4da132021-10-07 15:08:29 +0200338
339
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100340Support scripts
341---------------
342
343Meson has a special convention for invoking Python scripts: if their
Peter Maydell35a4ca42021-07-26 15:23:29 +0100344first line is ``#! /usr/bin/env python3`` and the file is *not* executable,
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100345find_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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100350In case the script is not written in Python, use a ``#! /usr/bin/env ...``
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100351line 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),
Peter Maydell35a4ca42021-07-26 15:23:29 +0100356should be invoked through the ``python`` variable in meson.build. For
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200357example::
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100358
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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100380Tests 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``.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100384
Paolo Bonzini8b8939e2021-09-07 16:25:50 +0200385Useful 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
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100395Important 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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100405``Makefile``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200406 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.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100410
Peter Maydell35a4ca42021-07-26 15:23:29 +0100411``*/meson.build``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200412 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.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100416
Peter Maydell35a4ca42021-07-26 15:23:29 +0100417``tests/Makefile.include``
Paolo Bonzinief6a0d62020-09-07 18:39:13 +0200418 Rules for external test harnesses. These include the TCG tests,
Willian Rampazzobbbd9b62021-11-05 12:53:54 -0300419 ``qemu-iotests`` and the Avocado-based integration tests.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100420
Peter Maydell35a4ca42021-07-26 15:23:29 +0100421``tests/docker/Makefile.include``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200422 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.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100425
Peter Maydell35a4ca42021-07-26 15:23:29 +0100426``tests/vm/Makefile.include``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200427 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.
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100430
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
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100440Built by configure:
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100441
Peter Maydell35a4ca42021-07-26 15:23:29 +0100442``config-host.mak``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200443 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
Peter Maydell35a4ca42021-07-26 15:23:29 +0100446 variety of ``CONFIG_*`` variables related to optionally enabled features.
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200447 This is imported by the top level Makefile and meson.build in order to
448 tailor the build output.
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100449
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200450 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.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100453
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200454 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...
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100457
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100458
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100459Built by Meson:
460
Peter Maydell35a4ca42021-07-26 15:23:29 +0100461``${TARGET-NAME}-config-devices.mak``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200462 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.
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100466
Paolo Bonzini49334362021-11-05 13:45:40 +0100467``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.
Daniel P. Berrange717171b2015-09-24 14:41:38 +0100471
Peter Maydell35a4ca42021-07-26 15:23:29 +0100472``build.ninja``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200473 The build rules.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100474
475
476Built by Makefile:
477
Peter Maydell35a4ca42021-07-26 15:23:29 +0100478``Makefile.ninja``
Paolo Bonzini09e93322020-08-13 09:28:11 -0400479 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.
Paolo Bonzini77d27b92020-02-04 11:43:54 +0100481
Peter Maydell35a4ca42021-07-26 15:23:29 +0100482``Makefile.mtest``
Paolo Bonzinia14f0bf2020-08-11 18:34:40 +0200483 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.