cmake: added docs

docs/markdown/CMake-module.md

@@ -48,8 +48,6 @@ 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).
@@ -87,6 +85,49 @@ 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.
 
+### Configuration options
+
+*New in meson 0.55.0*
+
+Meson also supports passing configuration options to CMake and overriding
+certain build details extracted from the CMake subproject.
+
+```meson
+cmake   = import('cmake')
+opt_var = cmake.subproject_options()
+
+# Call CMake with `-DSOME_OTHER_VAR=ON`
+opt_var.add_cmake_defines({'SOME_OTHER_VAR': true})
+
+# Globally override the C++ standard to c++11
+opt_var.set_override_option('cpp_std', 'c++11')
+
+# Override the previous global C++ standard
+# with c++14 only for the CMake target someLib
+opt_var.set_override_option('cpp_std', 'c++14', target: 'someLib')
+
+sub_pro = cmake.subproject('someLibProject', options: opt_var)
+
+# Further changes to opt_var have no effect
+```
+
+See [the CMake options object](#cmake-options-object) for a complete reference
+of all supported functions.
+
+The CMake configuration options object is very similar to the
+[configuration data object](Reference-manual.md#configuration-data-object) object
+returned by [`configuration_data`](Reference-manual.md#configuration_data). It
+is generated by the `subproject_options` function
+
+All configuration options have to be set *before* the subproject is configured
+and must be passed to the `subproject` method via the `options` key. Altering
+the configuration object won't have any effect on previous `cmake.subproject`
+calls.
+
+In earlier meson versions CMake command-line parameters could be set with the
+`cmake_options` kwarg. However, this feature is deprecated since 0.55.0 and only
+kept for compatibility. It will not work together with the `options` kwarg.
+
 ### `subproject` object
 
 This object is returned by the `subproject` function described above
@@ -103,7 +144,37 @@ and supports the following methods:
    the subproject. Usually `dependency()` or `target()` should be
    preferred to extract build targets.
  - `found` returns true if the subproject is available, otherwise false
-   *new in in 0.53.2*
+   *new in meson 0.53.2*
+
+### `cmake options` object
+
+This object is returned by the `subproject_options()` function and consumed by
+the `options` kwarg of the `subproject` function. The following methods are
+supported:
+
+ - `add_cmake_defines({'opt1': val1, ...})` add additional CMake commandline defines
+ - `set_override_option(opt, val)` set specific [build options](Build-options.md)
+   for targets. This will effectively add `opt=val` to the `override_options`
+   array of the [build target](Reference-manual.md#executable)
+ - `set_install(bool)` override wether targets should be installed or not
+ - `append_compile_args(lang, arg1, ...)` append compile flags for a specific
+   language to the targets
+ - `append_link_args(arg1, ...)` append linger args to the targets
+ - `clear()` reset all data in the `cmake options` object
+
+The methods `set_override_option`, `set_install`, `append_compile_args` and
+`append_link_args` support the optional `target` kwarg. If specified, the set
+options affect the specific target. The effect of the option is global for the
+subproject otherwise.
+
+If, for instance, `opt_var.set_install(false)` is called, no target will be
+installed regardless of what is set by CMake. However, it is still possible to
+install specific targets (here `foo`) by setting the `target` kwarg:
+`opt_var.set_install(true, target: 'foo')`
+
+Options that are not set won't affect the generated subproject. So, if for
+instance, `set_install` was not called then the values extracted from CMake will
+be used.
 
 ## CMake configuration files
 

docs/markdown/snippets/cmake.md

@@ -0,0 +1,17 @@
+## Configure CMake subprojects with meson.subproject_options
+
+Meson now supports passing configuration options to CMake and overriding
+certain build details extracted from the CMake subproject.
+
+The new CMake configuration options object is very similar to the
+[configuration data object](Reference-manual.md#configuration-data-object) object
+returned by [`configuration_data`](Reference-manual.md#configuration_data). It
+is generated by the `subproject_options` function
+
+All configuration options have to be set *before* the subproject is configured
+and must be passed to the `subproject` method via the `options` key. Altering
+the configuration object won't have any effect on previous `cmake.subproject`
+calls.
+
+**Note:** The `cmake_options` kwarg for the `subproject` function is now
+deprecated since it is replaced by the new `options` system.