diff options
Diffstat (limited to 'docs/markdown/CMake-module.md')
| -rw-r--r-- | docs/markdown/CMake-module.md | 112 |
1 files changed, 61 insertions, 51 deletions
diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md index f811ab4..7e981c6 100644 --- a/docs/markdown/CMake-module.md +++ b/docs/markdown/CMake-module.md @@ -48,13 +48,13 @@ 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. -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). +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. +`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: @@ -111,22 +111,24 @@ 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. +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 +[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. +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. +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 @@ -151,9 +153,9 @@ and supports the following methods: ### `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: +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) @@ -165,39 +167,42 @@ supported: - `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. +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')` +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. +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. ### Cross compilation *New in 0.56.0* -Meson will try to automatically guess most of the required CMake toolchain -variables from existing entries in the cross and native files. These variables -will be stored in an automatically generate CMake toolchain file in the build -directory. The remaining variables that can't be guessed can be added by the -user in the `[cmake]` cross/native file section (*new in 0.56.0*). +Meson will try to automatically guess most of the required CMake +toolchain variables from existing entries in the cross and native +files. These variables will be stored in an automatically generate +CMake toolchain file in the build directory. The remaining variables +that can't be guessed can be added by the user in the `[cmake]` +cross/native file section (*new in 0.56.0*). Adding a manual CMake toolchain file is also supported with the -`cmake_toolchain_file` setting in the `[properties]` section. Directly setting -a CMake toolchain file with `-DCMAKE_TOOLCHAIN_FILE=/path/to/some/Toolchain.cmake` -in the `meson.build` is **not** supported since the automatically generated -toolchain file is also used by Meson to inject arbitrary code into CMake to -enable the CMake subproject support. +`cmake_toolchain_file` setting in the `[properties]` section. Directly +setting a CMake toolchain file with +`-DCMAKE_TOOLCHAIN_FILE=/path/to/some/Toolchain.cmake` in the +`meson.build` is **not** supported since the automatically generated +toolchain file is also used by Meson to inject arbitrary code into +CMake to enable the CMake subproject support. -The closest configuration to only using a manual CMake toolchain file would be -to set these options in the machine file: +The closest configuration to only using a manual CMake toolchain file +would be to set these options in the machine file: ```ini [properties] @@ -210,17 +215,19 @@ cmake_defaults = false # No entries in this section ``` -This will result in a toolchain file with just the bare minimum to enable the -CMake subproject support and `include()` the `cmake_toolchain_file` as the -last instruction. +This will result in a toolchain file with just the bare minimum to +enable the CMake subproject support and `include()` the +`cmake_toolchain_file` as the last instruction. -For more information see the [cross and native file specification](Machine-files.md). +For more information see the [cross and native file +specification](Machine-files.md). ## 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), +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), it generates a `name` package version file. * `name`: the name of the package. @@ -242,10 +249,13 @@ cmake.write_basic_package_version_file(name: 'myProject', version: '1.0.0') ### cmake.configure_package_config_file() -This function is the equivalent of the corresponding [CMake function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-configuration-file), -it generates a `name` package configuration file from the `input` template file. Just like the cmake function -in this file the `@PACKAGE_INIT@` statement will be replaced by the appropriate piece of cmake code. -The equivalent `PATH_VARS` argument is given through the `configuration` parameter. +This function is the equivalent of the corresponding [CMake +function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-configuration-file), +it generates a `name` package configuration file from the `input` +template file. Just like the cmake function in this file the +`@PACKAGE_INIT@` statement will be replaced by the appropriate piece +of cmake code. The equivalent `PATH_VARS` argument is given through +the `configuration` parameter. * `name`: the name of the package. * `input`: the template file where that will be treated for variable substitutions contained in `configuration`. |