IDE 集成指南

简介

集成开发环境 (IDE) 可能希望与 CMake 集成，以改善 CMake 用户的发展体验。本文档阐述了此类集成的推荐最佳实践。

捆绑

许多 IDE 供应商希望在其 IDE 中捆绑 CMake 的副本。捆绑 CMake 的 IDE 应为用户提供使用外部 CMake 安装而不是捆绑安装的选项，以防捆绑副本过时且用户想要使用较新版本。

虽然 IDE 供应商可能很想在其应用程序中捆绑不同版本的 CMake，但不建议这样做。CMake 具有强大的向后兼容性保证，并且没有理由不使用比项目所需的 CMake 版本更新的版本，或者实际上是最新的版本。因此，建议在其应用程序中捆绑 CMake 的 IDE 供应商始终包含发布时可用的最新 CMake 补丁版本。

作为建议，IDE 也可以随 CMake 一起提供 Ninja 构建系统的副本。Ninja 具有高性能，并且在所有支持 CMake 的平台上都得到良好支持。捆绑 Ninja 的 IDE 应使用 Ninja 1.10 或更高版本，其中包含支持 Fortran 构建所需的功能。

预设

CMake 支持名为 CMakePresets.json 的文件格式，及其用户特定的对应文件 CMakeUserPresets.json。此文件包含有关用户可能需要的各种配置预设的信息。每个预设可能具有不同的编译器、构建标志等。此格式的详细信息在 cmake(1) 手册中进行了解释。

鼓励 IDE 供应商以与 CMake 相同的方式读取和评估此文件，并向用户显示文件中列出的预设。用户应该能够看到（并可能编辑）为给定预设定义的 CMake 缓存变量、环境变量和命令行选项。然后，IDE 应根据这些设置构造适当的 cmake(1) 命令行参数列表，而不是直接使用 --preset= 选项。--preset= 选项仅用作命令行用户的便捷前端，不应由 IDE 使用。

例如，如果名为 ninja 的预设指定 Ninja 作为生成器，并将 ${sourceDir}/build 作为构建目录，而不是运行

cmake -S /path/to/source --preset=ninja

IDE 应改为计算 ninja 预设的设置，然后运行

cmake -S /path/to/source -B /path/to/source/build -G Ninja

在预设包含大量缓存变量，并且将所有这些变量作为 -D 标志传递会导致平台命令行长度限制被超出，IDE 应改为构造一个临时缓存脚本，并使用 -C 标志传递它。

虽然读取、解析和评估 CMakePresets.json 的内容很简单，但它并非易事。除了文档外，IDE 供应商可能还希望参考 CMake 源代码和测试用例，以便更好地理解如何实现该格式。此 文件 提供了 CMakePresets.json 格式的机器可读 JSON 模式，IDE 供应商可能会发现它对于验证和提供编辑辅助很有用。

配置

调用 cmake(1) 以运行配置步骤的 IDE 可能希望接收有关构建将生成的产物以及用于构建产物的包含目录、编译定义等信息。可以通过使用 File API 来获得此类信息。File API 的手册页包含有关 API 以及如何调用它的更多信息。Server mode 已在 CMake 3.20 中删除，不应在 CMake 3.14 或更高版本上使用。

IDE 应避免创建不必要的构建树，并且仅在用户希望切换到不同的编译器、使用不同的编译标志等时才创建多个构建树。特别是，IDE 不应创建多个单配置构建树，这些构建树除了 CMAKE_BUILD_TYPE 不同之外，其他属性都相同，从而有效地创建多配置环境。相反，Ninja Multi-Config 生成器应与 File API 结合使用，以获取构建配置列表，以达到此目的。

IDE 不应将“额外生成器”与 Makefile 或 Ninja 生成器一起使用，这会在 Makefile 或 Ninja 文件之外生成 IDE 项目文件。相反，应使用 File API 来获取构建产物列表。

构建

如果使用 Makefile 或 Ninja 生成器来生成构建树，则不建议直接调用 make 或 ninja。相反，建议 IDE 使用 --build 参数调用 cmake(1)，这将反过来调用适当的构建工具。

如果使用 IDE 项目生成器，例如 Xcode 或 Visual Studio 生成器之一，并且 IDE 理解所使用的项目格式，则 IDE 应读取项目文件并以其通常的方式构建它。

File API 可用于从构建树中获取构建配置列表，并且 IDE 应向用户显示此列表以选择构建配置。

测试

ctest(1) 支持输出 JSON 格式，其中包含有关可用测试和测试配置的信息。想要运行 CTest 的 IDE 应获取此信息并使用它向用户显示测试列表。

IDE 不应调用生成的构建系统的 test 目标。相反，它们应该直接调用 ctest(1)。

集成 CMake 的 IDE

以下 IDE 原生支持 CMake

此外，CMake 还内置支持某些 IDE