3.3 检测 Python 模块和包

NOTE : 此示例代码可以在 https://github.com/devcafe/cmake-cookbook/tree/v1.0/chapter-03/recipe-03 中找到，包含一个 C++示例。该示例在 CMake 3.5 版（或更高版本) 中是有效的，并且已经在 GNU/Linux、macOS 和 Windows 上进行过测试。

前面的示例中，我们演示了如何检测 Python 解释器，以及如何编译一个简单的 C 程序（嵌入 Python 解释器)。通常，代码将依赖于特定的 Python 模块，无论是 Python 工具、嵌入 Python 的程序，还是扩展 Python 的库。例如，科学界非常流行使用 NumPy 处理矩阵问题。依赖于 Python 模块或包的项目中，确定满足对这些 Python 模块的依赖非常重要。本示例将展示如何探测用户的环境，以找到特定的 Python 模块和包。

准备工作

我们将尝试在 C++程序中嵌入一个稍微复杂一点的例子。这个示例再次引用 Python 在线文档 ，并展示了如何通过调用编译后的 C++可执行文件，来执行用户定义的 Python 模块中的函数。

Python 3 示例代码( Py3-pure-embedding.cpp ) 包含以下源代码（请参见 https://docs.python.org/2/extending/embedding.html#pure-embedded 与 Python 2 代码等效):

#include <Python.h>
int main(int argc, char* argv[]) {
  PyObject* pName, * pModule, * pDict, * pFunc;
  PyObject* pArgs, * pValue;
  int i;
  if (argc < 3) {
    fprintf(stderr, "Usage: pure-embedding pythonfile funcname [args]\n");
    return 1;
  }
  Py_Initialize();
  PyRun_SimpleString("import sys");
  PyRun_SimpleString("sys.path.append(\".\")");
  pName = PyUnicode_DecodeFSDefault(argv[1]);
  /* Error checking of pName left out */
  pModule = PyImport_Import(pName);
  Py_DECREF(pName);
  if (pModule != NULL) {
    pFunc = PyObject_GetAttrString(pModule, argv[2]);
    /* pFunc is a new reference */
    if (pFunc && PyCallable_Check(pFunc)) {
      pArgs = PyTuple_New(argc - 3);
      for (i = 0; i < argc - 3; ++i) {
        pValue = PyLong_FromLong(atoi(argv[i + 3]));
        if (!pValue) {
          Py_DECREF(pArgs);
          Py_DECREF(pModule);
          fprintf(stderr, "Cannot convert argument\n");
          return 1;
        }
        /* pValue reference stolen here: */
        PyTuple_SetItem(pArgs, i, pValue);
      }
      pValue = PyObject_CallObject(pFunc, pArgs);
      Py_DECREF(pArgs);
      if (pValue != NULL) {
        printf("Result of call: %ld\n", PyLong_AsLong(pValue));
        Py_DECREF(pValue);
      }
      else {
        Py_DECREF(pFunc);
        Py_DECREF(pModule);
        PyErr_Print();
        fprintf(stderr, "Call failed\n");
        return 1;
      }
    }
    else {
      if (PyErr_Occurred())
        PyErr_Print();
      fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
    }
    Py_XDECREF(pFunc);
    Py_DECREF(pModule);
  }
  else {
    PyErr_Print();
    fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
    return 1;
  }
  Py_Finalize();
  return 0;
}

我们希望嵌入的 Python 代码( use_numpy.py ) 使用 NumPy 设置一个矩阵，所有矩阵元素都为 1.0:

import numpy as np
def print_ones(rows, cols):
  A = np.ones(shape=(rows, cols), dtype=float)
  print(A)
​
  # we return the number of elements to verify
  # that the C++ code is able to receive return values
  num_elements = rows*cols
  return(num_elements)

具体实施

下面的代码中，我们能够使用 CMake 检查 NumPy 是否可用。我们需要确保 Python 解释器、头文件和库在系统上是可用的。然后，将再来确认 NumPy 的可用性：

1. 首先，我们定义了最低 CMake 版本、项目名称、语言和 C++标准:

   cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
   project(recipe-03 LANGUAGES CXX)
   set(CMAKE_CXX_STANDARD 11)
   set(CMAKE_CXX_EXTENSIONS OFF)
   set(CMAKE_CXX_STANDARD_REQUIRED ON)

2. 查找解释器、头文件和库的方法与前面的方法完全相同:

   find_package(PythonInterp REQUIRED)
   find_package(PythonLibs ${PYTHON_VERSION_MAJOR}.${PYTHON_VERSION_MINOR} EXACT REQUIRED)

3. 正确打包的 Python 模块，指定安装位置和版本。可以在 CMakeLists.txt 中执行 Python 脚本进行探测:

   execute_process(
     COMMAND
         ${PYTHON_EXECUTABLE} "-c" "import re, numpy; print(re.compile('/__init__.py.*').sub('',numpy.__file__))"
     RESULT_VARIABLE _numpy_status
     OUTPUT_VARIABLE _numpy_location
     ERROR_QUIET
     OUTPUT_STRIP_TRAILING_WHITESPACE
     )

4. 如果找到 NumPy，则 _numpy_status 变量为整数，否则为错误的字符串，而 _numpy_location 将包含 NumPy 模块的路径。如果找到 NumPy，则将它的位置保存到一个名为 NumPy 的新变量中。注意，新变量被缓存，这意味着 CMake 创建了一个持久性变量，用户稍后可以修改该变量:

   if(NOT _numpy_status)
       set(NumPy ${_numpy_location} CACHE STRING "Location of NumPy")
   endif()

5. 下一步是检查模块的版本。同样，我们在 CMakeLists.txt 中施加了一些 Python 魔法，将版本保存到 _numpy_version 变量中:

   execute_process(
     COMMAND
         ${PYTHON_EXECUTABLE} "-c" "import numpy; print(numpy.__version__)"
     OUTPUT_VARIABLE _numpy_version
     ERROR_QUIET
     OUTPUT_STRIP_TRAILING_WHITESPACE
     )

6. 最后， FindPackageHandleStandardArgs 的 CMake 包以正确的格式设置 NumPy_FOUND 变量和输出信息:

   include(FindPackageHandleStandardArgs)
   find_package_handle_standard_args(NumPy
     FOUND_VAR NumPy_FOUND
     REQUIRED_VARS NumPy
     VERSION_VAR _numpy_version
     )

7. 一旦正确的找到所有依赖项，我们就可以编译可执行文件，并将其链接到 Python 库:

   add_executable(pure-embedding "")
   ​
   target_sources(pure-embedding
     PRIVATE
         Py${PYTHON_VERSION_MAJOR}-pure-embedding.cpp
     )
   ​
   target_include_directories(pure-embedding
     PRIVATE
         ${PYTHON_INCLUDE_DIRS}
     )
   ​
   target_link_libraries(pure-embedding
     PRIVATE
         ${PYTHON_LIBRARIES}
     )

8. 我们还必须保证 use_numpy.py 在 build 目录中可用:

   add_custom_command(
     OUTPUT
         ${CMAKE_CURRENT_BINARY_DIR}/use_numpy.py
     COMMAND
         ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/use_numpy.py
         ${CMAKE_CURRENT_BINARY_DIR}/use_numpy.py
     DEPENDS
         ${CMAKE_CURRENT_SOURCE_DIR}/use_numpy.py
     )
   ​
   # make sure building pure-embedding triggers the above custom command
   target_sources(pure-embedding
     PRIVATE
         ${CMAKE_CURRENT_BINARY_DIR}/use_numpy.py
     )

9. 现在，我们可以测试嵌入的代码:

   $ mkdir -p build
   $ cd build
   $ cmake ..
   ​
   -- ...
   -- Found PythonInterp: /usr/bin/python (found version "3.6.5")
   -- Found PythonLibs: /usr/lib/libpython3.6m.so (found suitable exact version "3.6.5")
   -- Found NumPy: /usr/lib/python3.6/site-packages/numpy (found version "1.14.3")
   ​
   $ cmake --build .
   $ ./pure-embedding use_numpy print_ones 2 3
   ​
   [[1. 1. 1.]
   [1. 1. 1.]]
   Result of call: 6

工作原理

例子中有三个新的 CMake 命令，需要 include(FindPackageHandleStandardArgs) ：

• execute_process
• add_custom_command
• find_package_handle_standard_args

execute_process 将作为通过子进程执行一个或多个命令。最后，子进程返回值将保存到变量作为参数，传递给 RESULT_VARIABLE ，而管道标准输出和标准错误的内容将被保存到变量作为参数传递给 OUTPUT_VARIABLE 和 ERROR_VARIABLE 。 execute_process 可以执行任何操作，并使用它们的结果来推断系统配置。本例中，用它来确保 NumPy 可用，然后获得模块版本。

find_package_handle_standard_args 提供了，用于处理与查找相关程序和库的标准工具。引用此命令时，可以正确的处理与版本相关的选项( REQUIRED 和 EXACT )，而无需更多的 CMake 代码。稍后将介绍 QUIET 和 COMPONENTS 选项。本示例中，使用了以下方法:

include(FindPackageHandleStandardArgs)
find_package_handle_standard_args(NumPy
  FOUND_VAR NumPy_FOUND
  REQUIRED_VARS NumPy
  VERSION_VAR _numpy_version
  )

所有必需的变量都设置为有效的文件路径(NumPy) 后，发送到模块( NumPy_FOUND )。它还将版本保存在可传递的版本变量( _numpy_version ) 中并打印:

-- Found NumPy: /usr/lib/python3.6/site-packages/numpy (found version "1.14.3")

目前的示例中，没有进一步使用这些变量。如果返回 NumPy_FOUND 为 FALSE ，则停止配置。

最后，将 use_numpy.py 复制到 build 目录，对代码进行注释:

add_custom_command(
  OUTPUT
      ${CMAKE_CURRENT_BINARY_DIR}/use_numpy.py
  COMMAND
      ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/use_numpy.py
      ${CMAKE_CURRENT_BINARY_DIR}/use_numpy.py
  DEPENDS
      ${CMAKE_CURRENT_SOURCE_DIR}/use_numpy.py
  )
​
target_sources(pure-embedding
  PRIVATE
      ${CMAKE_CURRENT_BINARY_DIR}/use_numpy.py
  )

我们也可以使用 file(COPY…) 命令来实现复制。这里，我们选择使用 add_custom_command ，来确保文件在每次更改时都会被复制，而不仅仅是第一次运行配置时。我们将在第 5 章更详细地讨论 add_custom_command 。还要注意 target_sources 命令，它将依赖项添加到 ${CMAKE_CURRENT_BINARY_DIR}/use_numpy.py ；这样做是为了确保构建目标，能够触发之前的命令。