cmake: Added docs

3 files changed, 103 insertions, 30 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index f59d627..5662708 100644
--- a/docs/markdown/Reference-manual.md
+++ b/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
diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md
index 2546441..21cb2cb 100644
--- a/docs/markdown/Subprojects.md
+++ b/docs/markdown/Subprojects.md
@@ -14,17 +14,16 @@ Meson tries to solve this problem by making it extremely easy to
 provide both at the same time. The way this is done is that Meson
 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. 
+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
 
-Usually dependencies consist of some header files plus a library to link against. 
-To declare this internal dependency use `declare_dependency` function.  
+Usually dependencies consist of some header files plus a library to link against.
+To declare this internal dependency use `declare_dependency` function.
 
 As an example, suppose we have a simple project that provides a shared
 library. Its `meson.build` would look like this.
@@ -33,22 +32,22 @@ library. Its `meson.build` would look like this.
 project('libsimple', 'c')
 
 inc = include_directories('include')
-libsimple = shared_library('simple', 
-  'simple.c', 
-  include_directories : inc, 
+libsimple = shared_library('simple',
+  'simple.c',
+  include_directories : inc,
   install : true)
 
-libsimple_dep = declare_dependency(include_directories : inc, 
+libsimple_dep = declare_dependency(include_directories : inc,
   link_with : libsimple)
 ```
 
 ### Naming convention for dependency variables
 
-Ideally the dependency variable name should be of `<project_name>_dep` form. 
+Ideally the dependency variable name should be of `<project_name>_dep` form.
 This way one can just use it without even looking inside build definitions of that subproject.
 
-In cases where there are multiple dependencies need to be declared, the default one 
-should be named as `<project_name>_dep` (e.g. `gtest_dep`), and others can have 
+In cases where there are multiple dependencies need to be declared, the default one
+should be named as `<project_name>_dep` (e.g. `gtest_dep`), and others can have
 `<project_name>_<other>_<name>_dep` form (e.g. `gtest_main_dep` - gtest with main function).
 
 There may be exceptions to these rules where common sense should be applied.
@@ -65,16 +64,16 @@ as a subproject, use the `is_subproject` function.
 
 ## Using a subproject
 
-All subprojects must be inside `subprojects` directory.  
-The `subprojects` directory must be at the top level of your project.  
-Subproject declaration must be in your top level `meson.build`.  
+All subprojects must be inside `subprojects` directory.
+The `subprojects` directory must be at the top level of your project.
+Subproject declaration must be in your top level `meson.build`.
 
 ### A simple example
 
 Let's use `libsimple` as a subproject.
 
-At the top level of your project create `subprojects` directory. 
-Then copy `libsimple` into `subprojects` directory. 
+At the top level of your project create `subprojects` directory.
+Then copy `libsimple` into `subprojects` directory.
 
 Your project's `meson.build` should look like this.
 
@@ -84,9 +83,9 @@ project('my_project', 'cpp')
 libsimple_proj = subproject('libsimple')
 libsimple_dep = libsimple_proj.get_variable('libsimple_dep')
 
-executable('my_project', 
-  'my_project.cpp', 
-  dependencies : libsimple_dep, 
+executable('my_project',
+  'my_project.cpp',
+  dependencies : libsimple_dep,
   install : true)
 ```
 
@@ -102,7 +101,7 @@ embed any sources. Some distros have a rule forbidding embedded
 dependencies so your project must be buildable without them or
 otherwise the packager will hate you.
 
-Here's how you would use system libraries and fall back to embedding sources 
+Here's how you would use system libraries and fall back to embedding sources
 if the dependency is not available.
 
 ```meson
@@ -115,9 +114,9 @@ if not libsimple_dep.found()
   libsimple_dep = libsimple_proj.get_variable('libsimple_dep')
 endif
 
-executable('my_project', 
-  'my_project.cpp', 
-  dependencies : libsimple_dep, 
+executable('my_project',
+  'my_project.cpp',
+  dependencies : libsimple_dep,
   install : true)
 ```
 
@@ -141,14 +140,14 @@ project('my_project', 'cpp')
 
 libsimple_dep = dependency('libsimple', fallback : ['libsimple', 'libsimple_dep'])
 
-executable('my_project', 
-  'my_project.cpp', 
-  dependencies : libsimple_dep, 
+executable('my_project',
+  'my_project.cpp',
+  dependencies : libsimple_dep,
   install : true)
 ```
 
 With this setup when libsimple is provided by the system, we use it. When
-that is not the case we use the embedded version (the one from subprojects). 
+that is not the case we use the embedded version (the one from subprojects).
 
 Note that `libsimple_dep` can point to an external or an internal dependency but
 you don't have to worry about their differences. Meson will take care
@@ -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
diff --git a/docs/markdown/snippets/cmake_subprojects.md b/docs/markdown/snippets/cmake_subprojects.md
new file mode 100644
index 0000000..94f68a1
--- /dev/null
+++ b/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.