如何通过Python安装仅头文件C++库并保留文件结构？

Alright, let's tackle your two problems step by step. I’ve worked through this exact scenario for header-only C++ dependencies in Python extensions, so here’s a practical, maintainable solution:

1. 先梳理你的项目结构（关键前提） #

First, make sure your project follows a standard Python package structure—this is essential for setuptools to properly handle your headers. Here’s an example structure (adjust to match your actual files):

your_cpp_header_lib/
├── setup.py
├── MANIFEST.in
└── your_cpp_header_lib/       # 与项目同名的子包目录
    ├── __init__.py            # 必须存在，标记为Python包
    └── include/               # 存放所有C++头文件的目录
        ├── your_lib/
        │   ├── core.h
        │   └── utils/
        │       └── helper.h
        └── global_config.h

2. 配置setup.py安装头文件并保留结构 #

Modify your setup.py to explicitly tell setuptools to include your header files and preserve their directory hierarchy. Here’s the code:

from setuptools import setup, find_packages

setup(
    name="your_cpp_header_lib",
    version="0.1.0",
    packages=find_packages(),  # 自动发现你的Python包
    # 指定要包含的头文件，**递归匹配所有子目录
    package_data={
        "your_cpp_header_lib": [
            "include/**/*.h",
            "include/*.h"
        ]
    },
    include_package_data=True,  # 启用包数据包含
    # 可选：帮助其他扩展快速定位你的库
    provides=["your_cpp_header_lib"],
)

关键说明： #

• package_data：通过通配符**递归匹配所有子目录下的.h文件，确保原有的目录结构被完整保留。
• include_package_data=True：让setuptools读取MANIFEST.in（下面会说）来确认要包含的文件，避免头文件被遗漏在分发包之外。

3. 添加MANIFEST.in确保头文件被打包 #

Create a MANIFEST.in file in your project root—this tells setuptools which non-Python files to include when building distributions (like .egg or .wheel):

# 递归包含包目录下的所有.h文件
recursive-include your_cpp_header_lib/include *.h

4. 安装并验证 #

Run the install command as usual:

python3 setup.py install

To verify:

• Navigate to your Python environment’s site-packages directory (e.g., venv/lib/python3.x/site-packages/your_cpp_header_lib/include/)
• You’ll see your full header file structure preserved exactly as in your source code.

5. 在其他Python扩展中使用这些头文件 #

When building another Python extension that depends on your header library, you can easily reference the installed headers using pkg_resources:

from setuptools import setup, Extension
import pkg_resources

# 自动获取安装后的头文件路径
include_dirs = [
    pkg_resources.resource_filename("your_cpp_header_lib", "include")
]

# 定义你的扩展
my_extension = Extension(
    "my_python_extension",
    sources=["extension_source.cpp"],
    include_dirs=include_dirs
)

setup(
    name="my_python_extension",
    ext_modules=[my_extension]
)

为什么你的原有方法没生效？ #

• By default, setuptools ignores non-Python files unless explicitly told to include them—this is why your headers weren’t being installed with the .egg file.
• Without recursive wildcards or proper package structure, setuptools would flatten your header directories instead of preserving their hierarchy.

内容的提问来源于stack exchange，提问作者Tom de Geus