向 Meson 传递参数

meson-python 调用 meson setup、ninja 和 meson install 命令来构建将包含在 Python wheel 中的文件，并调用 meson dist 来收集将包含在 Python sdist 中的文件。可以向这些命令传递参数来修改它们的行为。有关详细信息，请参阅 Meson 文档 和 ninja 文档。

可以 pyproject.toml 中的工具特定设置以字符串列表形式指定 meson 和 ninja 的命令行参数，用于 tool.meson-python.args 表中的 setup、compile、install 和 dist 键。例如

[tool.meson-python.args]
setup = ['-Doption=false', '-Dfeature=enabled', '-Dvalue=42']
compile = ['-j4']
install = ['--tags=bindings']
dist = ['--include-subprojects']

或者可以通过 Python 构建前端传递的配置设置以 setup-args、compile-args、install-args 和 dist-args 配置设置 指定。通过 Python 构建前端指定的配置设置优先于 pyproject.toml 中指定的设置，并且可以用来覆盖它们。

meson-python 使用 设置 覆盖一些默认的 Meson 选项，这些设置更适合构建 Python wheel。用户通过 pyproject.toml 或通过 Python 构建前端配置设置指定的选项将覆盖 meson-python 的默认设置。

在 Windows 上构建时，meson-python 通过 meson compile 包装器调用 ninja 命令。当在 $PATH 上找不到 GCC 或 LLVM 编译器时，这将激活 Visual Studio 环境，并允许 ninja 使用 MSVC 编译器。要无条件激活 Visual Studio 环境，请将 --vsenv 选项传递给 meson setup，请参见此 示例。使用 meson compile 包装器时，用户为编译命令提供的选项将通过 --ninja-args 选项传递。这确保了行为独立于构建的启动方式。有关详细信息，请参阅 Meson 文档。

示例

将默认库设置为静态

在构建二进制 wheel 时将默认库类型设置为静态。

要在项目的 pyproject.toml 中永久设置此选项

[tool.meson-python.args]
setup = ['--default-library=static']

要在构建时临时设置此选项

$ python -m build -Csetup-args="--default-library=static" .

$ python -m pip wheel --config-settings=setup-args="--default-library=static" .

选择要包含在 wheel 中的构建目标

可以使用 Meson 安装标签 通过 meson install 的 --tags 命令行选项将 Python wheel 中包含的可安装文件子集。当指定 --tags 时，只有具有指定标签之一的文件才会被安装。

Meson 在某些文件上设置预定义的标签。可以使用传递给目标定义函数的 install_tag 关键字参数设置自定义安装标签。在此示例中，只有标记为 runtime 或 python-runtime 的目标包含在 Python wheel 中。

要在项目的 pyproject.toml 中永久设置此选项

[tool.meson-python.args]
install = ['--tags=runtime,python-runtime']

要在构建时临时设置此选项

$ python -m build -Cinstall-args="--tags=runtime,python-runtime" .

$ python -m pip wheel --config-settings=install-args="--tags=runtime,python-runtime" .

设置构建优化级别

构建二进制 wheel 时的默认编译优化级别当前设置为 2。可以通过将 -Doptimization 参数传递给 meson setup 命令来覆盖它。

要在项目的 pyproject.toml 中永久设置此选项

[tool.meson-python.args]
setup = ['-Doptimization=3']

要在构建时临时设置此选项

$ python -m build -Csetup-args="-Doptimization=3" .

$ python -m pip wheel --config-settings=setup-args="-Doptimization=3" .

强制在 Windows 上使用 MSVC 编译器

MSVC 编译器未安装在 $PATH 中。需要激活 Visual Studio 环境才能使 ninja 能够使用这些编译器。这由 meson compile 处理，但前提是在 $PATH 上找不到 GCC 编译器或 LLVM 编译器。将 --vsenv 选项传递给 meson setup 会强制激活 Visual Studio 环境，并在激活失败时生成错误。

此选项对其他平台没有影响，因此，如果您的项目需要用 MSVC 编译，您可以考虑在项目的 pyproject.toml 中永久设置此选项

[tool.meson-python.args]
setup = ['--vsenv']

要在构建时临时设置此选项

$ python -m build -Csetup-args="--vsenv" .

$ python -m pip wheel --config-settings=setup-args="--vsenv" .