使用 CMake 构建项目

操作指南：使用 CMake 构建

要为所选套件指定构建设置，请转至Projects >Build Settings 。

在Qt Creator 中配置中型至大型CMake项目可能颇具挑战性，因为需要向CMake传递大量变量才能正确配置项目。为简化此过程，Qt Creator 会根据套件首选项为您生成初始配置，并将其显示在项目Build Settings 中的Initial Configuration 中。或者，您也可以使用CMake预设来配置CMake。

“Configure ”字段显示了Qt Creator 根据“Build directory ”和“Build type ”字段的值构建的实际 CMake 调用。

您可以在“Additional CMake options ”中指定其他 CMake 选项，例如“--find-debug ”、“--trace-expand ”或“--warn-uninitialized ”。有关这些选项的更多信息，请单击字段名称中的链接，或参阅《CMake：cmake(1)》。

选择Kit Configuration 以编辑该项目所选构建和运行套件的 CMake 设置。

您可以使用CMake 预设文件来指定常见的配置、构建和测试选项，并与他人共享。

初始配置

Initial Configuration 列出了“Qt Creator ”在首次配置 CMake 项目时使用的变量。其中，来自套件 CMake 配置的默认值以斜体显示。Qt Creator 将变量的初始配置列表保存到文件CMakeLists.txt.user 中，该文件位于项目源代码目录下的.qtcreator 目录中。

当前配置

Current Configuration 列出了位于.cmake/api/v1/reply 目录中cmake-file-api JSON 导出文件中的 CMake 变量。其中，来自初始配置的变量以斜体显示，不匹配的值则以红色显示。

点击“Run CMake ”按钮后，您可以查看并修改Qt Creator 传递给 CMake 的变量的实际值。“Key ”列列出了变量名称，“Value ”列列出了其当前值。 有关这些变量的更多信息，请在上下文菜单中选择“Help ”，或参阅《CMake：cmake-variables(7)》。有关 Qt XML 特定变量的更多信息，请参阅《CMake 变量参考》。

多配置支持

Qt Creator 支持多配置生成器，例如 Xcode、Visual Studio 和 Ninja Multi-Config。这意味着您只需配置一次 CMake 并仅需一个构建目录，即可更快速地在不同构建类型之间切换。

不过，这也意味着Qt Creator 无法再简单地解析第一个 CMake file-api JSON 导出内容。因此，Build type 字段的值必须与CMAKE_BUILD_TYPE 变量的值一致，以便单配置生成器（Ninja、Makefile）能够确定应使用哪个生成器。

在 iOS 平台上使用 Qt 6 进行开发时，仅支持 Xcode 生成器。

修改变量值

您可以在Initial Configuration 或Current Configuration 中查看并编辑传递给CMake的变量的实际值。

您可以选择多个变量并对其应用操作。要清除选择，请点击视图中的任意位置。

要批量编辑变量值，请选择“Batch Edit ”。

若要使用当前配置进行构建，请选择“Run CMake ”。构建过程中，按钮文字将变为“Stop CMake ”。点击该按钮可取消当前构建。

添加变量

要添加变量，请选择“Add ”，然后选择要添加的变量类型：Boolean 、String 、Directory 或File 。

要更改所选变量的类型，请在“Key ”列中右键单击变量名称，然后在上下文菜单中选择“Force to bool ”、“Force to file ”、“Force to directory ”或“Force to string ”。

若要将所选变量的名称或值复制到剪贴板，请在上下文菜单中选择“Copy ”。

更改变量值

要更改变量的值，请双击该变量或选中它，然后选择“Edit ”。如果初始配置、当前配置和套件配置出现不一致，请在Initial Configuration 或Current Configuration 中，从上下文菜单中选择“Apply Kit Value ”或“Apply Initial Configuration Value ”。

若要重置您所做的所有更改，请选择“Reset ”。

您更改的变量值会通过 `-D<option>=<value> ` 传递给 CMake，CMake 会将这些选项存储在 `CMakeCache.txt ` 文件中。这意味着，如果您删除了构建目录，所有不属于初始 CMake 配置的自定义变量也会被删除。

若要使用已更改的变量值重新配置项目，请转至Build 并选择Clear CMake Configuration ，这将删除CMakeCache.txt 文件。这样您就可以进行全面重建。

删除变量

要删除所选变量，请选择“Unset ”。要撤销删除操作，请选择“Set ”。

查看高级变量

要查看所有变量，请选择“Advanced ”。

若要默认查看所有变量，请转至“Preferences ” > “CMake ” > “General ”，然后选择“Show advanced options by default ”。

使用初始变量重新配置

若要将 CMake 变量重置为初始值，请在Initial Configuration 中选择Re-configure with Initial Variables 。Qt Creator 会删除当前的 CMake 配置并运行 CMake。初始配置值存储在CMakeLists.txt.user 文件中，因此删除构建目录不会删除初始配置。

若希望在“Qt Creator ”重置更改前获得确认提示，请转至Preferences >CMake >General ，并选择“Ask before re-configuring with initial parameters ”。

查看 CMake 输出

在“Projects ”模式下，CMake 的输出内容会显示在“Build Settings ”、“Deploy Settings ”和“Run Settings ”选项卡旁边。

要清除 CMake 的输出，请选择“ ”（Clear ）。

若要在每次运行 CMake 时始终清除旧输出，请转至“Preferences ” > “CMake ” > “General ”，然后选择“Clear old CMake output on a new run ”。

您可以在“Filter ”字段中输入字符串来过滤输出内容。若要指定过滤选项，请选择“ ”。您可以使用正则表达式或区分大小写来过滤输出内容。选择“Show Non-matching Lines ”可隐藏与过滤条件匹配的行。您还可以设置要显示的前后行数。

按Ctrl+F可在输出中搜索字符串。

要增大或缩小输出文本的字号，请选择“ ”（Zoom In ）、按 Ctrl++、选择“ ”（Zoom Out ）或按Ctrl+-。

要隐藏输出，请选择 （Hide Right Sidebar ）或按Alt+Shift+0。

CLICOLOR_FORCE 环境变量

Qt Creator 将环境变量CLICOLOR_FORCE 设置为1，可显示 CMake 的 ANSI 彩色输出。这可能会影响进程输出。

如果输出看起来不正确或与早期的Qt Creator 版本不同，请尝试在Use Build Environment 中将CLICOLOR_FORCE 设置为0。

CMake 构建步骤

Qt Creator 通过运行cmake . --build 来构建 CMake 项目，该命令随后会运行项目配置中指定的 CMake 生成器：例如make 、mingw32-make 、nmake 或ninja 。CMake 生成器会生成用于Qt Creator 的项目文件。同时还支持多配置生成器。

您可以在Build Steps 中添加要传递给 CMake 和生成器的参数，以及构建命令的目标。

若要将应用程序安装到暂存目录，请选择Install into staging directory 并指定暂存目录的路径。 该选项会运行 CMake 的install 目标，并将DESTDIR 设置为指定的目录。部署配置的目标位置不受影响。例如，如果您针对远程目标设备进行开发，且不想将应用程序安装到构建设备的系统目录中，或者希望在构建设备上为不同的构建配置使用单独的安装目录，请使用此选项。

将 Ninja 用作 CMake 生成器

若要将Ninja与 CMake 配合使用，您必须先安装 Ninja，并在构建和运行套件中将其选为 CMake 生成器：

1. 安装 Ninja。
2. 将 Ninja 可执行文件的路径添加到 PATH 系统变量的值中。
3. 转至“Projects ” > “Build Settings ”，并选择“Kit Configuration ”。

   

4. 在“CMake generator ”字段旁选择“Change ”，以打开“CMake Generator ”对话框。

   

5. 在“Generator ”中，选择“Ninja ”。
6. 选择“OK ”以保存更改并关闭对话框。
7. 选择“Close ”以关闭“Kit CMake Configuration ”对话框，并返回“Build Settings ”。

在包管理器中使用 CMake

要自动配置Conan或vcpkg包管理器以供 CMake 使用：

1. 在项目源代码目录中创建一个 CMake 脚本文件，该文件用于从conanfile.txt 、conanfile.py 或vcpkg.json 文件安装依赖项。
2. 将该脚本的路径设置为CMAKE_PROJECT_INCLUDE_BEFORE 变量的值。
3. 转到“Preferences ” > “CMake ” > “General ”，然后选择“Package manager auto setup ”。

QTC_RUN 环境变量

Qt Creator 在执行cmake 进程时，将环境变量QTC_RUN 设置为1 。

这使得 CMake 代码能够检测到是否是从Qt Creator 执行的。

CMake 清理步骤

使用 CMake 构建时，您可以在Clean Steps 中为 clean 命令添加要传递给 CMake、生成器及目标的参数。

构建错误和警告会被解析并显示在“问题”中。