Messense Lv

使用 CMake 构建 Python C/C++ 扩展

众所周知，Python 语言的性能相比其他语言如 C/C++ 等要弱很多，所以当我们需要高性能的时候往往借助于 Python 的 C/C++ 扩展或者 Cython。

通常构建 Python C/C++ 扩展会使用 distutils 的 Extension 类，需要在 setup.py 中配置头文件包含路径 include_dirs、C/C++ 源文件路径 sources 等，比如下面这个Python 官方文档上的例子：

from distutils.core import setup, Extension



module1 = Extension(

    'demo',

    define_macros=[

        ('MAJOR_VERSION', '1'),

        ('MINOR_VERSION', '0')

    ],

    include_dirs=['/usr/local/include'],

    libraries =['tcl83'],

    library_dirs=['/usr/local/lib'],

    sources=['demo.c']

)



setup(

    name='PackageName',

    version='1.0',

    description='This is a demo package',

    author='Martin v. Loewis',

    author_email='martin@v.loewis.de',

    url='https://docs.python.org/extending/building',

    long_description='''

This is really just a demo package.

''',

    ext_modules=[module1]

)

这种方式对于绝大多数简单的项目应该是足够了，而当你需要用到一些 C/C++ 第三方库的时候可能会遇到因为某些原因需要将三方库的源码和项目源码一起进行编译的情况（比如 abseil-cpp），这个情况下往往会遇到 C/C++ 依赖管理的问题，CMake 则是常用的 C/C++ 依赖管理工具，本文将总结、分享一下使用 CMake 来构建 Python C/C++ 扩展的方案。

调研可选方案

首先来看一下 CMake 项目本身一般是如何构建的，一般 CMake 项目都会在项目根目录下有个 CMakeLists.txt 的 CMake 项目定义文件，构建方式通常如下：

mkdir build

cd build

cmake ..

make

那基本的思路就是在 Python 包构建过程中（pip install 或者 python setup.py install 等）调用上述命令完成扩展构建。通过 Google 搜索可以发现，一个方案是通过继承 distutils 的 Extension 来手工实现，另一个方案则是用别人写好的现成的封装库 scikit-build。

方案一 distutils CMake extension

这个方案有个现成的例子，pybind11 的 CMake 示例项目，BTW，pybind11 也是一个写 Python C++ 扩展的项目。看一下它的 setup.py 的代码：

import os

import re

import sys

import platform

import subprocess



from setuptools import setup, Extension

from setuptools.command.build_ext import build_ext

from distutils.version import LooseVersion





class CMakeExtension(Extension):

    def __init__(self, name, sourcedir=''):

        Extension.__init__(self, name, sources=[])

        self.sourcedir = os.path.abspath(sourcedir)





class CMakeBuild(build_ext):

    def run(self):

        try:

            out = subprocess.check_output(['cmake', '--version'])

        except OSError:

            raise RuntimeError("CMake must be installed to build the following extensions: " +

                               ", ".join(e.name for e in self.extensions))



        if platform.system() == "Windows":

            cmake_version = LooseVersion(re.search(r'version\s*([\d.]+)', out.decode()).group(1))

            if cmake_version < '3.1.0':

                raise RuntimeError("CMake >= 3.1.0 is required on Windows")



        for ext in self.extensions:

            self.build_extension(ext)



    def build_extension(self, ext):

        extdir = os.path.abspath(os.path.dirname(self.get_ext_fullpath(ext.name)))

        # required for auto-detection of auxiliary "native" libs

        if not extdir.endswith(os.path.sep):

            extdir += os.path.sep



        cmake_args = ['-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=' + extdir,

                      '-DPYTHON_EXECUTABLE=' + sys.executable]



        cfg = 'Debug' if self.debug else 'Release'

        build_args = ['--config', cfg]



        if platform.system() == "Windows":

            cmake_args += ['-DCMAKE_LIBRARY_OUTPUT_DIRECTORY_{}={}'.format(cfg.upper(), extdir)]

            if sys.maxsize > 2**32:

                cmake_args += ['-A', 'x64']

            build_args += ['--', '/m']

        else:

            cmake_args += ['-DCMAKE_BUILD_TYPE=' + cfg]

            build_args += ['--', '-j2']



        env = os.environ.copy()

        env['CXXFLAGS'] = '{} -DVERSION_INFO=\\"{}\\"'.format(env.get('CXXFLAGS', ''),

                                                              self.distribution.get_version())

        if not os.path.exists(self.build_temp):

            os.makedirs(self.build_temp)

        subprocess.check_call(['cmake', ext.sourcedir] + cmake_args, cwd=self.build_temp, env=env)

        subprocess.check_call(['cmake', '--build', '.'] + build_args, cwd=self.build_temp)



setup(

    name='cmake_example',

    version='0.0.1',

    author='Dean Moldovan',

    author_email='dean0x7d@gmail.com',

    description='A test project using pybind11 and CMake',

    long_description='',

    ext_modules=[CMakeExtension('cmake_example')],

    cmdclass=dict(build_ext=CMakeBuild),

    zip_safe=False,

)

可以看出，它通过重写 setuptools 的 build_ext cmdclass 在构建过程中调用了 cmake 命令完成扩展的构建。

这个方案比较适合 pybind11 的项目，因为它已经提供了很多 CMake 的 module 比如怎么找到 Python.h、libpython 等，打开示例项目的 CMakeLists.txt 可以发现它使用了一个 pybind11 提供的 CMake 函数 pybind11_add_module 来定义 Python 扩展，免去了很多繁琐的配置。

cmake_minimum_required(VERSION 2.8.12)

project(cmake_example)



add_subdirectory(pybind11)

pybind11_add_module(cmake_example src/main.cpp)

如果不使用 pybind11 则比较麻烦，看看 Apache Arrow Python 包的 CMakeLists.txt 感受一下。

方案二 scikit-build

scikit-build 是一个增强的 Python C/C++/Fortan/Cython 扩展构建系统生成器，本质上也是 Python setuptools 和 CMake 的胶水。

我们看一下 sciket-build 的 hello-cpp 示例：

  • setup.py
import sys



from skbuild import setup



# Require pytest-runner only when running tests

pytest_runner = (['pytest-runner>=2.0,<3dev']

                 if any(arg in sys.argv for arg in ('pytest', 'test'))

                 else [])



setup_requires = pytest_runner



setup(

    name="hello-cpp",

    version="1.2.3",

    description="a minimal example package (cpp version)",

    author='The scikit-build team',

    license="MIT",

    packages=['hello'],

    tests_require=['pytest'],

    setup_requires=setup_requires

)

基本上就是一个 setuptools.setup 的完整替代，不再使用 from setuptools import set 转用 from skbuild import setup。

  • CMakeLists.txt
cmake_minimum_required(VERSION 3.4.0)



project(hello)



find_package(PythonExtensions REQUIRED)



add_library(_hello MODULE hello/_hello.cxx)

python_extension_module(_hello)

install(TARGETS _hello LIBRARY DESTINATION hello)

这里没有看到类似上面 pybind11 CMake 示例中的 add_subdirectory(pybind11) 语句，而是直接用的 find_package(PythonExtensions REQUIRED) 和 python_extension_module CMake 函数：

  1. PythonExtensions 的 CMake 定义已经打包在 scikit-build 中
  2. 调用 skbuild.setup 的过程中 scikit-build 自动把它打包的 CMake 定义文件加载了所以上面才不需要像 pybind11 那样做
  3. install(TARGETS _hello LIBRARY DESTINATION hello) 将构建好的扩展的动态链接库复制到 hello/ 目录中，从而可以在 Python 中使用 from hello._hello import hello 导入扩展中的 hello 函数

通常还会增加 pyproject.toml 来安装 pip 构建时候需要的依赖包：

[build-system]

requires = ["setuptools", "wheel", "scikit-build", "cmake", "ninja"]

比较有意思的是，scikit-build 并不需要你的系统上全局安装 CMake/Ninja，它打包了 manylinux 的 CMake 和 Ninja 的二进制 wheels 并发布到了 PyPi 上，cool.

scikit-build 还支持类似的方式构建使用 Cython 和 pybind11 等的扩展，功能强大非常方便。

后记

最近工作中完成了使用 CMake 和 scikit-build 改造一个 C++ 和 Cython 写的 Python 扩展项目以便能够使用 abseil-cpp 的 Swiss Tables 优化性能，这篇文章差不多就是 brain dump 一下调研的过程，后面我想写一下如何在 Cython 中使用 abseil-cpp 的 containers 的文章，stay tuned.