# 快速 CMake 教程

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

本教程将指导您在 CLion 中创建和开发一个简单的 CMake 项目。 逐步学习 [CMake](https://cmake.org/) 作为构建系统的基础知识，以及 CMake 特定的 IDE 设置和操作。

> **Note:**
> 下方示例项目的源代码可在 [GitHub](https://github.com/JetBrains/CMake-Tutorial-sample) 上获取。

> **Note:**
> 不支持早于 3.15. 的 CMake 版本。 如果从捆绑的 CMake 切换到自定义安装，请确保其版本为 3.15. 或更高。

## 1. 简单的 CMake 项目

[CMake](https://cmake.org/) 是一个元构建系统，它使用称为   CMakeLists   的脚本为特定环境生成构建文件（例如，Unix 机器上的 makefiles）。

当您在 CLion 中创建一个新的 CMake 项目时，会在项目根目录下自动生成一个  `CMakeLists.txt`  文件。

Procedure: 启动一个示例 CMake 项目

1. 从主菜单中选择  `文件 | 新建项目` 。

2. 在左侧窗格中选择   C++ 可执行文件  。

在我们的示例中，项目名称为  cmake_testapp ，选择的语言标准为  C++17 。

![创建一个新的 CMake 项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_create_prj.png)

点击   创建  。

3. CLion 将生成一个包含单个源文件  `main.cpp`  和一个 [CMakeLists.txt](cmakelists-txt-file.html) 脚本的初始项目。

![在一个存根 CMake 项目中使用 CMakeLists.txt](https://resources.jetbrains.com/help/img/idea/2026.3/cl_simple_cmakeprj.png)

自动生成的  `CMakeLists.txt`  包含以下命令：

|  命令  |  描述  |
| --- | --- |
|   `cmake_minimum_required(VERSION 3.26)`   |  [指定](https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html) CMake 的最低要求版本，如默认的 [toolchain](how-to-create-toolchain-in-clion.html) 中所设置。 在大多数情况下，如果 CMake 可执行文件未被有意更改，则使用的是捆绑的 CMake 版本。  |
|   `project(cmake_testapp)`   |  根据我们在项目创建期间提供的内容定义项目名称。  |
|   `set(CMAKE_CXX_STANDARD 17)`   |     [设置](https://cmake.org/cmake/help/latest/command/set.html)  CMAKE_CXX_STANDARD  变量的值为  17 ，这是我们在创建项目时选择的。     |
|   `add_executable(cmake_testapp main.cpp)`   |  [添加](https://cmake.org/cmake/help/latest/command/add_executable.html)  cmake_testapp  可执行目标以从  `main.cpp`  构建。 我们将在 [下文](#targets-configs)进一步讨论目标。  |

4. 点击 IDE 左侧工具栏上的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.icons.expui.CMakeToolWindow.svg) 打开   CMake   工具窗口，您可以在其中检查项目加载的进度和状态：

![CMake 工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_toolwindow.png)

> **Tip:**
> 如果加载失败，CMake 工具窗口会自动打开。

## 2. CMake 目标和 CLion 配置

[目标](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#binary-targets) 是一个可执行文件或库，通过 CMake 脚本构建。 您可以在单个脚本中定义多个构建目标。

目前，我们的测试项目只有一个构建目标，  `cmake_testapp` 。 在首次加载项目时，CLion 会自动添加与此目标关联的运行/调试配置：

![新建 CMake 项目的默认配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_defaultconf1.png)

在切换器中，点击   编辑配置   查看详细信息。 目标名称和可执行文件名称与  `CMakeLists.txt`  中指定的相同：

![新建 CMake 项目默认配置的详细信息](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_defaultconf2.png)

请注意此对话框的   启动前   区域。   构建   默认设置为启动前步骤。 因此，我们不仅可以使用此配置调试或运行目标，还可以执行构建。 有关 CLion 中各种构建操作的更多信息，请查看 [构建操作](build-actions.html)。

## 3. 向现有目标添加文件

让我们创建一个新的源文件  `general.cpp`  并将其添加到  `cmake_testapp`  目标。

Procedure:

1. 右键点击项目树中的根文件夹，然后选择   新建 | C/C++ 源文件  ：

![添加源文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_addsourcefile.png)

2. 选中   添加到目标   复选框：

![将文件添加到现有目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_tutorial_addfiletotarget.png)

3. 点击   确定  ，新文件将被添加到  `add_executable`  命令中：

![源文件已添加到 add_executable](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_tutorial_newfile_incmake.png)

> **Tip:**
> 当您以这种方式将文件添加到目标时，无需手动编辑  `CMakeLists.txt`  脚本，CLion 会在后台自动重新加载项目。

## 4. 添加新目标

现在让我们再添加两个文件，并为它们创建一个可执行目标和一个库目标。

Procedure: 新的可执行目标

1. 右键点击项目树中的根文件夹，然后再次选择   新建 | C/C++ 源文件  。

2. 设置文件名（在我们的示例中为  `calc` ）。

3. 在   添加到目标   字段中，清除   cmake_testapp   复选框。

4. 点击   添加新目标  链接：

![将文件添加到新目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_newfile_addtotargets.png)

5. 指定目标名称（  `cmake_testapp_calc` ），然后点击   Add  ：

![添加新的可执行目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_newexetarget.png)

6. 新创建的目标将出现在列表中。

确保仅选择了  `cmake_testapp_calc`  目标：

![新目标已添加到目标列表](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_newtarget_added.png)

点击   确定  。

7. CLion 将向  `CMakeLists.txt`  添加一个新的  `add_executable`  命令并重新加载项目：

![在 CMakeLists.txt 中的新目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_newexetarget_incmakelists.png)

8. 重新加载后，配置切换器中将出现一个新配置：

![新添加目标的配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_addtarget_conf.png)

> **Note:**
> 这是一个说明如何添加新可执行目标的示例。 请注意，如果您想运行此配置，则需要向  `calc.cpp`  添加一个  `int main()`  函数。

Procedure: 新的库目标

1. 右键点击项目树中的根文件夹，然后再次选择   新建 | C/C++ 源文件  。

2. 提供文件名（  `calc_lib` ）。

3. 清除   添加到目标   字段中的复选框。

4. 点击   添加新目标  。

![添加新目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_addlib_clicknewtargets.png)

5. 在下拉列表中，选择  `add_library` ：

![新的库目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_newlibtarget.png)

> **Tip:**
> 在此下拉列表中，您可以找到用于添加 [CUDA](cuda-projects.html) 和 [Qt](qt-tutorial.html) 目标的命令。

6. 设置目标名称（  `cmake_testapp_lib` ），然后点击   Add  。

![添加库目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_addlib_clicknewtargets.png)

7. 新创建的目标将出现在列表中。

确保清除了其他目标的复选框。

![新的库目标已添加](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_newlibtarget_added.png)

选中   创建关联头文件   复选框以同时添加一个头文件，  `calc_lib.h` 。

点击   确定  。

8. CLion 将向  `CMakeLists.txt`  添加一个  `add_library`  命令并重新加载项目：

![在 CMakeLists.txt 中的新库目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_newlibtarget_addedtocmakelists.png)

9. 与可执行目标的情况类似，CLion 会自动为库目标创建配置：

![新添加库目标的配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_addlibrary_conf.png)

然而，这是一个不可执行的配置，因此如果您尝试运行或调试它，您将收到 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.balloonError.svg)  未指定可执行文件  错误消息：

![未指定可执行文件错误](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_libtarget_exenotspecified.png)

10. 要获取库文件，您需要构建此配置。 在切换器中选择它，然后按 `Ctrl+F9` (Windows), `⌘ F9` (macOS), `⌘ F9` (IntelliJ IDEA Classic (macOS)), `⌘ ⌃ B` (macOS System Shortcuts), `Ctrl+F9` (XWin), `Ctrl+F9` (GNOME), `Ctrl+9` (KDE), `Ctrl+F9` (Emacs), `Ctrl+F9` (Sublime Text), `Ctrl+F9` (Sublime Text (macOS)), `⌘ B` (Xcode), `F7` (Visual Studio), `F7` (Visual Studio (macOS)), `F7` (ReSharper), `F7` (ReSharper (macOS)), `Ctrl+F9` (QtCreator), `⌘ F9` (QtCreator (macOS)), `F11` (NetBeans), `Ctrl+F9` (Eclipse), `⌘ B` (Eclipse (macOS)) 或点击构建图标：

![构建库目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_build_lib.png)

结果，  `libcmake_testapp_lib.a`  文件将出现在  `cmake-build-debug`  文件夹中。

![库构建产物](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_libfile.png)

## 5. 重新加载项目

让我们手动在  `CMakeLists.txt`  中引入一些更改。 例如，将  `STATIC`  添加到库目标的声明中：

![手动更改 CMakeLists.txt](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_cmakelists_manualchanges.png)

当我们在  `CMakeLists.txt`  中进行更改时，CLion 会显示一个图标，提示重新加载项目。 点击它或按快捷键：

![CMake 重新加载图标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_reload_icon.png)

> **Tip:**
> 如果您希望 CLion 在每次更改  `CMakeLists.txt`  时静默重新加载项目，请转到  `设置 | 构建、执行、部署 | CMake`  并启用自动重新加载：
>
> ![在 CMake 设置中启用自动重新加载](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_autoreloadsetting.png)

## 6. CMake 预设和 CLion CMake 配置文件

要为您的项目配置和共享 CMake 选项，您可以使用 CMake 预设、CLion 的 CMake 配置文件，或两者兼用。

[CMake 配置文件](cmake-profile.html) 与 [CMake 预设](cmake-presets.html) 有许多共同设置，并且也可以通过 VCS 共享。 主要区别在于配置文件引用了 CLion 的 [toolchain](how-to-create-toolchain-in-clion.html)，其中包含 CMake 预设中不存在且不需要的信息（例如调试器或环境设置）。

Procedure: CMake 预设

[CMake 预设](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) 是一种使用两个文件配置和共享 CMake 选项的方法：

* 用于项目作用域的构建的 `CMakePresets.json` 。 此文件可以通过 VCS 共享。

* 用于开发者本地构建的 `CMakeUserPresets.json` 。 此文件不应提交到 VCS。

这两个文件格式相同，应位于项目的根目录中。

> **Note:**
> 了解更多关于在 CLion 中使用预设的信息： [CMake 预设](cmake-presets.html)

Procedure: CMake 配置文件

一个配置文件包括 [toolchain](how-to-create-toolchain-in-clion.html) 和 [构建类型](cmake-profile.html#buildtypes)，以及 CMake 选项，例如 [生成器](cmake-profile.html#cmake-generators) 和 [环境变量](cmake-profile.html#EnvVariables)。 您可以为项目配置多个配置文件，例如使用不同的编译器或以不同的设置构建目标。

请参阅下一章，了解为 Release 构建添加配置文件的示例。

## 7. 构建类型

到目前为止创建的所有运行/调试配置都是  Debug  配置，这是为我们的项目自动配置的 [CMake 配置文件](cmake-profile.html) 的默认构建类型。

例如，让我们将  Debug  和  Release  构建分开。 为此，在  `设置 | 构建、执行、部署 | CMake`  中添加（ ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.inlineAddHover.svg)）一个新的 CMake 配置文件，并将其构建类型设置为   Release  ：

![添加一个 Release CMake 配置文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_addprofile.png)

注意   构建目录   字段，它指定了构建结果的位置。 默认文件夹是  `cmake-build-debug`  用于  Debug  配置文件，  `cmake-build-release`  用于  Release  配置文件。 您始终可以设置 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.menu-open.svg) 其他您选择的位置。

保存配置文件后，它将出现在切换器中：

![配置切换器中的 CMake 配置文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_profiles_configs.png)

> **Tip:**
> 切换配置或 CMake 配置文件可能会影响用于解析代码的预处理器定义。 有关更多信息，请参阅 [解析上下文](switching-resolve-context.html)。

## 8. 添加包含目录

要使用位于单独目录中的额外头文件，您需要将它们添加到所有目标或某些特定目标。

Procedure:

1. 例如，让我们在项目根目录下创建三个目录：  `includes` 、  `includes/general`  和  `includes/math` 。 在项目树上下文菜单中使用  `新建 | 目录`  选项。

![新的包含目录](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_includedirs.png)

2. 打开  `CMakeLists.txt`  并添加以下命令：

```CMAKE
target_include_directories (cmake_testapp_lib PUBLIC includes/math)
target_include_directories (cmake_testapp_lib PUBLIC includes/general)

```

这两个命令使位于  `general`  和  `math`  的头文件可从  `cmake_testapp_lib`  目标的源文件中访问。

例如，如果我们将一个名为  `header_math.h`  的头文件放在  `includes/math`  文件夹中，我们可以使用  `#include "header_math.h"`  从  `calc_lib.cpp`  中包含它。

## 9. 链接库

### 静态库

在 [第 4 步](#new-lib-target) 中，我们创建了一个名为  `cmake_testapp_lib`  的静态库（默认文件名为  `libcmake_testapp_lib.a` ）。

现在让我们看看如何将此库链接到我们的项目。 为了方便起见，我们将为其创建并使用一个单独的文件夹。

Procedure:

1. 在项目根目录下创建一个  `lib`  目录。

2. 将  `libcmake_testapp_lib.a`  从其默认位置（即  `cmake-build-debug` ）复制到  `lib`  文件夹。

![lib 文件夹中的库构建产物](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_libartifact_inlibfolder.png)

3. 添加以下命令以将此库链接到  cmake_testapp  目标：

```CMAKE
find_library(TEST_LIBRARY cmake_testapp_lib lib)
target_link_libraries(cmake_testapp LINK_PUBLIC ${TEST_LIBRARY})

```

* [find_library](https://cmake.org/cmake/help/latest/command/find_library.html) 提供了库的完整路径，

* 然后我们通过 `${TEST_LIBRARY}` 变量将其直接传递到 [target_link_libraries](https://cmake.org/cmake/help/latest/command/target_link_libraries.html) 命令中。

![链接静态库](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_link_staticlib.png)

> **Note:**
> 注释  ：确保将  `target_link_libraries`  放在  `add_executable`  命令之后，以便 CMake 实际在链接库之前构建目标。

### 动态库

为了说明共享（动态）库的情况，我们将以使用 [LibPNG](https://libspng.org) 为例，这是一个用于读取和写入便携式网络图形（PNG）文件的 C 库。

Procedure: 使用 vcpkg 安装库包

CLion 与 [vcpkg](package-management.html) 集成，这是一个 C/C++ 的包管理器。 我们将使用它直接从 IDE 快速安装库。

1. 按照 [此说明](package-management.html#install-vcpkg) 安装 vcpkg。

2. 在 vcpkg 工具窗口中搜索   libpng  ：

![在 vcpkg 中搜索 libpng](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_libpng_searchvcpkg.png)

3. 点击右侧窗格中的   安装   并等待安装完成。

Procedure: 将库添加到 CMakeLists.txt

1. 打开  `CMakeLists.txt`  文件并添加以下命令：

```CMAKE
find_package(PNG REQUIRED)
include_directories(${PNG_INCLUDE_DIR})
target_link_libraries(cmake_testapp PRIVATE ${PNG_LIBRARY})

```

2. 要检查库是否正确链接，请尝试将其中一个库头文件包含到  `main.cpp`  中：

![包含一个 LibPNG 头文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_libpng_includeheader.png)

例如，包含  `png.h` 。 然后您可以按 `Ctrl+B` (Windows), `⌘ B` (macOS), `⌘ B` (IntelliJ IDEA Classic (macOS)), `⌘ B` (macOS System Shortcuts), `Ctrl+B` (XWin), `Ctrl+B` (GNOME), `Ctrl+B` (KDE), `Ctrl+Alt+G` (Emacs), `F12` (Sublime Text), `F12` (Sublime Text (macOS)), `⌘ Click` (Xcode), `F12` (Visual Studio), `F12` (Visual Studio (macOS)), `Ctrl+B` (ReSharper), `⌘ B` (ReSharper (macOS)), `F2` (QtCreator), `F2` (QtCreator (macOS)), `Ctrl+B` (NetBeans), `F3` (Eclipse), `F3` (Eclipse (macOS)) 打开此文件：

![转到 png.h 文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_libpng_gotoheader.png)

## 10. CMake 调试

如果在 CMake 配置期间出现错误或不希望的行为，您可以像调试项目中的其他代码一样调试 CMake 脚本。

> **Note:**
> 调试器不会调试您的实际项目构建，并且在调试下执行 CMake 后，项目模型不会被 [重新加载](reloading-project.html)。

Procedure:

1. 在您的  `CMakeLists.txt`  文件或文件中设置断点。

2. 打开顶层  `CMakeLists.txt` ，点击第一个命令旁边的边距图标，然后选择   调试  ：

![从边距启动 CMake 调试会话](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_boost_debug_gutter.png)

> **Tip:**
> 当 CMake 生成失败时，您可以点击 CMake 工具窗口中的   调试   提示以开始调试：
>
>
>
> ![CMake 工具窗口中的调试提示](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_debug_tw_hint.png)

3. CLion 将启动一个 CMake 调试会话：

![CMake 调试会话](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_boost_debug_session.png)

有关更多信息，请参阅 [CMake 调试功能](cmake-debug.html#cmake-debug-features)。

## 11. 编辑 CMakeLists.txt 的提示

CLion 提供代码洞察功能，帮助您高效地处理 CMake 脚本。 例如：

* [结构](file-structure.html)视图用于显示 CMake 脚本中使用的变量、函数、宏和目标。 要打开它，请按 `Alt+7` (Windows), `⌘ 7` (macOS), `⌘ 7` (IntelliJ IDEA Classic (macOS)), `⌘ 7` (macOS System Shortcuts), `Alt+7` (XWin), `Alt+7` (GNOME), `Alt+7` (KDE), `Alt+7` (Emacs), `Alt+7` (Sublime Text), `⌘ 7` (Sublime Text (macOS)), `⌘ 3` (Xcode), `Ctrl+Alt+F` (Visual Studio), `⌃ ⌥ F` (Visual Studio (macOS)), `Ctrl+F11` (ReSharper), `⌃ F11` (ReSharper (macOS)), `Alt+7` (QtCreator), `⌘ 7` (QtCreator (macOS)), `Ctrl+7` (NetBeans), `Alt+7` (Eclipse), `⌘ 7` (Eclipse (macOS))（工具窗口）或 `Ctrl+F12` (Windows), `⌘ F12` (macOS), `⌘ F12` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ 7` (macOS System Shortcuts), `Ctrl+F12` (XWin), `Ctrl+F12` (GNOME), `Ctrl+0` (KDE), `Ctrl+F12` (Emacs), `Ctrl+R` (Sublime Text), `⌘ R` (Sublime Text (macOS)), `⌃ 6` (Xcode), `Alt+\` (Visual Studio), `⌥ \` (Visual Studio (macOS)), `Ctrl+F12` (ReSharper), `⌘ F12` (ReSharper (macOS)), `Ctrl+F12` (QtCreator), `⌘ F12` (QtCreator (macOS)), `Ctrl+F12` (NetBeans), `Ctrl+F3` (Eclipse), `⌘ O` (Eclipse (macOS))（弹出窗口）。 ![CMake 脚本结构](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_tutorial_structure.png)

* 代码补全适用于 `CMakeLists.txt` 中的大多数元素，包括像 `find_package()` 这样的命令参数。 ![find_package 的补全](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_tutorial_boost_find_completion.png)

* [快速文档弹出](viewing-inline-documentation.html) 帮助您获取代码元素的更多信息。 要调用它，请使用鼠标悬停或按 `Ctrl+Q` (Windows), `F1` (macOS), `⌃ J` (IntelliJ IDEA Classic (macOS)), `⌘ I` (macOS System Shortcuts), `Ctrl+Q` (XWin), `Ctrl+Q` (GNOME), `Ctrl+Q` (KDE), `Ctrl+Q` (Emacs), `Ctrl+Q` (Sublime Text), `Ctrl+Q` (Sublime Text (macOS)), `⌘ ⌃ ⇧ /` (Xcode), `Ctrl+K, I` (Visual Studio), `⌘ K, I` (Visual Studio (macOS)), `Ctrl+Q` (ReSharper), `⌃ Q` (ReSharper (macOS)), `Ctrl+Q` (QtCreator), `Ctrl+Q` (QtCreator (macOS)), `Ctrl+Q` (NetBeans), `Alt+Middle-Click` (Eclipse), `⌥ Middle-Click` (Eclipse (macOS))。 您甚至可以为补全建议查看快速文档： ![补全建议的快速文档](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_tutorial_boost_completion_quickdoc.png)

* 您可以在 `设置 | 编辑器 | 配色方案 | CMake` 中调整 CMake 文件的配色和字体方案： ![CMake 的配色方案设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmake_codestyle_settings.png) > **Tip:** > 有关更多实用功能提示，请参阅 [CMake 中的代码洞察](cmakelists-txt-file.html#code-insight-cmake)。

## 12. 使用 CTest

本章提供了一个简单的示例，说明如何使用 [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html)，这是一个在 CMake 构建过程中编译和运行测试的框架。 您可以在 [CTest 支持](ctest-support.html) 中找到该框架的一般描述。

Procedure: 将 CTest 添加到示例项目

1. 在项目根目录下创建一个  `ctest`  目录。

2. 将以下文件添加到  `ctest`  目录中：

* 一个源文件 `addvalues_zero.cpp` 。 暂时不要将此文件链接到任何 CMake 目标。

* 一个头文件 `assert_macro.h` 。 暂时不要将此文件链接到任何 CMake 目标。

* 一个 `CMakeLists.txt` 脚本。

![为 CTest 添加一个文件夹](https://resources.jetbrains.com/help/img/idea/2026.3/CMakeLists.txt` ：

```
cmake_minimum_required(VERSION 3.14.0 FATAL_ERROR)

add_executable(ctest_exe_addvalues_zero addvalues_zero.cpp)

target_link_libraries(ctest_exe_addvalues_zero LINK_PUBLIC cmake_testapp_lib)

add_test(NAME ctest_addvalues_zero COMMAND ctest_exe_addvalues_zero)

set_tests_properties(ctest_addvalues_zero PROPERTIES PASS 0)

```

第一行声明了 CTest 的最低支持版本，对应于 CMake 的版本 3.14。

我们在这里使用 [add_test](https://cmake.org/cmake/help/latest/command/add_test.html) 命令将  `ctest_exe_addvalues_zero`  可执行文件注册到 CTest。

4. 接下来，我们需要在顶层  `CMakeLists.txt`  中启用 CTest 并声明子项目：

```CMAKE
enable_testing()
add_subdirectory(ctest)

```

[enable_testing](https://cmake.org/cmake/help/latest/command/enable_testing.html) 命令创建了一个内置目标  `test` ，执行 CTest。

5. 重新加载项目。

Procedure: 添加要测试的代码

让我们准备一段代码以使用 CTest 进行测试。

1. 在  `calc_lib.cpp`  中添加一个简单的函数

```CPLUSPLUS
int add_values (int a, int b) { return a+b;}

```

2. 在关联的头文件  `calc_lib.h`  中添加函数声明：

```CPLUSPLUS
int add_values (int a, int b);
```

![添加一个要测试的函数](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_testfunc_upd.png)

Procedure: 将代码添加到测试源中

1. `assert_macro.h` :

```CPLUSPLUS
#include <iostream>
#include <sstream>


#define assertEqual( ... )               \
do {                                            \
if( !( __VA_ARGS__ ) ) {                     \
std::cerr << "Unit test assert [ " \
<< ( #__VA_ARGS__ )             \
<< " ] failed in line [ "       \
<< __LINE__                     \
<< " ] file [ "                 \
<< __FILE__ << " ]"             \
<< std::endl;                     \
err_code = 1;                           \
}                                            \
} while( false )

```

2. `addvalues_zero.cpp` :

```CPLUSPLUS
#include "assert_macro.h"
#include "../calc_lib.h"

int test_addvalues_zero() {
int err_code = 0;
assertEqual (add_values(0, 0) == 0);
assertEqual (add_values(-5, 5) == 0);
return err_code;
}

int main() {
return test_addvalues_zero();
}

```

Procedure: 编辑 CTest 配置

1. 在主菜单中，进入  `运行 | 编辑配置` .

2. 在   CTest 应用程序   节点下，您将找到自动创建的   所有 CTest   配置。

由于要测试的代码位于  `ctest_exe_addvalues_zero`  可执行文件中，我们需要在配置设置中选择该可执行文件作为构建目标：

![CTest 配置——更改目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_ctest_config_targets_to_build_upd.png)

> **Tip:**
> 要将此应用于项目中的所有 CTest 配置，请点击同一对话框左下角的   编辑配置模板……  ，选择   CTest 应用程序  ，并更改模板中的目标：
>
> ![编辑 CTest 配置模板](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_ctest_configtemplate_upd.png)

3. 我们还检查一下   要运行的测试列表   字段。 点击笔图标打开   可用测试列表   对话框，在其中我们可以查看和调整测试集：

![CTest 配置中可用测试的列表](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_ctest_allconfig.png)

> **Tip:**
> 有关   CTest 应用程序   模板的更多信息，请参阅 [CTest 运行/调试配置](ctest-support.html#ctest-configs)。

Procedure: 运行 CTest 配置并查看结果

1. 在配置切换器中选择   所有 CTest  ，然后点击 ![运行 按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.execute.svg) 或按 `Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `⌘ ⌥ ⇧ R` (Xcode), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `Ctrl+F5` (ReSharper), `⌃ F5` (ReSharper (macOS)), `Ctrl+R` (QtCreator), `⌘ R` (QtCreator (macOS)), `F6` (NetBeans), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS))。

![运行 CTest 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_ctestrun.png)

2. 在 [测试运行器](viewing-and-exploring-test-results.html) 窗口中找到结果：

![CTest 结果](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cmaketutorial_ctest_results.png)

## 13. 有用的链接

要深入了解 CLion 中的 CMake，请学习以下内容：

* [更改项目根目录](change-project-root-directory.html)

* [重置 CMake 缓存](cmake-cache.html)

* [指定编译器标志](cmake-profile.html#compiler-flags)

* [切换编译器](how-to-switch-compilers-in-clion.html)

* 运行 [构建操作](build-actions.html) 和 [CMake 安装](using-cmake-install.html)

* 使用 [环境变量](cmake-profile.html#EnvVariables) 和 [CLION_IDE](detecting-origin-of-cmake-invocation.html) 宏。

* 运行 [CMake 性能分析](cmake-profiling.html)

* [调试 CMake](cmake-debug.html)

* 使用 [CMake 安装](using-cmake-install.html)

## See also

### 操作指南

[CTest support](ctest-support.html)

