使用scikit-build和nanobind构建wheel时如何打包二进制与Python代码

1. 修正CMakeLists.txt的安装路径 #

核心问题是CMake未将编译出的C++模块安装到Python包的对应目录下，需修改install规则，让nanobind生成的.so文件最终落在site-packages的包目录中：

# 导入nanobind依赖
find_package(nanobind REQUIRED)

# 生成nanobind模块（示例模块名为_mypkg，通常作为Python包的底层实现）
nanobind_add_module(
    _mypkg
    STABLE_ABI
    NO_EXCEPTIONS
    src/your_cpp_source.cpp  # 替换为你的C++源码路径
)

# 关键配置：将模块安装到Python包目录下
install(
    TARGETS _mypkg
    LIBRARY DESTINATION "${PYTHON_PACKAGE_DIR}/mypkg"
)

${PYTHON_PACKAGE_DIR}是scikit-build-core自动注入的变量，会自动映射到wheel中对应Python包的安装路径，最终对应site-packages/mypkg目录。

2. 配置pyproject.toml确保包结构正确 #

无需改用setup.py，保持pyproject.toml的简洁配置，明确Python包结构：

[build-system]
requires = ["scikit-build-core>=0.7", "nanobind>=2.0", "ninja"]
build-backend = "scikit_build_core.build"

[project]
name = "mypkg"
version = "0.1.0"
packages = ["mypkg"]  # 指定你的Python源码包目录

[tool.scikit-build]
cmake.minimum-version = "3.15"
build-type = "Release"

确保项目目录结构符合规范：

├── mypkg/               # Python源码包目录
│   ├── __init__.py      # 必须存在，用于导入C++模块
│   └── other_py_files.py
├── src/                 # C++源码目录
│   └── your_cpp_source.cpp
├── CMakeLists.txt
└── pyproject.toml

在mypkg/__init__.py中添加模块导入：

from ._mypkg import *  # 导入编译好的C++模块

3. 重新构建与验证 #

执行命令重新生成wheel并安装：

python -m pip wheel . --no-deps
pip install mypkg-0.1.0-cpXX-cpXX-linux_x86_64.whl

安装完成后，检查site-packages/mypkg目录，.so文件会与Python源码共存，直接导入mypkg即可使用C++模块，无需修改环境变量。

常见问题排查 #

• 若${PYTHON_PACKAGE_DIR}未识别，确保scikit-build-core版本≥0.7，或直接用相对路径DESTINATION "mypkg"，scikit-build-core会自动映射到正确路径。
• 禁止在CMake中使用绝对路径安装，否则会导致wheel打包路径错误。
• 确保nanobind模块名与__init__.py中的导入路径一致，避免导入失败。

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