FindPython3

在 3.12 版本加入。

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

在 3.19 版本加入：當請求特定版本時，可以將其指定為簡單值或範圍。有關版本範圍用法和功能的詳細說明，請參閱 find_package() 命令。

支援以下組件

  • Interpreter：搜尋 Python 3 直譯器

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

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

    在 3.18 版本加入：此組件包含兩個可以獨立指定的子組件

    • Development.Module：搜尋 Python 3 模組開發的產物。

    • Development.Embed：搜尋 Python 3 嵌入式開發的產物。

    在 3.26 版本加入

  • NumPy：搜尋 NumPy 包含目錄。

在 3.14 版本加入：加入 NumPy 組件。

如果未指定 COMPONENTS，則預設為 Interpreter。

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

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

find_package (Python3 COMPONENTS Interpreter Development)

此模組僅尋找 Python 3 版本。此模組可以與 FindPython2 模組同時使用，以使用兩個 Python 版本。

如果 Python 版本對您來說並不重要，則可以使用 FindPython 模組。

注意

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

導入目標

此模組定義以下 導入目標

在 3.14 版本變更：只有當 CMAKE_ROLE 為 PROJECT 時，才會建立 導入目標。

Python3::Interpreter

Python 3 直譯器。只有在找到 Interpreter 組件時，才會定義此目標。

Python3::InterpreterDebug

在 3.30 版本加入。

Python 3 除錯直譯器。只有在找到 Interpreter 組件並定義 Python3_EXECUTABLE_DEBUG 變數時，才會定義此目標。此目標僅在 Windows 平台上定義。

Python3::InterpreterMultiConfig

在 3.30 版本加入。

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

Python3::Compiler

Python 3 編譯器。只有在找到 Compiler 組件時，才會定義此目標。

Python3::Module

在 3.15 版本加入。

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

Python3::SABIModule

在 3.26 版本加入。

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

Python3::Python

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

Python3::NumPy

在 3.14 版本加入。

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

結果變數

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

Python3_FOUND

系統具有請求的 Python 3 組件。

Python3_Interpreter_FOUND

系統具有 Python 3 直譯器。

Python3_EXECUTABLE

Python 3 直譯器的路徑。

Python3_EXECUTABLE_DEBUG

在 3.30 版本加入。

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

Python3_INTERPRETER

在 3.30 版本加入。

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

Python3_INTERPRETER_ID
直譯器獨有的簡短字串。可能的值包括

  • Python

  • ActivePython

  • Anaconda

  • Canopy

  • IronPython

  • PyPy

Python3_STDLIB

標準平台獨立安裝目錄。

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

Python3_STDARCH

標準平台相依安裝目錄。

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

Python3_SITELIB

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

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

Python3_SITEARCH

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

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

Python3_SOABI

在 3.17 版本加入。

模組的副檔名。

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

Python3_SOSABI

在 3.26 版本加入。

使用穩定應用程式二進位介面的模組副檔名。

如果指定了組件 Interpreter，則從 importlib.machinery.EXTENSION_SUFFIXES 計算得出的資訊。否則，此副檔名為 abi3，但 Windows、MSYS 和 CYGWIN 除外，它們的副檔名為空字串。

Python3_Compiler_FOUND

系統具有 Python 3 編譯器。

Python3_COMPILER

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

Python3_COMPILER_ID
編譯器獨有的簡短字串。可能的值包括

  • IronPython

Python3_DOTNET_LAUNCHER

在 3.18 版本加入。

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

Python3_Development_FOUND

系統具有 Python 3 開發產物。

Python3_Development.Module_FOUND

在 3.18 版本加入。

系統具有用於 Python 模組的 Python 3 開發產物。

Python3_Development.SABIModule_FOUND

在 3.26 版本加入。

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

Python3_Development.Embed_FOUND

在 3.18 版本加入。

系統具有用於 Python 嵌入的 Python 3 開發產物。

Python3_INCLUDE_DIRS

Python 3 包含目錄。

Python3_DEFINITIONS

在 3.30.3 版本加入。

Python 3 前置處理器定義。

Python3_DEBUG_POSTFIX

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

Python3_LINK_OPTIONS

在 3.19 版本加入。

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

Python3_LIBRARIES

Python 3 函式庫。

Python3_LIBRARY_DIRS

Python 3 函式庫目錄。

Python3_RUNTIME_LIBRARY_DIRS

Python 3 執行階段函式庫目錄。

Python3_SABI_LIBRARIES

在 3.26 版本加入。

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

Python3_SABI_LIBRARY_DIRS

在 3.26 版本加入。

Python 3 SABI 函式庫目錄。

Python3_RUNTIME_SABI_LIBRARY_DIRS

在 3.26 版本加入。

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

Python3_VERSION

Python 3 版本。

Python3_VERSION_MAJOR

Python 3 主要版本。

Python3_VERSION_MINOR

Python 3 次要版本。

Python3_VERSION_PATCH

Python 3 修補版本。

Python3_PyPy_VERSION

在 3.18 版本加入。

Python 3 PyPy 版本。

Python3_NumPy_FOUND

在 3.14 版本加入。

系統有 NumPy。

Python3_NumPy_INCLUDE_DIRS

在 3.14 版本加入。

NumPy 包含目錄。

Python3_NumPy_VERSION

在 3.14 版本加入。

NumPy 版本。

提示

Python3_ROOT_DIR

定義 Python 3 安裝的根目錄。

Python3_USE_STATIC_LIBS

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

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

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

注意

此提示在 Windows 上將被忽略，因為此平台上沒有靜態函式庫可用。

Python3_FIND_ABI

在 3.16 版本中新增。

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

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

在 3.30 版本中新增: 新增第四個元素，指定 gil_disabled 旗標（即 free threaded 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 (Python3_FIND_ABI "ON" "ANY" "ANY" "ON")

以下旗標組合將依此順序附加到成品名稱：tdmu、tdm、tdu 和 td。

以及搜尋任何可能的 ABI

set (Python3_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 時，才會找到來自 python.org 的 Python 發行版，第四個旗標（gil_disabled）除外。

Python3_FIND_STRATEGY

在 3.15 版本加入。

此變數定義將如何進行查找。Python3_FIND_STRATEGY 變數可以設定為下列其中一個

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

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

另請參閱 Python3_FIND_UNVERSIONED_NAMES。

Python3_FIND_REGISTRY

在 3.13 版本中新增。

在 Windows 上，Python3_FIND_REGISTRY 變數決定登錄檔和環境變數之間的優先順序。Python3_FIND_REGISTRY 變數可以設定為下列其中一個

  • FIRST：嘗試先使用登錄檔，再使用環境變數。此為預設值。

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

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

Python3_FIND_FRAMEWORK

在 3.15 版本加入。

在 macOS 上，Python3_FIND_FRAMEWORK 變數決定 Apple 風格和 Unix 風格套件元件之間的優先順序。此變數可以採用與 CMAKE_FIND_FRAMEWORK 變數相同的值。

注意

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

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

Python3_FIND_VIRTUALENV

在 3.15 版本加入。

此變數定義 virtualenv 或 conda 管理的虛擬環境的處理方式。它僅在虛擬環境處於活動狀態時才有意義（即已評估 activate 指令碼）。在這種情況下，它會優先於 Python3_FIND_REGISTRY 和 CMAKE_FIND_FRAMEWORK 變數。Python3_FIND_VIRTUALENV 變數可以設定為下列其中一個

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

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

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

在 3.17 版本中新增: 新增對 conda 環境的支援。

注意

如果請求元件 Development，**強烈**建議也包含元件 Interpreter 以獲得預期的結果。

Python3_FIND_IMPLEMENTATIONS

在 3.18 版本加入。

此變數定義將搜尋的不同實作的排序清單。Python3_FIND_IMPLEMENTATIONS 變數可以保存以下值

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

  • IronPython：此實作在 動態語言執行階段 (DLR) 之上，使用 .NET Framework 的 CSharp 語言。請參閱 IronPython。

  • PyPy：此實作使用 RPython 語言和 RPython 翻譯 工具鏈 來產生 Python 直譯器。請參閱 PyPy。

預設值為

  • Windows 平台：CPython、IronPython

  • 其他平台：CPython

注意

此提示的優先級在所有提示中是最低的，因此即使您先指定 IronPython，然後指定 CPython，基於 CPython 的 Python 產品仍然可能被選中。這是因為，例如使用 Python3_FIND_STRATEGY=LOCATION 時，每個位置會先搜尋 IronPython，然後才搜尋 CPython。

注意

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

Python3_FIND_UNVERSIONED_NAMES

在 3.20 版本中新增。

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

  • FIRST：在搜尋更特定的名稱（例如 python3.5）之前，先搜尋通用名稱。

  • LAST：在搜尋更特定的名稱之後，才搜尋通用名稱。這是預設值。

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

另請參閱 Python3_FIND_STRATEGY。

構件規範

在 3.16 版本中新增。

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

Python3_EXECUTABLE

直譯器的路徑。

Python3_COMPILER

編譯器的路徑。

Python3_DOTNET_LAUNCHER

在 3.18 版本加入。

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

Python3_LIBRARY

程式庫的路徑。它將用於計算變數 Python3_LIBRARIES、Python3_LIBRARY_DIRS 和 Python3_RUNTIME_LIBRARY_DIRS。

Python3_SABI_LIBRARY

在 3.26 版本加入。

用於穩定應用程式二進位介面的程式庫路徑。它將用於計算變數 Python3_SABI_LIBRARIES、Python3_SABI_LIBRARY_DIRS 和 Python3_RUNTIME_SABI_LIBRARY_DIRS。

Python3_INCLUDE_DIR

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

Python3_NumPy_INCLUDE_DIR

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

注意

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

注意

當指定構件時，所有 HINTS 都將被忽略，並且不會針對此構件執行任何搜尋。

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

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

Python3_ARTIFACTS_INTERACTIVE

在 3.18 版本加入。

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

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

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

命令

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

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

如果未指定程式庫類型，則預設為 MODULE。

在 3.17 版本中新增：對於 MODULE 程式庫類型，如果指定了選項 WITH_SOABI，則模組字尾將包含 Python3_SOABI 值（如果有的話）。

在 3.26 版本中新增：對於 MODULE 類型，如果指定了選項 USE_SABI，則將為目標 <name> 指定預處理器定義 Py_LIMITED_API，並將其設為 PRIVATE，其值由 <version> 引數計算得出。<version> 的預期格式為 major[.minor]，其中每個元件都是數值。如果指定了 minor 元件，則版本應至少為 3.2，這是引入 穩定應用程式二進位介面的版本。僅指定主要版本 3 等同於 3.2。

當也指定選項 WITH_SOABI 時，模組字尾將包含 Python3_SOSABI 值（如果有的話）。

在 3.30 版本中新增：對於 MODULE 類型，DEBUG_POSTFIX 目標屬性會使用 Python3_DEBUG_POSTFIX 變數的值（如果已定義）進行初始化。