From a6f73449e6a03ef0d565f796df126e87a1cc9c07 Mon Sep 17 00:00:00 2001
From: Jon Turney <jon.turney@dronecode.org.uk>
Date: Fri, 20 Oct 2017 18:07:59 +0100
Subject: [PATCH] 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 #2324
---
 docs/markdown/Reference-manual.md                  | 11 +++++++----
 docs/markdown/snippets/not-found-dependency.md     | 14 ++++++++++++++
 mesonbuild/interpreter.py                          |  5 +++++
 .../common/163 not-found dependency/meson.build    | 11 +++++++++++
 .../meson.build                                    |  2 ++
 5 files changed, 39 insertions(+), 4 deletions(-)
 create mode 100644 docs/markdown/snippets/not-found-dependency.md
 create mode 100644 test cases/common/163 not-found dependency/meson.build
 create mode 100644 test cases/failing/64 dependency not-found and required/meson.build

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 14097ed18376..f81f2c11babb 100644
--- a/docs/markdown/Reference-manual.md
+++ b/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.
diff --git a/docs/markdown/snippets/not-found-dependency.md b/docs/markdown/snippets/not-found-dependency.md
new file mode 100644
index 000000000000..b0c6e81bc2f8
--- /dev/null
+++ b/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 `[]'.
diff --git a/mesonbuild/interpreter.py b/mesonbuild/interpreter.py
index e385a886a5a8..de424c6a1c49 100644
--- a/mesonbuild/interpreter.py
+++ b/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:
diff --git a/test cases/common/163 not-found dependency/meson.build b/test cases/common/163 not-found dependency/meson.build
new file mode 100644
index 000000000000..87b066077bb3
--- /dev/null
+++ b/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
diff --git a/test cases/failing/64 dependency not-found and required/meson.build b/test cases/failing/64 dependency not-found and required/meson.build
new file mode 100644
index 000000000000..f76855ee63eb
--- /dev/null
+++ b/test cases/failing/64 dependency not-found and required/meson.build	
@@ -0,0 +1,2 @@
+project('dep-test')
+dep = dependency(required:true)