FindPython3

3.12 版本新增。

查找 Python 3 解释器、编译器和开发环境（包含目录和库）

find_package(Python3 [<version>] [COMPONENTS <components>...] [...])

在版本 3.19 中添加： 当请求版本时，可以指定为简单值或范围。有关版本范围用法和功能的详细说明，请参阅 find_package() 命令。

支持以下组件

  • Interpreter：查找 Python 3 解释器

  • Compiler：查找 Python 3 编译器。仅由 IronPython 提供。

  • Development: 搜索开发工件（包含目录和库）。

    3.18 版新增：此组件包含两个子组件，可以独立指定

    • Development.Module：查找用于 Python 3 模块开发的构件。

    • Development.Embed：查找用于 Python 3 嵌入式开发的构件。

    3.26 版新增

在版本 3.14 中添加

  • NumPy：查找 NumPy 的包含目录。指定此组件也意味着指定 Interpreter 和 Development.Module 组件。

在版本 4.2 中更改： 当策略 CMP0201 设置为 NEW 时，Development.Module 组件不再被默认包含。

如果未指定 COMPONENTS，则假定为 Interpreter。

如果指定了 Development 组件，则它会包含子组件 Development.Module 和 Development.Embed。

在版本 4.1 中更改： 在交叉编译模式下（即 CMAKE_CROSSCOMPILING 变量被定义为 true），当策略 CMP0190 设置为 NEW 时，以下约束适用于请求的组件：

  • Interpreter 或 Compiler 单独：将搜索主机工件。

  • Interpreter 或 Compiler 搭配 Development 或任何子组件：将查找目标构件。在这种情况下，必须定义 CMAKE_CROSSCOMPILING_EMULATOR 变量，并使用它来执行解释器或编译器。

当同时需要主机和目标构件时，应两次调用 find_package() 命令。在这种情况下，Python_ARTIFACTS_PREFIX 变量可能很有用。

为确保 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 3 模块的 Python 库。当找到 Development.Module 组件时，定义此目标。

Python3::SABIModule

3.26 版新增。

使用稳定应用程序二进制接口的 Python 3 模块的 Python 库。当找到 Development.SABIModule 组件时，定义此目标。

Python3::Python

Python 3 嵌入的 Python 库。当找到 Development.Embed 组件时，定义此目标。

Python3::NumPy

3.14 版新增。

NumPy 的 Python 3 库。当找到 NumPy 组件时，定义此目标。此外，此目标将 Python3::Module 目标作为依赖项。

在版本 4.2 中更改： 当策略 CMP0201 设置为 NEW 时，此目标不再将 Python3::Module 目标作为依赖项。

结果变量

此模块定义了以下变量（请参阅 标准变量名）

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

使用稳定应用程序二进制接口的模块的扩展后缀。

如果指定了 COMPONENT 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 模块的 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 标志（即无 GIL 的 Python），该元素是可选的。如果未指定，则值为 OFF。

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

  • ON：选中相应标志。

  • OFF：不选中相应标志。

  • ANY：将搜索两种可能性（ON 和 OFF）。

注意

如果未定义 Python3_FIND_ABI，则将搜索任何 ABI，不包括 gil_disabled 标志。

从这个 4 元组开始，将按顺序搜索各种 ABI，从最专业的到最通用的。此外，当为 pydebug 和 gil_disabled 指定 ANY 时，将 **在** 非调试 和 非无 GIL 版本 **之后** 搜索 调试 和 无 GIL 版本。

例如，如果我们有

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 时，来自 python.org 的 Python 分发版仅在每个标志的值为 OFF 或 ANY 时才会找到，除了第四个标志（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：此实现使用 CSharp 语言为 .NET Framework 提供支持，建立在 Dynamic Language Runtime（DLR）之上。请参阅 IronPython。

  • PyPy：此实现使用 RPython 语言和 RPython translation toolchain 来生成 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_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_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 选项，则预处理器定义 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 目标属性将使用其值进行初始化。