FindPython

3.12 版本加入。

查找 Python 解释器、编译器和开发环境(包含目录和库)。

3.19 版本加入: 当请求版本时,可以指定为简单值或范围。 有关版本范围用法和功能的详细描述,请参阅 find_package() 命令。

支持以下组件

  • Interpreter:搜索 Python 解释器。

  • Compiler:搜索 Python 编译器。 仅 IronPython 提供。

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

    3.18 版本加入: 此组件包含两个可以独立指定的子组件

    • Development.Module:搜索 Python 模块开发所需的工件。

    • Development.Embed:搜索 Python 嵌入式开发所需的工件。

    3.26 版本加入

    • Development.SABIModule:搜索使用 稳定应用二进制接口 的 Python 模块开发所需的工件。 此组件仅适用于 3.2 及更高版本。

  • NumPy:搜索 NumPy 包含目录。

3.14 版本加入: 添加了 NumPy 组件。

如果未指定 COMPONENTS,则假定为 Interpreter

如果指定了组件 Development,则意味着子组件 Development.ModuleDevelopment.Embed

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

find_package (Python COMPONENTS Interpreter Development)

此模块优先查找 Python 3 版本。 如果未找到,则搜索版本 2。 要管理 Python 的并发版本 3 和 2,请使用 FindPython3FindPython2 模块,而不是此模块。

注意

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

导入目标

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

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

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_EXECUTABLEPython_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 版本加入。

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

如果指定了 COMPONENT Interpreter,则从 importlib.machinery.EXTENSION_SUFFIXES 计算的信息。 否则,扩展名为 abi3,但对于 WindowsMSYSCYGWIN,则为空字符串。

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:将搜索两种可能性(ONOFF)。

注意

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

从此 4 元组中,将搜索各种 ABI,从最专业的到最通用的。 此外,当为 pydebuggil_disabled 指定 ANY 时,将在 non-debugnon-gil-disabled 版本**之后**搜索 debugfree threaded 版本。

例如,如果我们有

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

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

并且要搜索任何可能的 ABI

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

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

注意

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

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 版本加入。

此变量定义如何处理由 virtualenvconda 管理的虚拟环境。 仅当虚拟环境处于活动状态时(即已评估 activate 脚本),此变量才有意义。 在这种情况下,它优先于 Python_FIND_REGISTRYCMAKE_FIND_FRAMEWORK 变量。 Python_FIND_VIRTUALENV 变量可以设置为以下之一

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

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

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

3.17 版本加入: 增加了对 conda 环境的支持。

注意

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

Python_FIND_IMPLEMENTATIONS

3.18 版本加入。

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

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

  • IronPython:此实现使用 CSharp 语言,用于 .NET Framework,基于 Dynamic Language Runtime (DLR)。 请参阅 IronPython

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

默认值为

  • Windows 平台:CPythonIronPython

  • 其他平台:CPython

注意

此提示的优先级在所有提示中最低,因此即使例如,您首先指定 IronPython,然后在第二位指定 CPython,也可能会选择基于 CPython 的 python 产品,因为例如使用 Python_FIND_STRATEGY=LOCATION,将首先搜索每个位置的 IronPython,然后搜索 CPython

注意

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

Python_FIND_UNVERSIONED_NAMES

3.20 版本加入。

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

Python_SABI_LIBRARY

3.26 版本加入。

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

当也指定选项 WITH_SOABI 时,模块后缀将包含 Python_SOSABI 值(如果有)。

3.30 版本加入: 对于 MODULE 类型,DEBUG_POSTFIX 目标属性使用 Python_DEBUG_POSTFIX 变量的值(如果已定义)初始化。