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；这样做是为了确保构建目标，能够触发之前的命令。