Features/Meson: Difference between revisions

Latest revision as of 12:58, 8 August 2024

For the rationale behind the conversion and the development notes, see Features/Meson/Design.

Summary of changes

Source code changes

You cannot #include "config-target.h" and "config-devices.h". Instead, you #include CONFIG_TARGET and CONFIG_DEVICES (i.e. filenames are specified via macros; meson.build takes care of defining the macros).
.c files (including .inc.c files) cannot be #included. They have been renamed to .c.inc, for consistency with existing .rst.inc files.
The name of files produced by decodetree is fixed (the C code for XYZ.decode ends up in decode-XYZ.c.inc).
Subdirectories with trace events require a forwarding header file; see hw/scsi/trace.h for an example.

Build layout changes

The Makefile is not recursive anymore. You don't make aarch64-softmmu/all or make arm-linux-user/all, you make qemu-system-aarch64 or make qemu-arm.
Emulator binaries have moved to the root of the build directory. For now, paths such as cris-softmmu/qemu-system-cris are preserved for backwards compatibility through symlinks (created by configure). They are just a user convenience however. You cannot "rm" them to force a rebuild, for example.
Other binaries have moved to the directory where they reside in the source tree. For example, "virtiofsd" has moved to "tools/virtiofsd/virtiofsd".
Most binaries are built by default by make all, including several in contrib/ that weren't built before. Currently, vhost-user-blk and rdmacm-mux are not because they fail on 32-bit and big-endian platforms respectively.
Sphinx manuals are only built if their constituent files are changed, therefore "make sphinxdocs" will be plenty fast when you've only modified a file or two.
Dependencies added to libqemuutil.a will propagate to all programs that link to it. If util/ code has dependencies, it should be conditional on have_system or have_block if applicable (this was a bug in the Makefiles).
For bisection: incremental builds across the conversion work fine in the forwards direction. They probably don't work at all backwards across the conversion, so you'll need to throw away your build tree when bisection moves you backwards across the conversion. This is mitigated by the fact that bisection usually starts at a release, and the patches have been applied on top of the 5.1.0 tag.

New conventions

New configure options should also be added to meson_options.txt so that dependencies are tested in meson.build rather than configure. How to do so is documented in docs/devel.

Impact to developers

If you were already using out-of-tree (VPATH) builds, nothing changes; an incremental pull of these changes should still build.
If you are used to in-tree builds, you'll want to do make distclean prior to merging in these changes (if you forget, git will remind you about various trace.h files that still exist as built files in your in-tree build vs. checked-in files post-patch). After that one-time clean, you can then proceed to do ./configure && make as before, but things will now automatically create a subdirectory build/ on your behalf where the actual build is performed.

CI holes

The following issues were _not_ found by GitLab CI:

SDL 2.0.8 requires -Wno-undef
s390x-softmmu is special for cross-compilation, because it is the only target to use the host C compiler.
There is special code in configure to handle a C++ compiler that does not play well with the C compiler.
Not all linux-user TCG tests are covered.
Big endian platforms are not covered.
ARM host platforms are not covered.
32-bit POSIX platforms are not covered.
SystemTap is not covered.
daxctl is not covered.
--disable-tools --enable-system builds are not covered.
Peter uses Ubuntu+MXE instead of Fedora-mingw to build cross compilers. docker-test-mingw only works for Fedora and should be made more generic. Also container images for Fedora-mingw should be prepared in the same way as the existing container images for Debian+MXE.

Reported and unfixed bugs

meson.build files are missing copyright/license header comments

Known issues

Meson does not like outputs of custom_target (e.g. tracetool and qapi-gen.py) to be in multiple directories. Right now this is only a problem for the QAPI tests.

Projects

Write a linter for meson.build

Visit the output of meson introspect --ast meson.build (including subdirectories) and warn for:

dependencies searched with a method other than "pkg-config" or "system"
dependencies lacking "static: enable_static"
variables not defined on all paths (Meson accepts undefined variables on the RHS of short-circuiting boolean operators)

Links to Meson issues and pull requests

Meson changes that are pending or have not been put to use yet.

Pull requests

python: add automatic dependency tracking for scripts: Avoids listing sources for qapi-gen.py and tracetool.py

@@ Line 2: / Line 2: @@
 == Summary of changes ==
-;New system requirements:
-* GNU Make 3.82
-* Python setuptools
-* Meson 0.55.0 (in order to use the system-wide install).
 ;Source code changes:
 * You cannot <tt>#include "config-target.h"</tt> and <tt>"config-devices.h"</tt>.  Instead, you <tt>#include CONFIG_TARGET</tt> and <tt>CONFIG_DEVICES</tt> (i.e. filenames are specified via macros; <tt>meson.build</tt> takes care of defining the macros).
@@ Line 43: / Line 38: @@
 * Peter uses Ubuntu+MXE instead of Fedora-mingw to build cross compilers.  docker-test-mingw only works for Fedora and should be made more generic.  Also container images for Fedora-mingw should be prepared in the same way as the existing container images for Debian+MXE.
-== Reported bugs ==
+== Reported and unfixed bugs ==
+* meson.build files are missing copyright/license header comments
-* --enable-trace-backends= builds fail with 'Unknown variable "exe_name"' -- https://lists.gnu.org/archive/html/qemu-devel/2020-08/msg05552.html
+== Known issues ==
-* building now modifies pc-bios/keymaps/ files in the source tree
+* Meson does not like outputs of custom_target (e.g. tracetool and qapi-gen.py) to be in multiple directories.  Right now this is only a problem for the QAPI tests.
-* meson.build files are missing copyright/license header comments
-* scripts/ninjatool.py is missing license statement
+== Projects ==
-* windows binaries fail to launch unless  --disable-pie is given to configure -- https://lists.gnu.org/archive/html/qemu-devel/2020-08/msg05205.html
+;Write a linter for meson.build
+:Visit the output of <tt>meson introspect --ast meson.build</tt> (including subdirectories) and warn for:
+:* dependencies searched with a method other than "pkg-config" or "system"
+:* dependencies lacking "static: enable_static"
+:* variables not defined on all paths (Meson accepts undefined variables on the RHS of short-circuiting boolean operators)
-== Blockers for further conversions ==
+<!--
+== Done ==
+;"Handle (faked-up) in-tree build
+:'''Benefit''': simpler upgrade path
 ;Complete moving installation rules to meson.build
-:See [https://github.com/bonzini/qemu/tree/meson-poc here]. You're welcome to propose yourself for helping!
 :'''Benefit:''' allows removing parts of Makefile, leaving it as just an orchestrator for submodules, Makefile.ninja and Makefile.mtest
-;Complete moving build rules to meson.build
+;Complete moving tests/Makefile.include build rules to meson.build
-:Move the build rules from tests/Makefile.include to tests/meson.build.  You can take inspiration from tests/qtest/Makefile.include.
+:'''Benefit:''' allows removing CFLAGS, LDFLAGS, LIBS and LIBS_SOFTMMU, as well as almost all of rules.mak.
-:[https://github.com/bonzini/qemu/tree/meson-poc Here] you can also find patches to convert the build rules in roms/ and pc-bios/
+;Remove pkg-config variables from QEMU_CFLAGS and LIBS
-:[https://github.com/elmarco/qemu/blob/meson-tests WIP] for tests/ conversion
+:All Meson executables should specify their dependencies explicitly, either directly or indirectly via declare_dependency.  Makefiles instead did not propagate dependencies correctly from static libraries, for example. Therefore, flags for dependencies had to be included in QEMU_CFLAGS and LIBS.
-:'''Benefit:''' allows removing CFLAGS, LDFLAGS, LIBS and LIBS_SOFTMMU, as well as most if not all of rules.mak.
+:'''Benefit:''' allows moving pkg-config dependencies to Meson.
 ;Relocatable install
-:Not really related to Meson, but it allows removing the <tt>pre_prefix</tt> hack in the configure script.
 :'''Benefit:''' on Windows only /usr/share/qemu is relocatable, everything else (icons etc.) is not.  POSIX is currently not relocatable and would get it for free.
+;Convert submodule build rules to meson
-== Easy ==
+:Our submodules are small and the rules to build them can easily be embedded in QEMU itself (just like we're already doing for tests/fp).  SLIRP could use subprojects, but that requires https://github.com/mesonbuild/meson/pull/7740.
-;Diagnose "make is too old" in configure (or in the makefile?)
+:'''Benefit''': make QEMU build fully non-recursive
-:In particular OSX system make is too old, so we'll get a lot of confused users there otherwise, because the error message  is pretty obscure ("multiple target patterns"). Possibly checking in the makefile itself would be nicer, to catch the situation where the user forgets and runs 'make' when they meant 'gmake'.
+:'''Disadvantage''': QEMU duplicates build rules for foreign code.
-:'''Proposal''' can be found [https://lists.gnu.org/archive/html/qemu-devel/2020-08/msg05530.html here]
+;Include config-target.mak files in the source tree
-;Move pkg-config tests to meson.build
-:Replace declare_dependency statements with dependency statements. This can only be done for dependencies that are not used by tests (or after tests have been converted from Make to Meson).
-:'''Benefit''': allows removing *_CFLAGS and *_LIBS variables from config-host.mak.  Allows using dependency objects instead of CONFIG_* symbols when declaring sourcesets.
-;Change simple config-host.mak symbols to Meson options
-:Some symbols (e.g. CONFIG_PARALLELS) are not anymore used in the Makefiles, and are only placed in config-host.mak to be read from Meson.  Instead pass them through -D... command-line options
-:'''Benefit''': allows removing CONFIG_* variables from config-host.mak.
-== Medium ==
-;"Handle (faked-up) in-tree build
-:And cleanup code to handle in-tree builds in configure. Or fail gracefully and explain the situation (which would be easier).
-:'''Benefit''': simpler upgrade path
-;Include config-target.mak files in the tree
 :Remove the configuration loop in configure and just include the content of the .mak files directly in the tree, for example in a target/configs/ directory.  (There are some small complications because config-target.mak file currently includes the host disassembler symbols too, e.g. CONFIG_I386_DIS).
 :'''Benefit''': remove large swaths of imperative code, remove *-linux-user and *-softmmu directories from the build tree.
-;Move other compile tests from configure to meson.build
+;Get rid of ninjatool and just require Ninja
+:'''Benefit''': 1000 lines of code go away, can use things such as <tt>ninja -t clean &lt;TARGET&gt;</tt>
-== Hard(er) ==
+:'''Disadvantage''': recursive build re-enters through the window
 ;Create configure help and command line parsing code from meson_options.txt.
-:Write a program that takes the output of "meson introspect --buildoptions" and generates shell code to initialize variables, parse command line options, print the help and create -D command line options for meson.  May only make sense once many or most options are converted.
+:Use the output of "meson introspect --buildoptions" to initialize variables, parse command line options, print the help and create -D command line options for meson.  PoC [https://gist.github.com/bonzini/54571af56c1de4c3346f69b1483d0245 here] (requires developers to install "jq").
 :'''Benefit''': remove code duplication, centralize command line handling
+-->
-== TBD ==
+== Links to Meson issues and pull requests ==
-;Get rid of ninjatool and just require Ninja
+Meson changes that are pending or have not been put to use yet.
-:'''Benefit''': 1000 lines of code go away, can use things such as <tt>ninja -t clean &lt;TARGET&gt;</tt>
+=== Pull requests ===
-:'''Disadvantage''': recursive build re-enters through the window
+;[https://github.com/mesonbuild/meson/pull/6102 python: add automatic dependency tracking for scripts]
+:Avoids listing sources for qapi-gen.py and tracetool.py
+[[Category:Completed feature pages]]