Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 1 | ================================== |
| 2 | The QEMU build system architecture |
| 3 | ================================== |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 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 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 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 | |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 30 | - VPATH, build artifacts outside of QEMU source tree entirely:: |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 31 | |
| 32 | cd ../ |
| 33 | mkdir build |
| 34 | cd build |
| 35 | ../qemu/configure |
| 36 | make |
| 37 | |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 38 | - VPATH, build artifacts in a subdir of QEMU source tree:: |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 39 | |
| 40 | mkdir build |
| 41 | cd build |
| 42 | ../configure |
| 43 | make |
| 44 | |
Paolo Bonzini | 3b4da13 | 2021-10-07 15:08:29 +0200 | [diff] [blame] | 45 | The configure script automatically recognizes |
| 46 | command line options for which a same-named Meson option exists; |
| 47 | dashes in the command line are replaced with underscores. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 48 | |
Paolo Bonzini | 3b4da13 | 2021-10-07 15:08:29 +0200 | [diff] [blame] | 49 | Many checks on the compilation environment are still found in configure |
John Snow | ca0a0d1 | 2021-10-04 17:52:37 -0400 | [diff] [blame] | 50 | rather than ``meson.build``, but new checks should be added directly to |
| 51 | ``meson.build``. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 52 | |
Paolo Bonzini | 3b4da13 | 2021-10-07 15:08:29 +0200 | [diff] [blame] | 53 | Patches are also welcome to move existing checks from the configure |
John Snow | ca0a0d1 | 2021-10-04 17:52:37 -0400 | [diff] [blame] | 54 | phase to ``meson.build``. When doing so, ensure that ``meson.build`` does |
| 55 | not use anymore the keys that you have removed from ``config-host.mak``. |
| 56 | Typically these will be replaced in ``meson.build`` by boolean variables, |
| 57 | ``get_option('optname')`` invocations, or ``dep.found()`` expressions. |
Paolo Bonzini | 3b4da13 | 2021-10-07 15:08:29 +0200 | [diff] [blame] | 58 | In general, the remaining checks have little or no interdependencies, |
| 59 | so they can be moved one by one. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 60 | |
| 61 | Helper functions |
| 62 | ---------------- |
| 63 | |
| 64 | The configure script provides a variety of helper functions to assist |
| 65 | developers in checking for system features: |
| 66 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 67 | ``do_cc $ARGS...`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 68 | Attempt to run the system C compiler passing it $ARGS... |
| 69 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 70 | ``do_cxx $ARGS...`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 71 | Attempt to run the system C++ compiler passing it $ARGS... |
| 72 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 73 | ``compile_object $CFLAGS`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 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 |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 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()``. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 79 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 80 | ``compile_prog $CFLAGS $LDFLAGS`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 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. |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 84 | The replacement in Meson is ``cc.find_library()`` and ``cc.links()``. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 85 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 86 | ``has $COMMAND`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 87 | Determine if $COMMAND exists in the current environment, either as a |
Paolo Bonzini | 738aa60 | 2020-09-01 06:38:25 -0400 | [diff] [blame] | 88 | shell builtin, or executable binary, returning 0 on success. The |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 89 | replacement in Meson is ``find_program()``. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 90 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 91 | ``check_define $NAME`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 92 | Determine if the macro $NAME is defined by the system C compiler |
| 93 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 94 | ``check_include $NAME`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 95 | Determine if the include $NAME file is available to the system C |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 96 | compiler. The replacement in Meson is ``cc.has_header()``. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 97 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 98 | ``write_c_skeleton`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 99 | Write a minimal C program main() function to the temporary file |
| 100 | indicated by $TMPC |
| 101 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 102 | ``feature_not_found $NAME $REMEDY`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 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 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 107 | ``error_exit $MESSAGE $MORE...`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 108 | Print $MESSAGE to stderr, followed by $MORE... and then exit from the |
| 109 | configure script with non-zero status |
| 110 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 111 | ``query_pkg_config $ARGS...`` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 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 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 116 | Stage 2: Meson |
| 117 | ============== |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 118 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 119 | The Meson build system is currently used to describe the build |
| 120 | process for: |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 121 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 122 | 1) executables, which include: |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 123 | |
Philippe Mathieu-Daudé | c5ba621 | 2021-11-18 20:27:44 +0100 | [diff] [blame] | 124 | - Tools - ``qemu-img``, ``qemu-nbd``, ``qga`` (guest agent), etc |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 125 | |
Philippe Mathieu-Daudé | c5ba621 | 2021-11-18 20:27:44 +0100 | [diff] [blame] | 126 | - System emulators - ``qemu-system-$ARCH`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 127 | |
Philippe Mathieu-Daudé | c5ba621 | 2021-11-18 20:27:44 +0100 | [diff] [blame] | 128 | - Userspace emulators - ``qemu-$ARCH`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 129 | |
Paolo Bonzini | ef6a0d6 | 2020-09-07 18:39:13 +0200 | [diff] [blame] | 130 | - Unit tests |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 131 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 132 | 2) documentation |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 133 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 134 | 3) ROMs, which can be either installed as binary blobs or compiled |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 135 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 136 | 4) other data files, such as icons or desktop files |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 137 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 138 | All executables are built by default, except for some ``contrib/`` |
Paolo Bonzini | 27d551c | 2020-09-11 13:12:11 +0200 | [diff] [blame] | 139 | binaries that are known to fail to build on some platforms (for example |
| 140 | 32-bit or big-endian platforms). Tests are also built by default, |
| 141 | though that might change in the future. |
| 142 | |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 143 | The source code is highly modularized, split across many files to |
| 144 | facilitate building of all of these components with as little duplicated |
| 145 | compilation as possible. Using the Meson "sourceset" functionality, |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 146 | ``meson.build`` files group the source files in rules that are |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 147 | enabled according to the available system libraries and to various |
| 148 | configuration symbols. Sourcesets belong to one of four groups: |
| 149 | |
| 150 | Subsystem sourcesets: |
| 151 | Various subsystems that are common to both tools and emulators have |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 152 | their own sourceset, for example ``block_ss`` for the block device subsystem, |
| 153 | ``chardev_ss`` for the character device subsystem, etc. These sourcesets |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 154 | are then turned into static libraries as follows:: |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 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 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 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 |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 164 | correctly in the command line. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 165 | |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 166 | Target-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. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 171 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 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 |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 175 | emulators. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 176 | |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 177 | Target-independent sourcesets must exercise particular care when using |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 178 | ``if_false`` rules. The ``if_false`` rule will be used correctly when linking |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 179 | emulator binaries; however, when *compiling* target-independent files |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 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 |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 182 | achieve that, you can add a special rule using the ``CONFIG_ALL`` |
| 183 | symbol:: |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 184 | |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 185 | # Some targets have CONFIG_ACPI, some don't, so this is not enough |
Peter Maydell | d463f3c | 2021-07-26 15:23:30 +0100 | [diff] [blame] | 186 | softmmu_ss.add(when: 'CONFIG_ACPI', if_true: files('acpi.c'), |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 187 | if_false: files('acpi-stub.c')) |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 188 | |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 189 | # This is required as well: |
Peter Maydell | d463f3c | 2021-07-26 15:23:30 +0100 | [diff] [blame] | 190 | softmmu_ss.add(when: 'CONFIG_ALL', if_true: files('acpi-stub.c')) |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 191 | |
| 192 | Target-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 Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 196 | in the ``specific_ss`` sourceset. |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 197 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 198 | Each emulator also includes sources for files in the ``hw/`` and ``target/`` |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 199 | subdirectories. The subdirectory used for each emulator comes |
| 200 | from the target's definition of ``TARGET_BASE_ARCH`` or (if missing) |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 201 | ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``. |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 202 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 203 | Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary, |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 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 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 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 |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 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 | |
Gerd Hoffmann | 964711c | 2021-06-24 12:38:23 +0200 | [diff] [blame] | 223 | Module sourcesets: |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 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``. |
Gerd Hoffmann | 964711c | 2021-06-24 12:38:23 +0200 | [diff] [blame] | 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 | |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 240 | Utility sourcesets: |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 241 | All binaries link with a static library ``libqemuutil.a``. This library |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 242 | is built from several sourcesets; most of them however host generated |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 243 | code, and the only two of general interest are ``util_ss`` and ``stub_ss``. |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 244 | |
| 245 | The separation between these two is purely for documentation purposes. |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 246 | ``util_ss`` contains generic utility files. Even though this code is only |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 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 |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 249 | all QEMU binaries. ``stub_ss`` links dummy stubs that will only be linked |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 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 | |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 254 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 255 | The following files concur in the definition of which files are linked |
| 256 | into each emulator: |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 257 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 258 | ``default-configs/devices/*.mak`` |
| 259 | The files under ``default-configs/devices/`` control the boards and devices |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 260 | that are built into each QEMU system emulation targets. They merely contain |
| 261 | a list of config variable definitions such as:: |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 262 | |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 263 | include arm-softmmu.mak |
| 264 | CONFIG_XLNX_ZYNQMP_ARM=y |
| 265 | CONFIG_XLNX_VERSAL=y |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 266 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 267 | ``*/Kconfig`` |
| 268 | These files are processed together with ``default-configs/devices/*.mak`` and |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 269 | describe the dependencies between various features, subsystems and |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 270 | device models. They are described in :ref:`kconfig` |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 271 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 272 | ``default-configs/targets/*.mak`` |
| 273 | These files mostly define symbols that appear in the ``*-config-target.h`` |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 274 | file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH`` |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 275 | and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and |
| 276 | ``target/`` subdirectories that are compiled into each target. |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 277 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 278 | .. [#cfgtarget] This header is included by ``qemu/osdep.h`` when |
Paolo Bonzini | 2eba427 | 2020-10-29 13:06:09 +0100 | [diff] [blame] | 279 | compiling files from the target-specific sourcesets. |
| 280 | |
| 281 | These files rarely need changing unless you are adding a completely |
| 282 | new target, or enabling new devices or hardware for a particular |
| 283 | system/userspace emulation target |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 284 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 285 | |
Paolo Bonzini | 3b4da13 | 2021-10-07 15:08:29 +0200 | [diff] [blame] | 286 | Adding checks |
| 287 | ------------- |
| 288 | |
| 289 | New checks should be added to Meson. Compiler checks can be as simple as |
| 290 | the following:: |
| 291 | |
| 292 | config_host_data.set('HAVE_BTRFS_H', cc.has_header('linux/btrfs.h')) |
| 293 | |
| 294 | A more complex task such as adding a new dependency usually |
| 295 | comprises 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 Snow | ca0a0d1 | 2021-10-04 17:52:37 -0400 | [diff] [blame] | 301 | - Add code to include the feature status in ``config-host.h`` |
Paolo Bonzini | 3b4da13 | 2021-10-07 15:08:29 +0200 | [diff] [blame] | 302 | |
| 303 | - Add code to print out the feature status in the configure summary |
| 304 | upon completion. |
| 305 | |
| 306 | Taking the probe for SDL2_Image as an example, we have the following |
| 307 | in ``meson_options.txt``:: |
| 308 | |
| 309 | option('sdl_image', type : 'feature', value : 'auto', |
| 310 | description: 'SDL Image support for icons') |
| 311 | |
| 312 | Unless the option was given a non-``auto`` value (on the configure |
| 313 | command line), the detection code must be performed only if the |
| 314 | dependency 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 | |
| 323 | This avoids warnings on static builds of user-mode emulators, for example. |
| 324 | Most of the libraries used by system-mode emulators are not available for |
| 325 | static linking. |
| 326 | |
| 327 | The 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 | |
| 335 | For the configure script to parse the new option, the |
| 336 | ``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make |
John Snow | ca0a0d1 | 2021-10-04 17:52:37 -0400 | [diff] [blame] | 337 | update-buildoptions`` (or just ``make``) will take care of updating it. |
Paolo Bonzini | 3b4da13 | 2021-10-07 15:08:29 +0200 | [diff] [blame] | 338 | |
| 339 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 340 | Support scripts |
| 341 | --------------- |
| 342 | |
| 343 | Meson has a special convention for invoking Python scripts: if their |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 344 | first line is ``#! /usr/bin/env python3`` and the file is *not* executable, |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 345 | find_program() arranges to invoke the script under the same Python |
| 346 | interpreter that was used to invoke Meson. This is the most common |
| 347 | and preferred way to invoke support scripts from Meson build files, |
| 348 | because it automatically uses the value of configure's --python= option. |
| 349 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 350 | In case the script is not written in Python, use a ``#! /usr/bin/env ...`` |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 351 | line and make the script executable. |
| 352 | |
| 353 | Scripts written in Python, where it is desirable to make the script |
| 354 | executable (for example for test scripts that developers may want to |
| 355 | invoke from the command line, such as tests/qapi-schema/test-qapi.py), |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 356 | should be invoked through the ``python`` variable in meson.build. For |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 357 | example:: |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 358 | |
| 359 | test('QAPI schema regression tests', python, |
| 360 | args: files('test-qapi.py'), |
| 361 | env: test_env, suite: ['qapi-schema', 'qapi-frontend']) |
| 362 | |
| 363 | This is needed to obey the --python= option passed to the configure |
| 364 | script, which may point to something other than the first python3 |
| 365 | binary on the path. |
| 366 | |
| 367 | |
| 368 | Stage 3: makefiles |
| 369 | ================== |
| 370 | |
| 371 | The use of GNU make is required with the QEMU build system. |
| 372 | |
| 373 | The output of Meson is a build.ninja file, which is used with the Ninja |
| 374 | build system. QEMU uses a different approach, where Makefile rules are |
| 375 | synthesized from the build.ninja file. The main Makefile includes these |
| 376 | rules and wraps them so that e.g. submodules are built before QEMU. |
| 377 | The resulting build system is largely non-recursive in nature, in |
| 378 | contrast to common practices seen with automake. |
| 379 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 380 | Tests are also ran by the Makefile with the traditional ``make check`` |
| 381 | phony target, while benchmarks are run with ``make bench``. Meson test |
| 382 | suites such as ``unit`` can be ran with ``make check-unit`` too. It is also |
| 383 | possible to run tests defined in meson.build with ``meson test``. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 384 | |
Paolo Bonzini | 8b8939e | 2021-09-07 16:25:50 +0200 | [diff] [blame] | 385 | Useful 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 Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 395 | Important files for the build system |
| 396 | ==================================== |
| 397 | |
| 398 | Statically defined files |
| 399 | ------------------------ |
| 400 | |
| 401 | The following key files are statically defined in the source tree, with |
| 402 | the rules needed to build QEMU. Their behaviour is influenced by a |
| 403 | number of dynamically created files listed later. |
| 404 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 405 | ``Makefile`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 410 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 411 | ``*/meson.build`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 416 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 417 | ``tests/Makefile.include`` |
Paolo Bonzini | ef6a0d6 | 2020-09-07 18:39:13 +0200 | [diff] [blame] | 418 | Rules for external test harnesses. These include the TCG tests, |
Willian Rampazzo | bbbd9b6 | 2021-11-05 12:53:54 -0300 | [diff] [blame] | 419 | ``qemu-iotests`` and the Avocado-based integration tests. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 420 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 421 | ``tests/docker/Makefile.include`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 425 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 426 | ``tests/vm/Makefile.include`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 430 | |
| 431 | Dynamically created files |
| 432 | ------------------------- |
| 433 | |
| 434 | The following files are generated dynamically by configure in order to |
| 435 | control the behaviour of the statically defined makefiles. This avoids |
| 436 | the need for QEMU makefiles to go through any pre-processing as seen |
| 437 | with autotools, where Makefile.am generates Makefile.in which generates |
| 438 | Makefile. |
| 439 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 440 | Built by configure: |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 441 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 442 | ``config-host.mak`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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 |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 446 | variety of ``CONFIG_*`` variables related to optionally enabled features. |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 447 | This is imported by the top level Makefile and meson.build in order to |
| 448 | tailor the build output. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 449 | |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 453 | |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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... |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 457 | |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 458 | |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 459 | Built by Meson: |
| 460 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 461 | ``${TARGET-NAME}-config-devices.mak`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 466 | |
Paolo Bonzini | 4933436 | 2021-11-05 13:45:40 +0100 | [diff] [blame] | 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. |
Daniel P. Berrange | 717171b | 2015-09-24 14:41:38 +0100 | [diff] [blame] | 471 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 472 | ``build.ninja`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 473 | The build rules. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 474 | |
| 475 | |
| 476 | Built by Makefile: |
| 477 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 478 | ``Makefile.ninja`` |
Paolo Bonzini | 09e9332 | 2020-08-13 09:28:11 -0400 | [diff] [blame] | 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. |
Paolo Bonzini | 77d27b9 | 2020-02-04 11:43:54 +0100 | [diff] [blame] | 481 | |
Peter Maydell | 35a4ca4 | 2021-07-26 15:23:29 +0100 | [diff] [blame] | 482 | ``Makefile.mtest`` |
Paolo Bonzini | a14f0bf | 2020-08-11 18:34:40 +0200 | [diff] [blame] | 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. |