Debian Codegraph @

subprojects/meson-docs/docs/yaml/builtins/meson.yaml

raw
1 name: meson
2 long_name: Meson object
3 description: |
4 The `meson` object allows you to introspect various properties of the
5 system. This object is always mapped in the `meson` variable.
6
7 methods:
8 - name: add_dist_script
9 returns: void
10 since: 0.48.0
11 description: |
12 Causes the script given as argument to run during `dist`
13 operation after the
14 distribution source has been generated but before it is
15 archived. Note that this runs the script file that is in the
16 _staging_ directory, not the one in the source directory. If the
17 script file cannot be found in the staging directory, it is a hard
18 error. The `MESON_DIST_ROOT` environment variables is set when dist scripts is
19 run.
20
21 *(since 0.54.0)* The `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`
22 environment variables are set when dist scripts are run. They are path to the
23 root source and build directory of the main project, even when the script
24 comes from a subproject.
25
26 *(since 0.58.0)* This command can be invoked from a subproject, it was a hard
27 error in earlier versions. Subproject dist scripts will only be executed
28 when running `meson dist --include-subprojects`. `MESON_PROJECT_SOURCE_ROOT`,
29 `MESON_PROJECT_BUILD_ROOT` and `MESON_PROJECT_DIST_ROOT` environment
30 variables are set when dist scripts are run. They are identical to
31 `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` and `MESON_DIST_ROOT` for main project
32 scripts, but for subproject scripts they have the path to the root of the
33 subproject appended, usually `subprojects/<subproject-name>`.
34
35 *(since 1.4.0)* The `MESONREWRITE` environment variable contains the path
36 to the rewrite command that corresponds to the `meson` executable that
37 was used to configure the build. (This might be a different path than the
38 first executable found in `PATH`.) It can be used to remove or replace
39 any [[run_command]] that depends on the revision control system from the
40 build configuration. Note that the value will contain many parts. For
41 example, it may be `python3 /path/to/meson.py introspect`. The user is
42 responsible for splitting the string to an array if needed by splitting
43 lexically like a UNIX shell would. If your script uses Python,
44 `shlex.split()` is the easiest correct way to do this.
45
46 posargs:
47 script_name:
48 type: str | file | external_program
49 description: |
50 The script to execute.
51
52 *(since 0.55.0)* The output of [[find_program]] as well as strings are accepted.
53
54 *(since 0.57.0)* [[@file]] objects and the output of [[configure_file]] may be used.
55
56 varargs:
57 name: arg
58 type: str | file | external_program
59 since: 0.49.0
60 description: |
61 Additional arguments
62
63 *(since 0.55.0)* The output of [[configure_file]], [[files]], and [[find_program]]
64 as well as strings are accepted.
65
66 - name: add_install_script
67 returns: void
68 description: |
69 Causes the script given as an argument to be run during the install step,
70 this script will have the environment variables `MESON_SOURCE_ROOT`,
71 `MESON_BUILD_ROOT`, `MESON_INSTALL_PREFIX`,
72 `MESON_INSTALL_DESTDIR_PREFIX`, and `MESONINTROSPECT` set.
73 All positional arguments are passed as parameters.
74
75 *(since 0.54.0)* If `meson install` is called with the `--quiet` option, the
76 environment variable `MESON_INSTALL_QUIET` will be set.
77
78 *(since 1.1.0)* If `meson install` is called with the `--dry-run` option, the
79 environment variable `MESON_INSTALL_DRY_RUN` will be set.
80
81 Meson uses the `DESTDIR` environment variable as set by the
82 inherited environment to determine the (temporary) installation
83 location for files. Your install script must be aware of this while
84 manipulating and installing files. The correct way to handle this is
85 with the `MESON_INSTALL_DESTDIR_PREFIX` variable which is always set
86 and contains `DESTDIR` (if set) and `prefix` joined together. This
87 is useful because both are usually absolute paths and there are
88 platform-specific edge-cases in joining two absolute paths.
89
90 In case it is needed, `MESON_INSTALL_PREFIX` is also always set and
91 has the value of the `prefix` option passed to Meson.
92
93 `MESONINTROSPECT` contains the path to the introspect command that
94 corresponds to the `meson` executable that was used to configure the
95 build. (This might be a different path than the first executable
96 found in `PATH`.) It can be used to query build configuration. Note
97 that the value will contain many parts, f.ex., it may be `python3
98 /path/to/meson.py introspect`. The user is responsible for splitting
99 the string to an array if needed by splitting lexically like a UNIX
100 shell would. If your script uses Python, `shlex.split()` is the
101 easiest correct way to do this.
102
103 posargs:
104 script_name:
105 type: str | file | external_program | exe
106 description: |
107 The script to execute.
108
109 *(since 0.55.0)* The output of [[find_program]], [[executable]],
110 [[custom_target]], as well as strings are accepted.
111
112 *(since 0.57.0)* [[@file]] objects and the output of [[configure_file]] may be used.
113
114 varargs:
115 name: arg
116 type: str | file | external_program | exe | custom_tgt | custom_idx
117 since: 0.49.0
118 description: |
119 Additional arguments
120
121 *(since 0.55.0)* The output of [[find_program]], [[executable]],
122 [[custom_target]], as well as strings are accepted.
123
124 kwargs:
125 skip_if_destdir:
126 type: bool
127 since: 0.57.0
128 default: false
129 description: |
130 If `true` the script will not be run if DESTDIR is set during installation.
131 This is useful in the case the script updates system wide
132 cache that is only needed when copying files into final destination.
133
134 install_tag:
135 type: str
136 since: 0.60.0
137 description: |
138 A string used by the `meson install --tags` command
139 to install only a subset of the files.
140 By default the script has no install tag which means it is not being run when
141 `meson install --tags` argument is specified.
142
143 dry_run:
144 type: bool
145 since: 1.1.0
146 default: false
147 description: |
148 If `true` the script will be run even if `--dry-run` option is provided to
149 the `meson install` command. The script can use the `MESON_INSTALL_DRY_RUN`
150 variable to determine if it is in dry run mode or not.
151
152 - name: add_postconf_script
153 returns: void
154 description: |
155 Runs the given command after all project files have been generated.
156 This script will have the environment variables
157 `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT` set.
158
159 posargs_inherit: meson.add_dist_script
160 varargs_inherit: meson.add_dist_script
161
162 - name: backend
163 returns: str
164 since: 0.37.0
165 description: |
166 Returns a string representing the current backend:
167
168 - `ninja`
169 - `vs2010`
170 - `vs2012`
171 - `vs2013`
172 - `vs2015`
173 - `vs2017`
174 - `vs2019`
175 - `vs2022`
176 - `xcode`
177
178 - name: build_options
179 returns: str
180 since: 1.1.0
181 description: |
182 Returns a string with the configuration line used to set the current project up.
183 notes:
184 - |
185 **Do not try to parse this string!**
186
187 You should use [[cfg_data.set_quoted]] to safely escape any embedded
188 quotes prior to storing it into e.g. a C header macro.
189
190 The contents returned by this function are the same as the
191 "Build Options:" line reported in `<builddir>/meson-logs/meson-log.txt`.
192
193 - name: build_root
194 returns: str
195 deprecated: 0.56.0
196 description: |
197 Returns a string with the absolute path to the build root directory.
198 This function will return the
199 build root of the parent project if called from a subproject, which is usually
200 not what you want. Try using [[meson.current_build_dir]] or [[meson.project_build_root]].
201 In the rare cases where the root of the main project is needed,
202 use [[meson.global_build_root]] that has the same behaviour but with a more explicit
203 name.
204
205 - name: source_root
206 returns: str
207 deprecated: 0.56.0
208 description: |
209 Returns a string with the absolute path to the source root directory.
210
211 This function will return the source root of the
212 parent project if called from a subproject, which is usually not what you want.
213 Try using [[meson.current_source_dir]] or [[meson.project_source_root]].
214 In the rare cases where the root of the main project is needed,
215 use [[meson.global_source_root]] that has the same behaviour but with a more explicit
216 name.
217
218 notes:
219 - |
220 You should use the [[files]] function
221 to refer to files in the root source directory instead of
222 constructing paths manually with [[meson.source_root]].
223
224 - name: project_build_root
225 returns: str
226 since: 0.56.0
227 description: Returns a string with the absolute path to the build root directory of the current (sub)project.
228
229 - name: project_source_root
230 returns: str
231 since: 0.56.0
232 description: Returns a string with the absolute path to the source root directory of the current (sub)project.
233
234 - name: global_build_root
235 returns: str
236 since: 0.58.0
237 description: |
238 Returns a string with the absolute path to the build root directory.
239 This function will return the build root of the
240 main project if called from a subproject, which is usually not what you want.
241 It is usually preferable to use [[meson.current_build_dir]] or [[meson.project_build_root]].
242
243 - name: global_source_root
244 returns: str
245 since: 0.58.0
246 description: |
247 Returns a string with the absolute path to the source root directory.
248 This function will return the source root of the
249 main project if called from a subproject, which is usually not what you want.
250 It is usually preferable to use [[meson.current_source_dir]] or [[meson.project_source_root]].
251
252 - name: current_build_dir
253 returns: str
254 description: Returns a string with the absolute path to the current build directory.
255
256 - name: current_source_dir
257 returns: str
258 description: Returns a string to the current source directory.
259 notes:
260 - |
261 **You do not need to use this function!**
262
263 When passing files from the current source directory to a function since
264 that is the default. Also, you can use the [[files]] function to
265 refer to files in the current or any other source directory instead
266 of constructing paths manually with [[meson.current_source_dir]].
267
268 - name: get_compiler
269 returns: compiler
270 description: Returns a [[@compiler]] object describing a compiler.
271
272 posargs:
273 language:
274 type: str
275 description: |
276 The language of the compiler to return.
277
278 See our [list of supported languages](Reference-tables.md#language-arguments-parameter-names).
279
280 kwargs:
281 native:
282 type: bool
283 default: false
284 description: |
285 When set to `true` Meson returns the compiler for the build
286 machine (the "native" compiler) and when `false` it returns the host
287 compiler (the "cross" compiler). If `native` is omitted, Meson
288 returns the "cross" compiler if we're currently cross-compiling and
289 the "native" compiler if we're not.
290
291 - name: get_cross_property
292 returns: any
293 deprecated: 0.58.0
294 description: |
295 Returns the given property from a cross file, the optional fallback_value
296 is returned if not cross compiling or the given property is not found.
297
298 This method is replaced by [[meson.get_external_property]].
299
300 arg_flattening: false
301 posargs_inherit: meson.get_external_property
302 optargs_inherit: meson.get_external_property
303
304 - name: get_external_property
305 returns: any
306 since: 0.54.0
307 description: |
308 Returns the given property from a native or cross file.
309 The optional fallback_value is returned if the given property is not found.
310
311 arg_flattening: false
312
313 posargs:
314 propname:
315 type: str
316 description: Name of the property in the cross / native file.
317
318 optargs:
319 fallback_value:
320 type: any
321 description: Value to return if `propname` is not set in the machine file.
322
323 kwargs:
324 native:
325 type: bool
326 description: |
327 Setting `native` to `true` forces retrieving a variable from the
328 native file, even when cross-compiling.
329 If `native: false` or not specified, the variable is retrieved from the
330 cross-file if cross-compiling, and from the native-file when not cross-compiling.
331
332 - name: has_external_property
333 returns: bool
334 since: 0.58.0
335 description: Checks whether the given property exist in a native or cross file.
336 posargs_inherit: meson.get_external_property
337 kwargs_inherit: meson.get_external_property
338
339 - name: can_run_host_binaries
340 returns: bool
341 since: 0.55.0
342 description: |
343 Returns true if the build machine can run binaries compiled for the host.
344 This returns `true` unless you are
345 cross compiling, need a helper to run host binaries, and don't have one.
346 For example when cross compiling from Linux to Windows, one can use `wine`
347 as the helper.
348
349 - name: has_exe_wrapper
350 returns: bool
351 deprecated: 0.55.0
352 description: Use [[meson.can_run_host_binaries]] instead.
353
354 - name: install_dependency_manifest
355 returns: void
356 description: |
357 Installs a manifest file
358 containing a list of all subprojects, their versions and license names
359 to the file name given as the argument.
360
361 If license files are defined as well, they will be copied next to the
362 manifest and referenced in it.
363
364 If this function is not used, the builtin option `licensedir` can
365 be used to install the manifest to a given directory with the name
366 `depmf.json`.
367
368 posargs:
369 output_name:
370 type: str
371 description: Name of the manifest file to install
372
373 - name: override_find_program
374 returns: void
375 since: 0.46.0
376 description: |
377 specifies that whenever [[find_program]] is used to find a program
378 named `progname`, Meson should not look it up on the system but
379 instead return `program`, which may either be the result of
380 [[find_program]], [[configure_file]] or [[executable]].
381
382 *(since 0.55.0)* If a version
383 check is passed to [[find_program]] for a program that has been overridden with
384 an executable, the current project version is used.
385
386 posargs:
387 progname:
388 type: str
389 description: The name of the program to override.
390
391 program:
392 type: exe | file | external_program
393 description: The program to set as the override for `progname`.
394
395 - name: override_dependency
396 returns: void
397 since: 0.54.0
398 description: |
399 Specifies that whenever [[dependency]] with `name` is used, Meson should not
400 look it up on the system but instead return `dep_object`, which may either be
401 the result of [[dependency]] or [[declare_dependency]].
402
403 Doing this in a subproject allows the parent
404 project to retrieve the dependency without having to know the dependency
405 variable name: `dependency(name, fallback : subproject_name)`.
406
407 posargs:
408 name:
409 type: str
410 description: The name of the dependency to override.
411
412 dep_object:
413 type: dep
414 description: The dependency to set as the override for `name`.
415
416 kwargs:
417 native:
418 type: bool
419 default: false
420 description: |
421 If set to `true`, the dependency is always overwritten for the build machine.
422 Otherwise, the dependency is overwritten for the host machine, which
423 differs from the build machine when cross-compiling.
424
425 static:
426 type: bool
427 since: 0.60.0
428 description: |
429 Used to override static and/or shared dependencies separately.
430 If not specified it is assumed
431 `dep_object` follows `default_library` option value.
432
433 - name: is_cross_build
434 returns: bool
435 description: Returns `true` if the current build is a [cross build](Cross-compilation.md) and `false` otherwise.
436
437 - name: is_subproject
438 returns: bool
439 description: Returns `true` if the current project is being built as a subproject of some other project and `false` otherwise.
440
441 - name: is_unity
442 returns: bool
443 description: Returns `true` when doing a [unity build](Unity-builds.md) (multiple sources are combined before compilation to reduce build time) and `false` otherwise.
444
445 - name: project_version
446 returns: str
447 description: Returns the version string specified in [[project]] function call.
448
449 - name: project_license
450 returns: list[str]
451 since: 0.45.0
452 description: Returns the array of licenses specified in [[project]] function call.
453
454 - name: project_license_files
455 returns: list[file]
456 since: 1.1.0
457 description: Returns the array of license files specified in the [[project]] function call.
458
459 - name: project_name
460 returns: str
461 description: Returns the project name specified in the [[project]] function call.
462
463 - name: version
464 returns: str
465 description: Return a string with the version of Meson.
466
467 - name: add_devenv
468 returns: void
469 since: 0.58.0
470 description: |
471 add an [[@env]] object (returned by [[environment]])
472 to the list of environments that will be applied when using [`meson devenv`](Commands.md#devenv)
473 command line.
474
475 This is useful for developers who wish to use the project without
476 installing it, it is often needed to set for example the path to plugins
477 directory, etc. Alternatively, a list or dictionary can be passed as first
478 argument.
479
480 ``` meson
481 devenv = environment()
482 devenv.set('PLUGINS_PATH', meson.current_build_dir())
483 ...
484 meson.add_devenv(devenv)
485 ```
486
487 After configuring and compiling that project, a terminal can be opened with
488 the environment set:
489
490 ```sh
491 $ meson devenv -C <builddir>
492 $ echo $PLUGINS_PATH
493 /path/to/source/subdir
494 ```
495
496 See [`meson devenv`](Commands.md#devenv) command documentation for a list of
497 environment variables that are set by default by Meson.
498
499 posargs:
500 env:
501 type: env | str | list[str] | dict[str] | dict[list[str]]
502 description: |
503 The [[@env]] object to add.
504 Since *0.62.0* list of strings is allowed in dictionary values. In that
505 case values are joined using the separator.
506 kwargs:
507 separator:
508 type: str
509 since: 0.62.0
510 description: |
511 The separator to use for the initial values defined in
512 the first positional argument. If not explicitly specified, the default
513 path separator for the host operating system will be used, i.e. ';' for
514 Windows and ':' for UNIX/POSIX systems.
515 method:
516 type: str
517 since: 0.62.0
518 description: |
519 Must be one of 'set', 'prepend', or 'append'
520 (defaults to 'set'). Controls if initial values defined in the first
521 positional argument are prepended, appended or replace the current value
522 of the environment variable.