Document and improve not-found dependency objects

Document dependency('', required:false) usage.
Avoid emitting 'Dependency  found: NO'.

4 files changed, 24 insertions, 4 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index e6aa9d3..4be06c4 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -316,6 +316,13 @@ 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 '', the dependency is always not found.  So with
+`required: false`, this always returns a dependency object for which the
+`found()` method returns `false`, and which can be passed like any other
+dependency to the `dependencies:` keyword argument of a `build_target`.  This
+can be used to implement a dependency which is sometimes not required e.g. in
+some branches of a conditional.
+
 The returned object also has methods that are documented in the
 [object methods section](#dependency-object) below.
 
@@ -436,10 +443,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.
diff --git a/mesonbuild/interpreter.py b/mesonbuild/interpreter.py
index ff93feb..86d25ea 100644
--- a/mesonbuild/interpreter.py
+++ b/mesonbuild/interpreter.py
@@ -2146,6 +2146,12 @@ to directly access options of other subprojects.''')
     def func_dependency(self, node, args, kwargs):
         self.validate_arguments(args, 1, [str])
         name = args[0]
+
+        if name == '':
+            if kwargs.get('required', True):
+                raise InvalidArguments('Dependency is both required and not-found')
+            return DependencyHolder(Dependency('not-found', {}))
+
         if '<' in name or '>' in name or '=' in name:
             raise InvalidArguments('Characters <, > and = are forbidden in dependency names. To specify'
                                    'version\n requirements use the \'version\' keyword argument instead.')
diff --git a/test cases/common/171 not-found dependency/meson.build b/test cases/common/171 not-found dependency/meson.build
new file mode 100644
index 0000000..7d92f5a
--- /dev/null
+++ b/test cases/common/171 not-found dependency/meson.build
@@ -0,0 +1,8 @@
+project('dep-test')
+
+dep = dependency('', required:false)
+if dep.found()
+  error('not-found dependency was found')
+endif
+
+assert(dep.type_name() == 'not-found', 'dependency should be of type "not-found" not ' + dep.type_name())
diff --git a/test cases/failing/67 dependency not-found and required/meson.build b/test cases/failing/67 dependency not-found and required/meson.build
new file mode 100644
index 0000000..1ce5747
--- /dev/null
+++ b/test cases/failing/67 dependency not-found and required/meson.build
@@ -0,0 +1,2 @@
+project('dep-test')
+dep = dependency('', required:true)