函數

此文件列出 meson.build 檔案中可用的所有函數。有關所有功能的概述，請參閱根手冊文件。

add_global_arguments()

將全域參數新增至編譯器命令列。

# Adds global arguments to the compiler command line
void add_global_arguments(
  str Compiler argument...,  # The compiler arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

參數

此函數接受介於 0 和 infinity 之間的變數參數 (Compiler argument...)，類型為 str。

要新增的編譯器參數

函數 add_global_arguments() 接受下列關鍵字參數

add_global_link_arguments()

將全域參數新增至連結器命令列。

與add_global_arguments()類似，但參數會傳遞至連結器。

# Adds global arguments to the linker command line
void add_global_link_arguments(
  str Linker argument...,  # The linker arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

參數

此函數接受介於 0 和 infinity 之間的變數參數 (Linker argument...)，類型為 str。

要新增的連結器參數

函數 add_global_link_arguments() 接受下列關鍵字參數

add_languages()

新增專案使用的程式設計語言。

這相當於在 project 宣告中包含它們。此函數通常用於新增僅在某些條件下使用的語言。

如果找到所有指定的語言，則傳回 true，否則傳回 false。

如果省略 native，則這些語言可用於建置或主機電腦，但建置電腦永遠不會需要它們。（也就是說，它相當於 add_languages(*langs*, native: false, required: *required*) 和 add_languages(*langs*, native: true, required: false)。此預設行為可能會在未來的 Meson 版本中變更為 native: false。

# Add programming languages used by the project
bool add_languages(
  str Language...,  # The languages to add

  # Keyword arguments:
  native   : bool            # If set to `true`, the language will be used to compile for the build
  required : bool | feature  # If set to `true`, Meson will halt if any of the languages
)

範例

project('foobar', 'c')

if compiling_for_osx
  add_languages('objc')
endif
if add_languages('cpp', required : false)
  executable('cpp-app', 'main.cpp')
endif

# More code...

參數

此函數接受介於 0 和 infinity 之間的變數參數 (Language...)，類型為 str。

要新增的語言

函數 add_languages() 接受下列關鍵字參數

add_project_arguments()

將專案特定的參數新增至編譯器命令列。

此函數的行為方式與add_global_arguments()相同，但參數僅用於目前的專案，它們不會用於任何其他子專案。

# Adds project specific arguments to the compiler command line
void add_project_arguments(
  str Compiler argument...,  # The compiler arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

參數

此函數接受介於 0 和 infinity 之間的變數參數 (Compiler argument...)，類型為 str。

要新增的編譯器參數

函數 add_project_arguments() 接受下列關鍵字參數

add_project_dependencies()

將參數新增至編譯器和連結器命令列，以便將給定的一組相依性包含在此專案的所有建置產品中。

# Adds arguments to the compiler and linker command line, so that the
void add_project_dependencies(
  dep dependencies...,  # The dependencies to add; if internal dependencies are included, they must not include any built object

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

參數

此函數接受介於 0 和 infinity 之間的變數參數 (dependencies...)，類型為 dep。

要新增的相依性；如果包含內部相依性，則它們不得包含任何建置的物件。

函數 add_project_dependencies() 接受下列關鍵字參數

add_project_link_arguments()

將專案特定的參數新增至連結器命令列。

與add_project_arguments()類似，但參數會傳遞至連結器。

# Adds project specific arguments to the linker command line
void add_project_link_arguments(
  str Linker argument...,  # The linker arguments to add

  # Keyword arguments:
  language : list[str]  [required]  # Specifies the language(s) that the arguments should be
  native   : bool                   # A boolean specifying whether the arguments should be
)

參數

此函數接受介於 0 和 infinity 之間的變數參數 (Linker argument...)，類型為 str。

要新增的連結器參數

函數 add_project_link_arguments() 接受下列關鍵字參數

add_test_setup()

新增自訂測試設定。此設定可用於使用自訂設定執行測試，例如在 Valgrind 下。

若要使用測試設定，請在建置目錄內執行 meson test --setup=*name*。

請注意，當執行 meson test 指令碼以執行測試而不是 ninja test 或 msbuild RUN_TESTS.vcxproj 等等 (取決於後端) 時，所有這些選項也都可用。

# Add a custom test setup
void add_test_setup(
  str name,     # The name of the test setup

  # Keyword arguments:
  env                : env | list[str] | dict[str]   # environment variables to set
  exclude_suites     : list[str]                     # A list of test suites that should be excluded when using this setup
  exe_wrapper        : list[str | external_program]  # The command or script followed by the arguments to it
  gdb                : bool                          # If `true`, the tests are also run under `gdb`
  is_default         : bool                          # Set whether this is the default test setup
  timeout_multiplier : int                           # A number to multiply the test timeout with
)

參數

函數 add_test_setup() 接受下列位置參數

最後，add_test_setup() 接受下列關鍵字參數

alias_target()

此函數會建立新的頂層目標。與所有頂層目標一樣，這會與選取的後端整合。例如，您可以使用 meson compile target_name 來執行它。這是一個虛擬目標，不會執行任何命令，但可確保建置所有相依性。相依性可以是任何建置目標。自 0.60.0 起，這包含 run_tgt。

自 1.6.0 起，傳遞 both_libs 物件會建置共用和靜態程式庫。

# This function creates a new top-level target
alias_tgt alias_target(
  str target_name,     # The name of the alias target
  tgt Dep...,          # The targets to depend on
)

參數

函數 alias_target() 接受下列位置參數

此外，此函數接受介於 1 和 infinity 之間的變數參數 (Dep...)，類型為 tgt。

要相依的目標

assert()

如果 condition 的評估結果為 false，則中止並顯示錯誤訊息。

# Abort with an error message if `condition` evaluates to `false`
void assert(
  bool condition,     # Abort if this evaluates to `false`
  str  [message],     # The error message to print
)

參數

函數 assert() 接受下列位置參數

benchmark()

建立一個基準測試項目，該項目將在基準測試目標執行時執行。此函數的行為與test()相同，但下列情況除外：

• benchmark() 沒有 is_parallel 關鍵字，因為基準測試不是並行執行的
• benchmark() 不會自動新增 MALLOC_PERTURB_ 環境變數

可以透過在建置目錄內呼叫 meson test --benchmark，或使用特定於後端的命令 (例如 ninja benchmark 或 msbuild RUN_TESTS.vcxproj) 以與後端無關的方式執行已定義的基準測試。

# Creates a benchmark item that will be run when the benchmark target is
void benchmark(
  str                                                           name,           # The *unique* test id
  exe | jar | external_program | file | custom_tgt | custom_idx executable,     # The program to execute

  # Keyword arguments:
  args        : list[str | file | tgt | external_program]  # Arguments to pass to the executable
  depends     : list[build_tgt | custom_tgt]               # specifies that this test depends on the specified
  env         : env | list[str] | dict[str]                # environment variables to set, such as `['NAME1=value1',
  priority    : int                                        # specifies the priority of a test
  protocol    : str                                        # specifies how the test results are parsed and can
  should_fail : bool                                       # when true the test is considered passed if the
  suite       : str | list[str]                            # `'label'` (or list of labels `['label1', 'label2']`)
  timeout     : int                                        # the amount of seconds the test is allowed to run, a test
  verbose     : bool                                       # if true, forces the test results to be logged as if `--verbose` was passed
  workdir     : str                                        # absolute path that will be used as the working directory
)

參數

函數 benchmark() 接受下列位置參數

最後，benchmark() 接受以下關鍵字引數：

both_libraries()

使用給定的原始碼建置靜態和共享程式庫。位置和關鍵字引數與 library() 的引數相同。原始碼檔案只會編譯一次，且物件檔案將重複使用來建置共享和靜態程式庫，除非 b_staticpic 使用者選項或 pic 引數設定為 false，在這種情況下，原始碼會編譯兩次。

# Builds both a static and shared library with the given sources
both_libs both_libraries(
  str                                                   target_name,     # The *unique* name of the build target
  str | file | custom_tgt | custom_idx | generated_list source...,       # Input source to compile

  # Keyword arguments:
  <lang>_args                  : list[str]                                                               # compiler flags to use for the given language;
  <lang>_pch                   : str                                                                     # precompiled header file to use for the given language
  <lang>_shared_args           : list[str]                                                               # Arguments that are only passed to a shared library
  <lang>_static_args           : list[str]                                                               # Arguments that are only passed to a static library
  build_by_default             : bool                                                                    # Causes, when set to `true`, to have this target be built by default
  build_rpath                  : str                                                                     # A string to add to target's rpath definition in the build dir,
  d_debug                      : list[str]                                                               # The [D version identifiers](https://dlang
  d_import_dirs                : list[inc | str]                                                         # the directories to add to the string search path (i
  d_module_versions            : list[str | int]                                                         # List of module version identifiers set when compiling D sources
  d_unittest                   : bool                                                                    # When set to true, the D modules are compiled in debug mode
  darwin_versions              : str | int | list[str]                                                   # Defines the `compatibility version` and `current version` for the dylib on macOS
  dependencies                 : list[dep]                                                               # one or more dependency objects
  extra_files                  : str | file | custom_tgt | custom_idx                                    # Not used for the build itself but are shown as source files in IDEs
  gnu_symbol_visibility        : str                                                                     # Specifies how symbols should be exported, see
  gui_app                      : bool                                                                    # When set to true flags this target as a GUI application
  implicit_include_directories : bool                                                                    # Controls whether Meson adds the current source and build directories to the include path
  include_directories          : list[inc | str]                                                         # one or more objects created with the include_directories() function,
  install                      : bool                                                                    # When set to true, this executable should be installed
  install_dir                  : str                                                                     # override install directory for this file
  install_mode                 : list[str | int]                                                         # Specify the file mode in symbolic format
  install_rpath                : str                                                                     # A string to set the target's rpath to after install
  install_tag                  : str                                                                     # A string used by the `meson install --tags` command
  link_args                    : list[str]                                                               # Flags to use during linking
  link_depends                 : str | file | custom_tgt | custom_idx                                    # Strings, files, or custom targets the link step depends on
  link_language                : str                                                                     # Makes the linker for this target be for the specified language
  link_whole                   : list[lib | custom_tgt | custom_idx]                                     # Links all contents of the given static libraries whether they are used or
  link_with                    : list[lib | custom_tgt | custom_idx]                                     # One or more shared or static libraries
  name_prefix                  : str | list[void]                                                        # The string that will be used as the prefix for the
  name_suffix                  : str | list[void]                                                        # The string that will be used as the extension for the
  native                       : bool                                                                    # Controls whether the target is compiled for the build or host machines
  objects                      : list[extracted_obj | file | str]                                        # List of object files that should be linked in this target
  override_options             : list[str] | dict[str | bool | int | list[str]]                            # takes an array of strings in the same format as `project`'s `default_options`
  pic                          : bool                                                                    # Builds the library as positional independent code
  prelink                      : bool                                                                    # If `true` the object files in the target will be prelinked,
  rust_abi                     : str                                                                     # Set the specific ABI to compile (when compiling rust)
  rust_crate_type              : str                                                                     # Set the specific type of rust crate to compile (when compiling rust)
  rust_dependency_map          : dict[str]                                                               # On rust targets this provides a map of library names to the crate name
  sources                      : str | file | custom_tgt | custom_idx | generated_list | structured_src  # Additional source files
  soversion                    : str | int                                                               # A string or integer specifying the soversion of this shared library,
  vala_args                    : list[str | file]                                                        # Compiler flags for Vala
  vala_shared_args             : list[str | file]                                                        # Arguments that are only passed to a shared library
  vala_static_args             : list[str | file]                                                        # Arguments that are only passed to a static library
  version                      : str                                                                     # A string specifying the version of this shared library,
  vs_module_defs               : str | file | custom_tgt | custom_idx                                    # Specify a Microsoft module definition file for controlling symbol exports,
  win_subsystem                : str                                                                     # Specifies the subsystem type to use
)

參數

函式 both_libraries() 接受以下位置引數：

此外，函式還接受介於 0 和 無限 個變數引數 (source...)，其類型為 str | file | custom_tgt | custom_idx | generated_list。

要編譯的輸入原始碼。支援以下類型：

• 相對於目前原始碼目錄的字串
• 在任何先前的建置檔案中定義的 file 物件
• 組態時間產生器的傳回值，例如 configure_file()
• 建置時間產生器的傳回值，例如 custom_target() 或 generator.process()

這些輸入檔案可以是原始碼、物件、程式庫或任何其他檔案。Meson 會根據副檔名自動對其進行分類並相應地使用它們。例如，原始碼 (.c、.cpp、.vala、.rs 等) 會被編譯，而物件 (.o、.obj) 和程式庫 (.so、.dll 等) 會被連結。

使用 Ninja 後端，Meson 將在所有產生的輸入檔案上建立建置時間的 僅順序相依性，包括未知的檔案。這是為了引導在您的編譯器產生的 depfile 中產生實際的相依性，以判斷何時重建原始碼。Ninja 依賴此相依性檔案來處理所有輸入檔案，無論是產生的還是非產生的。其他後端的行為類似。

最後，both_libraries() 接受以下關鍵字引數：

build_target()

建立一個建置目標，其類型可以使用 target_type 關鍵字引數動態設定。

target_type 可以設定為下列其中一個

• executable (請參閱 executable())
• shared_library (請參閱 shared_library())
• shared_module (請參閱 shared_module())
• static_library (請參閱 static_library())
• both_libraries (請參閱 both_libraries())
• library (請參閱 library())
• jar (請參閱 jar())*

此宣告

executable(<arguments and keyword arguments>)

等效於此

build_target(<arguments and keyword arguments>, target_type : 'executable')

kwargs 的列表 (例如 sources、objects 和 dependencies) 永遠會被扁平化，這表示您可以在建立最終列表時自由地巢狀和新增列表。

傳回的物件也具有在 build_tgt 中記載的方法。

*"jar" 已過時，因為它在本質上與其他 build_target 類型不同。

# Creates a build target whose type can be set dynamically with the
build_tgt build_target(
  str                                                   target_name,     # The *unique* name of the build target
  str | file | custom_tgt | custom_idx | generated_list source...,       # Input source to compile

  # Keyword arguments:
  <lang>_args                  : list[str]                                                               # compiler flags to use for the given language;
  <lang>_pch                   : str                                                                     # precompiled header file to use for the given language
  <lang>_shared_args           : list[str]                                                               # Arguments that are only passed to a shared library
  <lang>_static_args           : list[str]                                                               # Arguments that are only passed to a static library
  build_by_default             : bool                                                                    # Causes, when set to `true`, to have this target be built by default
  build_rpath                  : str                                                                     # A string to add to target's rpath definition in the build dir,
  d_debug                      : list[str]                                                               # The [D version identifiers](https://dlang
  d_import_dirs                : list[inc | str]                                                         # the directories to add to the string search path (i
  d_module_versions            : list[str | int]                                                         # List of module version identifiers set when compiling D sources
  d_unittest                   : bool                                                                    # When set to true, the D modules are compiled in debug mode
  darwin_versions              : str | int | list[str]                                                   # Defines the `compatibility version` and `current version` for the dylib on macOS
  dependencies                 : list[dep]                                                               # one or more dependency objects
  export_dynamic               : bool                                                                    # when set to true causes the target's symbols to be
  extra_files                  : str | file | custom_tgt | custom_idx                                    # Not used for the build itself but are shown as source files in IDEs
  gnu_symbol_visibility        : str                                                                     # Specifies how symbols should be exported, see
  gui_app                      : bool                                                                    # When set to true flags this target as a GUI application
  implib                       : bool | str                                                              # When set to true, an import library is generated for the
  implicit_include_directories : bool                                                                    # Controls whether Meson adds the current source and build directories to the include path
  include_directories          : list[inc | str]                                                         # one or more objects created with the include_directories() function,
  install                      : bool                                                                    # When set to true, this executable should be installed
  install_dir                  : str                                                                     # override install directory for this file
  install_mode                 : list[str | int]                                                         # Specify the file mode in symbolic format
  install_rpath                : str                                                                     # A string to set the target's rpath to after install
  install_tag                  : str                                                                     # A string used by the `meson install --tags` command
  java_resources               : structured_src                                                          # Resources to be added to the jar
  link_args                    : list[str]                                                               # Flags to use during linking
  link_depends                 : str | file | custom_tgt | custom_idx                                    # Strings, files, or custom targets the link step depends on
  link_language                : str                                                                     # Makes the linker for this target be for the specified language
  link_whole                   : list[lib | custom_tgt | custom_idx]                                     # Links all contents of the given static libraries whether they are used or
  link_with                    : list[lib | custom_tgt | custom_idx]                                     # One or more shared or static libraries
  main_class                   : str                                                                     # Main class for running the built jar
  name_prefix                  : str | list[void]                                                        # The string that will be used as the prefix for the
  name_suffix                  : str | list[void]                                                        # The string that will be used as the extension for the
  native                       : bool                                                                    # Controls whether the target is compiled for the build or host machines
  objects                      : list[extracted_obj | file | str]                                        # List of object files that should be linked in this target
  override_options             : list[str] | dict[str | bool | int | list[str]]                            # takes an array of strings in the same format as `project`'s `default_options`
  pic                          : bool                                                                    # Builds the library as positional independent code
  pie                          : bool                                                                    # Build a position-independent executable
  prelink                      : bool                                                                    # If `true` the object files in the target will be prelinked,
  rust_abi                     : str                                                                     # Set the specific ABI to compile (when compiling rust)
  rust_crate_type              : str                                                                     # Set the specific type of rust crate to compile (when compiling rust)
  rust_dependency_map          : dict[str]                                                               # On rust targets this provides a map of library names to the crate name
  sources                      : str | file | custom_tgt | custom_idx | generated_list | structured_src  # Additional source files
  soversion                    : str | int                                                               # A string or integer specifying the soversion of this shared library,
  target_type                  : str                                                                     # The actual target type to build
  vala_args                    : list[str | file]                                                        # Compiler flags for Vala
  vala_shared_args             : list[str | file]                                                        # Arguments that are only passed to a shared library
  vala_static_args             : list[str | file]                                                        # Arguments that are only passed to a static library
  version                      : str                                                                     # A string specifying the version of this shared library,
  vs_module_defs               : str | file | custom_tgt | custom_idx                                    # Specify a Microsoft module definition file for controlling symbol exports,
  win_subsystem                : str                                                                     # Specifies the subsystem type to use
)

參數

函數 build_target() 接受以下位置引數

此外，函式還接受介於 0 和 無限 個變數引數 (source...)，其類型為 str | file | custom_tgt | custom_idx | generated_list。

要編譯的輸入原始碼。支援以下類型：

• 相對於目前原始碼目錄的字串
• 在任何先前的建置檔案中定義的 file 物件
• 組態時間產生器的傳回值，例如 configure_file()
• 建置時間產生器的傳回值，例如 custom_target() 或 generator.process()

這些輸入檔案可以是原始碼、物件、程式庫或任何其他檔案。Meson 會根據副檔名自動對其進行分類並相應地使用它們。例如，原始碼 (.c、.cpp、.vala、.rs 等) 會被編譯，而物件 (.o、.obj) 和程式庫 (.so、.dll 等) 會被連結。

使用 Ninja 後端，Meson 將在所有產生的輸入檔案上建立建置時間的 僅順序相依性，包括未知的檔案。這是為了引導在您的編譯器產生的 depfile 中產生實際的相依性，以判斷何時重建原始碼。Ninja 依賴此相依性檔案來處理所有輸入檔案，無論是產生的還是非產生的。其他後端的行為類似。

最後，build_target() 接受以下關鍵字引數

configuration_data()

建立空的組態物件。您應該使用 cfg_data 方法呼叫新增組態，最後在呼叫 configure_file() 時使用它。

# Creates an empty configuration object
cfg_data configuration_data(
  dict[str | bool | int] [data],   # Optional dictionary to specify an initial data set
)

參數

函數 configuration_data() 接受以下位置引數

configure_file()

此函式可以根據傳遞給它的關鍵字參數以三種模式執行。

當將 cfg_data 物件傳遞給 configuration: 關鍵字參數時，它會使用樣板檔案作為 input:（可選），並根據 組態檔案文件中詳述的方式，將組態資料中的值代入，產生 output:（必要）。(自 0.49.0 起) 可以傳遞字典來代替 cfg_data 物件。

當將字串列表傳遞給 command: 關鍵字參數時，它會使用任何來源或已組態的檔案作為 input:，並假設執行指定的命令時會產生 output:。

(自 0.47.0 起) 當 copy: 關鍵字參數設定為 true 時，此函式會將 input: 中提供的檔案複製到建置目錄中，並將其命名為目前目錄中的 output:。

# This function can run in three modes depending on the keyword arguments
file configure_file(
  capture       : bool                               # When this argument is set to true,
  command       : list[str | file]                   # As explained above, if specified, Meson does not create
  configuration : cfg_data | dict[str | int | bool]  # As explained above, when passed this will provide the replacement
  copy          : bool                               # As explained above, if specified Meson only
  depfile       : str                                # A dependency file that the command can write listing
  encoding      : str                                # Set the file encoding for the input and output file
  format        : str                                # The format of defines
  input         : str | file                         # The input file name
  install       : bool                               # When true, this generated file is installed during
  install_dir   : str                                # The subdirectory to install the generated file to
  install_mode  : list[str | int]                    # Specify the file mode in symbolic format
  install_tag   : str                                # A string used by the `meson install --tags` command
  macro_name    : str                                # When specified, macro guards will be used instead of '#pragma once'
  output        : str                                # The output file name
  output_format : str                                # The format of the output to generate when no input
)

參數

函式 configure_file() 接受以下關鍵字參數

custom_target()

建立自訂的頂層建置目標。唯一的位置引數是此目標的名稱，且不能包含路徑分隔符號 (/ 或 \)。並非所有後端都可能使用自訂目標的名稱，例如，使用 Ninja 後端時，subdir/meson.build 包含以下範例，ninja -C builddir foo 或 ninja -C builddir subdir/foo 將無法運作，而應使用 ninja -C builddir subdir/file.txt。不過，接受 meson compile subdir/foo。

custom_target('foo', output: 'file.txt', ...)

自 0.60.0 起，name 引數為可選，預設為第一個輸出的基本名稱 (在上述範例中為 file.txt)。

傳遞給 command 關鍵字引數的字串清單接受以下特殊字串取代

• @INPUT@：傳遞給 input 的輸入完整路徑。如果指定多個輸入，則只有當命令使用 '@INPUT@' 作為獨立引數時，才會將它們全部取代為個別引數。例如，這不會運作：command : ['cp', './@INPUT@']，但是這會：command : ['cp', '@INPUT@']。
• @OUTPUT@：傳遞給 output 的輸出完整路徑。如果指定多個輸出，則行為與 @INPUT@ 相同。
• @INPUT0@ @INPUT1@ ...：輸入中具有指定陣列索引的輸入完整路徑 input
• @OUTPUT0@ @OUTPUT1@ ...：輸出中具有指定陣列索引的輸出完整路徑 output
• @OUTDIR@：必須寫入輸出所在的目錄的完整路徑
• @DEPFILE@：傳遞給 depfile 的相依性檔案的完整路徑
• @PLAINNAME@：輸入檔名，不含路徑
• @PLAINNAME0@ @PLAINNAME1@ ... (自 1.5.0 起)：輸入檔名不含路徑，在 input 中具有指定的陣列索引
• @BASENAME@：輸入檔名，已移除副檔名
• @BASENAME0@ @BASENAME1@ ... (自 1.5.0 起)：輸入檔名已移除副檔名，在 input 中具有指定的陣列索引
• @PRIVATE_DIR@ (自 0.50.1 起)：自訂目標必須儲存其所有中繼檔案的目錄路徑。
• @SOURCE_ROOT@：來源樹根目錄的路徑。根據後端而定，這可能是絕對路徑或相對於目前工作目錄的路徑。
• @BUILD_ROOT@：建置樹根目錄的路徑。根據後端而定，這可能是絕對路徑或相對於目前工作目錄的路徑。
• @CURRENT_SOURCE_DIR@：這是目前處理的 meson.build 所在目錄。根據後端而定，這可能是絕對路徑或相對於目前工作目錄的路徑。

(自 0.47.0 起) depfile 關鍵字引數也接受 @BASENAME@ 和 @PLAINNAME@ 取代。

傳回的物件也有 custom_tgt 中記錄的方法。

# Create a custom top level build target
custom_tgt custom_target(
  str [name],   # The *unique* id of the custom target

  # Keyword arguments:
  build_always       : bool                                       # If `true` this target is always considered out of
  build_always_stale : bool                                       # If `true` the target is always considered out of date
  build_by_default   : bool                                       # Causes, when set to true, to
  capture            : bool                                       # There are some compilers that can't be told to write
  command            : list[str | file | exe | external_program]  # Command to run to create outputs from inputs
  console            : bool                                       # Keyword argument conflicts with `capture`, and is meant
  depend_files       : list[str | file]                           # files (str,
  depends            : list[build_tgt | custom_tgt | custom_idx]  # Specifies that this target depends on the specified
  depfile            : str                                        # A dependency file that the command can write listing
  env                : env | list[str] | dict[str]                # environment variables to set, such as
  feed               : bool                                       # There are some compilers that can't be told to read
  input              : list[str | file]                           # List of source files
  install            : bool                                       # When true, one or more files of this target are installed during the install step (see `install_dir` for details)
  install_dir        : str | list[str | bool]                     # If only one install_dir is provided, all outputs are installed there
  install_mode       : list[str | int]                            # The file mode and optionally the owner/uid and group/gid
  install_tag        : list[str]                                  # A list of strings, one per output, used by the `meson install --tags` command
  output             : list[str]                                  # List of output files
)

參數

函式 custom_target() 接受以下位置引數

最後，custom_target() 接受以下關鍵字引數

custom_target('different-install-dirs',
  output : ['first.file', 'second.file'],
  install : true,
  install_dir : ['somedir', 'otherdir'])

    custom_target('only-install-second',
      output : ['first.file', 'second.file'],
      install : true,
      install_dir : [false, 'otherdir'])

debug()

將引數字串寫入 meson 建置記錄。

# Write the argument string to the meson build log
void debug(
  str | int | bool | list[str | int | bool] | dict[str | int | bool] message,     # The message to print
  str | int | bool | list[str | int | bool] | dict[str | int | bool] msg...,      # Additional parameters will be separated by spaces
)

參數

函式 debug() 接受以下位置引數

此外，此函式接受介於 0 和 infinity 之間的變數引數 (msg...)，類型為 str | int | bool | list[str | int | bool] | dict[str | int | bool]。

其他參數將以空格分隔

declare_dependency()

此函式會傳回一個 dep 物件，其行為類似於 dependency() 的傳回值，但屬於目前建置的內部。此物件的主要用例是在子專案中。這允許子專案輕鬆指定應如何使用它。這使其可與系統外部提供的相同相依性互換。

# This function returns a dep object that
dep declare_dependency(
  compile_args        : list[str]                                                    # Compile arguments to use
  d_import_dirs       : list[inc | str]                                              # the directories to add to the string search path (i
  d_module_versions   : str | int | list[str | int]                                  # The [D version identifiers](https://dlang
  dependencies        : list[dep]                                                    # Other dependencies needed to use this dependency
  extra_files         : list[str | file]                                             # extra files to add to targets
  include_directories : list[inc | str]                                              # the directories to add to header search path,
  link_args           : list[str]                                                    # Link arguments to use
  link_whole          : list[lib]                                                    # Libraries to link fully, same as executable().
  link_with           : list[lib]                                                    # Libraries to link against
  objects             : list[extracted_obj]                                          # a list of object files, to be linked directly into the targets that use the
  sources             : list[str | file | custom_tgt | custom_idx | generated_list]  # sources to add to targets
  variables           : dict[str] | list[str]                                        # a dictionary of arbitrary strings,
  version             : str                                                          # the version of this dependency,
)

參數

函式 declare_dependency() 接受以下關鍵字引數

dependency()

使用給定的名稱透過 pkg-config 和 使用 CMake (如果 pkg-config 失敗) 尋找外部相依性 (通常是安裝在您系統上的程式庫)。此外，還支援框架 (僅限 OSX) 和特定於程式庫的回退偵測邏輯。

自 0.60.0 起 可以提供多個名稱，它們會依序嘗試，並且會使用找到的第一個名稱。僅當系統上找不到任何名稱時，才會使用回退子專案。一旦找到其中一個名稱，所有其他名稱都會新增到快取中，以便後續對這些名稱的任何呼叫都將傳回相同的值。如果相依性可能具有不同的名稱 (例如 png 和 libpng)，這會很有用。

• 自 0.64.0 起，可以由 WrapDB 提供相依性回退。只需使用 meson wrap update-db 命令在本機下載資料庫，如果系統上找不到相依性且專案未運送自己的 .wrap 檔案，Meson 會自動回退到 WrapDB 提供的子專案。

也可以透過其他兩種方式解析相依性

• 如果在呼叫 dependency 之前在 meson.override_dependency 中使用了相同的名稱，則會無條件傳回覆寫相依性；也就是說，無論系統中是否安裝外部相依性，都會使用覆寫相依性。通常，子專案會使用 meson.override_dependency。

• 透過回退子專案，如果需要，會將其帶入目前的建置規格，就像呼叫了 subproject() 一樣。可以使用 fallback 引數指定子專案。或者，如果缺少 fallback 引數，自 0.55.0 起，如果 wrap 檔案提供相依性，或者子專案的名稱與相依性相同，則 Meson 可以自動識別子專案作為回退。在後一種情況下，子專案必須使用 meson.override_dependency 來指定替換，否則 Meson 會報告硬性錯誤。如需更多詳細資訊，請參閱 Wrap 文件。可以使用 allow_fallback 關鍵字引數來控制此自動搜尋。

如果 dependency_name 是 ''，則永遠找不到相依性。因此，在 required: false 的情況下，這會永遠回傳一個相依性物件，其 found() 方法會回傳 false，並且可以像其他相依性一樣傳遞給 build_target 的 dependencies: 關鍵字引數。這可以用來實作有時不需要的相依性，例如在條件式的某些分支中，或者使用 fallback: 關鍵字引數，可以用來宣告一個可選的相依性，該相依性僅在指定的子專案中尋找，而且僅在 --wrap-mode 允許的情況下才會尋找。

回傳的物件 dep 也具有其他方法。

# Finds an external dependency (usually a library installed on your
dep dependency(
  str names...,  # The names of the dependency to look up

  # Keyword arguments:
  allow_fallback    : bool                                          # Specifies whether Meson should automatically pick a fallback subproject
  default_options   : list[str] | dict[str | bool | int | list[str]]  # An array of default option values
  disabler          : bool                                          # Returns a disabler() object instead of a not-found dependency
  fallback          : list[str] | str                               # Manually specifies a subproject fallback
  include_type      : str                                           # An enum flag, marking how the dependency
  language          : str                                           # Defines what language-specific dependency to find
  method            : str                                           # Defines the way the dependency is detected, the default is
  native            : bool                                          # If set to `true`, causes Meson to find the dependency on
  not_found_message : str                                           # An optional string that will be printed as a message() if the dependency was not found.
  required          : bool | feature                                # When set to `false`, Meson will proceed with the build
  static            : bool                                          # Tells the dependency provider to try to get static
  version           : list[str] | str                               # Specifies the required version,
)

參數

此函式接受 1 到 無限 個可變引數 (names...)，類型為 str。

要查找的相依性名稱。相依性會按照此處提供的順序查找。將會使用第一個找到的相依性。只有在系統上找不到任何名稱時，才會使用後備子專案。一旦找到其中一個名稱，所有其他名稱都會被新增到快取中，因此後續對這些名稱的任何呼叫都將回傳相同的值。如果相依性可能有不同的名稱，例如 png 和 libpng，這會很有用。

注意： 在 0.60.0 之前，只允許單一相依性名稱。

函式 dependency() 接受以下關鍵字引數

disabler()

回傳 disabler 物件。

disabler disabler()

environment()

回傳空的 env 物件。

# Returns an empty env object.
env environment(
  str | list[str] | dict[str] | dict[list[str]] [env],   # If provided, each key/value pair is added into the env object

  # Keyword arguments:
  method    : str  # Must be one of 'set', 'prepend', or 'append'
  separator : str  # The separator to use for the initial values defined in
)

參數

此函式不支援引數扁平化。

函式 environment() 接受以下位置引數

最後，environment() 接受以下關鍵字引數

error()

列印引數字串並停止組建程序。

# Print the argument string and halts the build process
void error(
  str message,     # The message to print
  str msg...,      # Additional parameters will be separated by spaces
)

參數

此函式不支援引數扁平化。

函式 error() 接受以下位置引數

此外，該函式接受 0 到 無限 個可變引數 (msg...)，類型為 str。

其他參數將以空格分隔

executable()

建立新的可執行檔。第一個引數指定其名稱，其餘的位置引數定義要使用的輸入檔案。

kwargs 的列表 (例如 sources、objects 和 dependencies) 永遠會被扁平化，這表示您可以在建立最終列表時自由地巢狀和新增列表。

回傳的物件也具有在 exe 中記載的方法。

自 1.3.0 起，只要每個可執行檔都有不同的 name_suffix，就可以在多個目標之間使用相同的可執行檔名稱。

# Creates a new executable
exe executable(
  str                                                   target_name,     # The *unique* name of the build target
  str | file | custom_tgt | custom_idx | generated_list source...,       # Input source to compile

  # Keyword arguments:
  <lang>_args                  : list[str]                                                               # compiler flags to use for the given language;
  <lang>_pch                   : str                                                                     # precompiled header file to use for the given language
  build_by_default             : bool                                                                    # Causes, when set to `true`, to have this target be built by default
  build_rpath                  : str                                                                     # A string to add to target's rpath definition in the build dir,
  d_debug                      : list[str]                                                               # The [D version identifiers](https://dlang
  d_import_dirs                : list[inc | str]                                                         # the directories to add to the string search path (i
  d_module_versions            : list[str | int]                                                         # List of module version identifiers set when compiling D sources
  d_unittest                   : bool                                                                    # When set to true, the D modules are compiled in debug mode
  dependencies                 : list[dep]                                                               # one or more dependency objects
  export_dynamic               : bool                                                                    # when set to true causes the target's symbols to be
  extra_files                  : str | file | custom_tgt | custom_idx                                    # Not used for the build itself but are shown as source files in IDEs
  gnu_symbol_visibility        : str                                                                     # Specifies how symbols should be exported, see
  gui_app                      : bool                                                                    # When set to true flags this target as a GUI application
  implib                       : bool | str                                                              # When set to true, an import library is generated for the
  implicit_include_directories : bool                                                                    # Controls whether Meson adds the current source and build directories to the include path
  include_directories          : list[inc | str]                                                         # one or more objects created with the include_directories() function,
  install                      : bool                                                                    # When set to true, this executable should be installed
  install_dir                  : str                                                                     # override install directory for this file
  install_mode                 : list[str | int]                                                         # Specify the file mode in symbolic format
  install_rpath                : str                                                                     # A string to set the target's rpath to after install
  install_tag                  : str                                                                     # A string used by the `meson install --tags` command
  link_args                    : list[str]                                                               # Flags to use during linking
  link_depends                 : str | file | custom_tgt | custom_idx                                    # Strings, files, or custom targets the link step depends on
  link_language                : str                                                                     # Makes the linker for this target be for the specified language
  link_whole                   : list[lib | custom_tgt | custom_idx]                                     # Links all contents of the given static libraries whether they are used or
  link_with                    : list[lib | custom_tgt | custom_idx]                                     # One or more shared or static libraries
  name_prefix                  : str | list[void]                                                        # The string that will be used as the prefix for the
  name_suffix                  : str | list[void]                                                        # The string that will be used as the extension for the
  native                       : bool                                                                    # Controls whether the target is compiled for the build or host machines
  objects                      : list[extracted_obj | file | str]                                        # List of object files that should be linked in this target
  override_options             : list[str] | dict[str | bool | int | list[str]]                            # takes an array of strings in the same format as `project`'s `default_options`
  pie                          : bool                                                                    # Build a position-independent executable
  rust_crate_type              : str                                                                     # Set the specific type of rust crate to compile (when compiling rust)
  rust_dependency_map          : dict[str]                                                               # On rust targets this provides a map of library names to the crate name
  sources                      : str | file | custom_tgt | custom_idx | generated_list | structured_src  # Additional source files
  vala_args                    : list[str | file]                                                        # Compiler flags for Vala
  vs_module_defs               : str | file | custom_tgt | custom_idx                                    # Specify a Microsoft module definition file for controlling symbol exports,
  win_subsystem                : str                                                                     # Specifies the subsystem type to use
)

參數

函式 executable() 接受以下位置引數

此外，函式還接受介於 0 和 無限 個變數引數 (source...)，其類型為 str | file | custom_tgt | custom_idx | generated_list。

要編譯的輸入原始碼。支援以下類型：

• 相對於目前原始碼目錄的字串
• 在任何先前的建置檔案中定義的 file 物件
• 組態時間產生器的傳回值，例如 configure_file()
• 建置時間產生器的傳回值，例如 custom_target() 或 generator.process()

這些輸入檔案可以是原始碼、物件、程式庫或任何其他檔案。Meson 會根據副檔名自動對其進行分類並相應地使用它們。例如，原始碼 (.c、.cpp、.vala、.rs 等) 會被編譯，而物件 (.o、.obj) 和程式庫 (.so、.dll 等) 會被連結。

使用 Ninja 後端，Meson 將在所有產生的輸入檔案上建立建置時間的 僅順序相依性，包括未知的檔案。這是為了引導在您的編譯器產生的 depfile 中產生實際的相依性，以判斷何時重建原始碼。Ninja 依賴此相依性檔案來處理所有輸入檔案，無論是產生的還是非產生的。其他後端的行為類似。

最後，executable() 接受以下關鍵字引數

files()

此命令會取得在引數中給定的字串，並回傳對應的 File 物件，您可以用作組建目標的來源。不同之處在於，檔案物件會記住它們定義所在的子目錄，並且可以在來源樹中的任何位置使用。

# This command takes the strings given to it in arguments and returns
list[file] files(
  str file...,  # Path to the file
)

範例

舉例來說，假設您在子目錄 bar1 中有一個來源檔案 foo.cpp，並且您想在 bar2 中定義的組建目標中使用它。若要實現此目的，您首先在 bar1 中建立物件，如下所示

    foofile = files('foo.cpp')

然後，您可以在 bar2 中使用它，如下所示

    executable('myprog', 'myprog.cpp', foofile, ...)

Meson 接著會做正確的事情。

參數

此函式接受 0 到 無限 個可變引數 (file...)，類型為 str。

檔案的路徑。

find_program()

這裡的 program_name 是一個字串，它可以是要在 PATH 或專案內其他地方搜尋的可執行檔或腳本。搜尋順序如下：

1. 透過 meson.override_find_program() 設定的程式覆寫。
2. 子專案 wrap 檔案中的 [provide] 區塊，如果 wrap_mode 設定為 forcefallback。
3. 機器檔案中的 [binaries] 區塊。
4. 使用 dirs: kwarg 提供的目錄（見下文）。
5. 相對於目前子目錄的專案原始碼樹。
   • 如果您使用 configure_file() 的回傳值，則會改用建置樹內的目前子目錄。
6. PATH 環境變數。
7. 子專案 wrap 檔案中的 [provide] 區塊，如果 wrap_mode 設定為除 nofallback 以外的任何值。

Meson 也會自動偵測具有 shebang 行的腳本，並在 Windows（因為命令呼叫器會拒絕該命令）和 Unix（如果腳本檔案未設定執行位元）上，使用其中指定的執行檔/解譯器執行它們。因此，當使用此腳本作為命令清單的一部分時，您*必須不要*手動新增解譯器。自 *0.50.0* 起，如果請求 "python3" 程式且在系統中找不到，Meson 將會回傳其目前的解譯器。

如果您需要在非標準位置檢查程式，您可以將絕對路徑傳遞給 find_program，例如：

setcap = find_program('setcap', '/usr/sbin/setcap', '/sbin/setcap', required : false)

如果需要動態建構要搜尋的路徑集合，也可以將陣列傳遞給 find_program。

setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false)

自 1.2.0 起，find_program('meson') 會自動覆寫為用於執行建置腳本的 Meson 命令。

回傳的 external_program 物件也有記載的方法。

# `program_name` here is a string that can be an executable or script
external_program find_program(
  str | file program_name,     # The name of the program to search, or a file object to be used
  str | file fallback...,      # These parameters are used as fallback names to search for

  # Keyword arguments:
  default_options  : list[str] | dict[str | bool | int | list[str]]  # An array of default option values
  dirs             : list[str]                                     # extra list of absolute paths where to look for program names
  disabler         : bool                                          # If `true` and the program couldn't be found, return a disabler object
  native           : bool                                          # Defines how this executable should be searched
  required         : bool | feature                                # When `true`, Meson will abort if no program can be found
  version          : str | list[str]                               # Specifies the required version, see
  version_argument : str                                           # Specifies the argument to pass when trying to find the version of the program
)

參數

函式 find_program() 接受以下位置參數：

此外，函式接受 0 到 infinity 個可變參數 (fallback...)，類型為 str | file。

這些參數用作要搜尋的回退名稱。這用於程式可能有多個替代名稱的情況，例如 foo 和 foo.py。函式會逐一檢查這些參數，並回傳找到的第一個。

最後，find_program() 接受以下關鍵字參數：

generator()

另請參閱：custom_target()

此函式會建立 generator 物件，該物件可用於執行自訂編譯命令。唯一的位置引數是要使用的可執行檔。它可以是自行建置的可執行檔，也可以是 find_program 回傳的可執行檔。

傳遞給所有關鍵字引數的範本字串接受以下特殊取代：

• @PLAINNAME@：完整的輸入檔案名稱，例如：foo.c 變成 foo.c（未變更）。
• @BASENAME@：輸入檔案名稱的基底名稱，例如：foo.c.y 變成 foo.c（移除副檔名）。

傳遞給 output 關鍵字引數的每個字串*必須*使用這兩個取代之一或兩個來建構。

除了上述取代之外，arguments 關鍵字引數也接受以下取代：

• @OUTPUT@：輸出檔案的完整路徑。
• @INPUT@：輸入檔案的完整路徑。
• @DEPFILE@：depfile 的完整路徑。
• @SOURCE_DIR@：原始碼樹根目錄的完整路徑。
• @CURRENT_SOURCE_DIR@：這是目前處理的 meson.build 所在的目錄。
• @BUILD_DIR@：將放置輸出的建置目錄根目錄的完整路徑。

注意：產生器只能用於 *僅* 用作 build_target() 或 custom_target() 輸入的輸出。當您在多個目標中使用產生器的處理輸出時，產生器將會執行多次，以為每個目標建立輸出。每個輸出都將在目標私有目錄 @BUILD_DIR@ 中建立。

如果您想要產生用於通用目的的檔案，例如產生要由多個來源使用的標頭，或將要安裝的資料等等，請改用 custom_target()。

# See also: custom_target()
generator generator(
  exe | external_program exe,     # Executable for the command to run

  # Keyword arguments:
  arguments : list[str]                                  # A list of template strings that will be the command line arguments passed to the executable
  capture   : bool                                       # When this argument is set to true, Meson captures `stdout`
  depends   : list[build_tgt | custom_tgt | custom_idx]  # An array of build targets that must be built before
  depfile   : str                                        # A template string pointing to a dependency file that a
  output    : list[str]                                  # Template string (or list of template strings) defining
)

參數

函式 generator() 接受以下位置引數：

最後，generator() 接受以下關鍵字引數：