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