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