]>
Commit | Line | Data |
---|---|---|
a14f0bf1 PB |
1 | ================================== |
2 | The QEMU build system architecture | |
3 | ================================== | |
717171bd DB |
4 | |
5 | This document aims to help developers understand the architecture of the | |
6 | QEMU build system. As with projects using GNU autotools, the QEMU build | |
fe3ab4eb | 7 | system has two stages; first the developer runs the "configure" script |
717171bd | 8 | to determine the local build environment characteristics, then they run |
fe3ab4eb | 9 | "make" to build the project. This is about where the similarities with |
717171bd DB |
10 | GNU autotools end, so try to forget what you know about them. |
11 | ||
fe3ab4eb | 12 | The two general ways to perform a build are as follows: |
717171bd | 13 | |
fe3ab4eb | 14 | - build artifacts outside of QEMU source tree entirely:: |
77d27b92 PB |
15 | |
16 | cd ../ | |
17 | mkdir build | |
18 | cd build | |
19 | ../qemu/configure | |
20 | make | |
21 | ||
fe3ab4eb | 22 | - build artifacts in a subdir of QEMU source tree:: |
77d27b92 PB |
23 | |
24 | mkdir build | |
25 | cd build | |
26 | ../configure | |
27 | make | |
28 | ||
fe3ab4eb PB |
29 | Most of the actual build process uses Meson under the hood, therefore |
30 | build artifacts cannot be placed in the source tree itself. | |
31 | ||
32 | ||
33 | Stage 1: configure | |
34 | ================== | |
35 | ||
36 | The configure script has five tasks: | |
37 | ||
38 | - detect the host architecture | |
39 | ||
40 | - list the targets for which to build emulators; the list of | |
41 | targets also affects which firmware binaries and tests to build | |
3b4da132 | 42 | |
fe3ab4eb PB |
43 | - find the compilers (native and cross) used to build executables, |
44 | firmware and tests. The results are written as either Makefile | |
45 | fragments (``config-host.mak``) or a Meson machine file | |
46 | (``config-meson.cross``) | |
3b4da132 | 47 | |
fe3ab4eb PB |
48 | - create a virtual environment in which all Python code runs during |
49 | the build, and possibly install packages into it from PyPI | |
50 | ||
51 | - invoke Meson in the virtual environment, to perform the actual | |
52 | configuration step for the emulator build | |
53 | ||
54 | The configure script automatically recognizes command line options for | |
55 | which a same-named Meson option exists; dashes in the command line are | |
56 | replaced with underscores. | |
57 | ||
58 | Almost all QEMU developers that need to modify the build system will | |
59 | only be concerned with Meson, and therefore can skip the rest of this | |
60 | section. | |
61 | ||
62 | ||
63 | Modifying ``configure`` | |
64 | ----------------------- | |
65 | ||
66 | ``configure`` is a shell script; it uses ``#!/bin/sh`` and therefore | |
67 | should be compatible with any POSIX shell. It is important to avoid | |
68 | using bash-isms to avoid breaking development platforms where bash is | |
69 | the primary host. | |
70 | ||
71 | The configure script provides a variety of functions to help writing | |
72 | portable shell code and providing consistent behavior across architectures | |
73 | and operating systems: | |
74 | ||
75 | ``error_exit $MESSAGE $MORE...`` | |
76 | Print $MESSAGE to stderr, followed by $MORE... and then exit from the | |
77 | configure script with non-zero status. | |
78 | ||
79 | ``has $COMMAND`` | |
80 | Determine if $COMMAND exists in the current environment, either as a | |
81 | shell builtin, or executable binary, returning 0 on success. The | |
82 | replacement in Meson is ``find_program()``. | |
717171bd | 83 | |
fe3ab4eb PB |
84 | ``probe_target_compiler $TARGET`` |
85 | Detect a cross compiler and cross tools for the QEMU target $TARGET (e.g., | |
86 | ``$CPU-softmmu``, ``$CPU-linux-user``, ``$CPU-bsd-user``). If a working | |
87 | compiler is present, return success and set variables ``$target_cc``, | |
88 | ``$target_ar``, etc. to non-empty values. | |
717171bd | 89 | |
fe3ab4eb PB |
90 | ``write_target_makefile`` |
91 | Write a Makefile fragment to stdout, exposing the result of the most | |
92 | ``probe_target_compiler`` call as the usual Make variables (``CC``, | |
93 | ``AR``, ``LD``, etc.). | |
717171bd | 94 | |
717171bd | 95 | |
fe3ab4eb PB |
96 | Configure does not generally perform tests for compiler options beyond |
97 | basic checks to detect the host platform and ensure the compiler is | |
98 | functioning. These are performed using a few more helper functions: | |
717171bd | 99 | |
35a4ca40 | 100 | ``compile_object $CFLAGS`` |
717171bd DB |
101 | Attempt to compile a test program with the system C compiler using |
102 | $CFLAGS. The test program must have been previously written to a file | |
fe3ab4eb | 103 | called $TMPC. |
717171bd | 104 | |
35a4ca40 | 105 | ``compile_prog $CFLAGS $LDFLAGS`` |
717171bd DB |
106 | Attempt to compile a test program with the system C compiler using |
107 | $CFLAGS and link it with the system linker using $LDFLAGS. The test | |
108 | program must have been previously written to a file called $TMPC. | |
717171bd | 109 | |
35a4ca40 | 110 | ``check_define $NAME`` |
fe3ab4eb PB |
111 | Determine if the macro $NAME is defined by the system C compiler. |
112 | ||
113 | ``do_compiler $CC $ARGS...`` | |
114 | Attempt to run the C compiler $CC, passing it $ARGS... This function | |
115 | does not use flags passed via options such as ``--extra-cflags``, and | |
116 | therefore can be used to check for cross compilers. However, most | |
117 | such checks are done at ``make`` time instead (see for example the | |
118 | ``cc-option`` macro in ``pc-bios/option-rom/Makefile``). | |
717171bd | 119 | |
35a4ca40 | 120 | ``write_c_skeleton`` |
717171bd | 121 | Write a minimal C program main() function to the temporary file |
fe3ab4eb | 122 | indicated by $TMPC. |
717171bd | 123 | |
717171bd | 124 | |
fe3ab4eb PB |
125 | Python virtual environments and the QEMU build system |
126 | ----------------------------------------------------- | |
127 | ||
128 | TBD | |
717171bd | 129 | |
77d27b92 PB |
130 | Stage 2: Meson |
131 | ============== | |
717171bd | 132 | |
fe3ab4eb | 133 | The Meson build system describes the build and install process for: |
717171bd | 134 | |
77d27b92 | 135 | 1) executables, which include: |
a14f0bf1 | 136 | |
fe3ab4eb | 137 | - Tools - ``qemu-img``, ``qemu-nbd``, ``qemu-ga`` (guest agent), etc |
a14f0bf1 | 138 | |
c5ba6219 | 139 | - System emulators - ``qemu-system-$ARCH`` |
a14f0bf1 | 140 | |
c5ba6219 | 141 | - Userspace emulators - ``qemu-$ARCH`` |
a14f0bf1 | 142 | |
ef6a0d6e | 143 | - Unit tests |
717171bd | 144 | |
77d27b92 | 145 | 2) documentation |
717171bd | 146 | |
fe3ab4eb PB |
147 | 3) ROMs, whether provided as binary blobs in the QEMU distributions |
148 | or cross compiled under the direction of the configure script | |
717171bd | 149 | |
77d27b92 | 150 | 4) other data files, such as icons or desktop files |
717171bd | 151 | |
35a4ca40 | 152 | All executables are built by default, except for some ``contrib/`` |
27d551c0 PB |
153 | binaries that are known to fail to build on some platforms (for example |
154 | 32-bit or big-endian platforms). Tests are also built by default, | |
155 | though that might change in the future. | |
156 | ||
2eba427e PB |
157 | The source code is highly modularized, split across many files to |
158 | facilitate building of all of these components with as little duplicated | |
159 | compilation as possible. Using the Meson "sourceset" functionality, | |
35a4ca40 | 160 | ``meson.build`` files group the source files in rules that are |
2eba427e PB |
161 | enabled according to the available system libraries and to various |
162 | configuration symbols. Sourcesets belong to one of four groups: | |
163 | ||
164 | Subsystem sourcesets: | |
165 | Various subsystems that are common to both tools and emulators have | |
35a4ca40 PM |
166 | their own sourceset, for example ``block_ss`` for the block device subsystem, |
167 | ``chardev_ss`` for the character device subsystem, etc. These sourcesets | |
2eba427e | 168 | are then turned into static libraries as follows:: |
717171bd | 169 | |
77d27b92 PB |
170 | libchardev = static_library('chardev', chardev_ss.sources(), |
171 | name_suffix: 'fa', | |
172 | build_by_default: false) | |
717171bd | 173 | |
77d27b92 | 174 | chardev = declare_dependency(link_whole: libchardev) |
717171bd | 175 | |
35a4ca40 PM |
176 | As of Meson 0.55.1, the special ``.fa`` suffix should be used for everything |
177 | that is used with ``link_whole``, to ensure that the link flags are placed | |
2eba427e PB |
178 | correctly in the command line. |
179 | ||
180 | Target-independent emulator sourcesets: | |
181 | Various general purpose helper code is compiled only once and | |
182 | the .o files are linked into all output binaries that need it. | |
183 | This includes error handling infrastructure, standard data structures, | |
184 | platform portability wrapper functions, etc. | |
185 | ||
de6cd759 | 186 | Target-independent code lives in the ``common_ss``, ``system_ss`` and |
35a4ca40 | 187 | ``user_ss`` sourcesets. ``common_ss`` is linked into all emulators, |
de6cd759 | 188 | ``system_ss`` only in system emulators, ``user_ss`` only in user-mode |
2eba427e PB |
189 | emulators. |
190 | ||
191 | Target-independent sourcesets must exercise particular care when using | |
35a4ca40 | 192 | ``if_false`` rules. The ``if_false`` rule will be used correctly when linking |
2eba427e | 193 | emulator binaries; however, when *compiling* target-independent files |
35a4ca40 PM |
194 | into .o files, Meson may need to pick *both* the ``if_true`` and |
195 | ``if_false`` sides to cater for targets that want either side. To | |
2eba427e PB |
196 | achieve that, you can add a special rule using the ``CONFIG_ALL`` |
197 | symbol:: | |
198 | ||
199 | # Some targets have CONFIG_ACPI, some don't, so this is not enough | |
de6cd759 | 200 | system_ss.add(when: 'CONFIG_ACPI', if_true: files('acpi.c'), |
2eba427e PB |
201 | if_false: files('acpi-stub.c')) |
202 | ||
203 | # This is required as well: | |
de6cd759 | 204 | system_ss.add(when: 'CONFIG_ALL', if_true: files('acpi-stub.c')) |
2eba427e PB |
205 | |
206 | Target-dependent emulator sourcesets: | |
207 | In the target-dependent set lives CPU emulation, some device emulation and | |
208 | much glue code. This sometimes also has to be compiled multiple times, | |
209 | once for each target being built. Target-dependent files are included | |
35a4ca40 | 210 | in the ``specific_ss`` sourceset. |
2eba427e | 211 | |
35a4ca40 | 212 | Each emulator also includes sources for files in the ``hw/`` and ``target/`` |
2eba427e PB |
213 | subdirectories. The subdirectory used for each emulator comes |
214 | from the target's definition of ``TARGET_BASE_ARCH`` or (if missing) | |
35a4ca40 | 215 | ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``. |
2eba427e | 216 | |
35a4ca40 | 217 | Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary, |
2eba427e PB |
218 | for example:: |
219 | ||
220 | arm_ss = ss.source_set() | |
221 | arm_ss.add(files('boot.c'), fdt) | |
222 | ... | |
223 | hw_arch += {'arm': arm_ss} | |
224 | ||
225 | The sourceset is only used for system emulators. | |
226 | ||
35a4ca40 PM |
227 | Each subdirectory in ``target/`` instead should add one sourceset to each |
228 | of the ``target_arch`` and ``target_softmmu_arch``, which are used respectively | |
2eba427e PB |
229 | for all emulators and for system emulators only. For example:: |
230 | ||
231 | arm_ss = ss.source_set() | |
de6cd759 | 232 | arm_system_ss = ss.source_set() |
2eba427e PB |
233 | ... |
234 | target_arch += {'arm': arm_ss} | |
de6cd759 | 235 | target_softmmu_arch += {'arm': arm_system_ss} |
2eba427e | 236 | |
964711c4 | 237 | Module sourcesets: |
35a4ca40 PM |
238 | There are two dictionaries for modules: ``modules`` is used for |
239 | target-independent modules and ``target_modules`` is used for | |
240 | target-dependent modules. When modules are disabled the ``module`` | |
de6cd759 | 241 | source sets are added to ``system_ss`` and the ``target_modules`` |
35a4ca40 | 242 | source sets are added to ``specific_ss``. |
964711c4 GH |
243 | |
244 | Both dictionaries are nested. One dictionary is created per | |
245 | subdirectory, and these per-subdirectory dictionaries are added to | |
246 | the toplevel dictionaries. For example:: | |
247 | ||
248 | hw_display_modules = {} | |
249 | qxl_ss = ss.source_set() | |
250 | ... | |
251 | hw_display_modules += { 'qxl': qxl_ss } | |
252 | modules += { 'hw-display': hw_display_modules } | |
253 | ||
2eba427e | 254 | Utility sourcesets: |
35a4ca40 | 255 | All binaries link with a static library ``libqemuutil.a``. This library |
2eba427e | 256 | is built from several sourcesets; most of them however host generated |
35a4ca40 | 257 | code, and the only two of general interest are ``util_ss`` and ``stub_ss``. |
2eba427e PB |
258 | |
259 | The separation between these two is purely for documentation purposes. | |
35a4ca40 | 260 | ``util_ss`` contains generic utility files. Even though this code is only |
2eba427e PB |
261 | linked in some binaries, sometimes it requires hooks only in some of |
262 | these and depend on other functions that are not fully implemented by | |
35a4ca40 | 263 | all QEMU binaries. ``stub_ss`` links dummy stubs that will only be linked |
2eba427e PB |
264 | into the binary if the real implementation is not present. In a way, |
265 | the stubs can be thought of as a portable implementation of the weak | |
266 | symbols concept. | |
267 | ||
ebedb37c | 268 | |
77d27b92 PB |
269 | The following files concur in the definition of which files are linked |
270 | into each emulator: | |
ebedb37c | 271 | |
35a4ca40 PM |
272 | ``default-configs/devices/*.mak`` |
273 | The files under ``default-configs/devices/`` control the boards and devices | |
2eba427e PB |
274 | that are built into each QEMU system emulation targets. They merely contain |
275 | a list of config variable definitions such as:: | |
717171bd | 276 | |
a14f0bf1 PB |
277 | include arm-softmmu.mak |
278 | CONFIG_XLNX_ZYNQMP_ARM=y | |
279 | CONFIG_XLNX_VERSAL=y | |
717171bd | 280 | |
35a4ca40 PM |
281 | ``*/Kconfig`` |
282 | These files are processed together with ``default-configs/devices/*.mak`` and | |
a14f0bf1 | 283 | describe the dependencies between various features, subsystems and |
2eba427e PB |
284 | device models. They are described in :ref:`kconfig` |
285 | ||
35a4ca40 PM |
286 | ``default-configs/targets/*.mak`` |
287 | These files mostly define symbols that appear in the ``*-config-target.h`` | |
2eba427e | 288 | file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH`` |
35a4ca40 PM |
289 | and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and |
290 | ``target/`` subdirectories that are compiled into each target. | |
2eba427e | 291 | |
35a4ca40 | 292 | .. [#cfgtarget] This header is included by ``qemu/osdep.h`` when |
2eba427e | 293 | compiling files from the target-specific sourcesets. |
717171bd | 294 | |
2eba427e PB |
295 | These files rarely need changing unless you are adding a completely |
296 | new target, or enabling new devices or hardware for a particular | |
297 | system/userspace emulation target | |
717171bd | 298 | |
77d27b92 | 299 | |
3b4da132 PB |
300 | Adding checks |
301 | ------------- | |
302 | ||
fe3ab4eb | 303 | Compiler checks can be as simple as the following:: |
3b4da132 PB |
304 | |
305 | config_host_data.set('HAVE_BTRFS_H', cc.has_header('linux/btrfs.h')) | |
306 | ||
307 | A more complex task such as adding a new dependency usually | |
308 | comprises the following tasks: | |
309 | ||
310 | - Add a Meson build option to meson_options.txt. | |
311 | ||
312 | - Add code to perform the actual feature check. | |
313 | ||
ca0a0d12 | 314 | - Add code to include the feature status in ``config-host.h`` |
3b4da132 PB |
315 | |
316 | - Add code to print out the feature status in the configure summary | |
317 | upon completion. | |
318 | ||
319 | Taking the probe for SDL2_Image as an example, we have the following | |
320 | in ``meson_options.txt``:: | |
321 | ||
322 | option('sdl_image', type : 'feature', value : 'auto', | |
323 | description: 'SDL Image support for icons') | |
324 | ||
325 | Unless the option was given a non-``auto`` value (on the configure | |
326 | command line), the detection code must be performed only if the | |
327 | dependency will be used:: | |
328 | ||
329 | sdl_image = not_found | |
330 | if not get_option('sdl_image').auto() or have_system | |
331 | sdl_image = dependency('SDL2_image', required: get_option('sdl_image'), | |
a0cbd2e8 | 332 | method: 'pkg-config') |
3b4da132 PB |
333 | endif |
334 | ||
335 | This avoids warnings on static builds of user-mode emulators, for example. | |
336 | Most of the libraries used by system-mode emulators are not available for | |
337 | static linking. | |
338 | ||
339 | The other supporting code is generally simple:: | |
340 | ||
341 | # Create config-host.h (if applicable) | |
342 | config_host_data.set('CONFIG_SDL_IMAGE', sdl_image.found()) | |
343 | ||
344 | # Summary | |
345 | summary_info += {'SDL image support': sdl_image.found()} | |
346 | ||
347 | For the configure script to parse the new option, the | |
348 | ``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make | |
ca0a0d12 | 349 | update-buildoptions`` (or just ``make``) will take care of updating it. |
3b4da132 PB |
350 | |
351 | ||
77d27b92 PB |
352 | Support scripts |
353 | --------------- | |
354 | ||
355 | Meson has a special convention for invoking Python scripts: if their | |
35a4ca40 | 356 | first line is ``#! /usr/bin/env python3`` and the file is *not* executable, |
77d27b92 PB |
357 | find_program() arranges to invoke the script under the same Python |
358 | interpreter that was used to invoke Meson. This is the most common | |
359 | and preferred way to invoke support scripts from Meson build files, | |
360 | because it automatically uses the value of configure's --python= option. | |
717171bd | 361 | |
35a4ca40 | 362 | In case the script is not written in Python, use a ``#! /usr/bin/env ...`` |
77d27b92 | 363 | line and make the script executable. |
717171bd | 364 | |
77d27b92 PB |
365 | Scripts written in Python, where it is desirable to make the script |
366 | executable (for example for test scripts that developers may want to | |
367 | invoke from the command line, such as tests/qapi-schema/test-qapi.py), | |
35a4ca40 | 368 | should be invoked through the ``python`` variable in meson.build. For |
a14f0bf1 | 369 | example:: |
717171bd | 370 | |
77d27b92 PB |
371 | test('QAPI schema regression tests', python, |
372 | args: files('test-qapi.py'), | |
373 | env: test_env, suite: ['qapi-schema', 'qapi-frontend']) | |
717171bd | 374 | |
77d27b92 PB |
375 | This is needed to obey the --python= option passed to the configure |
376 | script, which may point to something other than the first python3 | |
377 | binary on the path. | |
717171bd DB |
378 | |
379 | ||
fe3ab4eb PB |
380 | Stage 3: Make |
381 | ============= | |
77d27b92 | 382 | |
fe3ab4eb PB |
383 | The next step in building QEMU is to invoke make. GNU Make is required |
384 | to build QEMU, and may be installed as ``gmake`` on some hosts. | |
77d27b92 | 385 | |
fe3ab4eb PB |
386 | The output of Meson is a ``build.ninja`` file, which is used with the |
387 | Ninja build tool. However, QEMU's build comprises other components than | |
388 | just the emulators (namely firmware and the tests in ``tests/tcg``) which | |
389 | need different cross compilers. The QEMU Makefile wraps both Ninja and | |
390 | the smaller build systems for firmware and tests; it also takes care of | |
391 | running ``configure`` again when the script changes. Apart from invoking | |
392 | these sub-Makefiles, the resulting build is largely non-recursive. | |
77d27b92 | 393 | |
fe3ab4eb PB |
394 | Tests, whether defined in ``meson.build`` or not, are also ran by the |
395 | Makefile with the traditional ``make check`` phony target, while benchmarks | |
396 | are run with ``make bench``. Meson test suites such as ``unit`` can be ran | |
397 | with ``make check-unit``, and ``make check-tcg`` builds and runs "non-Meson" | |
398 | tests for all targets. | |
399 | ||
400 | If desired, it is also possible to use ``ninja`` and ``meson test``, | |
401 | respectively to build emulators and run tests defined in meson.build. | |
402 | The main difference is that ``make`` needs the ``-jN`` flag in order to | |
403 | enable parallel builds or tests. | |
717171bd | 404 | |
8b8939e4 PB |
405 | Useful make targets |
406 | ------------------- | |
407 | ||
408 | ``help`` | |
409 | Print a help message for the most common build targets. | |
410 | ||
411 | ``print-VAR`` | |
412 | Print the value of the variable VAR. Useful for debugging the build | |
413 | system. | |
414 | ||
fe3ab4eb | 415 | |
77d27b92 PB |
416 | Important files for the build system |
417 | ==================================== | |
418 | ||
717171bd DB |
419 | Statically defined files |
420 | ------------------------ | |
421 | ||
422 | The following key files are statically defined in the source tree, with | |
423 | the rules needed to build QEMU. Their behaviour is influenced by a | |
424 | number of dynamically created files listed later. | |
425 | ||
35a4ca40 | 426 | ``Makefile`` |
a14f0bf1 PB |
427 | The main entry point used when invoking make to build all the components |
428 | of QEMU. The default 'all' target will naturally result in the build of | |
fe3ab4eb | 429 | every component. |
a14f0bf1 | 430 | |
35a4ca40 | 431 | ``*/meson.build`` |
a14f0bf1 PB |
432 | The meson.build file in the root directory is the main entry point for the |
433 | Meson build system, and it coordinates the configuration and build of all | |
434 | executables. Build rules for various subdirectories are included in | |
435 | other meson.build files spread throughout the QEMU source tree. | |
436 | ||
35a4ca40 | 437 | ``tests/Makefile.include`` |
fe3ab4eb PB |
438 | Rules for external test harnesses. These include the TCG tests |
439 | and the Avocado-based integration tests. | |
a14f0bf1 | 440 | |
35a4ca40 | 441 | ``tests/docker/Makefile.include`` |
fe3ab4eb PB |
442 | Rules for Docker tests. Like ``tests/Makefile.include``, this file is |
443 | included directly by the top level Makefile, anything defined in this | |
444 | file will influence the entire build system. | |
a14f0bf1 | 445 | |
35a4ca40 | 446 | ``tests/vm/Makefile.include`` |
fe3ab4eb PB |
447 | Rules for VM-based tests. Like ``tests/Makefile.include``, this file is |
448 | included directly by the top level Makefile, anything defined in this | |
449 | file will influence the entire build system. | |
717171bd DB |
450 | |
451 | Dynamically created files | |
452 | ------------------------- | |
453 | ||
fe3ab4eb PB |
454 | The following files are generated at run-time in order to control the |
455 | behaviour of the Makefiles. This avoids the need for QEMU makefiles to | |
456 | go through any pre-processing as seen with autotools, where configure | |
457 | generates ``Makefile`` from ``Makefile.in``. | |
717171bd | 458 | |
77d27b92 | 459 | Built by configure: |
717171bd | 460 | |
35a4ca40 | 461 | ``config-host.mak`` |
a14f0bf1 | 462 | When configure has determined the characteristics of the build host it |
fe3ab4eb PB |
463 | will write them to this file for use in ``Makefile`` and to a smaller |
464 | extent ``meson.build``. These include the paths to various tools and a | |
35a4ca40 | 465 | variety of ``CONFIG_*`` variables related to optionally enabled features. |
717171bd | 466 | |
fe3ab4eb | 467 | ``config-host.mak`` is also used as a dependency checking mechanism. If make |
a14f0bf1 | 468 | sees that the modification timestamp on configure is newer than that on |
fe3ab4eb PB |
469 | ``config-host.mak``, then configure will be re-run. |
470 | ||
471 | The variables defined here apply to all QEMU | |
472 | build outputs. | |
473 | ||
474 | ``config-meson.cross`` | |
475 | ||
476 | A Meson "cross file" (or native file) used to communicate the paths to | |
477 | the toolchain and other configuration options. | |
478 | ||
479 | ``config.status`` | |
717171bd | 480 | |
fe3ab4eb PB |
481 | A small shell script that will invoke configure again with the same |
482 | environment variables that were set during the first run. It's used to | |
483 | rerun configure after changes to the source code, but it can also be | |
484 | inspected manually to check the contents of the environment. | |
717171bd | 485 | |
fe3ab4eb PB |
486 | ``Makefile.prereqs`` |
487 | ||
488 | A set of Makefile dependencies that order the build and execution of | |
489 | firmware and tests after the container images and emulators that they | |
490 | need. | |
491 | ||
492 | ``pc-bios/*/config.mak``, ``tests/tcg/config-host.mak``, ``tests/tcg/*/config-target.mak`` | |
493 | ||
494 | Configuration variables used to build the firmware and TCG tests, | |
495 | including paths to cross compilation toolchains. | |
496 | ||
497 | ``pyvenv`` | |
498 | ||
499 | A Python virtual environment that is used for all Python code running | |
500 | during the build. Using a virtual environment ensures that even code | |
501 | that is run via ``sphinx-build``, ``meson`` etc. uses the same interpreter | |
502 | and packages. | |
717171bd | 503 | |
77d27b92 PB |
504 | Built by Meson: |
505 | ||
fe3ab4eb PB |
506 | ``config-host.h`` |
507 | Used by C code to determine the properties of the build environment | |
508 | and the set of enabled features for the entire build. | |
509 | ||
35a4ca40 | 510 | ``${TARGET-NAME}-config-devices.mak`` |
fe3ab4eb PB |
511 | TARGET-NAME is the name of a system emulator. The file is |
512 | generated by Meson using files under ``configs/devices`` as input. | |
513 | ||
514 | ``${TARGET-NAME}-config-target.mak`` | |
515 | TARGET-NAME is the name of a system or usermode emulator. The file is | |
516 | generated by Meson using files under ``configs/targets`` as input. | |
517 | ||
518 | ``$TARGET_NAME-config-target.h``, ``$TARGET_NAME-config-devices.h`` | |
519 | Used by C code to determine the properties and enabled | |
520 | features for each target. enabled. They are generated from | |
521 | the contents of the corresponding ``*.mak`` files using Meson's | |
522 | ``configure_file()`` function; each target can include them using | |
523 | the ``CONFIG_TARGET`` and ``CONFIG_DEVICES`` macro respectively. | |
77d27b92 | 524 | |
35a4ca40 | 525 | ``build.ninja`` |
a14f0bf1 | 526 | The build rules. |
77d27b92 PB |
527 | |
528 | ||
529 | Built by Makefile: | |
530 | ||
35a4ca40 | 531 | ``Makefile.ninja`` |
09e93326 PB |
532 | A Makefile include that bridges to ninja for the actual build. The |
533 | Makefile is mostly a list of targets that Meson included in build.ninja. | |
77d27b92 | 534 | |
35a4ca40 | 535 | ``Makefile.mtest`` |
a14f0bf1 PB |
536 | The Makefile definitions that let "make check" run tests defined in |
537 | meson.build. The rules are produced from Meson's JSON description of | |
538 | tests (obtained with "meson introspect --tests") through the script | |
539 | scripts/mtest2make.py. |