Allow to fallback to cmake subproject

The method can be overridden by setting the `method` key in the wrap
file and always defaults to 'meson'. cmake.subproject() is still needed
in case specific cmake options need to be passed.

This also makes it easier to extend to other methods in the future e.g.
cargo.

2 files changed, 36 insertions, 0 deletions

diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md
index 3aeea14..9000c40 100644
--- a/docs/markdown/Wrap-dependency-system-manual.md
+++ b/docs/markdown/Wrap-dependency-system-manual.md
@@ -87,6 +87,10 @@ previously reserved to `wrap-file`:
   `subprojects/packagefiles`.
 - `diff_files` - *Since 0.63.0* Comma-separated list of local diff files (see
   [Diff files](#diff-files) below).
+- `method` - *Since 1.3.0* The build system used by this subproject. Defaults to `meson`.
+  Supported methods:
+  - `meson` requires `meson.build` file.
+  - `cmake` requires `CMakeLists.txt` file. [See details](#cmake-wraps).
 
 ### Specific to wrap-file
 - `source_url` - download url to retrieve the wrap-file source archive
@@ -290,6 +294,26 @@ With such wrap file, `find_program('myprog')` will automatically
 fallback to use the subproject, assuming it uses
 `meson.override_find_program('myprog')`.
 
+### CMake wraps
+
+Since the CMake module does not know the public name of the provided
+dependencies, a CMake `.wrap` file cannot use the `dependency_names = foo`
+syntax. Instead, the `dep_name = <target_name>_dep` syntax should be used, where
+`<target_name>` is the name of a CMake library with all non alphanumeric
+characters replaced by underscores `_`.
+
+For example, a CMake project that contains `add_library(foo-bar ...)` in its
+`CMakeList.txt` and that applications would usually find using the dependency
+name `foo-bar-1.0` (e.g. via pkg-config) would have a wrap file like this:
+
+```ini
+[wrap-file]
+...
+method = cmake
+[provide]
+foo-bar-1.0 = foo_bar_dep
+```
+
 ## Using wrapped projects
 
 Wraps provide a convenient way of obtaining a project into your
diff --git a/docs/markdown/snippets/wrap.md b/docs/markdown/snippets/wrap.md
new file mode 100644
index 0000000..6e03c2e
--- /dev/null
+++ b/docs/markdown/snippets/wrap.md
@@ -0,0 +1,12 @@
+## Automatic fallback to `cmake` subproject
+
+CMake subprojects have been supported for a while using the `cmake.subproject()`
+module method. However until now it was not possible to use a CMake subproject
+as fallback in a `dependency()` call.
+
+A wrap file can now specify the method used to build it by setting the `method`
+key in the wrap file's first section. The method defaults to `meson`.
+
+Supported methods:
+- `meson` requires `meson.build` file.
+- `cmake` requires `CMakeLists.txt` file. [See details](Wrap-dependency-system-manual.md#cmake-wraps).