| 1 |
# CMake module |
| 2 |
|
| 3 |
**Note**: the functionality of this module is governed by [Meson's |
| 4 |
rules on mixing build systems](Mixing-build-systems.md). |
| 5 |
|
| 6 |
This module provides helper tools for generating cmake package files. |
| 7 |
It also supports the usage of CMake based subprojects, similar to |
| 8 |
the normal [Meson subprojects](Subprojects.md). |
| 9 |
|
| 10 |
|
| 11 |
## Usage |
| 12 |
|
| 13 |
To use this module, just do: **`cmake = import('cmake')`**. The |
| 14 |
following functions will then be available as methods on the object |
| 15 |
with the name `cmake`. You can, of course, replace the name `cmake` |
| 16 |
with anything else. |
| 17 |
|
| 18 |
It is generally recommended to use the latest Meson version and |
| 19 |
CMake >=3.17 for best compatibility. CMake subprojects will |
| 20 |
usually also work with older CMake versions. However, this can |
| 21 |
lead to unexpected issues in rare cases. |
| 22 |
|
| 23 |
## CMake subprojects |
| 24 |
|
| 25 |
Using CMake subprojects is similar to using the "normal" Meson |
| 26 |
subprojects. They also have to be located in the `subprojects` |
| 27 |
directory. |
| 28 |
|
| 29 |
Example: |
| 30 |
|
| 31 |
```cmake |
| 32 |
add_library(cm_lib SHARED ${SOURCES}) |
| 33 |
``` |
| 34 |
|
| 35 |
```meson |
| 36 |
cmake = import('cmake') |
| 37 |
|
| 38 |
# Configure the CMake project |
| 39 |
sub_proj = cmake.subproject('libsimple_cmake') |
| 40 |
|
| 41 |
# Fetch the dependency object |
| 42 |
cm_lib = sub_proj.dependency('cm_lib') |
| 43 |
|
| 44 |
executable('exe1', ['sources'], dependencies: [cm_lib]) |
| 45 |
``` |
| 46 |
|
| 47 |
The `subproject` method is almost identical to the normal Meson |
| 48 |
[[subproject]] function. The only difference is that a CMake project |
| 49 |
instead of a Meson project is configured. |
| 50 |
|
| 51 |
The returned `sub_proj` supports the same options as a "normal" |
| 52 |
subproject. Meson automatically detects CMake build targets, which can |
| 53 |
be accessed with the methods listed [below](#subproject-object). |
| 54 |
|
| 55 |
It is usually enough to just use the dependency object returned by the |
| 56 |
`dependency()` method in the build targets. This is almost identical |
| 57 |
to using the [[declare_dependency]] object from a normal Meson subproject. |
| 58 |
|
| 59 |
It is also possible to use executables defined in the CMake project as code |
| 60 |
generators with the `target()` method: |
| 61 |
|
| 62 |
```cmake |
| 63 |
add_executable(cm_exe ${EXE_SRC}) |
| 64 |
``` |
| 65 |
|
| 66 |
```meson |
| 67 |
cmake = import('cmake') |
| 68 |
|
| 69 |
# Subproject with the "code generator" |
| 70 |
sub_pro = cmake.subproject('cmCodeGen') |
| 71 |
|
| 72 |
# Fetch the code generator exe |
| 73 |
sub_exe = sub_pro.target('cm_exe') |
| 74 |
|
| 75 |
# Use the code generator |
| 76 |
generated = custom_target( |
| 77 |
'cmake-generated', |
| 78 |
input: [], |
| 79 |
output: ['test.cpp'], |
| 80 |
command: [sub_exe, '@OUTPUT@'] |
| 81 |
) |
| 82 |
``` |
| 83 |
|
| 84 |
It should be noted that not all projects are guaranteed to work. The |
| 85 |
safest approach would still be to create a `meson.build` for the |
| 86 |
subprojects in question. |
| 87 |
|
| 88 |
### Configuration options |
| 89 |
|
| 90 |
*New in meson 0.55.0* |
| 91 |
|
| 92 |
Meson also supports passing configuration options to CMake and overriding |
| 93 |
certain build details extracted from the CMake subproject. |
| 94 |
|
| 95 |
```meson |
| 96 |
cmake = import('cmake') |
| 97 |
opt_var = cmake.subproject_options() |
| 98 |
|
| 99 |
# Call CMake with `-DSOME_OTHER_VAR=ON` |
| 100 |
opt_var.add_cmake_defines({'SOME_OTHER_VAR': true}) |
| 101 |
|
| 102 |
# Globally override the C++ standard to c++11 |
| 103 |
opt_var.set_override_option('cpp_std', 'c++11') |
| 104 |
|
| 105 |
# Override the previous global C++ standard |
| 106 |
# with c++14 only for the CMake target someLib |
| 107 |
opt_var.set_override_option('cpp_std', 'c++14', target: 'someLib') |
| 108 |
|
| 109 |
sub_pro = cmake.subproject('someLibProject', options: opt_var) |
| 110 |
|
| 111 |
# Further changes to opt_var have no effect |
| 112 |
``` |
| 113 |
|
| 114 |
See [the CMake options object](#cmake-options-object) for a complete |
| 115 |
reference of all supported functions. |
| 116 |
|
| 117 |
The CMake configuration options object is very similar to the |
| 118 |
[[@cfg_data]] object] object returned |
| 119 |
by [[configuration_data]]. It |
| 120 |
is generated by the `subproject_options` method. |
| 121 |
|
| 122 |
All configuration options have to be set *before* the subproject is |
| 123 |
configured and must be passed to the `subproject` method via the |
| 124 |
`options` key. Altering the configuration object won't have any effect |
| 125 |
on previous `cmake.subproject` calls. |
| 126 |
|
| 127 |
In earlier Meson versions CMake command-line parameters could be set |
| 128 |
with the `cmake_options` kwarg. However, this feature is deprecated |
| 129 |
since 0.55.0 and only kept for compatibility. It will not work |
| 130 |
together with the `options` kwarg. |
| 131 |
|
| 132 |
### `subproject` object |
| 133 |
|
| 134 |
This object is returned by the `subproject` method described above |
| 135 |
and supports the following methods: |
| 136 |
|
| 137 |
- `dependency(target)` returns a dependency object for any CMake target. The |
| 138 |
`include_type` kwarg *(new in 0.56.0)* controls the include type of the |
| 139 |
returned dependency object similar to the same kwarg in the |
| 140 |
[[dependency]] function. |
| 141 |
- `include_directories(target)` returns a Meson [[@inc]] |
| 142 |
object for the specified target. Using this method is not necessary |
| 143 |
if the dependency object is used. |
| 144 |
- `target(target)` returns the raw build target. |
| 145 |
- `target_type(target)` returns the type of the target as a string |
| 146 |
- `target_list()` returns a list of all target *names*. |
| 147 |
- `get_variable(name)` fetches the specified variable from inside |
| 148 |
the subproject. Usually `dependency()` or `target()` should be |
| 149 |
preferred to extract build targets. |
| 150 |
- `found` returns true if the subproject is available, otherwise false |
| 151 |
*new in Meson 0.53.2* |
| 152 |
|
| 153 |
### `cmake options` object |
| 154 |
|
| 155 |
This object is returned by the `subproject_options()` method and |
| 156 |
consumed by the `options` kwarg of the `subproject` method. The |
| 157 |
following methods are supported: |
| 158 |
|
| 159 |
- `add_cmake_defines({'opt1': val1, ...})` add additional CMake commandline defines |
| 160 |
- `set_override_option(opt, val)` set specific [build options](Build-options.md) |
| 161 |
for targets. This will effectively add `opt=val` to the `override_options` |
| 162 |
array of the [[build_target]] |
| 163 |
- `set_install(bool)` override whether targets should be installed or not |
| 164 |
- `append_compile_args(lang, arg1, ...)` append compile flags for a specific |
| 165 |
language to the targets |
| 166 |
- `append_link_args(arg1, ...)` append linker args to the targets |
| 167 |
- `clear()` reset all data in the `cmake options` object |
| 168 |
|
| 169 |
The methods `set_override_option`, `set_install`, |
| 170 |
`append_compile_args` and `append_link_args` support the optional |
| 171 |
`target` kwarg. If specified, the set options affect the specific |
| 172 |
target. The effect of the option is global for the subproject |
| 173 |
otherwise. |
| 174 |
|
| 175 |
If, for instance, `opt_var.set_install(false)` is called, no target |
| 176 |
will be installed regardless of what is set by CMake. However, it is |
| 177 |
still possible to install specific targets (here `foo`) by setting the |
| 178 |
`target` kwarg: `opt_var.set_install(true, target: 'foo')` |
| 179 |
|
| 180 |
Options that are not set won't affect the generated subproject. So, if |
| 181 |
for instance, `set_install` was not called then the values extracted |
| 182 |
from CMake will be used. |
| 183 |
|
| 184 |
### Cross compilation |
| 185 |
|
| 186 |
*New in 0.56.0* |
| 187 |
|
| 188 |
Meson will try to automatically guess most of the required CMake |
| 189 |
toolchain variables from existing entries in the cross and native |
| 190 |
files. These variables will be stored in an automatically generate |
| 191 |
CMake toolchain file in the build directory. The remaining variables |
| 192 |
that can't be guessed can be added by the user in the `[cmake]` |
| 193 |
cross/native file section (*new in 0.56.0*). |
| 194 |
|
| 195 |
Adding a manual CMake toolchain file is also supported with the |
| 196 |
`cmake_toolchain_file` setting in the `[properties]` section. Directly |
| 197 |
setting a CMake toolchain file with |
| 198 |
`-DCMAKE_TOOLCHAIN_FILE=/path/to/some/Toolchain.cmake` in the |
| 199 |
`meson.build` is **not** supported since the automatically generated |
| 200 |
toolchain file is also used by Meson to inject arbitrary code into |
| 201 |
CMake to enable the CMake subproject support. |
| 202 |
|
| 203 |
The closest configuration to only using a manual CMake toolchain file |
| 204 |
would be to set these options in the machine file: |
| 205 |
|
| 206 |
```ini |
| 207 |
[properties] |
| 208 |
|
| 209 |
cmake_toolchain_file = '/path/to/some/Toolchain.cmake' |
| 210 |
cmake_defaults = false |
| 211 |
|
| 212 |
[cmake] |
| 213 |
|
| 214 |
# No entries in this section |
| 215 |
``` |
| 216 |
|
| 217 |
This will result in a toolchain file with just the bare minimum to |
| 218 |
enable the CMake subproject support and `include()` the |
| 219 |
`cmake_toolchain_file` as the last instruction. |
| 220 |
|
| 221 |
For more information see the [cross and native file |
| 222 |
specification](Machine-files.md). |
| 223 |
|
| 224 |
## CMake configuration files |
| 225 |
|
| 226 |
### cmake.write_basic_package_version_file() |
| 227 |
|
| 228 |
This method is the equivalent of the corresponding [CMake |
| 229 |
function](https://cmake.org/cmake/help/latest/module/CMakePackageConfigHelpers.html#command:write_basic_package_version_file), |
| 230 |
it generates a `name` package version file. |
| 231 |
|
| 232 |
* `name`: the name of the package. |
| 233 |
* `version`: the version of the generated package file. |
| 234 |
* `compatibility`: a string indicating the kind of compatibility, the accepted values are |
| 235 |
`AnyNewerVersion`, `SameMajorVersion`, `SameMinorVersion` or `ExactVersion`. |
| 236 |
It defaults to `AnyNewerVersion`. Depending on your cmake installation some kind of |
| 237 |
compatibility may not be available. |
| 238 |
* `arch_independent`: *new in 0.62.0*, if true the generated package file |
| 239 |
will skip architecture checks. Useful for header-only libraries. |
| 240 |
* `install_dir`: optional installation directory, it defaults to `$(libdir)/cmake/$(name)` |
| 241 |
|
| 242 |
|
| 243 |
Example: |
| 244 |
|
| 245 |
```meson |
| 246 |
cmake = import('cmake') |
| 247 |
|
| 248 |
cmake.write_basic_package_version_file(name: 'myProject', version: '1.0.0') |
| 249 |
``` |
| 250 |
|
| 251 |
### cmake.configure_package_config_file() |
| 252 |
|
| 253 |
This method is the equivalent of the corresponding [CMake |
| 254 |
function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-configuration-file), |
| 255 |
it generates a `name` package configuration file from the `input` |
| 256 |
template file. Just like the cmake function in this file the |
| 257 |
`@PACKAGE_INIT@` statement will be replaced by the appropriate piece |
| 258 |
of cmake code. The equivalent `PATH_VARS` argument is given through |
| 259 |
the `configuration` parameter. |
| 260 |
|
| 261 |
* `name`: the name of the package. |
| 262 |
* `input`: the template file where that will be treated for variable substitutions contained in `configuration`. |
| 263 |
* `install_dir`: optional installation directory, it defaults to `$(libdir)/cmake/$(name)`. |
| 264 |
* `configuration`: a `configuration_data` object that will be used for variable substitution in the template file. |
| 265 |
*Since 0.62.0* it can take a dictionary instead. |
| 266 |
|
| 267 |
|
| 268 |
Example: |
| 269 |
|
| 270 |
meson.build: |
| 271 |
|
| 272 |
```meson |
| 273 |
cmake = import('cmake') |
| 274 |
|
| 275 |
conf = configuration_data() |
| 276 |
conf.set_quoted('VAR', 'variable value') |
| 277 |
|
| 278 |
cmake.configure_package_config_file( |
| 279 |
name: 'myProject', |
| 280 |
input: 'myProject.cmake.in', |
| 281 |
configuration: conf |
| 282 |
) |
| 283 |
``` |
| 284 |
|
| 285 |
myProject.cmake.in: |
| 286 |
|
| 287 |
```text |
| 288 |
@PACKAGE_INIT@ |
| 289 |
|
| 290 |
set(MYVAR VAR) |
| 291 |
``` |