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 devenv 命令文件，以獲取 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
)

參數

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	用於在第一個位置參數中定義的初始值的分隔符。如果未明確指定，則將使用主機作業系統的預設路徑分隔符，即 Windows 為 ';'，而 UNIX/POSIX 系統為 ':'。	(自 0.62.0 起)

---

meson.add_dist_script()

導致在 dist 操作期間，在生成發布來源之後但在封存之前執行作為參數提供的腳本。請注意，這會執行 暫存 目錄中的腳本檔案，而不是來源目錄中的腳本檔案。如果無法在暫存目錄中找到腳本檔案，則會發生硬錯誤。執行 dist 腳本時會設定 MESON_DIST_ROOT 環境變數。

(自 0.54.0 起) 執行 dist 腳本時會設定 MESON_SOURCE_ROOT 和 MESON_BUILD_ROOT 環境變數。它們是主要專案的根來源和建置目錄的路徑，即使腳本來自子專案也是如此。

(自 0.58.0 起) 此命令可以從子專案中調用，在早期版本中會發生硬錯誤。僅當執行 meson dist --include-subprojects 時，才會執行子專案 dist 腳本。執行 dist 腳本時會設定 MESON_PROJECT_SOURCE_ROOT、MESON_PROJECT_BUILD_ROOT 和 MESON_PROJECT_DIST_ROOT 環境變數。它們對於主要專案腳本而言與 MESON_SOURCE_ROOT、MESON_BUILD_ROOT 和 MESON_DIST_ROOT 相同，但對於子專案腳本，它們具有附加到子專案根目錄的路徑，通常是 subprojects/<子專案名稱>。

(自 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 和 無限 個可變參數 (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 起) 如果使用 --quiet 選項呼叫 meson install，則會設定環境變數 MESON_INSTALL_QUIET。

(自 1.1.0 起) 如果使用 --dry-run 選項呼叫 meson install，則會設定環境變數 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 和 無限 個可變參數 (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，即使為 meson install 命令提供 --dry-run 選項，也會執行腳本。該腳本可以使用 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 和 無限 個可變參數 (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()

當進行 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()

---