cmake: Added docs

docs/markdown/Reference-manual.md

@@ -1405,6 +1405,11 @@ arguments:
  - `version` keyword argument that works just like the one in
    `dependency`. It specifies what version the subproject should be,
    as an example `>=1.0.1`
+ - `method` *(added 0.50.0)* Specifies the configuration method of the
+   subproject. Possible values are `meson`, `cmake` and `auto`. With
+   `auto` meson will always prefer a `meson.build` in the subproject
+    over other methods. The default value of `method` is `auto`.
+ - `cmake_options` *(added 0.50.0)* List of additional CMake options
  - `required` *(added 0.48.0)* By default, `required` is `true` and
    Meson will abort if the subproject could not be setup. You can set
    this to `false` and then use the `.found()` method on the [returned

docs/markdown/Subprojects.md

@@ -16,10 +16,9 @@ allows you to take any other Meson project and make it a part of your
 build without (in the best case) any changes to its Meson setup. It
 becomes a transparent part of the project.
 
-It should be noted that this only works for subprojects that are built
-with Meson. It can not be used with any other build system. The reason
-is the simple fact that there is no possible way to do this reliably
-with mixed build systems.
+It should be noted that this is only guaranteed to work for subprojects
+that are built with Meson. Using CMake based subprojects is not guaranteed
+to work for all projects.
 
 ## A subproject example
 
@@ -161,6 +160,41 @@ in the top level `subprojects` directory. Recursive use of subprojects
 is not allowed, though, so you can't have subproject `a` that uses
 subproject `b` and have `b` also use `a`.
 
+## CMake subprojects
+
+Meson is also able to use CMake subprojects directly. Using CMake
+subprojects is almost identical to using the "normal" meson subprojects:
+
+```meson
+sub_proj = subproject('libsimple_cmake', method : 'cmake')
+```
+
+The `method` key is optional if the subproject only has a `CMakeList.txt`.
+Without specifying a method meson will always first try to find and use a
+`meson.build` in the subproject.
+
+Project specific CMake options can be added with the `cmake_options` key.
+
+The returned `sub_proj` supports the same options as a "normal" subproject.
+Meson automatically detects build targets, which can be retrieved with
+`get_variable`. Meson also generates a dependency object for each target.
+
+These variable names are generated based on the CMake target name.
+
+```cmake
+add_library(cm_exe SHARED ${SOURCES})
+```
+
+For `cm_exe`, meson will then define the following variables:
+
+- `cm_exe` The raw library target (similar to `cm_exe = library('cm_exe', ...)` in meson)
+- `cm_exe_dep` The dependency object for the target (similar to `declare_dependency()` in meson)
+- `cm_exe_inc` A meson include directory object, containing all include irectories of the target.
+
+It should be noted that not all projects are guaranteed to work. The
+safest approach would still be to create a `meson.build` for the
+subprojects in question.
+
 ## Obtaining subprojects
 
 Meson ships with a dependency system to automatically obtain

docs/markdown/snippets/cmake_subprojects.md

@@ -0,0 +1,34 @@
+## CMake subprojects
+
+Meson can now directly consume CMake based subprojects. Using CMake
+subprojects is almost identical to using the "normal" meson subprojects:
+
+```meson
+sub_proj = subproject('libsimple_cmake', method : 'cmake')
+```
+
+The `method` key is optional if the subproject only has a `CMakeList.txt`.
+Without specifying a method meson will always first try to find and use a
+`meson.build` in the subproject.
+
+Project specific CMake options can be added with the new `cmake_options` key.
+
+The returned `sub_proj` supports the same options as a "normal" subproject.
+Meson automatically detects build targets, which can be retrieved with
+`get_variable`. Meson also generates a dependency object for each target.
+
+These variable names are generated based on the CMake target name.
+
+```cmake
+add_library(cm_exe SHARED ${SOURCES})
+```
+
+For `cm_exe`, meson will then define the following variables:
+
+- `cm_exe` The raw library target (similar to `cm_exe = library('cm_exe', ...)` in meson)
+- `cm_exe_dep` The dependency object for the target (similar to `declare_dependency()` in meson)
+- `cm_exe_inc` A meson include directory object, containing all include irectories of the target.
+
+It should be noted that not all projects are guaranteed to work. The
+safest approach would still be to create a `meson.build` for the
+subprojects in question.