如何配置cibuildwheel/auditwheel识别并适配ctypes调用的外部库

核心问题分析 #

auditwheel默认通过静态扫描Python扩展模块的动态依赖处理库打包，但ctypes是运行时动态加载依赖，无法被静态检测到。当前流程中手动将libspatialindex复制到rtree/lib，auditwheel会扫描到该二进制文件并迁移到标准的Rtree.libs目录，但原rtree/lib下的文件未被清理，导致最终wheel中存在两份重复库。

现代实践方案 #

方案一：调整构建流程，将libspatialindex作为系统依赖交由auditwheel处理 #

这是最符合auditwheel设计逻辑的方案，避免手动管理库路径：

1. 修改编译脚本：更新install_libspatialindex.bash，将编译好的libspatialindex安装到构建环境的系统路径（如/usr/local/lib），而非复制到rtree/lib：

   # 替换原复制到rtree/lib的代码
   make install DESTDIR=/usr/local
   ldconfig /usr/local/lib
   

2. 更新构建配置：在setup.py（或pyproject.toml）中移除rtree/lib的package_data配置，不再手动打包库文件。
3. 配置cibuildwheel：在构建阶段设置LD_LIBRARY_PATH指向libspatialindex的安装路径，确保auditwheel能扫描到该依赖：

   # 在GitHub Actions的build.yml中添加
   - name: Set library path
     run: echo "LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH" >> $GITHUB_ENV
   

4. 运行时适配：在Rtree的初始化代码中，无需硬编码库路径，auditwheel会自动设置RPATH，ctypes可直接通过库名加载：

   from ctypes import CDLL
   lib = CDLL("libspatialindex_c.so")
   

方案二：通过auditwheel配置排除重复库文件 #

如果暂时无法调整编译流程，可直接让auditwheel清理原目录的重复库：

1. 添加auditwheel参数：在cibuildwheel.toml或GitHub Actions的build.yml中，配置auditwheel排除rtree/lib下的库文件：

   [tool.cibuildwheel.linux]
   auditwheel_args = ["--exclude", "rtree/lib/libspatialindex*.so*"]
   

2. 运行时路径适配：在Rtree代码中手动指定Rtree.libs的路径供ctypes加载：

   import os
   from importlib.resources import files
   
   pkg_root = files("rtree")
   lib_dir = os.path.join(pkg_root, "Rtree.libs")
   os.environ["LD_LIBRARY_PATH"] = f"{lib_dir}:{os.environ.get('LD_LIBRARY_PATH', '')}"
   from ctypes import CDLL
   lib = CDLL("libspatialindex_c.so")
   

方案三：集成临时清理步骤到构建流程 #

如果前两种方案暂不适用，可将你当前的手动清理步骤自动化集成到cibuildwheel的后构建阶段：

# 在GitHub Actions的build.yml中添加
- name: Remove duplicate library directory
  if: runner.os == 'Linux'
  run: |
    WHEEL_FILE=$(ls dist/*.whl)
    wheel unpack "$WHEEL_FILE"
    WHEEL_DIR=$(basename "$WHEEL_FILE" .whl)
    rm -rf "$WHEEL_DIR"/rtree/lib
    wheel pack "$WHEEL_DIR"
    rm -rf "$WHEEL_DIR"

总结 #

优先推荐方案一，它遵循auditwheel的设计规范，减少手动维护成本，同时避免库重复问题。方案二适合需要保留现有编译流程的场景，方案三作为临时过渡方案。

内容的提问来源于stack exchange，提问作者Mike T