基于CMake构建分发MacOS应用遇库依赖问题求助

问题背景 #

我在Windows平台开发了基于CMake的C++桌面应用，依赖Qt和OpenCV库。适配macOS环境时，用brew安装依赖、find_package引入后本地构建正常，但在其他macOS设备运行时提示缺失.dylib库。

Windows上用windeployqt加手动复制OpenCV就能解决依赖，但macOS上用macdeployqt部署到.app bundle并修改路径后，发现复制的OpenCV库仍链接系统安装版本，写脚本用install_name_tool改路径解决了这个问题，却又遇到macdeployqt没部署必要的Qt QDBus框架的问题。我从没接触过macOS，不确定当前构建分发方式是否正确，求不用Xcode、仅通过终端CMake构建的正确方案及参考项目示例。

现有代码 #

CMakeLists.txt #

cmake_minimum_required(VERSION 3.20)
project(example LANGUAGES CXX)

# 查找依赖库
find_package(OpenCV REQUIRED)
find_package(Qt6 COMPONENTS Widgets Gui OpenGL OpenGLWidgets Multimedia MultimediaWidgets PrintSupport Charts REQUIRED)

add_executable(some_executable)
target_sources(some_executable PRIVATE "main.cpp")

# 设置生成bundle包
set_target_properties(some_executable PROPERTIES MACOSX_BUNDLE TRUE)

# 链接依赖库
# 使用的OpenCV库
target_link_libraries(some_executable PRIVATE opencv_core opencv_xfeatures2d opencv_videoio opencv_highgui opencv_video)
# 使用的Qt库
target_link_libraries(some_executable PRIVATE Qt6::Widgets Qt6::Multimedia Qt6::MultimediaWidgets Qt6::PrintSupport Qt6::Charts)

main.cpp #

#include <QApplication>
#include <QLabel>
int main(int argc, char** argv) {
    QApplication app(argc, argv);
    QLabel hello;
    hello.setText("Hello There!");
    hello.show();
    return app.exec();
}

deploy.sh #

echo 部署macOS bundle...

# 查看链接的库可以用这个命令
# otool -l some_executable.app/Contents/MacOS/some_executable

# 使用macdeployqt部署必要的库和框架
macdeployqt some_executable.app

FRAMEWORKS_PATH=some_executable.app/Contents/Frameworks

# 错误路径：OPENCV_LIB_PATH=/usr/local/Cellar/opencv/4.5.5_2/lib
OPENCV_LIB_PATH=@rpath
OPENCV_VER=405 # <- 根据你的OpenCV版本修改

echo 修改OpenCV路径...

OPENCV_LIBS=(
"libopencv_calib3d"
"libopencv_core"
"libopencv_dnn"
"libopencv_features2d"
"libopencv_flann"
"libopencv_highgui"
"libopencv_imgcodecs"
"libopencv_imgproc"
"libopencv_ml"
"libopencv_shape"
"libopencv_video"
"libopencv_videoio"
"libopencv_xfeatures2d"
)

replace_opencv_lib_path() {
    # 要修补的库
    LIB=$1

    # 待替换的链接库
    TO_REPLACE=$2

    install_name_tool -change ${OPENCV_LIB_PATH}/${TO_REPLACE}.${OPENCV_VER}.dylib @executable_path/../Frameworks/${TO_REPLACE}.${OPENCV_VER}.dylib $FRAMEWORKS_PATH/$LIB.${OPENCV_VER}.dylib
}

for lib in ${OPENCV_LIBS[@]}; do
    for lib2 in ${OPENCV_LIBS[@]}; do
        replace_opencv_lib_path $lib $lib2
    done
done

现有执行命令 #

# 配置项目
cmake .

# 构建项目
cmake --build .

# 部署
sudo /bin/sh deploy.sh

# 创建可在其他电脑测试的DMG文件
sudo macdeployqt some_executable.app -dmg

正确解决方案 #

1. 修复Qt QDBus框架缺失问题 #

macdeployqt默认不会部署所有Qt框架，尤其是QDBus这类隐式依赖。可以在命令中显式指定要部署的模块，或者添加-verbose=3参数查看缺失的依赖，再手动复制对应框架到Contents/Frameworks目录并修正路径。推荐直接在macdeployqt命令中指定模块：

macdeployqt some_executable.app -modules=Qt6DBus

2. 优化OpenCV依赖处理 #

方法一：构建阶段配置rpath

在CMakeLists.txt中添加rpath配置，让可执行文件默认从bundle内的Frameworks目录查找库，减少后续路径修改的工作量：

set_target_properties(some_executable PROPERTIES
    MACOSX_BUNDLE TRUE
    # 设置运行时库搜索路径
    INSTALL_RPATH "@executable_path/../Frameworks"
    BUILD_WITH_INSTALL_RPATH TRUE
)

方法二：自动复制OpenCV库到bundle

在deploy.sh中添加自动复制逻辑，避免手动拷贝：

# 获取brew安装的OpenCV路径
OPENCV_INSTALL_PATH=$(brew --prefix opencv)
# 复制所有OpenCV库到Frameworks目录
cp ${OPENCV_INSTALL_PATH}/lib/libopencv_*.${OPENCV_VER}.dylib ${FRAMEWORKS_PATH}/

方法三：简化路径修改脚本

当前双重循环效率低下，可通过otool自动识别依赖并修正：

# 修正每个OpenCV库的id和依赖路径
for lib in ${OPENCV_LIBS[@]}; do
    LIB_PATH=${FRAMEWORKS_PATH}/${lib}.${OPENCV_VER}.dylib
    # 修正库的自身id
    install_name_tool -id @executable_path/../Frameworks/${lib}.${OPENCV_VER}.dylib ${LIB_PATH}
    # 修正该库依赖的其他OpenCV库
    otool -L ${LIB_PATH} | grep ${OPENCV_LIB_PATH} | awk '{print $1}' | while read DEP; do
        DEP_NAME=$(basename ${DEP})
        install_name_tool -change ${DEP} @executable_path/../Frameworks/${DEP_NAME} ${LIB_PATH}
    done
done

3. 完整部署流程 #

1. 配置CMake：开启BUILD_WITH_INSTALL_RPATH，避免依赖系统库路径
2. 构建项目：推荐用out-of-source构建，避免污染源码目录
3. 复制OpenCV库：自动将brew安装的OpenCV库复制到bundle的Frameworks目录
4. 运行macdeployqt：带上必要的模块参数部署Qt依赖
5. 修正库路径：用install_name_tool修正OpenCV库的id和相互引用路径
6. 创建DMG：用macdeployqt生成DMG，避免使用sudo（防止权限问题）

4. 权限注意事项 #

部署过程中尽量不要用sudo，否则生成的bundle会带有root权限，导致其他用户运行时出现权限错误。如果遇到权限问题，检查项目目录的读写权限，确保当前用户拥有完整权限。

参考项目示例（纯终端CMake构建） #

优化后的CMakeLists.txt #

cmake_minimum_required(VERSION 3.20)
project(example LANGUAGES CXX)

# 设置C++标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 查找依赖库（显式包含DBus）
find_package(OpenCV REQUIRED)
find_package(Qt6 COMPONENTS Widgets Gui OpenGL OpenGLWidgets Multimedia MultimediaWidgets PrintSupport Charts DBus REQUIRED)

add_executable(some_executable)
target_sources(some_executable PRIVATE "main.cpp")

# 配置bundle和rpath
set_target_properties(some_executable PROPERTIES
    MACOSX_BUNDLE TRUE
    MACOSX_BUNDLE_BUNDLE_NAME "ExampleApp"
    MACOSX_BUNDLE_GUI_IDENTIFIER "com.example.app"
    INSTALL_RPATH "@executable_path/../Frameworks"
    BUILD_WITH_INSTALL_RPATH TRUE
)

# 链接依赖库
target_link_libraries(some_executable PRIVATE
    opencv_core opencv_xfeatures2d opencv_videoio opencv_highgui opencv_video
    Qt6::Widgets Qt6::Multimedia Qt6::MultimediaWidgets Qt6::PrintSupport Qt6::Charts Qt6::DBus
)

优化后的deploy.sh #

#!/bin/bash
set -e # 出错时终止脚本

echo 开始部署macOS应用...

APP_BUNDLE="some_executable.app"
FRAMEWORKS_PATH="${APP_BUNDLE}/Contents/Frameworks"
OPENCV_VER=405
OPENCV_INSTALL_PATH=$(brew --prefix opencv)

# 1. 运行macdeployqt部署Qt依赖，包含DBus模块
macdeployqt ${APP_BUNDLE} -verbose=2 -modules=Qt6DBus

# 2. 复制OpenCV库到Frameworks目录
echo 复制OpenCV库...
cp ${OPENCV_INSTALL_PATH}/lib/libopencv_*.${OPENCV_VER}.dylib ${FRAMEWORKS_PATH}/

# 3. 修正OpenCV库的路径和id
echo 修正OpenCV库路径...
OPENCV_LIBS=$(ls ${FRAMEWORKS_PATH}/libopencv_*.${OPENCV_VER}.dylib | xargs basename | sed "s/.${OPENCV_VER}.dylib//")

for lib in ${OPENCV_LIBS}; do
    LIB_PATH="${FRAMEWORKS_PATH}/${lib}.${OPENCV_VER}.dylib"
    # 修正库的自身id
    install_name_tool -id "@executable_path/../Frameworks/${lib}.${OPENCV_VER}.dylib" ${LIB_PATH}
    # 修正依赖的其他OpenCV库
    otool -L ${LIB_PATH} | grep "libopencv_" | awk '{print $1}' | while read DEP; do
        DEP_NAME=$(basename ${DEP})
        install_name_tool -change "${DEP}" "@executable_path/../Frameworks/${DEP_NAME}" ${LIB_PATH}
    done
done

# 4. 验证依赖路径是否正确
echo 验证依赖路径...
otool -L ${APP_BUNDLE}/Contents/MacOS/some_executable | grep -E "(Qt|opencv)"

# 5. 生成DMG
echo 生成DMG文件...
macdeployqt ${APP_BUNDLE} -dmg

echo 部署完成！

执行命令 #

# 创建构建目录（推荐out-of-source构建）
mkdir build && cd build
cmake ..
cmake --build . --config Release
# 回到项目根目录执行部署脚本
cd ..
./deploy.sh

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