Document and improve not-found dependency objects

Document the dependency('', required:false) usage.  Add dependency() as a
shorthand for that.

Avoid emitting 'Dependency  found: NO' in either case.

Fixes mesonbuild#2324

docs/markdown/Reference-manual.md

@@ -316,6 +316,12 @@ otherwise. This function supports the following keyword arguments:
   You can also specify multiple restrictions by passing a list to this
   keyword argument, such as: `['>=3.14.0', '<=4.1.0']`.
 
+If dependency_name is omitted, this returns a dependency object for
+which the found() method returns `false`.  This can be used to
+represent a 'disabled dependency' and passed like any other dependency
+to the `dependencies:` keyword argument of a `build_target`.
+(*Added 0.44.0*).
+
 The returned object also has methods that are documented in the
 [object methods section](#dependency-object) below.
 
@@ -436,10 +442,7 @@ be passed to [shared and static libraries](#library).
 
 The list of `sources`, `objects`, and `dependencies` is always
 flattened, which means you can freely nest and add lists while
-creating the final list. As a corollary, the best way to handle a
-'disabled dependency' is by assigning an empty list `[]` to it and
-passing it like any other dependency to the `dependencies:` keyword
-argument.
+creating the final list.
 
 The returned object also has methods that are documented in the
 [object methods section](#build-target-object) below.

docs/markdown/snippets/not-found-dependency.md

@@ -0,0 +1,14 @@
+# Not-found dependency objects
+
+```meson
+dep = dependency('', required:false)
+```
+
+can now be more simply written as
+
+```meson
+dep = dependency()
+```
+
+which can be used to represent a disabled dependency, and is safe to call
+`found()` on, unlike `[]'.

mesonbuild/interpreter.py

@@ -2083,6 +2083,11 @@ def _find_cached_dep(self, name, kwargs):
         return identifier, cached_dep
 
     def func_dependency(self, node, args, kwargs):
+        if len(args) == 0 or args[0] == '':
+            if kwargs.get('required', (len(args) != 0)):
+                raise InvalidArguments('Dependency is both required and not-found')
+            return DependencyHolder(Dependency('null', {}))
+
         self.validate_arguments(args, 1, [str])
         name = args[0]
         if '<' in name or '>' in name or '=' in name:

test cases/common/163 not-found dependency/meson.build

@@ -0,0 +1,11 @@
+project('dep-test')
+
+foo_dep = dependency('', required:false)
+if foo_dep.found()
+  error('not-found dependency was found')
+endif
+
+bar_dep = dependency()
+if bar_dep.found()
+  error('not-found dependency was found')
+endif

test cases/failing/64 dependency not-found and required/meson.build

@@ -0,0 +1,2 @@
+project('dep-test')
+dep = dependency(required:true)