From e1a83793ae986db44bc810c36a8ea8090d81fe3f Mon Sep 17 00:00:00 2001
From: Daniel Mensinger <daniel@mensinger-ka.de>
Date: Thu, 31 Jan 2019 23:25:21 +0100
Subject: CMake: Added support for CMAKE_MODULE_PATH and extra CMake args
 (closes #4779)

---
 docs/markdown/Dependencies.md               |  8 ++++++++
 docs/markdown/howtox.md                     | 17 +++++++++++++++++
 docs/markdown/snippets/cmake_module_path.md |  9 +++++++++
 3 files changed, 34 insertions(+)
 create mode 100644 docs/markdown/snippets/cmake_module_path.md

(limited to 'docs/markdown')

diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md
index 4ff5a2a..259f09e 100644
--- a/docs/markdown/Dependencies.md
+++ b/docs/markdown/Dependencies.md
@@ -148,6 +148,14 @@ it automatically.
     cmake_dep = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB'])
 ```
 
+It is also possible to reuse existing `Find<name>.cmake` files with the
+`cmake_module_path` property. Using this property is equivalent to setting the
+`CMAKE_MODULE_PATH` variable in CMake. The path(s) given to `cmake_module_path`
+should all be relative to the project source directory. Absolute paths
+should only be used if the CMake files are not stored in the project itself.
+
+Additional CMake parameters can be specified with the `cmake_args` property.
+
 ### Some notes on Dub
 
 Please understand that meson is only able to find dependencies that
diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md
index 3d8515f..8ae4fde 100644
--- a/docs/markdown/howtox.md
+++ b/docs/markdown/howtox.md
@@ -203,3 +203,20 @@ executable(..., dependencies : m_dep)
 ```meson
 executable(..., install : true, install_dir : get_option('libexecdir'))
 ```
+
+## Use existing `Find<name>.cmake` files
+
+Meson can use the CMake `find_package()` ecosystem if CMake is installed.
+To find a dependency with custom `Find<name>.cmake`, set the `cmake_module_path`
+property to the path in your project where the CMake scripts are stored.
+
+Example for a `FindCmakeOnlyDep.cmake` in a `cmake` subdirectory:
+
+```meson
+cm_dep = dependency('CmakeOnlyDep', cmake_module_path : 'cmake')
+```
+
+The `cmake_module_path` property is only needed for custom CMake scripts. System
+wide CMake scripts are found automatically.
+
+More information can be found [here](Dependencies.md#cmake)
diff --git a/docs/markdown/snippets/cmake_module_path.md b/docs/markdown/snippets/cmake_module_path.md
new file mode 100644
index 0000000..7beb453
--- /dev/null
+++ b/docs/markdown/snippets/cmake_module_path.md
@@ -0,0 +1,9 @@
+## Added `cmake_module_path` and `cmake_args` to dependency
+
+The CMake dependency backend can now make use of existing `Find<name>.cmake`
+files by setting the `CMAKE_MODULE_PATH` with the new `dependency()` property
+`cmake_module_path`. The paths given to `cmake_module_path` should be relative
+to the project source directory.
+
+Furthermore the property `cmake_args` was added to give CMake additional
+parameters.
-- 
cgit v1.1