cmake: updated docs

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 prokect 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 is 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
+   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),

docs/markdown/Reference-manual.md

@@ -1405,11 +1405,6 @@ 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.51.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.51.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

@@ -17,8 +17,11 @@ 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 is only guaranteed to work for subprojects
-that are built with Meson. Using CMake based subprojects is not guaranteed
-to work for all projects.
+that are built with Meson. The reason is the simple fact that there is
+no possible way to do this reliably with mixed build systems. Because of
+this, only meson subprojects are described here.
+[CMake based subprojects](CMake-module.md#CMake-subprojects) are also
+supported but not guaranteed to work.
 
 ## A subproject example
 
@@ -160,41 +163,6 @@ 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

@@ -1,33 +1,29 @@
 ## CMake subprojects
 
-Meson can now directly consume CMake based subprojects. Using CMake
-subprojects is almost identical to using the "normal" meson subprojects:
+Meson can now directly consume CMake based subprojects with the
+CMake module.
 
-```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.
+Using CMake subprojects is similar to using the "normal" meson
+subprojects. They also have to be located in the `subprojects`
+directory.
 
-These variable names are generated based on the CMake target name.
+Example:
 
 ```cmake
-add_library(cm_exe SHARED ${SOURCES})
+add_library(cm_lib SHARED ${SOURCES})
 ```
 
-For `cm_exe`, meson will then define the following variables:
+```meson
+cmake = import('cmake')
+
+# Configure the CMake project
+sub_proj = cmake.subproject('libsimple_cmake')
 
-- `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.
+# Fetch the dependency object
+cm_lib = sub_proj.dependency('cm_lib')
+
+executable(exe1, ['sources'], dependencies: [cm_lib])
+```
 
 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