FindPython

版本 3.12 新增。

尋找 Python 直譯器、編譯器和開發環境（包含目錄和函式庫）。

版本 3.19 新增：當請求特定版本時，可以指定為簡單值或範圍。 有關版本範圍用法和功能的詳細描述，請參閱 find_package() 命令。

支援以下組件

  • Interpreter：搜尋 Python 直譯器。

  • Compiler：搜尋 Python 編譯器。 僅 IronPython 提供。

  • Development：搜尋開發工件（包含目錄和函式庫）。

    版本 3.18 新增：此組件包含兩個可以獨立指定的子組件

    • Development.Module：搜尋 Python 模組開發的工件。

    • Development.Embed：搜尋 Python 嵌入式開發的工件。

    版本 3.26 新增

  • NumPy：搜尋 NumPy 包含目錄。

版本 3.14 新增：新增 NumPy 組件。

如果未指定 COMPONENTS，則假定為 Interpreter。

如果指定組件 Development，則表示子組件 Development.Module 和 Development.Embed。

為了確保組件 Interpreter、Compiler、Development（或其子組件之一）和 NumPy 之間的版本一致，請同時指定所有組件

find_package (Python COMPONENTS Interpreter Development)

此模組優先尋找 Python 3 版本。 如果找不到，則搜尋版本 2。 為了管理 Python 3 和 2 的並行版本，請使用 FindPython3 和 FindPython2 模組，而不是此模組。

注意

如果同時指定組件 Interpreter 和 Development（或其子組件之一），則此模組僅搜尋與 CMake 配置定義的平台架構相同的直譯器。 如果僅指定 Interpreter 組件，則此限制不適用。

匯入目標

此模組定義以下 匯入目標

版本 3.14 變更：僅當 CMAKE_ROLE 為 PROJECT 時，才會建立 匯入目標。

Python::Interpreter

Python 直譯器。 僅當找到 Interpreter 組件時，才會定義此目標。

Python::InterpreterDebug

版本 3.30 新增。

Python 除錯直譯器。 僅當找到 Interpreter 組件且定義了 Python_EXECUTABLE_DEBUG 變數時，才會定義此目標。 此目標僅在 Windows 平台上定義。

Python::InterpreterMultiConfig

版本 3.30 新增。

Python 直譯器。 直譯器的發行或除錯版本將根據上下文（平台、組態）使用。 僅當找到 Interpreter 組件時，才會定義此目標

Python::Compiler

Python 編譯器。 僅當找到 Compiler 組件時，才會定義此目標。

Python::Module

版本 3.15 新增。

用於 Python 模組的 Python 函式庫。 如果找到組件 Development.Module，則定義目標。

Python::SABIModule

版本 3.26 新增。

用於使用穩定應用程式二進位介面的 Python 模組的 Python 函式庫。 如果找到組件 Development.SABIModule，則定義目標。

Python::Python

用於 Python 嵌入的 Python 函式庫。 如果找到組件 Development.Embed，則定義目標。

Python::NumPy

版本 3.14 新增。

NumPy Python 函式庫。 如果找到組件 NumPy，則定義目標。

結果變數

此模組將在您的專案中設定以下變數（請參閱 標準變數名稱）

Python_FOUND

系統具有請求的 Python 組件。

Python_Interpreter_FOUND

系統具有 Python 直譯器。

Python_EXECUTABLE

Python 直譯器的路徑。

Python_EXECUTABLE_DEBUG

版本 3.30 新增。

除錯 Python 直譯器的路徑。 它僅在 Windows 平台上定義。

Python_INTERPRETER

版本 3.30 新增。

Python 直譯器的路徑，定義為 產生器表達式，根據上下文（平台、組態）選擇 Python_EXECUTABLE 或 Python_EXECUTABLE_DEBUG 變數。

Python_INTERPRETER_ID
直譯器特有的簡短字串。 可能的值包括

  • Python

  • ActivePython

  • Anaconda

  • Canopy

  • IronPython

  • PyPy

Python_STDLIB

標準平台獨立安裝目錄。

由 sysconfig.get_path('stdlib') 傳回的資訊。

Python_STDARCH

標準平台相關安裝目錄。

由 sysconfig.get_path('platstdlib') 傳回的資訊。

Python_SITELIB

第三方平台獨立安裝目錄。

由 sysconfig.get_path('purelib') 傳回的資訊。

Python_SITEARCH

第三方平台相關安裝目錄。

由 sysconfig.get_path('platlib') 傳回的資訊。

Python_SOABI

版本 3.17 新增。

模組的擴充功能後綴。

從 sysconfig.get_config_var('EXT_SUFFIX') 或 sysconfig.get_config_var('SOABI') 或 python3-config --extension-suffix 計算的資訊。

Python_SOSABI

版本 3.26 新增。

使用穩定應用程式二進位介面的模組的擴充功能後綴。

如果指定了組件 Interpreter，則從 importlib.machinery.EXTENSION_SUFFIXES 計算的資訊。 否則，擴充功能為 abi3，但對於 Windows、MSYS 和 CYGWIN，則為空字串。

Python_Compiler_FOUND

系統具有 Python 編譯器。

Python_COMPILER

Python 編譯器的路徑。 僅 IronPython 提供。

Python_COMPILER_ID
編譯器特有的簡短字串。 可能的值包括

  • IronPython

Python_DOTNET_LAUNCHER

版本 3.18 新增。

.Net 直譯器。 僅由 IronPython 實作使用。

Python_Development_FOUND

系統具有 Python 開發工件。

Python_Development.Module_FOUND

版本 3.18 新增。

系統具有 Python 模組的 Python 開發工件。

Python_Development.SABIModule_FOUND

版本 3.26 新增。

系統具有使用穩定應用程式二進位介面的 Python 模組的 Python 開發工件。

Python_Development.Embed_FOUND

版本 3.18 新增。

系統具有 Python 嵌入式的 Python 開發工件。

Python_INCLUDE_DIRS

Python 包含目錄。

Python_DEFINITIONS

版本 3.30.3 新增。

Python 前處理器定義。

Python_DEBUG_POSTFIX

版本 3.30 新增。

除錯 Python 模組的後綴。 此變數可用於定義 DEBUG_POSTFIX 目標屬性。

Python_LINK_OPTIONS

版本 3.19 新增。

Python 連結選項。 某些組態需要特定的連結選項才能正確建置和執行。

Python_LIBRARIES

Python 函式庫。

Python_LIBRARY_DIRS

Python 函式庫目錄。

Python_RUNTIME_LIBRARY_DIRS

Python 執行時期函式庫目錄。

Python_SABI_LIBRARIES

版本 3.26 新增。

用於穩定應用程式二進位介面的 Python 函式庫。

Python_SABI_LIBRARY_DIRS

版本 3.26 新增。

Python SABI 函式庫目錄。

Python_RUNTIME_SABI_LIBRARY_DIRS

版本 3.26 新增。

Python 執行時期 SABI 函式庫目錄。

Python_VERSION

Python 版本。

Python_VERSION_MAJOR

Python 主要版本。

Python_VERSION_MINOR

Python 次要版本。

Python_VERSION_PATCH

Python 修補程式版本。

Python_PyPy_VERSION

版本 3.18 新增。

Python PyPy 版本。

Python_NumPy_FOUND

版本 3.14 新增。

系統具有 NumPy。

Python_NumPy_INCLUDE_DIRS

版本 3.14 新增。

NumPy 包含目錄。

Python_NumPy_VERSION

版本 3.14 新增。

NumPy 版本。

提示

Python_ROOT_DIR

定義 Python 安裝的根目錄。

Python_USE_STATIC_LIBS

  • 如果未定義，則依序搜尋共用函式庫和靜態函式庫。

  • 如果設定為 TRUE，則 **僅** 搜尋靜態函式庫。

  • 如果設定為 FALSE，則 **僅** 搜尋共用函式庫。

注意

在 Windows 上將忽略此提示，因為此平台上不提供靜態函式庫。

Python_FIND_ABI

版本 3.16 新增。

此變數定義應搜尋哪些 ABI，如 PEP 3149 中所定義。

注意

僅當搜尋 Python 版本 3 時，才會採用此提示。

Python_FIND_ABI 變數是一個 4 元組，依序指定 pydebug (d)、pymalloc (m)、unicode (u) 和 gil_disabled (t) 旗標。

版本 3.30 新增：新增了第四個元素，指定 gil_disabled 旗標（即自由執行緒 Python），並且是可選的。 如果未指定，則值為 OFF。

每個元素都可以設定為以下之一

  • ON：選取對應的旗標。

  • OFF：未選取對應的旗標。

  • ANY：將搜尋兩種可能性（ON 和 OFF）。

注意

如果未定義 Python3_FIND_ABI，則將搜尋任何 ABI，但不包括 gil_disabled 旗標。

從這個 4 元組中，將從最專業到最一般的順序搜尋各種 ABI。 此外，當為 pydebug 和 gil_disabled 指定 ANY 時，將在 non-debug 和 non-gil-disabled 版本 **之後** 搜尋 debug 和 free threaded 版本。

例如，如果我們有

set (Python_FIND_ABI "ON" "ANY" "ANY" "ON")

以下旗標組合將依序附加到工件名稱：tdmu、tdm、tdu 和 td。

以及搜尋任何可能的 ABI

set (Python_FIND_ABI "ANY" "ANY" "ANY" "ANY")

將使用以下組合，依序為：mu、m、u、<empty>、dmu、dm、du、d、tmu、tm、tu、t、tdmu、tdm、tdu 和 td。

注意

此提示僅在 POSIX 系統上有用，但 gil_disabled 旗標除外。 因此，在 Windows 系統上，當定義 Python_FIND_ABI 時，僅當每個旗標的值為 OFF 或 ANY，但第四個旗標（gil_disabled）除外時，才會找到來自 python.org 的 Python 發行版。

Python_FIND_STRATEGY

版本 3.15 新增。

此變數定義了查找的執行方式。 Python_FIND_STRATEGY 變數可以設定為以下之一

  • VERSION：嘗試在所有指定的位置中尋找最新的版本。 如果策略 CMP0094 未定義或設定為 OLD，則這是預設值。

  • LOCATION：一旦找到滿足版本約束的版本，即停止查找。 如果策略 CMP0094 設定為 NEW，則這是預設值。

另請參閱 Python_FIND_UNVERSIONED_NAMES。

Python_FIND_REGISTRY

版本 3.13 新增。

在 Windows 上，Python_FIND_REGISTRY 變數決定了登錄檔和環境變數之間的偏好順序。 Python_FIND_REGISTRY 變數可以設定為以下之一

  • FIRST：嘗試先使用登錄檔，然後再使用環境變數。 這是預設值。

  • LAST：嘗試先使用環境變數，然後再使用登錄檔。

  • NEVER：永遠不要嘗試使用登錄檔。

Python_FIND_FRAMEWORK

版本 3.15 新增。

在 macOS 上，Python_FIND_FRAMEWORK 變數決定了 Apple 風格和 Unix 風格套件組件之間的偏好順序。 此變數可以採用與 CMAKE_FIND_FRAMEWORK 變數相同的值。

注意

不支援值 ONLY，因此將改為使用 FIRST。

如果未定義 Python_FIND_FRAMEWORK，則將使用 CMAKE_FIND_FRAMEWORK 變數（如果有的話）。

Python_FIND_VIRTUALENV

版本 3.15 新增。

此變數定義了虛擬環境（由 virtualenv 或 conda 管理）的處理方式。 僅當虛擬環境處於活動狀態時（即已評估 activate 腳本），此變數才有意義。 在這種情況下，它優先於 Python_FIND_REGISTRY 和 CMAKE_FIND_FRAMEWORK 變數。 Python_FIND_VIRTUALENV 變數可以設定為以下之一

  • FIRST：虛擬環境在任何其他標準路徑之前用於查找直譯器。 這是預設值。

  • ONLY：僅虛擬環境用於查找直譯器。

  • STANDARD：虛擬環境不適用於查找直譯器，但始終會考慮環境變數 PATH。 在這種情況下，可以將變數 Python_FIND_REGISTRY (Windows) 或 CMAKE_FIND_FRAMEWORK (macOS) 設定為值 LAST 或 NEVER，以優先從虛擬環境中選擇直譯器。

版本 3.17 新增：新增了對 conda 環境的支援。

注意

如果請求了組件 Development（或其子組件之一）但未找到或傳回了錯誤的工件，則包含組件 Interpreter 可能會有幫助。

Python_FIND_IMPLEMENTATIONS

版本 3.18 新增。

此變數在有序列表中定義將搜尋的不同實作。 Python_FIND_IMPLEMENTATIONS 變數可以包含以下值

  • CPython：這是標準實作。 各種產品，例如 Anaconda 或 ActivePython，都依賴於此實作。

  • IronPython：此實作使用 CSharp 語言，用於 .NET Framework，基於 Dynamic Language Runtime (DLR)。 請參閱 IronPython。

  • PyPy：此實作使用 RPython 語言和 RPython translation toolchain 來產生 Python 直譯器。 請參閱 PyPy。

預設值為

  • Windows 平台：CPython、IronPython

  • 其他平台：CPython

注意

此提示具有所有提示中的最低優先順序，因此即使例如您先指定 IronPython，然後在第二個位置指定 CPython，也可能選擇基於 CPython 的 Python 產品，因為例如使用 Python_FIND_STRATEGY=LOCATION，每個位置將首先搜尋 IronPython，然後再搜尋 CPython。

注意

當指定 IronPython 時，在 Windows 以外的平台上，預期 .Net 直譯器（即 mono 命令）可通過 PATH 變數取得。

Python_FIND_UNVERSIONED_NAMES

版本 3.20 新增。

此變數定義了將如何搜尋通用名稱。 目前，它僅適用於直譯器的通用名稱，即 python3 或 python2 和 python。 Python_FIND_UNVERSIONED_NAMES 變數可以設定為以下值之一

  • FIRST：在更專業的名稱（例如 python2.5）之前搜尋通用名稱。

  • LAST：在更專業的名稱之後搜尋通用名稱。 這是預設值。

  • NEVER：完全不搜尋通用名稱。

另請參閱 Python_FIND_STRATEGY。

工件規格

版本 3.16 新增。

為了處理特殊情況，可以通過設定以下變數直接指定工件

Python_EXECUTABLE

直譯器的路徑。

Python_COMPILER

編譯器的路徑。

Python_DOTNET_LAUNCHER

版本 3.18 新增。

.Net 直譯器。 僅由 IronPython 實作使用。

Python_LIBRARY

函式庫的路徑。 它將用於計算變數 Python_LIBRARIES、Python_LIBRARY_DIRS 和 Python_RUNTIME_LIBRARY_DIRS。

Python_SABI_LIBRARY

版本 3.26 新增。

穩定應用程式二進位介面的函式庫路徑。 它將用於計算變數 Python_SABI_LIBRARIES、Python_SABI_LIBRARY_DIRS 和 Python_RUNTIME_SABI_LIBRARY_DIRS。

Python_INCLUDE_DIR

Python 標頭目錄的路徑。 它將用於計算變數 Python_INCLUDE_DIRS。

Python_NumPy_INCLUDE_DIR

NumPy 標頭目錄的路徑。 它將用於計算變數 Python_NumPy_INCLUDE_DIRS。

注意

所有路徑都必須是絕對路徑。 任何使用相對路徑指定的工件都將被忽略。

注意

當指定工件時，將忽略所有 HINTS，並且不會對此工件執行搜尋。

如果指定了多個工件，則使用者有責任確保各種工件的一致性。

預設情況下，此模組支援在專案的不同目錄中進行多次調用，並具有不同的版本/組件要求，同時為每次調用提供正確且一致的結果。 為了支援此行為，CMake 快取未使用傳統方式，這對於互動式規範可能會有問題。 因此，為了也啟用互動式規範，可以使用以下變數控制模組行為

Python_ARTIFACTS_INTERACTIVE

版本 3.18 新增。

選擇模組的行為。 這是一個布林變數

  • 如果設定為 TRUE：為上述工件規格變數建立 CMake 快取條目，以便使用者可以互動式地編輯它們。 這會停用對多個版本/組件要求的支援。

  • 如果設定為 FALSE 或未定義：啟用多個版本/組件需求。

Python_ARTIFACTS_PREFIX

在版本 4.0 中新增。

定義一個自訂前綴詞，用於定義所有結果變數、目標和命令。透過使用此變數，此模組支援在同一個目錄中以不同的版本/組件需求進行多次呼叫。例如，在交叉編譯的情況下，可能需要開發組件，但也可能需要本機 python 直譯器

find_package(Python COMPONENTS Development)

set(Python_ARTIFACTS_PREFIX "_HOST")
find_package(Python COMPONENTS Interpreter)

# Here Python_HOST_EXECUTABLE and Python_HOST::Interpreter artifacts are defined

注意

為了與模組的標準行為保持一致，各種標準的 _FOUND 變數（即不帶自訂前綴詞）也會在每次呼叫 find_package() 命令時定義。

命令

此模組定義了 Python_add_library 命令（當 CMAKE_ROLE 為 PROJECT 時），其語意與 add_library() 相同，並新增對目標 Python::Python 的依賴，或者，當庫類型為 MODULE 時，新增對目標 Python::Module 或 Python::SABIModule（當指定 USE_SABI 選項時）的依賴，並處理 Python 模組命名規則

Python_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
                    <source1> [<source2> ...])

如果未指定庫類型，則假定為 MODULE。

Added in version 3.17: 對於 MODULE 庫類型，如果指定了 WITH_SOABI 選項，模組後綴將包含 Python_SOABI 值（如果有的話）。

Added in version 3.26: 對於 MODULE 類型，如果指定了 USE_SABI 選項，則會為目標 <name> 指定前處理器定義 Py_LIMITED_API，作為 PRIVATE，其值從 <version> 參數計算而來。<version> 的預期格式為 major[.minor]，其中每個組件都是數值。如果指定了 minor 組件，則版本應至少為 3.2，這是引入 穩定應用程式二進位介面 的版本。僅指定主要版本 3 等同於 3.2。

當也指定了 WITH_SOABI 選項時，模組後綴將包含 Python_SOSABI 值（如果有的話）。

Added in version 3.30: 對於 MODULE 類型，如果定義了 Python_DEBUG_POSTFIX 變數，則 DEBUG_POSTFIX 目標屬性會使用其值初始化。