| 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. |