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 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/`. 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. 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. - 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_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 files to the file name given as the argument. 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] description: Returns the array of licenses specified in [[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 $ 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 dictionnary 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 repace the current value of the environment variable.