Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging

* Meson conversions + introspection-based command line parser

# gpg: Signature made Thu 14 Oct 2021 12:51:54 AM PDT
# gpg:                using RSA key F13338574B662389866C7682BFFBD25F78C7AE83
# gpg:                issuer "pbonzini@redhat.com"
# gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>" [full]
# gpg:                 aka "Paolo Bonzini <pbonzini@redhat.com>" [full]

* remotes/bonzini/tags/for-upstream: (26 commits)
  configure: automatically parse command line for meson -D options
  meson-buildoptions: include list of tracing backends
  configure: prepare for auto-generated option parsing
  configure: accept "internal" for --enable-capstone/slirp/fdt
  configure: remove deprecated --{enable, disable}-git-update
  configure, meson: move more compiler checks to Meson
  configure: remove obsolete Solaris ar check
  configure, meson: move Spice configure handling to meson
  configure, meson: move netmap detection to meson
  configure, meson: move vde detection to meson
  configure, meson: move libaio check to meson.build
  configure, meson: move pthread_setname_np checks to Meson
  configure, meson: move remaining HAVE_* compiler tests to Meson
  meson: HAVE_GDB_BIN is not used by C code
  configure, meson: remove CONFIG_GCOV from config-host.mak
  configure, meson: get HOST_WORDS_BIGENDIAN via the machine object
  configure, meson: move CONFIG_HOST_DSOSUF to Meson
  trace: move configuration from configure to Meson
  trace: simple: pass trace_file unmodified to config-host.h
  configure, meson: move fuzzing configuration to Meson
  ...

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

1 files changed, 69 insertions, 67 deletions

diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
index 0f636d620e..7f106d2f1c 100644
--- a/docs/devel/build-system.rst
+++ b/docs/devel/build-system.rst
@@ -42,73 +42,21 @@ perform a build:
      ../configure
      make
 
-For now, checks on the compilation environment are found in configure
-rather than meson.build, though this is expected to change.  The command
-line is parsed in the configure script and, whenever needed, converted
-into the appropriate options to Meson.
-
-New checks should be added to Meson, which usually comprises the
-following tasks:
-
- - Add a Meson build option to meson_options.txt.
-
- - Add support to the command line arg parser to handle any new
-   ``--enable-XXX``/``--disable-XXX`` flags required by the feature.
-
- - Add information to the help output message to report on the new
-   feature flag.
-
- - Add code to perform the actual feature check.
-
- - Add code to include the feature status in ``config-host.h``
-
- - Add code to print out the feature status in the configure summary
-   upon completion.
-
-
-Taking the probe for SDL2_Image as an example, we have the following pieces
-in configure::
-
-  # Initial variable state
-  sdl_image=auto
-
-  ..snip..
-
-  # Configure flag processing
-  --disable-sdl-image) sdl_image=disabled
-  ;;
-  --enable-sdl-image) sdl_image=enabled
-  ;;
-
-  ..snip..
-
-  # Help output feature message
-  sdl-image         SDL Image support for icons
-
-  ..snip..
-
-  # Meson invocation
-  -Dsdl_image=$sdl_image
-
-In meson_options.txt::
-
-  option('sdl', type : 'feature', value : 'auto',
-         description: 'SDL Image support for icons')
-
-In meson.build::
-
-  # Detect dependency
-  sdl_image = dependency('SDL2_image', required: get_option('sdl_image'),
-                         method: 'pkg-config',
-                         kwargs: static_kwargs)
-
-  # Create config-host.h (if applicable)
-  config_host_data.set('CONFIG_SDL_IMAGE', sdl_image.found())
-
-  # Summary
-  summary_info += {'SDL image support': sdl_image.found()}
-
-
+The configure script automatically recognizes
+command line options for which a same-named Meson option exists;
+dashes in the command line are replaced with underscores.
+
+Many checks on the compilation environment are still found in configure
+rather than `meson.build`, but new checks should be added directly to
+`meson.build`.
+
+Patches are also welcome to move existing checks from the configure
+phase to `meson.build`.  When doing so, ensure that `meson.build` does
+not use anymore the keys that you have removed from `config-host.mak`.
+Typically these will be replaced in `meson.build` by boolean variables,
+``get_option('optname')`` invocations, or `dep.found()` expressions.
+In general, the remaining checks have little or no interdependencies,
+so they can be moved one by one.
 
 Helper functions
 ----------------
@@ -335,6 +283,60 @@ new target, or enabling new devices or hardware for a particular
 system/userspace emulation target
 
 
+Adding checks
+-------------
+
+New checks should be added to Meson.  Compiler checks can be as simple as
+the following::
+
+  config_host_data.set('HAVE_BTRFS_H', cc.has_header('linux/btrfs.h'))
+
+A more complex task such as adding a new dependency usually
+comprises the following tasks:
+
+ - Add a Meson build option to meson_options.txt.
+
+ - Add code to perform the actual feature check.
+
+ - Add code to include the feature status in `config-host.h`
+
+ - Add code to print out the feature status in the configure summary
+   upon completion.
+
+Taking the probe for SDL2_Image as an example, we have the following
+in ``meson_options.txt``::
+
+  option('sdl_image', type : 'feature', value : 'auto',
+         description: 'SDL Image support for icons')
+
+Unless the option was given a non-``auto`` value (on the configure
+command line), the detection code must be performed only if the
+dependency will be used::
+
+  sdl_image = not_found
+  if not get_option('sdl_image').auto() or have_system
+    sdl_image = dependency('SDL2_image', required: get_option('sdl_image'),
+                           method: 'pkg-config',
+                           static: enable_static)
+  endif
+
+This avoids warnings on static builds of user-mode emulators, for example.
+Most of the libraries used by system-mode emulators are not available for
+static linking.
+
+The other supporting code is generally simple::
+
+  # Create config-host.h (if applicable)
+  config_host_data.set('CONFIG_SDL_IMAGE', sdl_image.found())
+
+  # Summary
+  summary_info += {'SDL image support': sdl_image.found()}
+
+For the configure script to parse the new option, the
+``scripts/meson-buildoptions.sh`` file must be up-to-date; ``make
+update-buildoptions`` (or just `make`) will take care of updating it.
+
+
 Support scripts
 ---------------