打包可执行文件、共享库及Python绑定时库路径无法解析问题咨询

我有一个名为cloudgen的项目，希望为其添加Python绑定以调用部分底层功能，目前已在特性分支完成初步框架搭建。由于项目主程序通过cmake构建，我决定采用scikit-build管理构建流程，使用pybind11实现绑定逻辑。

在虚拟环境中执行pip install .时流程运行正常：可执行文件安装至<prefix>/bin，共享库安装至<prefix>/lib，Python模块安装至<prefix>/lib/pythonX.Y/site-packages/cloudgen，执行pip uninstall cloudgen也能正确卸载所有相关文件。但测试Python绑定时出现两个关联问题：

• 若安装至Anaconda环境，Python模块可正常解析共享库路径并通过测试，但可执行文件无法找到对应共享库
• 若安装至python -m venv创建的虚拟环境，Python模块和可执行文件均无法解析共享库路径

搜索相关问题时，有方案提到可修改LD_LIBRARY_PATH（macOS对应DYLD_LIBRARY_PATH，Windows对应PATH）解决，但该做法通常不被推荐。我查找了相关的未解决issue、scikit-build分发构建产物相关问题、直接使用setuptools打包的相关问题，对应内容均未提及适用的库路径解析处理方案。

我想咨询：分发同时包含可执行文件、共享库和Python绑定模块的软件包时，应采用什么方案才能让库路径解析功能正常运行？

方案1：构建阶段设置RPATH（最优方案，无需修改用户环境） #

这是跨环境通用的原生解决方案，完全不需要修改用户的系统或环境变量，适配所有类Unix平台。
在项目的CMakeLists中添加如下配置：

# 开启RPATH相关配置
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)

# Linux平台配置
if(UNIX AND NOT APPLE)
    # 可执行文件RPATH：指向同安装前缀下的lib目录
    set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib")
    # Python扩展模块RPATH：从site-packages下的模块目录向上定位到lib目录
    set_target_properties(替换为你的pybind扩展目标名 PROPERTIES
        INSTALL_RPATH "$ORIGIN/../../.."
    )
endif()

# macOS平台配置
if(APPLE)
    set(CMAKE_INSTALL_RPATH "@loader_path/../lib")
    set_target_properties(替换为你的pybind扩展目标名 PROPERTIES
        INSTALL_RPATH "@loader_path/../../.."
    )
endif()

其中$ORIGIN（Linux）和@loader_path（macOS）是动态链接器识别的内置变量，代表当前二进制文件自身的所在目录，使用相对路径可以适配任意安装位置的虚拟环境或conda环境。

Windows平台无需配置RPATH，只需将共享库和可执行文件放在同一目录，Python扩展的依赖库放在扩展模块的同级目录即可，系统会自动查找同级路径下的依赖。

如果使用scikit-build-core，还需要在pyproject.toml中添加配置避免RPATH被自动清除：

[tool.scikit-build.cmake.args]
CMAKE_INSTALL_RPATH_USE_LINK_PATH = "ON"
CMAKE_BUILD_WITH_INSTALL_RPATH = "ON"

方案2：调整安装路径简化依赖查找 #

如果不想处理多平台RPATH配置，可以调整产物的安装位置：

• 将所有共享库直接安装到Python模块的目录下，即<prefix>/lib/pythonX.Y/site-packages/cloudgen
• 可执行文件的RPATH配置为指向上述Python模块目录

这种方式还可以避免和系统中其他同名共享库产生冲突，兼容性更强。

方案3：Python脚本封装可执行入口 #

如果你的可执行文件仅为核心逻辑的调用入口，可将其功能封装为Python函数，在pyproject.toml中声明控制台入口即可：

[project.scripts]
cloudgen = "cloudgen.cli:main"

这种方式完全由Python运行时处理依赖查找路径，不需要额外配置二进制文件的链接参数，适配所有平台和环境。

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