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 env object to add.

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

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

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

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

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()
Note:

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

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

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

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

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

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()
Note:

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