傳遞參數給 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 使用更適合建置 Python Wheel 的設定覆寫了一些預設的 Meson 選項。使用者透過 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']

若要在建置時暫時設定此選項：

pypa/build

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

pip

$ 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']

若要在建置時暫時設定此選項：

pypa/build

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

pip

$ 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']

若要在建置時暫時設定此選項：

pypa/build

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

pip

$ 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']

若要在建置時暫時設定此選項：

pypa/build

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

pip

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