CMake工程自动下载依赖的Qt SDK

背景

最近需要将部门某个SDK的CI流程，从部门自己部署的打包机，迁移到集团的打包集群上。
这个SDK的Demo依赖Qt。原有流程是打包机本地安装指定版本的Qt SDK并设置好QTDIR等环境变量，CMake工程通过环境变量查找Qt SDK。但因为各种原因，集团打包集群上无法预先安装Qt SDK。一番调研之后，实现了CMake工程在配置阶段自动下载并使用指定版本的Qt SDK。

方法

原理

  1. 通过FetchContent下载并解压指定版本的Qt SDK二进制。
  2. 使用find_package加载指定位置的Qt SDK。

获取指定Qt SDK版本的下载地址

我们的工程使用Qt官方编译的二进制文件。可以从Qt Downloads或者镜像站(比如清华大学开源软件镜像站)上查找对应的Qt SDK版本。当前目录结构大致按照系统/平台/Qt版本/组件的顺序归类。例如，qtsdkrepository/mac_x64/desktop/qt6_682/qt6_682/qt.qt6.682.clang_64/6.8.2-0-202501260836qtbase-MacOS-MacOS_14-Clang-MacOS-MacOS_14-X86_64-ARM64.7z对应了mac系统桌面端平台使用clang编译的universal版本的Qt 6.8.2。
如果使用自己编译的Qt，或者单纯的嫌麻烦，也可以将本地的Qt SDK压缩后上传到一个可以被下载的地方，比如集团内部的OSS。

配置CMake工程

简化后的配置，以mac平台为例：

1
2
3
4
5
6
7
8
9
10
11
FetchContent_Declare(
        qtbase
        URL https://download.qt.io/online/qtsdkrepository/mac_x64/desktop/qt6_682/qt6_682/qt.qt6.682.clang_64/6.8.2-0-202501260836qtbase-MacOS-MacOS_14-Clang-MacOS-MacOS_14-X86_64-ARM64.7z
        URL_HASH SHA256=7d7634ee7bdc6594961dd745fed9c1f8b6cef862d3442531231d8cf3c183210b
        EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(qtbase)
find_package(Qt6 COMPONENTS Core Widgets REQUIRED PATHS ${qtbase_SOURCE_DIR} NO_DEFAULT_PATH)

qt_add_executable(demo)
target_link_libraries(demo PUBLIC Qt6::Core Qt6::Widgets)
  1. 使用FetchContent_Declare从指定url上下载文件，校验hash后解压。
  2. 使用FetchContent_MakeAvailable确保在完成下载后再执行后续流程。
    • 完成后会设置一系列的变量值。如*_SOURCE_DIR，例子中对应qtbase_SOURCE_DIR，值为url对应的文件在本地被解压后的目录。
  3. 使用find_package从qtbase_SOURCE_DIR中查找并配置Qt SDK。
  4. 链接并使用Qt SDK。