1 files changed, 87 insertions, 0 deletions
diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md
index 4cc97cf..94f4708 100644
--- a/docs/markdown/CMake-module.md
+++ b/docs/markdown/CMake-module.md
@@ -1,6 +1,8 @@
 # CMake module
 
 This module provides helper tools for generating cmake package files.
+It also supports the usage of CMake based subprojects, similar to
+the normal [meson subprojects](Subprojects.md).
 
 
 ## Usage
@@ -10,6 +12,91 @@ following functions will then be available as methods on the object
 with the name `cmake`. You can, of course, replace the name `cmake`
 with anything else.
 
+## CMake subprojects
+
+Using CMake subprojects is similar to using the "normal" meson
+subprojects. They also have to be located in the `subprojects`
+directory.
+
+Example:
+
+```cmake
+add_library(cm_lib SHARED ${SOURCES})
+```
+
+```meson
+cmake = import('cmake')
+
+# Configure the CMake project
+sub_proj = cmake.subproject('libsimple_cmake')
+
+# Fetch the dependency object
+cm_lib = sub_proj.dependency('cm_lib')
+
+executable(exe1, ['sources'], dependencies: [cm_lib])
+```
+
+The `subproject` method is almost identical to the normal meson
+`subproject` function. The only difference is that a CMake project
+instead of a meson project is configured.
+
+Also, 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 CMake build targets, which can be accessed with
+the methods listed [below](#subproject-object).
+
+It is usually enough to just use the dependency object returned by the
+`dependency()` method in the build targets. This is almost identical to
+using `declare_dependency()` object from a normal meson subproject.
+
+It is also possible to use executables defined in the CMake project as code
+generators with the `target()` method:
+
+```cmake
+add_executable(cm_exe ${EXE_SRC})
+```
+
+```meson
+cmake = import('cmake')
+
+# Subproject with the "code generator"
+sub_pro = cmake.subproject('cmCodeGen')
+
+# Fetch the code generator exe
+sub_exe = sub_pro.target('cm_exe')
+
+# Use the code generator
+generated = custom_target(
+  'cmake-generated',
+  input: [],
+  output: ['test.cpp'],
+  command: [sub_exe, '@OUTPUT@']
+)
+```
+
+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.
+
+### `subproject` object
+
+This object is returned by the `subproject` function described above
+and supports the following methods:
+
+ - `dependency(target)` returns a dependency object for any CMake target.
+ - `include_directories(target)` returns a meson `include_directories()`
+   object for the specified target. Using this function is not neccessary
+   if the dependency object is used.
+ - `target(target)` returns the raw build target.
+ - `target_type(target)` returns the type of the target as a string
+ - `target_list()` returns a list of all target *names*.
+ - `get_variable(name)` fetches the specified variable from inside
+   the subproject. Usually `dependency()` or `target()` should be
+   prefered to extract build targets.
+
+## CMake configuration files
+
 ### cmake.write_basic_package_version_file()
 
 This function is the equivalent of the corresponding [CMake function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-version-file),