CMake find_package dependency backend (#4444)

3 files changed, 52 insertions, 6 deletions

diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md
index c853677..e3fedc4 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -114,13 +114,40 @@ of all the work behind the scenes to make this work.
 
 You can use the keyword `method` to let meson know what method to use
 when searching for the dependency. The default value is `auto`.
-Aditional dependencies methods are `pkg-config`, `config-tool`,
+Aditional dependencies methods are `pkg-config`, `config-tool`, `cmake`,
 `system`, `sysconfig`, `qmake`, `extraframework` and `dub`.
 
 ```meson
 cups_dep = dependency('cups', method : 'pkg-config')
 ```
 
+The dependency method order for `auto` is:
+
+  1. `pkg-config`
+  2. `cmake`
+  3. `extraframework` (OSX only)
+
+## CMake
+
+Meson can use the CMake `find_package()` function to detect
+dependencies with the builtin `Find<NAME>.cmake` modules and exported
+project configurations (usually in `/usr/lib/cmake`). Meson is able
+to use both the old-style `<NAME>_LIBRARIES` variables as well as
+imported targets.
+
+It is possible to manually specify a list of CMake targets that should
+be used with the `modules` property. Howerver, this step is optional
+since meson tries to automatically guess the correct target based on the
+name of the dependency.
+
+Depending on the dependency it may be neccessary to explicitly specify
+a CMake target with the `modules` property if meson is unable to guess
+it automatically.
+
+```meson
+    cmake_dep = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB'])
+```
+
 ### Some notes on Dub
 
 Please understand that meson is only able to find dependencies that
@@ -218,7 +245,7 @@ libraries that have been compiled for single-threaded use instead.
 
 ## CUPS
 
-`method` may be `auto`, `config-tool`, `pkg-config` or `extraframework`.
+`method` may be `auto`, `config-tool`, `pkg-config`, `cmake` or `extraframework`.
 
 ## GL
 
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 7df0717..a723b03 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -365,10 +365,10 @@ keyword arguments.
 ```
 
 Finds an external dependency (usually a library installed on your
-system) with the given name with `pkg-config` if possible, as a
-framework (OSX only), and with
+system) with the given name with `pkg-config` and [with CMake](Dependencies.md#CMake)
+if `pkg-config` fails. Additionally, frameworks (OSX only) and
 [library-specific fallback detection logic](Dependencies.md#dependencies-with-custom-lookup-functionality)
-otherwise. This function supports the following keyword arguments:
+are also supported. This function supports the following keyword arguments:
 
 - `default_options` *(added 0.37.0)* an array of default option values
   that override those set in the subproject's `meson_options.txt`
@@ -1442,7 +1442,7 @@ be up to date on every build. Keywords are similar to `custom_target`.
 
 Meson will read the contents of `input`, substitute the
 `replace_string` with the detected revision number, and write the
-result to `output`. This method returns a 
+result to `output`. This method returns a
 [`custom_target`](#custom_target) object that (as usual) should be
 used to signal dependencies if other targets use the file outputted
 by this.
diff --git a/docs/markdown/snippets/cmake.md b/docs/markdown/snippets/cmake.md
new file mode 100644
index 0000000..8848c7b
--- /dev/null
+++ b/docs/markdown/snippets/cmake.md
@@ -0,0 +1,19 @@
+## CMake `find_package` dependency backend
+
+Meson can now use the CMake `find_package` ecosystem to
+detect dependencies. Both the old-style `<NAME>_LIBRARIES`
+variables as well as imported targets are supported. Meson
+can automatically guess the correct CMake target in most
+cases but it is also possible to manually specify a target
+with the `modules` property.
+
+```meson
+# Implicitly uses CMake as a fallback and guesses a target
+dep1 = dependency('KF5TextEditor')
+
+# Manually specify one or more CMake targets to use
+dep2 = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB'])
+```
+
+CMake is automatically used after `pkg-config` fails when
+no `method` (or `auto`) was provided in the dependency options.