Meson 对象 (meson)

meson 对象允许您查看系统的各种属性。此对象始终映射到 meson 变量中。

Meson 对象方法

meson.add_devenv()

将 env 对象（由 environment() 返回）添加到将使用 meson devenv 命令行时应用的环境列表中。

这对希望在不安装的情况下使用项目的开发人员很有用，通常需要设置例如插件目录的路径等。或者，可以将列表或字典作为第一个参数传递。

devenv = environment()
devenv.set('PLUGINS_PATH', meson.current_build_dir())
...
meson.add_devenv(devenv)

在配置和编译该项目后，可以使用设置好的环境打开终端

$ meson devenv -C <builddir>
$ echo $PLUGINS_PATH
/path/to/source/subdir

有关 Meson 默认设置的环境变量列表，请参阅 meson devenv 命令文档。

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

参数

meson.add_devenv() 方法接受以下位置参数

名称	类型	描述	标签
env	env | str | list[str] | dict[str] | dict[list[str]]	要添加的 env 对象。自 0.62.0 起，字典值中允许使用字符串列表。在这种情况下，值将使用分隔符连接。

最后，meson.add_devenv() 接受以下关键字参数

名称	类型	描述	标签
method	str	必须是 'set'、'prepend' 或 'append' 之一（默认为 'set'）。控制第一个位置参数中定义的初始值是预先添加到环境变量的当前值中，追加到环境变量的当前值中，还是替换环境变量的当前值。	(自 0.62.0)
separator	str	用于第一个位置参数中定义的初始值的 separator。如果未显式指定，将使用主机操作系统的默认路径分隔符，即 Windows 为 ';'，UNIX/POSIX 系统为 ':'。	(自 0.62.0)

---

meson.add_dist_script()

导致在 dist 操作期间在生成分发源后但在将其归档之前运行作为参数给出的脚本。请注意，这将运行位于暂存目录中的脚本文件，而不是源目录中的脚本文件。如果在暂存目录中找不到脚本文件，则为硬错误。MESON_DIST_ROOT 环境变量在运行 dist 脚本时设置。

(自 0.54.0) MESON_SOURCE_ROOT 和 MESON_BUILD_ROOT 环境变量在运行 dist 脚本时设置。它们是主项目的根源目录和构建目录的路径，即使脚本来自子项目也是如此。

(自 0.58.0) 此命令可以从子项目中调用，在早期版本中为硬错误。仅当运行 meson dist --include-subprojects 时，才会执行子项目 dist 脚本。MESON_PROJECT_SOURCE_ROOT、MESON_PROJECT_BUILD_ROOT 和 MESON_PROJECT_DIST_ROOT 环境变量在运行 dist 脚本时设置。对于主项目脚本，它们与 MESON_SOURCE_ROOT、MESON_BUILD_ROOT 和 MESON_DIST_ROOT 相同，但对于子项目脚本，它们具有子项目根目录的路径附加，通常为 subprojects/<subproject-name>。

(自 1.4.0) MESONREWRITE 环境变量包含与用于配置构建的 meson 可执行文件相对应的重写命令的路径。（这可能与在 PATH 中找到的第一个可执行文件的路径不同。）它可用于从构建配置中删除或替换任何依赖于版本控制系统的 run_command()。请注意，该值将包含许多部分。例如，它可能是 python3 /path/to/meson.py introspect。如果需要，用户负责通过像 UNIX shell 一样词法分割来将字符串分割成数组。如果您的脚本使用 Python，shlex.split() 是最简单、正确的方法。

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

参数

meson.add_dist_script() 方法接受以下位置参数

名称	类型	描述	标签
script_name	str | file | external_program	要执行的脚本。 (自 0.55.0) find_program() 的输出以及字符串都被接受。 (自 0.57.0) 可以使用 file 对象和 configure_file() 的输出。

此外，该方法接受 0 到 infinity 之间的可变参数 (arg...)，其类型为 str | file | external_program。

附加参数

(自 0.55.0) configure_file()、files() 和 find_program() 的输出以及字符串都被接受。

---

meson.add_install_script()

导致在安装步骤期间运行作为参数给出的脚本，该脚本将具有 MESON_SOURCE_ROOT、MESON_BUILD_ROOT、MESON_INSTALL_PREFIX、MESON_INSTALL_DESTDIR_PREFIX 和 MESONINTROSPECT 环境变量设置。所有位置参数都作为参数传递。

(自 0.54.0) 如果 meson install 使用 --quiet 选项调用，则 MESON_INSTALL_QUIET 环境变量将被设置。

(自 1.1.0) 如果 meson install 使用 --dry-run 选项调用，则 MESON_INSTALL_DRY_RUN 环境变量将被设置。

Meson 使用从继承的环境中设置的 DESTDIR 环境变量来确定文件的（临时）安装位置。您的安装脚本在操作和安装文件时必须了解这一点。处理此问题的正确方法是使用始终设置的 MESON_INSTALL_DESTDIR_PREFIX 变量，它包含 DESTDIR（如果设置）和 prefix 连接在一起。这很有用，因为两者通常都是绝对路径，并且在连接两个绝对路径时存在特定于平台的边缘情况。

如果需要，MESON_INSTALL_PREFIX 也始终设置，并且具有传递给 Meson 的 prefix 选项的值。

MESONINTROSPECT 包含与用于配置构建的 meson 可执行文件相对应的 introspect 命令的路径。（这可能与在 PATH 中找到的第一个可执行文件的路径不同。）它可用于查询构建配置。请注意，该值将包含许多部分，例如，它可能是 python3 /path/to/meson.py introspect。如果需要，用户负责通过像 UNIX shell 一样词法分割来将字符串分割成数组。如果您的脚本使用 Python，shlex.split() 是最简单、正确的方法。

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

参数

meson.add_install_script() 方法接受以下位置参数

名称	类型	描述	标签
script_name	str | file | external_program | exe | custom_tgt | custom_idx	要执行的脚本。 (自 0.55.0) find_program()、executable()、custom_target() 的输出以及字符串都被接受。 (自 0.57.0) 可以使用 file 对象和 configure_file() 的输出。

此外，该方法接受 0 到 infinity 之间的可变参数 (arg...)，其类型为 str | file | external_program | exe | custom_tgt | custom_idx。

附加参数

(自 0.55.0) find_program()、executable()、custom_target() 的输出以及字符串都被接受。

最后，meson.add_install_script() 接受以下关键字参数

名称	类型	描述	标签
dry_run	bool	如果为 true，即使 --dry-run 选项提供给 meson install 命令，脚本也会运行。脚本可以使用 MESON_INSTALL_DRY_RUN 变量来确定它是否处于试运行模式。	(自 1.1.0) 默认值 = false
install_tag	str	meson install --tags 命令使用的字符串，用于仅安装文件子集。默认情况下，脚本没有安装标签，这意味着在指定 meson install --tags 参数时不会运行它。	(自 0.60.0)
skip_if_destdir	bool	如果为 true，则在安装期间设置 DESTDIR 时，脚本将不会运行。这在脚本更新系统范围缓存（仅在将文件复制到最终目标时才需要）的情况下很有用。	(自 0.57.0) 默认值 = false

---

meson.add_postconf_script()

在生成所有项目文件后运行给定的命令。该脚本将具有 MESON_SOURCE_ROOT 和 MESON_BUILD_ROOT 环境变量设置。

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

参数

meson.add_postconf_script() 方法接受以下位置参数

名称	类型	描述	标签
script_name	str | file | external_program	要执行的脚本。 (自 0.55.0) find_program() 的输出以及字符串都被接受。 (自 0.57.0) 可以使用 file 对象和 configure_file() 的输出。

此外，该方法接受 0 到 infinity 之间的可变参数 (arg...)，其类型为 str | file | external_program。

附加参数

(自 0.55.0) configure_file()、files() 和 find_program() 的输出以及字符串都被接受。

---

meson.backend()

返回表示当前后端的字符串

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

str backend()

---

meson.build_options()

返回用于设置当前项目的配置行。

str build_options()

---

meson.build_root()

返回指向构建根目录的绝对路径的字符串。如果从子项目中调用此函数，则它将返回父项目的构建根目录，这通常不是您想要的。尝试使用 meson.current_build_dir() 或 meson.project_build_root()。在极少数情况下需要主项目的根目录时，请使用 meson.global_build_root()，它具有相同的行为，但名称更明确。

str build_root()

---

meson.can_run_host_binaries()

如果构建机器可以运行为主机编译的二进制文件，则返回 true。除非您正在进行交叉编译、需要辅助程序来运行主机二进制文件并且没有辅助程序，否则此函数将返回 true。例如，当从 Linux 交叉编译到 Windows 时，可以使用 wine 作为辅助程序。

bool can_run_host_binaries()

---

meson.current_build_dir()

返回指向当前构建目录的绝对路径的字符串。

str current_build_dir()

---

meson.current_source_dir()

返回指向当前源目录的字符串。

str current_source_dir()

---

meson.get_compiler()

返回一个描述编译器的 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
)

参数

方法 meson.get_compiler() 接受以下位置参数

名称	类型	描述	标签
language	str	要返回的编译器的语言。 请查看我们支持语言的 列表。

最后，meson.get_compiler() 接受以下关键字参数

名称	类型	描述	标签
native	bool	当设置为 true 时，Meson 返回构建机器的编译器（“原生”编译器），当设置为 false 时，它返回主机编译器（“交叉”编译器）。如果省略 native，Meson 将在当前进行交叉编译时返回“交叉”编译器，在没有交叉编译时返回“原生”编译器。	默认值 = false

---

meson.get_cross_property()

从交叉文件返回给定属性，如果没有进行交叉编译或没有找到给定属性，则返回可选的 fallback_value。

此方法已被 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
)

参数

参数扁平化 不受此函数支持。

方法 meson.get_cross_property() 接受以下位置参数

名称	类型	描述	标签
propname	str	交叉/原生文件中属性的名称。
fallback_value	any	如果机器文件中未设置 propname，则返回的值。	[可选]

---

meson.get_external_property()

从原生或交叉文件返回给定属性。如果未找到给定属性，则返回可选的 fallback_value。

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

参数

参数扁平化 不受此函数支持。

方法 meson.get_external_property() 接受以下位置参数

名称	类型	描述	标签
propname	str	交叉/原生文件中属性的名称。
fallback_value	any	如果机器文件中未设置 propname，则返回的值。	[可选]

最后，meson.get_external_property() 接受以下关键字参数

名称	类型	描述	标签
native	bool	将 native 设置为 true 将强制从原生文件检索变量，即使在进行交叉编译时也是如此。如果 native: false 或未指定，则在进行交叉编译时从交叉文件检索变量，在没有进行交叉编译时从原生文件检索变量。

---

meson.global_build_root()

返回一个字符串，其中包含构建根目录的绝对路径。如果从子项目调用此函数，它将返回主项目的构建根目录，这通常不是你想要的。通常，最好使用 meson.current_build_dir() 或 meson.project_build_root()。

str global_build_root()

---

meson.global_source_root()

返回一个字符串，其中包含源根目录的绝对路径。如果从子项目调用此函数，它将返回主项目的源根目录，这通常不是你想要的。通常，最好使用 meson.current_source_dir() 或 meson.project_source_root()。

str global_source_root()

---

meson.has_exe_wrapper()

请改用 meson.can_run_host_binaries()。

bool has_exe_wrapper()

---

meson.has_external_property()

检查给定属性是否在原生或交叉文件中存在。

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

参数

方法 meson.has_external_property() 接受以下位置参数

名称	类型	描述	标签
propname	str	交叉/原生文件中属性的名称。

最后，meson.has_external_property() 接受以下关键字参数

名称	类型	描述	标签
native	bool	将 native 设置为 true 将强制从原生文件检索变量，即使在进行交叉编译时也是如此。如果 native: false 或未指定，则在进行交叉编译时从交叉文件检索变量，在没有进行交叉编译时从原生文件检索变量。

---

meson.install_dependency_manifest()

将包含所有子项目、其版本和许可证名称列表的清单文件安装到作为参数给定的文件名中。

如果也定义了许可证文件，它们将被复制到清单文件旁边并在其中引用。

如果未使用此函数，则可以使用内置选项 licensedir 将清单文件安装到给定目录中，名称为 depmf.json。

# Installs a manifest file
void install_dependency_manifest(
  str output_name,     # Name of the manifest file to install
)

参数

方法 meson.install_dependency_manifest() 接受以下位置参数

名称	类型	描述	标签
output_name	str	要安装的清单文件名称

---

meson.is_cross_build()

如果当前构建是 交叉构建，则返回 true，否则返回 false。

bool is_cross_build()

---

meson.is_subproject()

如果当前项目被构建为其他项目的子项目，则返回 true，否则返回 false。

bool is_subproject()

---

meson.is_unity()

在进行 统一构建（在编译之前合并多个源文件以减少构建时间）时返回 true，否则返回 false。

bool is_unity()

---

meson.override_dependency()

指定每当使用带有 name 的 dependency() 时，Meson 不应在系统上查找它，而应返回 dep_object，它可以是 dependency() 或 declare_dependency() 的结果。

在子项目中执行此操作允许父项目检索依赖项，而不必知道依赖项变量名：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
)

参数

方法 meson.override_dependency() 接受以下位置参数

名称	类型	描述	标签
name	str	要覆盖的依赖项的名称。
dep_object	dep	设置为 name 的覆盖依赖项。

最后，meson.override_dependency() 接受以下关键字参数

名称	类型	描述	标签
native	bool	如果设置为 true，则始终覆盖构建机器的依赖项。否则，将覆盖主机机器的依赖项，它在交叉编译时与构建机器不同。	默认值 = false
static	bool	用于分别覆盖静态和/或共享依赖项。如果未指定，则假设 dep_object 遵循 default_library 选项值。	(自 0.60.0)

---

meson.override_find_program()

指定每当使用 find_program() 查找名为 progname 的程序时，Meson 不应在系统上查找它，而应返回 program，它可以是 find_program()、configure_file() 或 executable() 的结果。

(自 0.55.0 版本起) 如果使用可执行文件覆盖的程序传递版本检查到 find_program()，则使用当前项目版本。

# 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`
)

参数

方法 meson.override_find_program() 接受以下位置参数

名称	类型	描述	标签
progname	str	要覆盖的程序的名称。
program	exe | file | external_program	设置为 progname 的覆盖程序。

---

meson.project_build_root()

返回一个字符串，其中包含当前（子）项目的构建根目录的绝对路径。

str project_build_root()

---

meson.project_license()

返回在 project() 函数调用中指定的许可证数组。

list[str] project_license()

---

meson.project_license_files()

返回在 project() 函数调用中指定的许可证文件数组。

list[file] project_license_files()

---

meson.project_name()

返回在 project() 函数调用中指定的项目名称。

str project_name()

---

meson.project_source_root()

返回一个字符串，其中包含当前（子）项目的源根目录的绝对路径。

str project_source_root()

---

meson.project_version()

返回在 project() 函数调用中指定的版本字符串。

str project_version()

---

meson.source_root()

返回一个字符串，其中包含源根目录的绝对路径。

如果从子项目调用此函数，它将返回父项目的源根目录，这通常不是你想要的。尝试使用 meson.current_source_dir() 或 meson.project_source_root()。在很少需要主项目根目录的情况下，使用 meson.global_source_root()，它的行为相同，但名称更明确。

str source_root()

---

meson.version()

返回一个字符串，其中包含 Meson 的版本。

str version()

---