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

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.

# add an env object (returned by environment())
void add_devenv(
  env | str | list[str] | dict[str] | dict[list[str]] env,     # The env object to add.

  # Keyword arguments:
  method    : str  # Must be one of 'set', 'prepend', or 'append'
  separator : str  # The separator to use for the initial values defined in
)

Arguments

The method meson.add_devenv() accepts the following positional arguments:

Name	Type	Description	Tags
env	env | str | list[str] | dict[str] | dict[list[str]]	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.

Finally, meson.add_devenv() accepts the following keyword arguments:

Name	Type	Description	Tags
method	str	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.	(since 0.62.0)
separator	str	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.	(since 0.62.0)

---

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

(since 1.4.0) The MESONREWRITE environment variable contains the path to the rewrite 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 remove or replace any run_command() that depends on the revision control system from the build configuration. Note that the value will contain many parts. For example, 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.

# Causes the script given as argument to run during `dist`
void add_dist_script(
  str | file | external_program script_name,     # The script to execute
  str | file | external_program 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	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.

Additionally, the method accepts between 0 and infinity variadic arguments (arg...) of type str | file | external_program.

Additional arguments

(since 0.55.0) The output of configure_file(), files(), and find_program() as well as strings are accepted.

---

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.

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

# 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:
  dry_run         : bool  # If `true` the script will be run even if `--dry-run` option is provided to
  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 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.

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 find_program(), executable(), custom_target(), as well as strings are accepted.

Finally, meson.add_install_script() accepts the following keyword arguments:

Name	Type	Description	Tags
dry_run	bool	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.	(since 1.1.0) default = false
install_tag	str	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.	(since 0.60.0)
skip_if_destdir	bool	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.	(since 0.57.0) default = false

---

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.

# Runs the given command after all project files have been generated
void add_postconf_script(
  str | file | external_program script_name,     # The script to execute
  str | file | external_program 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	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.

Additionally, the method accepts between 0 and infinity variadic arguments (arg...) of type str | file | external_program.

Additional arguments

(since 0.55.0) The output of configure_file(), files(), and find_program() as well as strings are accepted.

---

meson.backend()

Returns a string representing the current backend:

• ninja
• vs2010
• vs2012
• vs2013
• vs2015
• vs2017
• vs2019
• vs2022
• xcode

str backend()

---

meson.build_options()

Returns a string with the configuration line used to set the current project up.

str build_options()

---

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.

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.

bool can_run_host_binaries()

---

meson.current_build_dir()

Returns a string with the absolute path to the current build directory.

str current_build_dir()

---

meson.current_source_dir()

Returns a string to the current source directory.

str current_source_dir()

---

meson.get_compiler()

Returns a compiler object describing a compiler.

# 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 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.	default = false

---

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

# 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

Argument flattening is NOT SUPPORTED by this function.

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 propname is not set in the machine file.	[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.

# 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

Argument flattening is NOT SUPPORTED by this function.

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 propname is not set in the machine file.	[optional]

Finally, meson.get_external_property() accepts the following keyword arguments:

Name	Type	Description	Tags
native	bool	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.

---

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

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

str global_source_root()

---

meson.has_exe_wrapper()

Use meson.can_run_host_binaries() instead.

bool has_exe_wrapper()

---

meson.has_external_property()

Checks whether the given property exist in a native or cross file.

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

---

meson.install_dependency_manifest()

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.

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

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.

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.

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

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

Finally, meson.override_dependency() accepts the following keyword arguments:

Name	Type	Description	Tags
native	bool	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.	default = false
static	bool	Used to override static and/or shared dependencies separately. If not specified it is assumed dep_object follows default_library option value.	(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.

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

---

meson.project_build_root()

Returns a string with the absolute path to the build root directory of the current (sub)project.

str project_build_root()

---

meson.project_license()

Returns the array of licenses specified in project() function call.

list[str] project_license()

---

meson.project_license_files()

Returns the array of license files specified in the project() function call.

list[file] project_license_files()

---

meson.project_name()

Returns the project name specified in the project() function call.

str project_name()

---

meson.project_source_root()

Returns a string with the absolute path to the source root directory of the current (sub)project.

str project_source_root()

---

meson.project_version()

Returns the version string specified in project() function call.

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.

str source_root()

---

meson.version()

Return a string with the version of Meson.

str version()

---