Debian Codegraph @

subprojects/meson-docs/docs/markdown/CMake-module.md

raw
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 ```