Meson object (meson
)
The meson
object allows you to introspect various properties of the
system. This object is always mapped in the meson
variable.
Meson object methods
meson.add_devenv()
add an env
object (returned by environment()
)
to the list of environments that will be applied when using meson devenv
command line.
This is useful for developpers 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.
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:
$ meson devenv -C <builddir>
$ echo $PLUGINS_PATH
/path/to/source/subdir
See meson devenv
command documentation for a list of
environment variables that are set by default by Meson.
Signature
(since 0.58.0)
# add an env
object (returned by environment()
)
void add_devenv(
env env, # The env
object to add.
)
Arguments
The method meson.add_devenv()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
env |
env |
The |
|
meson.add_dist_script()
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 can not 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>
.
Signature
(since 0.48.0)
# Causes the script given as argument to run during `dist`
void add_dist_script(
str | file | external_program | exe | custom_tgt | custom_idx script_name, # The script to execute
str | file | external_program | exe | custom_tgt | custom_idx arg..., # Additional arguments
)
Arguments
The method meson.add_dist_script()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
script_name |
str | file | external_program | exe | custom_tgt | custom_idx
|
The script to execute. (since 0.55.0) The output of (since 0.57.0) |
|
Additionally, the
method accepts between 0
and infinity
variadic
arguments (arg...
) of type
.str
| file
| external_program
| exe
| custom_tgt
| custom_idx
Additional arguments
(since 0.55.0) The output of configure_file()
, files()
, and find_program()
as well as strings are accepted.
(since 0.57.0) file
objects and the output of configure_file()
may be used.
(since 0.49.0)
meson.add_install_script()
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.
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.
Signature
# Causes the script given as an argument to be run during the install step,
void add_install_script(
str | file | external_program | exe | custom_tgt | custom_idx script_name, # The script to execute
str | file | external_program | exe | custom_tgt | custom_idx arg..., # Additional arguments
# Keyword arguments:
install_tag : str # A string used by the `meson install --tags` command
skip_if_destdir : bool # If `true` the script will not be run if DESTDIR is set during installation
)
Arguments
The method meson.add_install_script()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
script_name |
str | file | external_program | exe | custom_tgt | custom_idx
|
The script to execute. (since 0.55.0) The output of (since 0.57.0) |
|
Additionally, the
method accepts between 0
and infinity
variadic
arguments (arg...
) of type
.str
| file
| external_program
| exe
| custom_tgt
| custom_idx
Additional arguments
(since 0.55.0) The output of configure_file()
, files()
, and find_program()
as well as strings are accepted.
(since 0.57.0) file
objects and the output of configure_file()
may be used.
(since 0.49.0)
Finally, meson.add_install_script()
accepts the following keyword arguments:
Name | Type | Description | Tags |
---|---|---|---|
install_tag |
str |
A string used by the |
(since 0.60.0) |
skip_if_destdir |
bool |
If |
(since 0.57.0)
|
meson.add_postconf_script()
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.
Signature
# Runs the given command after all project files have been generated
void add_postconf_script(
str | file | external_program | exe | custom_tgt | custom_idx script_name, # The script to execute
str | file | external_program | exe | custom_tgt | custom_idx arg..., # Additional arguments
)
Arguments
The method meson.add_postconf_script()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
script_name |
str | file | external_program | exe | custom_tgt | custom_idx
|
The script to execute. (since 0.55.0) The output of (since 0.57.0) |
|
Additionally, the
method accepts between 0
and infinity
variadic
arguments (arg...
) of type
.str
| file
| external_program
| exe
| custom_tgt
| custom_idx
Additional arguments
(since 0.55.0) The output of configure_file()
, files()
, and find_program()
as well as strings are accepted.
(since 0.57.0) file
objects and the output of configure_file()
may be used.
(since 0.49.0)
meson.backend()
Returns a string representing the current backend:
ninja
vs2010
vs2012
vs2013
vs2015
vs2017
vs2019
xcode
Signature
(since 0.37.0)
str backend()
meson.build_root()
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.
Signature
DEPRECATED
in 0.56.0
str build_root()
meson.can_run_host_binaries()
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.
Signature
(since 0.55.0)
bool can_run_host_binaries()
meson.current_build_dir()
Returns a string with the absolute path to the current build directory.
Signature
str current_build_dir()
meson.current_source_dir()
Returns a string to the current source directory.
Signature
str current_source_dir()
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()
.
meson.get_compiler()
Returns a compiler
object describing a compiler.
Signature
# Returns a compiler
object describing a compiler.
compiler get_compiler(
str language, # The language of the compiler to return
# Keyword arguments:
native : bool # When set to `true` Meson returns the compiler for the build
)
Arguments
The method meson.get_compiler()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
language |
str |
The language of the compiler to return. See our list of supported languages. |
|
Finally, meson.get_compiler()
accepts the following keyword arguments:
Name | Type | Description | Tags |
---|---|---|---|
native |
bool |
When set to |
|
meson.get_cross_property()
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()
.
Signature
DEPRECATED
in 0.58.0
# Returns the given property from a cross file, the optional fallback_value
any get_cross_property(
str propname, # Name of the property in the cross / native file
any [fallback_value], # Value to return if `propname` is not set in the machine file
)
Arguments
The method meson.get_cross_property()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
propname |
str |
Name of the property in the cross / native file. |
|
fallback_value |
any |
Value to return if |
[optional] |
meson.get_external_property()
Returns the given property from a native or cross file. The optional fallback_value is returned if the given property is not found.
Signature
(since 0.54.0)
# Returns the given property from a native or cross file
any get_external_property(
str propname, # Name of the property in the cross / native file
any [fallback_value], # Value to return if `propname` is not set in the machine file
# Keyword arguments:
native : bool # Setting `native` to `true` forces retrieving a variable from the
)
Arguments
The method meson.get_external_property()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
propname |
str |
Name of the property in the cross / native file. |
|
fallback_value |
any |
Value to return if |
[optional] |
Finally, meson.get_external_property()
accepts the following keyword arguments:
Name | Type | Description | Tags |
---|---|---|---|
native |
bool |
Setting |
|
meson.global_build_root()
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()
.
Signature
(since 0.58.0)
str global_build_root()
meson.global_source_root()
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()
.
Signature
(since 0.58.0)
str global_source_root()
meson.has_exe_wrapper()
Use meson.can_run_host_binaries()
instead.
Signature
DEPRECATED
in 0.55.0
bool has_exe_wrapper()
meson.has_external_property()
Checks whether the given property exist in a native or cross file.
Signature
(since 0.58.0)
# Checks whether the given property exist in a native or cross file
bool has_external_property(
str propname, # Name of the property in the cross / native file
# Keyword arguments:
native : bool # Setting `native` to `true` forces retrieving a variable from the
)
Arguments
The method meson.has_external_property()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
propname |
str |
Name of the property in the cross / native file. |
|
Finally, meson.has_external_property()
accepts the following keyword arguments:
Name | Type | Description | Tags |
---|---|---|---|
native |
bool |
Setting |
|
meson.install_dependency_manifest()
Installs a manifest file containing a list of all subprojects, their versions and license files to the file name given as the argument.
Signature
# Installs a manifest file
void install_dependency_manifest(
str output_name, # Name of the manifest file to install
)
Arguments
The method meson.install_dependency_manifest()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
output_name |
str |
Name of the manifest file to install |
|
meson.is_cross_build()
Returns true
if the current build is a cross build and false
otherwise.
Signature
bool is_cross_build()
meson.is_subproject()
Returns true
if the current project is being built as a subproject of some other project and false
otherwise.
Signature
bool is_subproject()
meson.is_unity()
Returns true
when doing a unity build (multiple sources are combined before compilation to reduce build time) and false
otherwise.
Signature
bool is_unity()
meson.override_dependency()
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)
.
Signature
(since 0.54.0)
# Specifies that whenever dependency()
with `name` is used, Meson should not
void override_dependency(
str name, # The name of the dependency to override
dep dep_object, # The dependency to set as the override for `name`
# Keyword arguments:
native : bool # If set to `true`, the dependency is always overwritten for the build machine
static : bool # Used to override static and/or shared dependencies separately
)
Arguments
The method meson.override_dependency()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
name |
str |
The name of the dependency to override. |
|
dep_object |
dep |
The dependency to set as the override for |
|
Finally, meson.override_dependency()
accepts the following keyword arguments:
Name | Type | Description | Tags |
---|---|---|---|
native |
bool |
If set to |
|
static |
bool |
Used to override static and/or shared dependencies separately.
If not specified it is assumed
|
(since 0.60.0) |
meson.override_find_program()
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.
Signature
(since 0.46.0)
# specifies that whenever find_program()
is used to find a program
void override_find_program(
str progname, # The name of the program to override
exe | file | external_program program, # The program to set as the override for `progname`
)
Arguments
The method meson.override_find_program()
accepts the following positional arguments:
Name | Type | Description | Tags |
---|---|---|---|
progname |
str |
The name of the program to override. |
|
program |
exe | file | external_program
|
The program to set as the override for |
|
meson.project_build_root()
Returns a string with the absolute path to the build root directory of the current (sub)project.
Signature
(since 0.56.0)
str project_build_root()
meson.project_license()
Returns the array of licenses specified in project()
function call.
Signature
list[str] project_license()
meson.project_name()
Returns the project name specified in the project()
function call.
Signature
str project_name()
meson.project_source_root()
Returns a string with the absolute path to the source root directory of the current (sub)project.
Signature
(since 0.56.0)
str project_source_root()
meson.project_version()
Returns the version string specified in project()
function call.
Signature
str project_version()
meson.source_root()
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.
Signature
DEPRECATED
in 0.56.0
str source_root()
You should use the files()
function
to refer to files in the root source directory instead of
constructing paths manually with meson.source_root()
.
meson.version()
Return a string with the version of Meson.
Signature
str version()
The results of the search are