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.ModuleDevelopment.Embed

4.1 版更改: 在交叉编译模式下(即 CMAKE_CROSSCOMPILING 变量定义为 true),当策略 CMP0190 设置为 NEW 时,以下限制适用于请求的组件

  • InterpreterCompiler 单独:将搜索主机工件。

  • InterpreterCompilerDevelopment 或任何子组件:将搜索目标工件。在这种情况下,必须定义 CMAKE_CROSSCOMPILING_EMULATOR 变量,并将其用于执行解释器或编译器。

当需要主机和目标工件时,应该对 find_package() 命令进行两次不同的调用。Python_ARTIFACTS_PREFIX 变量在这种情况下可能会有所帮助。

为了确保组件 InterpreterCompilerDevelopment(或其子组件之一)和 NumPy 之间的版本一致性,请同时指定所有组件

find_package (Python3 COMPONENTS Interpreter Development)

此模块仅查找 Python 3 版本。此模块可以与 FindPython2 模块同时使用,以使用两个 Python 版本。

如果 Python 版本对您不重要,可以使用 FindPython 模块。

注意

如果同时指定了组件 InterpreterDevelopment(或其子组件之一),此模块仅搜索与 CMake 配置定义的平台架构相同的解释器。如果仅指定了 Interpreter 组件,则此限制不适用。

导入的目标

此模块定义了以下 导入目标

3.14 版更改: 导入目标 仅在 CMAKE_ROLEPROJECT 时创建。

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 模块的 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_EXECUTABLEPython3_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,除了 WindowsMSYSCYGWIN,对于它们,这是一个空字符串。

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 模块的 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

3.30 版本新增。

调试 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 标志(即自由线程 Python),并且是可选的。如果未指定,则值为 OFF

每个元素都可以设置为以下之一

  • ON: 选中相应标志。

  • OFF: 未选中相应标志。

  • ANY: 将搜索两种可能性(ONOFF)。

注意

如果未定义 Python3_FIND_ABI,则将搜索除 gil_disabled 标志之外的任何 ABI。

从这个 4 元组开始,将从最特殊到最一般地搜索各种 ABI。此外,当 pydebuggil_disabled 指定 ANY 时,debugfree threaded 版本将在 non-debugnon-gil-disabled 之后搜索。

例如,如果我们有

set (Python3_FIND_ABI "ON" "ANY" "ANY" "ON")

以下标志组合将按该顺序附加到工件名称中:tdmutdmtdutd

并搜索任何可能的 ABI

set (Python3_FIND_ABI "ANY" "ANY" "ANY" "ANY")

将按该顺序使用以下组合:mumu<empty>dmudmdudtmutmtuttdmutdmtdutd

注意

此提示仅在 POSIX 系统上(除了 gil_disabled 标志)有用。因此,在 Windows 系统上,当定义了 Python_FIND_ABI 时,只有当每个标志的值为 OFFANY(除了第四个标志 gil_disabled)时,才能找到来自 python.orgPython 分发版。

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 新增。

此变量定义了由 virtualenvconda 管理的虚拟环境的处理方式。它仅在虚拟环境激活时(即已评估 activate 脚本时)有意义。在这种情况下,它优先于 Python3_FIND_REGISTRYCMAKE_FIND_FRAMEWORK 变量。Python3_FIND_VIRTUALENV 变量可以设置为以下之一

  • FIRST: 虚拟环境优先于任何其他标准路径用于查找解释器。这是默认值。

  • ONLY: 仅使用虚拟环境查找解释器。

  • STANDARD: 虚拟环境不用于查找解释器,但始终考虑环境变量 PATH。在这种情况下,变量 Python3_FIND_REGISTRY (Windows) 或 CMAKE_FIND_FRAMEWORK (macOS) 可以设置为值 LASTNEVER 以优先选择虚拟环境中的解释器。

3.17 版新增: 添加了对 conda 环境的支持。

注意

如果请求了组件 Development(或其子组件之一)但未找到或返回了错误的工件,则同时包含组件 Interpreter 可能会有所帮助。

Python3_FIND_IMPLEMENTATIONS

在 3.18 版本中新增。

此变量以有序列表的形式定义将搜索的不同实现。Python3_FIND_IMPLEMENTATIONS 变量可以包含以下值

  • CPython: 这是标准实现。各种产品,如 AnacondaActivePython,都依赖于此实现。

  • IronPython: 此实现使用 CSharp 语言在 动态语言运行时 (DLR) 之上构建 .NET Framework。请参阅 IronPython

  • PyPy: 此实现使用 RPython 语言和 RPython translation toolchain 来生成 Python 解释器。请参阅 PyPy

默认值为

  • Windows 平台:CPythonIronPython

  • 其他平台:CPython

注意

此提示在所有提示中优先级最低,因此即使您将 IronPython 排在第一位,CPython 排在第二位,仍然可能会选择基于 CPython 的 Python 产品,因为(例如,当 Python3_FIND_STRATEGY=LOCATION 时)每个位置将首先搜索 IronPython,然后搜索 CPython

注意

当指定 IronPython 时,在 Windows 以外的平台上,预计 .Net 解释器(即 mono 命令)可以通过 PATH 变量获得。

Python3_FIND_UNVERSIONED_NAMES

在 3.20 版本中添加。

此变量定义通用名称的搜索方式。目前,它仅适用于解释器的通用名称,即 python3pythonPython3_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_LIBRARIESPython3_LIBRARY_DIRSPython3_RUNTIME_LIBRARY_DIRS

Python3_SABI_LIBRARY

3.26 版新增。

稳定应用程序二进制接口的库路径。它将用于计算变量 Python3_SABI_LIBRARIESPython3_SABI_LIBRARY_DIRSPython3_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_ARTIFACTS_PREFIX

4.0 版本新增。

定义一个自定义前缀,它将用于定义所有结果变量、目标和命令。通过使用此变量,此模块支持在同一目录中多次调用,并带有不同的版本/组件要求。例如,在交叉编译的情况下,需要开发组件,但也可能需要本机 Python 解释器

find_package(Python3 COMPONENTS Development)

set(Python3_ARTIFACTS_PREFIX "_HOST")
find_package(Python3 COMPONENTS Interpreter)

# Here Python3_HOST_EXECUTABLE and Python3_HOST::Interpreter artifacts are defined

注意

为了与模块的标准行为保持一致,每次调用 find_package() 命令也会定义各种标准 _FOUND 变量(即不带自定义前缀)。

命令

此模块定义了命令 Python3_add_library(当 CMAKE_ROLEPROJECT 时),它与 add_library() 具有相同的语义,并添加了对目标 Python3::Python 的依赖,或者当库类型为 MODULE 时,对目标 Python3::ModulePython3::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,则将 Py_LIMITED_API 预处理器定义指定为 PRIVATE,用于目标 <name>,其值根据 <version> 参数计算。 <version> 的预期格式为 major[.minor],其中每个组件都是一个数字值。如果指定了 minor 组件,则版本应至少为 3.2,这是引入 稳定应用程序二进制接口 的版本。仅指定主版本 3 等效于 3.2

当同时指定选项 WITH_SOABI 时,模块后缀将包含 Python3_SOSABI 值(如果存在)。

3.30 版新增: 对于 MODULE 类型,如果定义了 Python3_DEBUG_POSTFIX 变量,则 DEBUG_POSTFIX 目标属性将使用其值进行初始化。