dependency: support boolean argument "allow_fallback"

Sometimes, distros want to configure a project so that it does not
use any bundled library.  In this case, meson.build might want
to do something like this, where slirp is a combo option
with values auto/system/internal:

  slirp = dependency('', required: false)
  if get_option('slirp') != 'internal'
    slirp = dependency('slirp',
                       required: get_option('slirp') == 'system')
  endif
  if not slirp.found()
    slirp = subproject('libslirp', ...) .variable('...')
  endif

and we cannot use "fallback" because the "system" value should never
look for a subproject.

This worked until 0.54.x, but in 0.55.x this breaks because of the
automatic subproject search.  Note that the desired effect here is
backwards compared to the policy of doing an automatic search on
"required: true"; we only want to do the search if "required" is false!

It would be possible to look for the dependency with  `required: false`
and issue the error manually, but it's ugly and it may produce an error
message that looks "different" from Meson's.

Instead, with this change it is possible to achieve this effect in an
even simpler way:

  slirp = dependency('slirp',
                     required: get_option('slirp') != 'auto',
                     allow_fallback: get_option('slirp') == 'system' ? false : ['slirp', 'libslirp_dep'])

The patch also adds support for "allow_fallback: true", which is
simple and enables automatic fallback to a wrap even for non-required
dependencies.

3 files changed, 27 insertions, 8 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index b6ca743..38ae558 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -454,15 +454,15 @@ Dependencies can also be resolved in two other ways:
 * by a fallback subproject which, if needed, will be brought into the current
   build specification as if [`subproject()`](#subproject) had been called.
   The subproject can be specified with the `fallback` argument.  Alternatively,
-  if the `fallback` argument is absent and `required` is `true` or
-  [`enabled`](Build-options.md#features), *since 0.55.0* Meson will
+  if the `fallback` argument is absent, *since 0.55.0* Meson can
   automatically identify a subproject as a fallback if a wrap file
   [provides](Wrap-dependency-system-manual.md#provide-section) the
   dependency, or if a subproject has the same name as the dependency.
   In the latter case, the subproject must use `meson.override_dependency` to
   specify the replacement, or Meson will report a hard error.  See the
   [Wrap documentation](Wrap-dependency-system-manual.md#provide-section)
-  for more details.
+  for more details.  This automatic search can be controlled using the
+  `allow_fallback` keyword argument.
 
 This function supports the following keyword arguments:
 
@@ -471,7 +471,16 @@ This function supports the following keyword arguments:
   (like `default_options` in [`project()`](#project), they only have
   effect when Meson is run for the first time, and command line
   arguments override any default options in build files)
-- `fallback`: manually specifies a subproject
+- `allow_fallback` (boolean argument, *since 0.56.0*): specifies whether Meson
+  should automatically pick a fallback subproject in case the dependency
+  is not found in the system.  If `true` and the dependency is not found
+  on the system, Meson will fallback to a subproject that provides this
+  dependency. If `false`, Meson will not fallback even if a subproject
+  provides this dependency.  By default, Meson will do so if `required`
+  is `true` or  [`enabled`](Build-options.md#features); see the [Wrap
+  documentation](Wrap-dependency-system-manual.md#provide-section)
+  for more details.
+- `fallback` (string or array argument): manually specifies a subproject
   fallback to use in case the dependency is not found in the system.
   This is useful if the automatic search is not applicable or if you
   want to support versions of Meson older than 0.55.0.  If the value is an
diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md
index 8e6282e..4189709 100644
--- a/docs/markdown/Wrap-dependency-system-manual.md
+++ b/docs/markdown/Wrap-dependency-system-manual.md
@@ -182,10 +182,12 @@ endif
   `dependency('foo-1.0', required: get_option('foo_opt'))` will only fallback
   when the user sets `foo_opt` to `enabled` instead of `auto`.
 
-If it is desired to fallback for an optional dependency, the `fallback` keyword
-argument must be passed explicitly. For example
-`dependency('foo-1.0', required: get_option('foo_opt'), fallback: 'foo')` will
-use the fallback even when `foo_opt` is set to `auto`.
+If it is desired to fallback for an optional dependency, the `fallback`
+or `allow_fallback` keyword arguments must be passed explicitly. *Since
+0.56.0*, `dependency('foo-1.0', required: get_option('foo_opt'),
+allow_fallback: true)` will use the fallback even when `foo_opt` is set
+to `auto`.  On version *0.55.0* the same effect could be achieved with
+`dependency('foo-1.0', required: get_option('foo_opt'), fallback: 'foo')`.
 
 This mechanism assumes the subproject calls `meson.override_dependency('foo-1.0', foo_dep)`
 so Meson knows which dependency object should be used as fallback. Since that
diff --git a/docs/markdown/snippets/fallback_bool.md b/docs/markdown/snippets/fallback_bool.md
new file mode 100644
index 0000000..14bef50
--- /dev/null
+++ b/docs/markdown/snippets/fallback_bool.md
@@ -0,0 +1,8 @@
+## Controlling subproject dependencies with  `dependency(allow_fallback: ...)`
+
+As an alternative to the `fallback` keyword argument to `dependency`,
+you may use `allow_fallback`, which accepts a boolean value. If `true`
+and the dependency is not found on the system, Meson will fallback
+to a subproject that provides this dependency, even if the dependency
+is optional. If `false`, Meson will not fallback even if a subproject
+provides this dependency.