函数

本文档列出了 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 到 无穷大 之间的可变参数 (编译器参数...)，类型为 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 到 无穷大 之间的可变参数 (链接器参数...)，类型为 str。

要添加的链接器参数

函数 add_global_link_arguments() 接受以下关键字参数

add_languages()

添加项目使用的编程语言。

这等效于在 project 声明中包含它们。此函数通常用于添加仅在某些条件下使用的语言。

如果找到所有指定的语言，则返回 true，否则返回 false。

如果省略 native，则语言可用于构建或主机机器，但绝不强制用于构建机器。 (即它等效于 add_languages(*langs*, native: false, required: *required*) and add_languages(*langs*, native: true, required: false)。此默认行为可能会更改为 native: false 在未来的 Meson 版本中。

# 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 到 无穷大 之间的可变参数 (语言...)，类型为 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 到 无穷大 之间的可变参数 (编译器参数...)，类型为 str。

要添加的编译器参数

函数 add_project_arguments() 接受以下关键字参数

add_project_dependencies()

向编译器和链接器命令行添加参数，以便将给定的依赖项集包含在此项目的 tất cả 产品构建中。

# 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 到 无穷大 之间的可变参数 (依赖项...)，类型为 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 到 无穷大 之间的可变参数 (链接器参数...)，类型为 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 到 无穷大 之间的可变参数 (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 到 infinity 之间的可变参数（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 将在构建时为所有生成的输入文件（包括未知文件）创建 顺序依赖项。这是在 依赖文件 中生成真正的依赖项所需的，该依赖文件由编译器生成，以确定何时重建源代码。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 到 infinity 之间的可变参数（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 将在构建时为所有生成的输入文件（包括未知文件）创建 顺序依赖项。这是在 依赖文件 中生成真正的依赖项所需的，该依赖文件由编译器生成，以确定何时重建源代码。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 版本开始，名称参数是可选的，默认为第一个输出的基名（以上示例中的 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 查找具有给定名称的外部依赖项（通常是安装在系统上的库），如果 pkg-config 失败，则使用 CMake。此外，框架（仅限 OSX）和 特定于库的回退检测逻辑 也受支持。

从 0.60.0 开始，可以提供多个名称，它们将按顺序尝试，找到的第一个名称将被使用。只有当系统上没有找到任何名称时，才会使用回退子项目。一旦找到一个名称，所有其他名称都将被添加到缓存中，因此对任何这些名称的后续调用都将返回相同的值。这在依赖项可能具有不同名称（例如 png 和 libpng）的情况下非常有用。

• 从 0.64.0 开始，WrapDB 可以提供依赖项回退。只需使用 meson wrap update-db 命令在本地下载数据库，Meson 就会在系统上找不到依赖项并且项目没有提供自己的 .wrap 文件时，自动回退到 WrapDB 提供的子项目。

依赖项也可以通过两种其他方式解决

• 如果在调用 dependency 之前在 meson.override_dependency 中使用了相同的名称，则将无条件返回覆盖依赖项；也就是说，覆盖依赖项将被使用，无论系统中是否安装了外部依赖项。通常，meson.override_dependency 将由子项目使用。

• 通过回退子项目，如果需要，它将被引入当前构建规范中，就像调用了 subproject() 一样。可以使用 fallback 参数指定子项目。或者，如果缺少 fallback 参数，从 0.55.0 开始，如果一个包装文件 提供 依赖项，或者如果子项目的名称与依赖项相同，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 到 infinity 之间的可变参数 (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 到 infinity 个可变参数（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 到 infinity 之间的可变参数（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 将在构建时为所有生成的输入文件（包括未知文件）创建 顺序依赖项。这是在 依赖文件 中生成真正的依赖项所需的，该依赖文件由编译器生成，以确定何时重建源代码。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 到 infinity 个可变参数（file...），其类型为 str。

文件的路径。

find_program()

program_name 这里是一个字符串，可以是可执行文件或脚本，在 PATH 或项目中的其他位置进行搜索。搜索顺序为：

1. 通过 meson.override_find_program() 设置的程序覆盖
2. 子项目包装文件中 [provide] 部分，如果 wrap_mode 设置为 forcefallback
3. 机器文件中 [binaries] 部分
4. 使用 dirs: 关键字参数提供的目录（见下文）
5. 相对于当前子目录的项目的源代码树
   • 如果使用 configure_file() 的返回值，则使用构建树中的当前子目录。
6. PATH 环境变量
7. 子项目包装文件中 [provide] 部分，如果 wrap_mode 设置为除 nofallback 以外的任何值

Meson 还会自动检测带有 shebang 行的脚本，并在 Windows（因为命令调用程序将拒绝该命令）和 Unixes（如果脚本文件没有设置可执行位）上使用其中指定的可执行文件/解释器运行它们。因此，您必须不要在将此脚本用作命令列表的一部分时手动添加解释器。从 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@：依赖文件的完整路径
• @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() 接受以下位置参数