• 无人机
• 智能硬件

本篇技术指南围绕 tools/skills/qt-cmake-project/references/configure.md 展开，系统讲解 Qt 6 + CMake 项目的"试运行"流程：先定位 cmake、ninja 与 Qt SDK 中的qt-cmake工具，再以 out-of-tree 方式完成首次配置，最后用ninja进行日常增量构建。文章同时结合本仓库（QGroundControl，基于 Qt 6 的跨平台地面站）的 CMakePresets.json、tools/configure.py 与平台预设，给出真实可复现的命令与排错要点。读完你将掌握一套不依赖 IDE、可在任意 CI 与终端环境中复用的 Qt 项目配置/构建工作流。

一、适用场景：本文解决什么问题

configure.md是 qt-cmake-project 技能集中关于"配置与构建"的参考文档，覆盖三个目标：

1. 定位框架与工具要求（cmake、ninja-build、Qt SDK）；
2. 首次配置项目（out-of-tree 构建，生成 Ninja 构建文件）；
3. 从命令行增量构建（ninja）。

它服务于"尝试运行一个 Qt 6 CMake 项目"这一核心诉求，不涉及 QML 模块编写、资源管理或子项目组织（那些属于 simple-project.md、modular-architecture.md、qml-integration.md 与 resources.md 的主题，可在需要时按 SKILL.md 的决策树取用）。

二、定位构建工具：cmake、ninja 与 Qt SDK

2.1 检查命令行工具

文档要求首先确认cmake与ninja（来自 ninja-build 包）可以从命令行直接调用：

cmake --version ninja --version

这两者是一切后续操作的基础：cmake负责生成构建系统，ninja负责实际编译与链接。QGroundControl 的根 CMakeLists.txt 声明cmake_minimum_required(VERSION 3.25)，CMakePresets.json 的cmakeMinimumRequired同样为 3.25.0——如果你的 CMake 版本低于此值，配置阶段会直接报错。Ninja 则是 QGC 全部预设统一采用的生成器（见下文第四部分），因此ninja也必须可用。

2.2 定位 Qt SDK 与 qt-cmake

文档给出的定位策略是"先确定主机操作系统，再按该 OS 的典型安装位置搜索 Qt 框架"。关键点有二：

• 开发环境中的 Qt 可能装在用户目录，而非系统目录，搜索时两者都要覆盖；
• 目标是找到包含工具链命令的 Qt 安装目录，即bin子目录下的qt-cmake（Windows 上为qt-cmake.bat）。

找到bin/qt-cmake后，所有配置活动都应使用qt-cmake，而不是裸cmake。原因是 Qt SDK 的qt-cmake包装脚本会自动注入 Qt 相关的工具链信息（主机路径、编译器前缀等），让配置阶段就能识别出正确的 Qt 安装。

本仓库的 tools/configure.py 中find_qt_cmake()函数完整实现了这一搜索策略，其优先级为：

1. 显式参数：--qt-root <dir>指定的 Qt 安装目录；
2. 环境变量：QT_ROOT_DIR；
3. 常见安装路径（按版本号降序，优先最新版本）：
   • Linux：~/Qt/*/gcc_64/bin/qt-cmake、/opt/Qt/*/gcc_64/bin/qt-cmake、/usr/lib/qt6/bin/qt-cmake（ARM64 主机则匹配gcc_arm64kit）；
   • macOS：~/Qt/*/macos/bin/qt-cmake、~/Qt/*/clang_64/bin/qt-cmake、/Applications/Qt/*/...；
   • Windows：C:/Qt/*/msvc*_64/bin/qt-cmake.bat（ARM64 主机匹配msvc*_arm64），Windows 上优先.bat变体，因为qt-cmake本身可能是 bash 脚本。

2.3 找不到 qt-cmake 怎么办

文档明确要求：找不到或不确定时，询问用户，不要臆测路径。这也与本仓库的实际行为一致——configure.py在找不到qt-cmake时会报错Error: qt-cmake not found并提示可改用--no-qt-cmake回退到裸cmake（仅适用于自定义工具链场景）。

三、首次配置：out-of-tree 构建

3.1 为什么坚持 out-of-tree

文档强调"倾向于 out-of-tree 构建"，即构建目录与源码目录分离、位于项目目录之外。这样做的直接收益是：源码树保持干净，.gitignore无需为构建产物打补丁；删除整个构建目录即可无损回到"未配置"状态，不影响任何源文件。

对于示例项目MyApp，在 Unix 系平台上的首次配置是：

mkdir MyApp-build cd MyApp-build qt-cmake -S ../MyApp -B . -G Ninja ninja

拆解这条命令：

配置完成后目录内会生成CMakeCache.txt、build.ninja等构建文件，之后ninja直接读取并执行构建。相比 Makefiles，Ninja 的增量构建更快、并行调度更好，是 Qt 官方模板与 QGC 的默认选择。

3.2 在 QGroundControl 中的实际配置命令

把上述流程映射到本仓库，官方构建文档 docs/en/qgc-dev-guide/getting_started/index.md 给出的命令行配置是：

~/Qt/6.11.1/gcc_64/bin/qt-cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug

注意三点差异：

• 当前仓库要求Qt 6.11.1（仅此版本，文档中有明确警告：不要使用其他版本），qt-cmake的路径需替换为你实际的 Qt 安装位置与 kit；
• -B build把构建目录放在源码树内的build/（QGC 预设体系的默认binaryDir是${sourceDir}/build，见 common.json）；
• 额外传入-DCMAKE_BUILD_TYPE=Debug显式指定构建类型——QGC 根CMakeLists.txt在未指定时会默认Release（见 CMakeLists.txt）。

Windows 上应使用对应 kit 的批处理入口，并从 VS 2022 的x64 Native Tools Command Prompt中执行：

C:\Qt\6.11.1\msvc2022_64\bin\qt-cmake.bat -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug

四、命令行构建：ninja 增量编译

首次配置完成后，日常构建只需要两条命令之一：

cd MyApp-build ninja

ninja只重建自上次构建以来发生变化的部分，并支持-jN控制并行任务数（QGC 的 justfile 中build任务即通过--parallel透传该能力）。

如果不想切换到构建目录，也可以用cmake --build通用形式，它根据CMakeCache.txt里记录的生成器自动调用底层构建工具：

cmake --build build --config Debug

这里--config只对 Visual Studio、Xcode 这类多配置生成器有意义；Ninja 是单配置生成器，构建类型由配置阶段的CMAKE_BUILD_TYPE决定。QGC 构建文档中的完整三步是：

# 1) 配置 ~/Qt/6.11.1/gcc_64/bin/qt-cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug # 2) 构建 cmake --build build --config Debug # 3) 运行 ./build/Debug/QGroundControl

Windows 上运行build\Debug\QGroundControl.exe。

五、进阶：预设体系与构建缓存（仓库实践）

5.1 CMake 预设：把"定位要求"固化为机器配置

configure.md的定位步骤本质上是人类对"Qt 装在哪"的手动探测；而 CMakePresets.json（version 6）把这一知识固化成了可复用的机器配置，这正是 QGC 大规模采用的做法：

• 通用预设（cmake/presets/common.json）：default（Debug）、default-release、default-relwithdebinfo、default-minsizerel，均使用 Ninja 生成器、binaryDir为${sourceDir}/build，并通过继承debug/release等隐藏预设控制QGC_BUILD_TESTING、QGC_DEBUG_QML等缓存变量；
• 平台预设（cmake/presets/Linux.json、cmake/presets/Windows.json）：通过toolchainFile: "$penv{QT_ROOT_DIR}/lib/cmake/Qt6/qt.toolchain.cmake"直接引用 Qt SDK 提供的工具链文件——这正是"定位 Qt SDK"的 CMake 原生形态：以QT_ROOT_DIR环境变量指向 Qt 安装目录，CMake 会从$penv{}宏读取它。该机制与qt-cmake包装脚本的目的相同：让配置阶段知道去哪里找 Qt 工具链。

列出全部预设、查看每个可见预设对应的 workflow：

cmake --list-presets=all cmake --workflow --preset Linux-debug

cmake --workflow可把 configure → build（→ test/package）串成一步，与configure.md中"配置 + ninja"的两步等价但更聚合。

5.2 构建缓存：ccache 与 moccache

QGC 在配置阶段自动启用两级缓存，均可视为对"重复配置/构建开销"的工程化优化：

• ccache：缓存编译器输出（.ccache/），检测到ccache在 PATH 中即启用；
• moccache（tools/moccache.py）：以内容寻址方式缓存 Qt moc 输出，通过配置期生成的启动脚本接入AUTOMOC_EXECUTABLE，缓存目录默认.cache/moccache/，可用QGC_USE_MOCCACHE开关控制。

这与configure.md强调的"优先 out-of-tree、构建产物可随时丢弃"相辅相成——缓存存放在源码树内，因此删除build/目录不会丢失已缓存的编译产物，重建时能跳过整个 moc 阶段。

六、常见问题与排错

七、小结

回顾configure.md的核心工作流，可以总结为一条主线：定位工具（cmake + ninja + Qt SDK 的 qt-cmake）→ out-of-tree 首次配置（qt-cmake -S <src> -B <build> -G Ninja）→ ninja 增量构建。本文又在本仓库中找到了这条主线的规模化实现：tools/configure.py的find_qt_cmake()实现了跨平台 Qt 定位逻辑，CMakePresets.json及其平台预设把 Qt 工具链路径固化为QT_ROOT_DIR+qt.toolchain.cmake，而justfile与 ccache/moccache 则覆盖了从"试运行"到"日常迭代"的完整闭环。这套流程不依赖任何特定 IDE，可原样迁移到本地终端、CI 流水线与容器构建场景。

• 无人机
• 智能硬件