11.3 通过PyPI发布使用CMake/CFFI构建C/Fortran/Python项目

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

基于第9章第6节的示例，我们将重用前一个示例中的构建块，不过这次使用Python CFFI来提供Python接口，而不是pybind11。这个示例中，我们通过PyPI共享一个Fortran项目，这个项目可以是C或C++项目，也可以是任何公开C接口的语言，非Fortran就可以。

准备工作

项目将使用如下的目录结构：

  1. .
  2. ├── account
  3. │    ├── account.h
  4. │    ├── CMakeLists.txt
  5. │    ├── implementation
  6. │    │    └── fortran_implementation.f90
  7. │    ├── __init__.py
  8. │    ├── interface_file_names.cfg.in
  9. │    ├── test.py
  10. │    └── version.py
  11. ├── CMakeLists.txt
  12. ├── MANIFEST.in
  13. ├── README.rst
  14. └── setup.py

主CMakeLists.txt文件和account下面的所有源文件(account/CMakeLists.txt除外)与第9章中的使用方式相同。README.rst文件与前面的示例相同。setup.py脚本比上一个示例多了一行(包含install_require =['cffi']的那一行):

  1. # ... up to this line the script is unchanged
  2. setup(
  3.   name=_this_package,
  4.   version=version['__version__'],
  5.   description='Description in here.',
  6.   long_description=long_description,
  7.   author='Bruce Wayne',
  8.   author_email='bruce.wayne@example.com',
  9.   url='http://example.com',
  10.   license='MIT',
  11.   packages=[_this_package],
  12.   install_requires=['cffi'],
  13.   include_package_data=True,
  14.   classifiers=[
  15.     'Development Status :: 3 - Alpha',
  16.     'Intended Audience :: Science/Research',
  17.     'Programming Language :: Python :: 2.7',
  18.     'Programming Language :: Python :: 3.6'
  19.   ],
  20.   cmdclass={'build': extend_build()})

MANIFEST.in应该与Python模块和包一起安装，并包含以下内容:

  1. include README.rst CMakeLists.txt
  2. recursive-include account *.h *.f90 CMakeLists.txt

account子目录下，我们看到两个新文件。一个version.py文件，其为setup.py保存项目的版本信息：

  1. __version__ = '0.0.0'

子目录还包含interface_file_names.cfg.in文件:

  1. [configuration]
  2. header_file_name = account.h
  3. library_file_name = $<TARGET_FILE_NAME:account>

具体实施

讨论一下实现打包的步骤：

  1. 示例基于第9章第6节，使用Python CFFI扩展了account/CMakeLists.txt，增加以下指令:

    1. file(
    2.   GENERATE OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg
    3.   INPUT ${CMAKE_CURRENT_SOURCE_DIR}/interface_file_names.cfg.in
    4.   )
    6. set_target_properties(account
    7.   PROPERTIES
    8.     PUBLIC_HEADER "account.h;${CMAKE_CURRENT_BINARY_DIR}/account_export.h"
    9.     RESOURCE "${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg"
    10.   )
    12. install(
    13.   TARGETS
    14.     account
    15.   LIBRARY
    16.     DESTINATION account/lib
    17.   RUNTIME
    18.     DESTINATION account/lib
    19.   PUBLIC_HEADER
    20.     DESTINATION account/include
    21.   RESOURCE
    22.     DESTINATION account
    23.   )

    安装目标和附加文件准备好之后，就可以测试安装了。为此，会在某处创建一个新目录，我们将在那里测试安装。

  2. 新创建的目录中，我们从本地路径运行pipenv install。调整本地路径，指向setup.py脚本保存的目录:

    1. $ pipenv install /path/to/fortran-example

  3. 现在在Pipenv环境中生成一个Python shell:

    1. $ pipenv run python

  4. Python shell中，可以测试CMake包:

    1. >>> import account
    2. >>> account1 = account.new()
    3. >>> account.deposit(account1, 100.0)
    4. >>> account.deposit(account1, 100.0)
    5. >>> account.withdraw(account1, 50.0)
    6. >>> print(account.get_balance(account1))
    8. 150.0

工作原理

使用Python CFFI和CMake安装混合语言项目的扩展与第9章第6节的例子相对比，和使用Python CFFI的Python包多了两个额外的步骤:

  1. 需要setup.pys
  2. 安装目标时，CFFI所需的头文件和动态库文件，需要安装在正确的路径中，具体路径取决于所选择的Python环境

setup.py的结构与前面的示例几乎一致，唯一的修改是包含install_require =['cffi']，以确保安装示例包时，也获取并安装了所需的Python CFFI。setup.py脚本会自动安装__init__.py和version.py。MANIFEST.in中的改变不仅有README.rst和CMake文件，还有头文件和Fortran源文件:

  1. include README.rst CMakeLists.txt
  2. recursive-include account *.h *.f90 CMakeLists.txt

这个示例中，使用Python CFFI和setup.py打包CMake项目时，我们会面临三个挑战:

  • 需要将account.h和account_export.h头文件，以及动态库复制到系统环境中Python模块的位置。
  • 需要告诉__init__.py，在哪里可以找到这些头文件和库。第9章第6节中，我们使用环境变量解决了这些问题，不过使用Python模块时，不可能每次去都设置这些变量。
  • Python方面，我们不知道动态库文件的确切名称(后缀)，因为这取决于操作系统。

让我们从最后一点开始说起：不知道确切的名称，但在CMake生成构建系统时是知道的，因此我们在interface_file_names.cfg,in中使用生成器表达式，对占位符进行展开：

  1. [configuration]
  2. header_file_name = account.h
  3. library_file_name = $<TARGET_FILE_NAME:account>

输入文件用来生成${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg：

  1. file(
  2.   GENERATE OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg
  3.   INPUT ${CMAKE_CURRENT_SOURCE_DIR}/interface_file_names.cfg.in
  4.   )

然后，将两个头文件定义为PUBLIC_HEADER(参见第10章)，配置文件定义为RESOURCE：

  1. set_target_properties(account
  2.   PROPERTIES
  3.       PUBLIC_HEADER "account.h;${CMAKE_CURRENT_BINARY_DIR}/account_export.h"
  4.       RESOURCE "${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg"
  5. )

最后，将库、头文件和配置文件安装到setup.py定义的安装路径中:

  1. install(
  2.   TARGETS
  3.       account
  4.   LIBRARY
  5.       DESTINATION account/lib
  6.   RUNTIME
  7.       DESTINATION account/lib
  8.   PUBLIC_HEADER
  9.       DESTINATION account/include
  10.   RESOURCE
  11.       DESTINATION account
  12.   )

注意，我们为库和运行时都设置了指向account/lib的目标。这对于Windows很重要，因为动态库具有可执行入口点，因此我们必须同时指定这两个入口点。

Python包将能够找到这些文件，要使用account/__init__.py来完成：

  1. # this interface requires the header file and library file
  2. # and these can be either provided by interface_file_names.cfg
  3. # in the same path as this file
  4. # or if this is not found then using environment variables
  5. _this_path = Path(os.path.dirname(os.path.realpath(__file__)))
  6. _cfg_file = _this_path / 'interface_file_names.cfg'
  7. if _cfg_file.exists():
  8.   config = ConfigParser()
  9.   config.read(_cfg_file)
  10.   header_file_name = config.get('configuration', 'header_file_name')
  11.   _header_file = _this_path / 'include' / header_file_name
  12.   _header_file = str(_header_file)
  13.   library_file_name = config.get('configuration', 'library_file_name')
  14.   _library_file = _this_path / 'lib' / library_file_name
  15.   _library_file = str(_library_file)
  16. else:
  17.   _header_file = os.getenv('ACCOUNT_HEADER_FILE')
  18.   assert _header_file is not None
  19.   _library_file = os.getenv('ACCOUNT_LIBRARY_FILE')
  20.   assert _library_file is not None

本例中，将找到_cfg_file并进行解析，setup.py将找到include下的头文件和lib下的库，并将它们传递给CFFI，从而构造库对象。这也是为什么，使用lib作为安装目标DESTINATION，而不使用CMAKE_INSTALL_LIBDIR的原因(否则可能会让account/__init__.py混淆)。

更多信息

将包放到PyPI测试和生产实例中的后续步骤，因为有些步骤是类似的，所以可以直接参考前面的示例。