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.
