diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/CMake-module.md | 77 | ||||
| -rw-r--r-- | docs/markdown/snippets/cmake.md | 17 |
2 files changed, 91 insertions, 3 deletions
diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md index 7103608..fc6157e 100644 --- a/docs/markdown/CMake-module.md +++ b/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 diff --git a/docs/markdown/snippets/cmake.md b/docs/markdown/snippets/cmake.md new file mode 100644 index 0000000..16da78e --- /dev/null +++ b/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. |