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 解释器的路径，定义为 generator expression，根据上下文（平台、配置）选择 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 中添加。

The .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

调试 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。此外，当 ANY 用于 pydebug 和 gil_disabled 时，debug 和 free threaded 版本将在 non-debug 和 non-gil-disabled 版本**之后**搜索。

例如，如果我们有

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 语言在 动态语言运行时 (DLR) 之上为 .NET Framework 生成 Python 解释器。请参见 IronPython。

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

默认值为

  • Windows 平台：CPython、IronPython

  • 其他平台：CPython

注意

此提示优先级最低，因此即使您先指定了 IronPython，然后指定了 CPython，也可能选择基于 CPython 的 Python 产品，因为例如，使用 Python_FIND_STRATEGY=LOCATION 时，每个位置将首先搜索 IronPython，然后搜索 CPython。

注意

当指定了 IronPython 时，在非 Windows 平台上，预计可以通过 PATH 环境变量访问 .Net 解释器（即 mono 命令）。

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 中添加。

The .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_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。

在 3.17 版本中添加： 对于 MODULE 库类型，如果指定了选项 WITH_SOABI，则模块后缀将包含 Python_SOABI 值（如果有）。

在 3.26 版本中添加： 对于 MODULE 类型，如果指定了选项 USE_SABI，则预处理器定义 Py_LIMITED_API 将被指定为 PRIVATE，用于目标 <name>，其值为从 <version> 参数计算得出。 <version> 的预期格式为 major[.minor]，其中每个组件都是一个数值。如果指定了 minor 组件，则版本至少应该是 3.2，这是引入 稳定应用程序二进制接口 的版本。仅指定主版本 3 等效于 3.2。

当也指定了选项 WITH_SOABI 时，模块后缀将包含 Python_SOSABI 值（如果有）。

在 3.30 版本中添加： 对于 MODULE 类型，如果定义了 Python_DEBUG_POSTFIX 变量，则 DEBUG_POSTFIX 目标属性将初始化为该变量的值。