linux-user: Add support for btrfs ioctls used to manage quota
[qemu.git] / docs / devel / build-system.rst
1 ==================================
2 The QEMU build system architecture
3 ==================================
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
7 system has two stages, first the developer runs the "configure" script
8 to determine the local build environment characteristics, then they run
9 "make" to build the project. There is about where the similarities with
10 GNU autotools end, so try to forget what you know about them.
11
12
13 Stage 1: configure
14 ==================
15
16 The QEMU configure script is written directly in shell, and should be
17 compatible with any POSIX shell, hence it uses #!/bin/sh. An important
18 implication of this is that it is important to avoid using bash-isms on
19 development platforms where bash is the primary host.
20
21 In contrast to autoconf scripts, QEMU's configure is expected to be
22 silent while it is checking for features. It will only display output
23 when an error occurs, or to show the final feature enablement summary
24 on completion.
25
26 Because QEMU uses the Meson build system under the hood, only VPATH
27 builds are supported.  There are two general ways to invoke configure &
28 perform 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
45 For now, checks on the compilation environment are found in configure
46 rather than meson.build, though this is expected to change.  The command
47 line is parsed in the configure script and, whenever needed, converted
48 into the appropriate options to Meson.
49
50 New checks should be added to Meson, which usually comprises the
51 following tasks:
52
53  - Add a Meson build option to meson_options.txt.
54
55  - Add support to the command line arg parser to handle any new
56    `--enable-XXX`/`--disable-XXX` flags required by the feature.
57
58  - Add information to the help output message to report on the new
59    feature flag.
60
61  - Add code to perform the actual feature check.
62
63  - Add code to include the feature status in `config-host.h`
64
65  - Add code to print out the feature status in the configure summary
66    upon completion.
67
68
69 Taking the probe for SDL2_Image as an example, we have the following pieces
70 in configure::
71
72   # Initial variable state
73   sdl_image=auto
74
75   ..snip..
76
77   # Configure flag processing
78   --disable-sdl-image) sdl_image=disabled
79   ;;
80   --enable-sdl-image) sdl_image=enabled
81   ;;
82
83   ..snip..
84
85   # Help output feature message
86   sdl-image         SDL Image support for icons
87
88   ..snip..
89
90   # Meson invocation
91   -Dsdl_image=$sdl_image
92
93 In meson_options.txt::
94
95   option('sdl', type : 'feature', value : 'auto',
96          description: 'SDL Image support for icons')
97
98 In meson.build::
99
100   # Detect dependency
101   sdl_image = dependency('SDL2_image', required: get_option('sdl_image'),
102                          method: 'pkg-config',
103                          static: enable_static)
104
105   # Create config-host.h (if applicable)
106   config_host_data.set('CONFIG_SDL_IMAGE', sdl_image.found())
107
108   # Summary
109   summary_info += {'SDL image support': sdl_image.found()}
110
111
112
113 Helper functions
114 ----------------
115
116 The configure script provides a variety of helper functions to assist
117 developers in checking for system features:
118
119 `do_cc $ARGS...`
120    Attempt to run the system C compiler passing it $ARGS...
121
122 `do_cxx $ARGS...`
123    Attempt to run the system C++ compiler passing it $ARGS...
124
125 `compile_object $CFLAGS`
126    Attempt to compile a test program with the system C compiler using
127    $CFLAGS. The test program must have been previously written to a file
128    called $TMPC.
129
130 `compile_prog $CFLAGS $LDFLAGS`
131    Attempt to compile a test program with the system C compiler using
132    $CFLAGS and link it with the system linker using $LDFLAGS. The test
133    program must have been previously written to a file called $TMPC.
134
135 `has $COMMAND`
136    Determine if $COMMAND exists in the current environment, either as a
137    shell builtin, or executable binary, returning 0 on success.
138
139 `path_of $COMMAND`
140    Return the fully qualified path of $COMMAND, printing it to stdout,
141    and returning 0 on success.
142
143 `check_define $NAME`
144    Determine if the macro $NAME is defined by the system C compiler
145
146 `check_include $NAME`
147    Determine if the include $NAME file is available to the system C
148    compiler
149
150 `write_c_skeleton`
151    Write a minimal C program main() function to the temporary file
152    indicated by $TMPC
153
154 `feature_not_found $NAME $REMEDY`
155    Print a message to stderr that the feature $NAME was not available
156    on the system, suggesting the user try $REMEDY to address the
157    problem.
158
159 `error_exit $MESSAGE $MORE...`
160    Print $MESSAGE to stderr, followed by $MORE... and then exit from the
161    configure script with non-zero status
162
163 `query_pkg_config $ARGS...`
164    Run pkg-config passing it $ARGS. If QEMU is doing a static build,
165    then --static will be automatically added to $ARGS
166
167
168 Stage 2: Meson
169 ==============
170
171 The Meson build system is currently used to describe the build
172 process for:
173
174 1) executables, which include:
175
176    - Tools - qemu-img, qemu-nbd, qga (guest agent), etc
177
178    - System emulators - qemu-system-$ARCH
179
180    - Userspace emulators - qemu-$ARCH
181
182    - Some (but not all) unit tests
183
184 2) documentation
185
186 3) ROMs, which can be either installed as binary blobs or compiled
187
188 4) other data files, such as icons or desktop files
189
190 The source code is highly modularized, split across many files to
191 facilitate building of all of these components with as little duplicated
192 compilation as possible. The Meson "sourceset" functionality is used
193 to list the files and their dependency on various configuration  
194 symbols.
195
196 Various subsystems that are common to both tools and emulators have
197 their own sourceset, for example `block_ss` for the block device subsystem,
198 `chardev_ss` for the character device subsystem, etc.  These sourcesets
199 are then turned into static libraries as follows::
200
201     libchardev = static_library('chardev', chardev_ss.sources(),
202                                 name_suffix: 'fa',
203                                 build_by_default: false)
204
205     chardev = declare_dependency(link_whole: libchardev)
206
207 The special `.fa` suffix is needed as long as unit tests are built with
208 the older Makefile infrastructure, and will go away later.
209
210 Files linked into emulator targets there can be split into two distinct groups
211 of files, those which are independent of the QEMU emulation target and
212 those which are dependent on the QEMU emulation target.
213
214 In the target-independent set lives various general purpose helper code,
215 such as error handling infrastructure, standard data structures,
216 platform portability wrapper functions, etc. This code can be compiled
217 once only and the .o files linked into all output binaries.
218 Target-independent code lives in the `common_ss`, `softmmu_ss` and
219 `user_ss` sourcesets.  `common_ss` is linked into all emulators, `softmmu_ss`
220 only in system emulators, `user_ss` only in user-mode emulators.
221
222 In the target-dependent set lives CPU emulation, device emulation and
223 much glue code. This sometimes also has to be compiled multiple times,
224 once for each target being built.
225
226 All binaries link with a static library `libqemuutil.a`, which is then
227 linked to all the binaries.  `libqemuutil.a` is built from several
228 sourcesets; most of them however host generated code, and the only two
229 of general interest are `util_ss` and `stub_ss`.
230
231 The separation between these two is purely for documentation purposes.
232 `util_ss` contains generic utility files.  Even though this code is only
233 linked in some binaries, sometimes it requires hooks only in some of
234 these and depend on other functions that are not fully implemented by
235 all QEMU binaries.  `stub_ss` links dummy stubs that will only be linked
236 into the binary if the real implementation is not present.  In a way,
237 the stubs can be thought of as a portable implementation of the weak
238 symbols concept.
239
240 The following files concur in the definition of which files are linked
241 into each emulator:
242
243 `default-configs/*.mak`
244   The files under default-configs/ control what emulated hardware is built
245   into each QEMU system and userspace emulator targets. They merely contain
246   a list of config variable definitions like the machines that should be
247   included. For example, default-configs/aarch64-softmmu.mak has::
248
249     include arm-softmmu.mak
250     CONFIG_XLNX_ZYNQMP_ARM=y
251     CONFIG_XLNX_VERSAL=y
252
253 `*/Kconfig`
254   These files are processed together with `default-configs/*.mak` and
255   describe the dependencies between various features, subsystems and
256   device models.  They are described in kconfig.rst.
257
258 These files rarely need changing unless new devices / hardware need to
259 be enabled for a particular system/userspace emulation target
260
261
262 Support scripts
263 ---------------
264
265 Meson has a special convention for invoking Python scripts: if their
266 first line is `#! /usr/bin/env python3` and the file is *not* executable,
267 find_program() arranges to invoke the script under the same Python
268 interpreter that was used to invoke Meson.  This is the most common
269 and preferred way to invoke support scripts from Meson build files,
270 because it automatically uses the value of configure's --python= option.
271
272 In case the script is not written in Python, use a `#! /usr/bin/env ...`
273 line and make the script executable.
274
275 Scripts written in Python, where it is desirable to make the script
276 executable (for example for test scripts that developers may want to
277 invoke from the command line, such as tests/qapi-schema/test-qapi.py),
278 should be invoked through the `python` variable in meson.build. For
279 example::
280
281   test('QAPI schema regression tests', python,
282        args: files('test-qapi.py'),
283        env: test_env, suite: ['qapi-schema', 'qapi-frontend'])
284
285 This is needed to obey the --python= option passed to the configure
286 script, which may point to something other than the first python3
287 binary on the path.
288
289
290 Stage 3: makefiles
291 ==================
292
293 The use of GNU make is required with the QEMU build system.
294
295 The output of Meson is a build.ninja file, which is used with the Ninja
296 build system.  QEMU uses a different approach, where Makefile rules are
297 synthesized from the build.ninja file.  The main Makefile includes these
298 rules and wraps them so that e.g. submodules are built before QEMU.
299 The resulting build system is largely non-recursive in nature, in
300 contrast to common practices seen with automake.
301
302 Tests are also ran by the Makefile with the traditional `make check`
303 phony target.  Meson test suites such as `unit` can be ran with `make
304 check-unit` too.  It is also possible to run tests defined in meson.build
305 with `meson test`.
306
307 The following text is only relevant for unit tests which still have to
308 be converted to Meson.
309
310 All binaries should link to `libqemuutil.a`, e.g.:
311
312    qemu-img$(EXESUF): qemu-img.o ..snip.. libqemuutil.a
313
314 On Windows, all binaries have the suffix `.exe`, so all Makefile rules
315 which create binaries must include the $(EXESUF) variable on the binary
316 name. e.g.
317
318    qemu-img$(EXESUF): qemu-img.o ..snip..
319
320 This expands to `.exe` on Windows, or an empty string on other platforms.
321
322 Variable naming
323 ---------------
324
325 The QEMU convention is to define variables to list different groups of
326 object files. These are named with the convention $PREFIX-obj-y.  The
327 Meson `chardev` variable in the previous example corresponds to a
328 variable 'chardev-obj-y'.
329
330 Likewise, tests that are executed by `make check-unit` are grouped into
331 a variable check-unit-y, like this:
332
333   check-unit-y += tests/test-visitor-serialization$(EXESUF)
334   check-unit-y += tests/test-iov$(EXESUF)
335   check-unit-y += tests/test-bitmap$(EXESUF)
336
337 When a test or object file which needs to be conditionally built based
338 on some characteristic of the host system, the configure script will
339 define a variable for the conditional. For example, on Windows it will
340 define $(CONFIG_POSIX) with a value of 'n' and $(CONFIG_WIN32) with a
341 value of 'y'. It is now possible to use the config variables when
342 listing object files. For example,
343
344   check-unit-$(CONFIG_POSIX) += tests/test-vmstate$(EXESUF)
345
346 On Windows this expands to
347
348   check-unit-n += tests/vmstate.exe
349
350 Since the `check-unit` target only runs tests included in `$(check-unit-y)`,
351 POSIX specific tests listed in `$(util-obj-n)` are ignored on the Windows
352 platform builds.
353
354
355 CFLAGS / LDFLAGS / LIBS handling
356 --------------------------------
357
358 There are many different binaries being built with differing purposes,
359 and some of them might even be 3rd party libraries pulled in via git
360 submodules. As such the use of the global CFLAGS variable is generally
361 avoided in QEMU, since it would apply to too many build targets.
362
363 Flags that are needed by any QEMU code (i.e. everything *except* GIT
364 submodule projects) are put in $(QEMU_CFLAGS) variable. For linker
365 flags the $(LIBS) variable is sometimes used, but a couple of more
366 targeted variables are preferred.
367
368 In addition to these variables, it is possible to provide cflags and
369 libs against individual source code files, by defining variables of the
370 form $FILENAME-cflags and $FILENAME-libs. For example, the test
371 test-crypto-tlscredsx509 needs to link to the libtasn1 library,
372 so tests/Makefile.include defines some variables:
373
374   tests/crypto-tls-x509-helpers.o-cflags := $(TASN1_CFLAGS)
375   tests/crypto-tls-x509-helpers.o-libs := $(TASN1_LIBS)
376
377 The scope is a little different between the two variables. The libs get
378 used when linking any target binary that includes the curl.o object
379 file, while the cflags get used when compiling the curl.c file only.
380
381
382 Important files for the build system
383 ====================================
384
385 Statically defined files
386 ------------------------
387
388 The following key files are statically defined in the source tree, with
389 the rules needed to build QEMU. Their behaviour is influenced by a
390 number of dynamically created files listed later.
391
392 `Makefile`
393   The main entry point used when invoking make to build all the components
394   of QEMU. The default 'all' target will naturally result in the build of
395   every component. Makefile takes care of recursively building submodules
396   directly via a non-recursive set of rules.
397
398 `*/meson.build`
399   The meson.build file in the root directory is the main entry point for the
400   Meson build system, and it coordinates the configuration and build of all
401   executables.  Build rules for various subdirectories are included in
402   other meson.build files spread throughout the QEMU source tree.
403
404 `rules.mak`
405   This file provides the generic helper rules for invoking build tools, in
406   particular the compiler and linker.
407
408 `tests/Makefile.include`
409   Rules for building the unit tests. This file is included directly by the
410   top level Makefile, so anything defined in this file will influence the
411   entire build system. Care needs to be taken when writing rules for tests
412   to ensure they only apply to the unit test execution / build.
413
414 `tests/docker/Makefile.include`
415   Rules for Docker tests. Like tests/Makefile, this file is included
416   directly by the top level Makefile, anything defined in this file will
417   influence the entire build system.
418
419 `tests/vm/Makefile.include`
420   Rules for VM-based tests. Like tests/Makefile, this file is included
421   directly by the top level Makefile, anything defined in this file will
422   influence the entire build system.
423
424 Dynamically created files
425 -------------------------
426
427 The following files are generated dynamically by configure in order to
428 control the behaviour of the statically defined makefiles. This avoids
429 the need for QEMU makefiles to go through any pre-processing as seen
430 with autotools, where Makefile.am generates Makefile.in which generates
431 Makefile.
432
433 Built by configure:
434
435 `config-host.mak`
436   When configure has determined the characteristics of the build host it
437   will write a long list of variables to config-host.mak file. This
438   provides the various install directories, compiler / linker flags and a
439   variety of `CONFIG_*` variables related to optionally enabled features.
440   This is imported by the top level Makefile and meson.build in order to
441   tailor the build output.
442
443   config-host.mak is also used as a dependency checking mechanism. If make
444   sees that the modification timestamp on configure is newer than that on
445   config-host.mak, then configure will be re-run.
446
447   The variables defined here are those which are applicable to all QEMU
448   build outputs. Variables which are potentially different for each
449   emulator target are defined by the next file...
450
451 `$TARGET-NAME/config-target.mak`
452   TARGET-NAME is the name of a system or userspace emulator, for example,
453   x86_64-softmmu denotes the system emulator for the x86_64 architecture.
454   This file contains the variables which need to vary on a per-target
455   basis. For example, it will indicate whether KVM or Xen are enabled for
456   the target and any other potential custom libraries needed for linking
457   the target.
458
459
460 Built by Meson:
461
462 `${TARGET-NAME}-config-devices.mak`
463   TARGET-NAME is again the name of a system or userspace emulator. The
464   config-devices.mak file is automatically generated by make using the
465   scripts/make_device_config.sh program, feeding it the
466   default-configs/$TARGET-NAME file as input.
467
468 `config-host.h`, `$TARGET-NAME/config-target.h`, `$TARGET-NAME/config-devices.h`
469   These files are used by source code to determine what features
470   are enabled.  They are generated from the contents of the corresponding
471   `*.h` files using the scripts/create_config program. This extracts
472   relevant variables and formats them as C preprocessor macros.
473
474 `build.ninja`
475   The build rules.
476
477
478 Built by Makefile:
479
480 `Makefile.ninja`
481   A Makefile conversion of the build rules in build.ninja.  The conversion
482   is straightforward and, were it necessary to debug the rules produced
483   by Meson, it should be enough to look at build.ninja.  The conversion
484   is performed by scripts/ninjatool.py.
485
486 `Makefile.mtest`
487   The Makefile definitions that let "make check" run tests defined in
488   meson.build.  The rules are produced from Meson's JSON description of
489   tests (obtained with "meson introspect --tests") through the script
490   scripts/mtest2make.py.
491
492
493 Useful make targets
494 -------------------
495
496 `help`
497   Print a help message for the most common build targets.
498
499 `print-VAR`
500   Print the value of the variable VAR. Useful for debugging the build
501   system.