cmake(1)¶

概要¶

Generate a Project Buildsystem
 cmake [<options>] -B <path-to-build> [-S <path-to-source>]
 cmake [<options>] <path-to-source | path-to-existing-build>

Build a Project
 cmake --build <dir> [<options>] [-- <build-tool-options>]

Install a Project
 cmake --install <dir> [<options>]

Open a Project
 cmake --open <dir>

Run a Script
 cmake [-D <var>=<value>]... -P <cmake-script-file>

Run a Command-Line Tool
 cmake -E <command> [<options>]

Run the Find-Package Tool
 cmake --find-package [<options>]

Run a Workflow Preset
 cmake --workflow <options>

View Help
 cmake --help[-<topic>]

描述¶

cmake 可执行文件是跨平台构建系统生成器 CMake 的命令行界面。上面的提要列出了该工具可以执行的各种操作，如下面各节所述。

要使用 CMake 构建软件项目，请生成项目构建系统。可以选择使用 cmake 来构建项目，安装项目，或者直接运行相应的构建工具（例如 make）。cmake 也可以用于查看帮助。

其他操作旨在供软件开发人员使用，他们使用 CMake 语言 编写脚本以支持其构建。

有关可替代 cmake 使用的图形用户界面，请参阅 ccmake 和 cmake-gui。有关 CMake 测试和打包设施的命令行界面，请参阅 ctest 和 cpack。

有关 CMake 的更多信息，请参阅本手册末尾的另请参阅链接。

CMake 构建系统简介¶

一个 *构建系统* 描述了如何使用 *构建工具* 从源代码构建项目的可执行文件和库以自动化该过程。例如，构建系统可以是用于命令行 make 工具的 Makefile，或集成开发环境 (IDE) 的项目文件。为了避免维护多个此类构建系统，项目可以使用 CMake 语言 编写的文件抽象地指定其构建系统。通过这些文件，CMake 通过一个名为 *生成器* 的后端为每个用户本地生成一个首选的构建系统。

要使用 CMake 生成构建系统，必须选择以下内容

源目录

包含项目提供的源文件的顶级目录。项目使用 cmake-language(7) 手册中描述的文件指定其构建系统，从名为 CMakeLists.txt 的顶级文件开始。这些文件指定了 cmake-buildsystem(7) 手册中描述的构建目标及其依赖项。

构建目录

存储构建系统文件和构建输出工件（例如可执行文件和库）的顶级目录。CMake 将写入一个 CMakeCache.txt 文件以将该目录标识为构建树，并存储持久信息，例如构建系统配置选项。

为了维护原始的源目录，请通过使用单独的专用构建目录来执行 *out-of-source* 构建。也支持将构建目录放置在与源目录相同的目录中的 *in-source* 构建，但不建议这样做。

生成器

此选项选择要生成的构建系统类型。有关所有生成器的文档，请参阅 cmake-generators(7) 手册。运行 cmake --help 以查看本地可用的生成器列表。可以选择使用下面的 -G 选项指定生成器，或者简单地接受 CMake 为当前平台选择的默认值。

当使用命令行构建工具生成器之一时，CMake 期望编译器工具链所需的环境已在 shell 中配置好。当使用 IDE 构建工具生成器之一时，不需要特定的环境。

生成项目构建系统¶

运行 CMake 时使用以下命令签名之一来指定源和构建目录并生成构建系统

cmake [<options>] -B <path-to-build> [-S <path-to-source>]

3.13 版本新增。

使用 <path-to-build> 作为构建目录，<path-to-source> 作为源目录。指定的路径可以是绝对路径，也可以是相对于当前工作目录的路径。源目录必须包含一个 CMakeLists.txt 文件。如果构建目录不存在，将自动创建。例如
$ cmake -S src -B build

cmake [<options>] <path-to-source>

使用当前工作目录作为构建树，并使用 <path-to-source> 作为源树。指定的路径可以是绝对路径，也可以是相对于当前工作目录的路径。源树必须包含一个 CMakeLists.txt 文件，并且*不能*包含一个 CMakeCache.txt 文件，因为后者标识了一个现有的构建树。例如

$ mkdir build ; cd build
$ cmake ../src

cmake [<options>] <path-to-existing-build>

使用 <path-to-existing-build> 作为构建目录，并从其 CMakeCache.txt 文件中加载源目录的路径，该文件必须已由 CMake 先前运行生成。指定的路径可以是绝对路径，也可以是相对于当前工作目录的路径。例如

$ cd build
$ cmake .

在所有情况下，<options> 可以是零个或多个选项。

以上指定源目录和构建目录的样式可以混合使用。使用 -S 或 -B 指定的路径总是分别归类为源目录或构建目录。使用普通参数指定的路径则根据其内容和之前提供的路径类型进行归类。如果只给出一种路径类型，则当前工作目录 (cwd) 用于另一种。例如

命令行	源目录	构建目录
`cmake -B build`	当前工作目录	`构建`
`cmake -B build src`	`src`	`构建`
`cmake -B build -S src`	`src`	`构建`
`cmake src`	`src`	当前工作目录
`cmake build` (现有)	已加载	`构建`
`cmake -S src`	`src`	当前工作目录
`cmake -S src build`	`src`	`构建`
`cmake -S src -B build`	`src`	`构建`

3.23 版中的更改：当指定多个源路径时，CMake 会发出警告。这从未被官方文档化或支持，但旧版本偶然接受了多个源路径并使用了指定的最后一个路径。避免传递多个源路径参数。

生成构建系统后，可以使用相应的原生构建工具来构建项目。例如，在使用 Unix Makefiles 生成器后，可以直接运行 make

$ make
$ make install

或者，可以使用 cmake 通过自动选择和调用适当的原生构建工具来构建项目。

选项¶

-S <path-to-source>¶: 要构建的 CMake 项目的根目录路径。

-B <path-to-build>¶

CMake 将用作构建目录根目录的目录路径。

如果该目录不存在，CMake 将创建它。

-C <initial-cache>¶

预加载脚本以填充缓存。

当 CMake 首次在一个空的构建目录中运行时，它会创建一个 CMakeCache.txt 文件，并用项目的可自定义设置填充它。此选项可用于指定一个文件，在项目 CMake 列表文件的第一次遍历之前从该文件加载缓存条目。加载的条目优先于项目的默认值。给定文件应该是一个 CMake 脚本，其中包含使用 CACHE 选项的 set() 命令，而不是缓存格式的文件。

脚本中对 CMAKE_SOURCE_DIR 和 CMAKE_BINARY_DIR 的引用会解析为顶级源目录和构建目录。

-D <var>:<type>=<value>, -D <var>=<value>¶

创建或更新 CMake CACHE 条目。

当 CMake 首次在一个空的构建目录中运行时，它会创建一个 CMakeCache.txt 文件，并用项目的可自定义设置填充它。此选项可用于指定一个设置，该设置优先于项目的默认值。该选项可以重复，以指定所需数量的 CACHE 条目。

如果给定了 :<type> 部分，它必须是 set() 命令文档中为其 CACHE 签名指定的类型之一。如果省略 :<type> 部分，则如果该条目不存在具有类型的条目，则将创建不带类型的条目。如果项目中的命令将类型设置为 PATH 或 FILEPATH，则 <value> 将转换为绝对路径。

此选项也可以作为单个参数给出：-D<var>:<type>=<value> 或 -D<var>=<value>。

值得注意的是，-C 和 -D 参数的顺序很重要。它们将按照列出的顺序执行，最后一个参数优先于前一个参数。例如，如果您指定 -DCMAKE_BUILD_TYPE=Debug，然后是一个 -C 参数，其中包含一个文件，该文件调用

set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE)

则 -C 参数将优先，并且 CMAKE_BUILD_TYPE 将设置为 Release。但是，如果 -D 参数位于 -C 参数之后，则它将设置为 Debug。

如果 -C 文件中的 set(... CACHE ...) 调用没有使用 FORCE，并且 -D 参数设置了相同的变量，则无论顺序如何，-D 参数都将优先，因为非 FORCE set(... CACHE ...) 调用的性质。

-U <globbing_expr>¶

从 CMake CACHE 中删除匹配的条目。

此选项可用于从 CMakeCache.txt 文件中删除一个或多个变量，支持使用 * 和 ? 的通配符表达式。此选项可以重复多次，以删除所需数量的 CACHE 条目。

谨慎使用，可能会使您的 CMakeCache.txt 无法正常工作。

-G <generator-name>¶

指定构建系统生成器。

CMake 可能在某些平台上支持多种原生构建系统。生成器负责生成特定的构建系统。可能的生成器名称在 cmake-generators(7) 手册中指定。

如果未指定，CMake 会检查 CMAKE_GENERATOR 环境变量，否则会回退到内置的默认选择。

-T <toolset-spec>¶

工具集规范（如果生成器支持）。

某些 CMake 生成器支持工具集规范，以告知原生构建系统如何选择编译器。有关详细信息，请参阅 CMAKE_GENERATOR_TOOLSET 变量。

-A <platform-name>¶

指定生成器支持的平台名称。

某些 CMake 生成器支持向原生构建系统提供平台名称，以选择编译器或 SDK。有关详细信息，请参阅 CMAKE_GENERATOR_PLATFORM 变量。

--toolchain <path-to-file>¶: 3.21 版本新增。

指定交叉编译工具链文件，相当于设置 CMAKE_TOOLCHAIN_FILE 变量。相对路径被解释为相对于构建目录，如果未找到，则相对于源目录。

--install-prefix <directory>¶: 3.21 版本新增。

指定安装目录，由 CMAKE_INSTALL_PREFIX 变量使用。必须是绝对路径。

--project-file <project-file-name>¶

4.0 版本新增。

指定备用项目文件名。

这决定了 CMake 配置项目时处理的顶级文件，以及 add_subdirectory() 处理的文件。

默认情况下，这是 CMakeLists.txt。如果设置为其他值，则当在项目子目录中找不到指定文件时，CMakeLists.txt 将作为回退使用。

注意

此功能旨在供开发人员在增量过渡期间临时使用，而非用于发布最终产品。当项目文件不是 CMakeLists.txt 时，CMake 总是会发出警告。

-Wno-dev¶

禁止开发人员警告。

禁止针对 CMakeLists.txt 文件作者的警告。默认情况下，这也会关闭弃用警告。

-Wdev¶

启用开发人员警告。

启用针对 CMakeLists.txt 文件作者的警告。默认情况下，这也会开启弃用警告。

-Wdeprecated¶

启用已弃用功能警告。

为使用已弃用功能启用警告，这些警告旨在针对 CMakeLists.txt 文件的作者。

-Wno-deprecated¶

禁用已弃用功能警告。

禁止使用已弃用功能的警告，这些警告是针对 CMakeLists.txt 文件作者的。

-Werror=<what>¶

将 CMake 警告视为错误。<what> 必须是以下之一

开发

将开发人员警告视为错误。

将针对 CMakeLists.txt 文件作者的警告视为错误。默认情况下，这也会将弃用警告视为错误。

已弃用

将弃用的宏和函数警告视为错误。

将针对 CMakeLists.txt 文件作者的弃用宏和函数使用警告视为错误。

-Wno-error=<what>¶

不要将 CMake 警告视为错误。<what> 必须是以下之一

开发: 不要将针对 CMakeLists.txt 文件作者的警告视为错误。默认情况下，这也会关闭将弃用警告视为错误的功能。
已弃用: 不要将针对 CMakeLists.txt 文件作者的已弃用宏和函数使用的警告视为错误。

--fresh¶: 在 3.24 版本中添加。

执行构建树的全新配置。这将删除任何现有的 CMakeCache.txt 文件和相关的 CMakeFiles/ 目录，并从头开始重新创建它们。

3.30 版本新增：对于以前由 FetchContent 填充的，策略 CMP0168 设置为 NEW 的依赖项，其来自任何先前运行的标记和脚本文件将被删除。因此，下载、更新和修补步骤将被强制重新执行。

-L[A][H]¶

列出非高级缓存变量。

列出 CACHE 变量将运行 CMake 并列出 CMake CACHE 中所有未标记为 INTERNAL 或 ADVANCED 的变量。这将有效地显示当前的 CMake 设置，然后可以使用 -D 选项进行更改。更改某些变量可能会导致创建更多变量。如果指定了 A，则还会显示高级变量。如果指定了 H，则还会显示每个变量的帮助信息。

-LR[A][H] <regex>¶

在版本 3.31 中添加。

显示特定的非高级缓存变量

显示 CMake CACHE 中与给定正则表达式匹配的非 INTERNAL 也不 ADVANCED 变量。如果指定了 A，则还会显示高级变量。如果指定了 H，则还会显示每个变量的帮助信息。

-N¶

仅查看模式。

仅加载缓存。不实际运行配置和生成步骤。

--graphviz=<file>¶

生成依赖关系的 graphviz，有关更多信息，请参阅 CMakeGraphVizOptions。

生成一个 graphviz 输入文件，其中包含项目中的所有库和可执行文件依赖项。有关详细信息，请参阅 CMakeGraphVizOptions 的文档。

--system-information [file]¶

转储有关此系统的信息。

转储有关当前系统的大量信息。如果从 CMake 项目的二进制树顶部运行，它将转储其他信息，例如缓存、日志文件等。

--print-config-dir¶

在版本 3.31 中添加。

打印 CMake 配置目录以进行用户范围的 FileAPI 查询。

有关详细信息，请参阅 CMAKE_CONFIG_DIR。

--log-level=<level>¶

3.16 版新增。

设置日志 <level>。

message() 命令只会输出指定日志级别或更高级别的消息。有效的日志级别是 ERROR、WARNING、NOTICE、STATUS (默认)、VERBOSE、DEBUG 或 TRACE。

要在 CMake 运行之间保持日志级别，请将 CMAKE_MESSAGE_LOG_LEVEL 设置为缓存变量。如果同时给出命令行选项和变量，则命令行选项优先。

出于向后兼容性原因，--loglevel 也被接受作为此选项的同义词。

3.25 版本新增：请参阅 cmake_language() 命令，以了解如何查询当前消息日志级别。

--log-context¶

启用 message() 命令输出附加到每条消息的上下文。

此选项仅开启当前 CMake 运行的上下文显示。要使上下文显示在所有后续 CMake 运行中持久化，请将 CMAKE_MESSAGE_CONTEXT_SHOW 设置为缓存变量。当给出此命令行选项时，CMAKE_MESSAGE_CONTEXT_SHOW 将被忽略。

--sarif-output=<path>¶

4.0 版本新增。

启用以 SARIF 格式记录 CMake 生成的诊断消息。

将诊断消息写入指定路径的 SARIF 文件。项目还可以将 CMAKE_EXPORT_SARIF 设置为 ON 以启用此构建树的功能。

--debug-trycompile¶

不要删除为 try_compile() / try_run() 调用创建的文件和目录。这对于调试失败的检查很有用。

请注意，try_compile() 的某些用法可能会使用相同的构建树，如果项目执行多个 try_compile()，这将限制此选项的有用性。例如，此类用法可能会改变结果，因为来自先前尝试编译的工件可能会导致不同的测试错误地通过或失败。此选项最好仅在调试时使用。

（就前述而言，try_run() 命令实际上是一个 try_compile()。两者的任何组合都可能存在所描述的潜在问题。）

3.25 版本新增：启用此选项后，每个 try-compile 检查都会打印一条日志消息，报告执行检查的目录。

--debug-output¶

将 cmake 置于调试模式。

在 cmake 运行时打印额外信息，例如带有 message(SEND_ERROR) 调用的堆栈跟踪。

--debug-find¶

在 3.17 版本中添加。

将 cmake find 命令置于调试模式。

在 cmake 运行期间向标准错误打印额外的 find 调用信息。输出旨在供人阅读，而非用于解析。另请参阅 CMAKE_FIND_DEBUG_MODE 变量，用于调试项目的更局部部分。

--debug-find-pkg=<pkg>[,...]¶

在版本 3.23 中添加。

当在调用 find_package(<pkg>) 下运行时，将 cmake find 命令置于调试模式，其中 <pkg> 是给定逗号分隔的区分大小写的包名称列表中的一个条目。

与 --debug-find 类似，但将范围限制为指定的包。

--debug-find-var=<var>[,...]¶

在版本 3.23 中添加。

当调用 cmake find 命令时，如果 <var> 作为结果变量，并且 <var> 是给定逗号分隔列表中的一个条目，则将 cmake find 命令置于调试模式。

类似于 --debug-find，但将范围限制为指定的变量名。

--trace¶

将 cmake 置于跟踪模式。

打印所有调用及其来源的跟踪信息。

--trace-expand¶

将 cmake 置于跟踪模式。

与 --trace 类似，但变量已展开。

--trace-format=<format>¶

在 3.17 版本中添加。

将 cmake 置于跟踪模式并设置跟踪输出格式。

<format> 可以是以下值之一。

人工
以人类可读的格式打印每条跟踪行。这是默认格式。

json-v1
将每行打印为单独的 JSON 文档。每个文档由换行符 (\n) 分隔。保证 JSON 文档内部不会出现换行符。
JSON 跟踪格式¶
{
  "file": "/full/path/to/the/CMake/file.txt",
  "line": 0,
  "cmd": "add_executable",
  "args": ["foo", "bar"],
  "time": 1579512535.9687231,
  "frame": 2,
  "global_frame": 4
}
成员是

文件
调用函数的 CMake 源文件的完整路径。

行
函数调用开始的 file 中的行。

行尾
如果函数调用跨多行，此字段将设置为函数调用结束的行。如果函数调用跨单行，此字段将取消设置。此字段在 json-v1 格式的次要版本 2 中添加。

延迟
可选成员，当函数调用被 cmake_language(DEFER) 延迟时出现。如果存在，其值是包含延迟调用 <id> 的字符串。

命令
被调用的函数名称。

参数
所有函数参数的字符串列表。

时间
函数调用的时间戳（自纪元以来的秒数）。

框架
在当前处理的 CMakeLists.txt 的上下文中，被调用函数的堆栈帧深度。

全局框架
被调用的函数在所有涉及跟踪的 CMakeLists.txt 文件中全局跟踪的堆栈帧深度。此字段在 json-v1 格式的次要版本 2 中添加。

此外，输出的第一个 JSON 文档包含当前主要和次要版本的 version 键
JSON 版本格式¶
{
  "version": {
    "major": 1,
    "minor": 2
  }
}
成员是

版本
指示 JSON 格式的版本。版本遵循语义版本约定，包含主要和次要组件。

--trace-source=<file>¶

将 cmake 置于跟踪模式，但只输出指定文件的行。

允许多个选项。

--trace-redirect=<file>¶: 将 cmake 置于跟踪模式，并将跟踪输出重定向到文件而不是 stderr。

--warn-uninitialized¶

警告未初始化的值。

当使用未初始化变量时打印警告。

--warn-unused-vars¶: 无操作。在 CMake 3.2 及以下版本中，此选项会启用关于未使用变量的警告。在 CMake 3.3 到 3.18 版本中，此选项损坏。在 CMake 3.19 及以上版本中，此选项已移除。

--no-warn-unused-cli¶

不警告命令行选项。

不查找在命令行声明但未使用的变量。

--check-system-vars¶

查找系统文件中变量使用的问题。

通常，未使用和未初始化的变量仅在 CMAKE_SOURCE_DIR 和 CMAKE_BINARY_DIR 中查找。此标志告诉 CMake 也警告其他文件。

--compile-no-warning-as-error¶: 在 3.24 版本中添加。

忽略目标属性 COMPILE_WARNING_AS_ERROR 和变量 CMAKE_COMPILE_WARNING_AS_ERROR，防止在编译时将警告视为错误。

--link-no-warning-as-error¶: 4.0 版本新增。

忽略目标属性 LINK_WARNING_AS_ERROR 和变量 CMAKE_LINK_WARNING_AS_ERROR，防止在链接时将警告视为错误。

--profiling-output=<path>¶: 在 3.18 版本中新增。

与 --profiling-format 结合使用，将输出到给定路径。

--profiling-format=<file>¶

启用以给定格式输出 CMake 脚本的性能分析数据。

这有助于 CMake 脚本的性能分析。应使用第三方应用程序将输出处理为人类可读的格式。

当前支持的值有：google-trace 输出为 Google Trace Format，可由 Google Chrome 的 about:tracing 选项卡或使用 Trace Compass 等工具的插件进行解析。

--preset <preset>, --preset=<preset>¶

从 CMakePresets.json 和 CMakeUserPresets.json 文件中读取 预设，这些文件必须位于与顶级 CMakeLists.txt 文件相同的目录中。预设可以指定生成器、构建目录、变量列表以及要传递给 CMake 的其他参数。必须存在 CMakePresets.json 或 CMakeUserPresets.json 至少一个。 CMake GUI 也识别并支持 CMakePresets.json 和 CMakeUserPresets.json 文件。有关这些文件的完整详细信息，请参阅 cmake-presets(7)。

预设在所有其他命令行选项之前读取，尽管 -S 选项可用于指定包含 CMakePresets.json 和 CMakeUserPresets.json 文件的源目录。如果未给出 -S，则假定当前目录是顶级源目录，并且必须包含预设文件。通过手动在命令行指定，可以选择的预设（变量、生成器等）的所有选项都可以被覆盖。例如，如果预设将名为 MYVAR 的变量设置为 1，但用户使用 -D 参数将其设置为 2，则值 2 优先。

--list-presets[=<type>]¶: 列出指定 <type> 的可用预设。 <type> 的有效值为 configure、build、test、package 或 all。如果省略 <type>，则假定为 configure。当前工作目录必须包含 CMake 预设文件，除非使用 -S 选项指定不同的顶级源目录。

--debugger¶

启用 CMake 语言的交互式调试。CMake 在 --debugger-pipe 命名的管道上公开了一个调试接口，该接口符合 Debug Adapter Protocol 规范，并进行了以下修改。

initialize 响应包含一个名为 cmakeVersion 的附加字段，该字段指定正在调试的 CMake 版本。

调试器初始化响应¶

{
  "cmakeVersion": {
    "major": 3,
    "minor": 27,
    "patch": 0,
    "full": "3.27.0"
  }
}

成员是

主要版本: 指定主版本号的整数。
次要版本: 指定次版本号的整数。
补丁版本: 指定补丁版本号的整数。
完整版: 指定完整 CMake 版本的字符串。

--debugger-pipe <pipe name>, --debugger-pipe=<pipe name>¶: 用于调试器通信的管道（在 Windows 上）或域套接字（在 Unix 上）的名称。

--debugger-dap-log <log path>, --debugger-dap-log=<log path>¶: 将所有调试器通信记录到指定文件。

构建项目¶

CMake 提供了命令行签名来构建已生成的项目二进制树

cmake --build <dir>             [<options>] [-- <build-tool-options>]
cmake --build --preset <preset> [<options>] [-- <build-tool-options>]

这抽象了原生构建工具的命令行界面，具有以下选项

--build <dir>¶: 要构建的项目二进制目录。这是必需的（除非指定了预设）并且必须放在第一位。

--preset <preset>, --preset=<preset>¶: 使用构建预设来指定构建选项。项目二进制目录从 configurePreset 键推断。当前工作目录必须包含 CMake 预设文件。有关详细信息，请参阅 preset。

--list-presets¶: 列出可用的构建预设。当前工作目录必须包含 CMake 预设文件。

-j [<jobs>], --parallel [<jobs>]¶

3.12 版本新增。

构建时使用的并发进程的最大数量。如果省略 <jobs>，则使用原生构建工具的默认数量。

如果设置了 CMAKE_BUILD_PARALLEL_LEVEL 环境变量，则在未给出此选项时指定默认并行级别。

有些原生构建工具总是并行构建。使用 1 的 <jobs> 值可用于限制为单个作业。

-t <tgt>..., --target <tgt>...¶: 构建 <tgt> 而不是默认目标。可以给出多个目标，用空格分隔。

--config <cfg>¶: 对于多配置工具，选择配置 <cfg>。

--clean-first¶: 先构建目标 clean，然后构建。（只清除，使用 --target clean。）

--resolve-package-references=<value>¶

在版本 3.23 中添加。

在构建之前解析来自外部包管理器（例如 NuGet）的远程包引用。当 <value> 设置为 on (默认) 时，包将在构建目标之前恢复。当 <value> 设置为 only 时，包将恢复，但不会执行构建。当 <value> 设置为 off 时，不会恢复任何包。

如果目标未定义任何包引用，则此选项无效。

此设置可在构建预设中指定（使用 resolvePackageReferences）。如果指定了此命令行选项，预设设置将被忽略。

如果没有提供命令行参数或预设选项，则将评估一个特定于环境的缓存变量，以决定是否执行包恢复。

当使用 Visual Studio 生成器时，包引用是使用 VS_PACKAGE_REFERENCES 属性定义的。包引用使用 NuGet 恢复。可以通过将 CMAKE_VS_NUGET_PACKAGE_RESTORE 变量设置为 OFF 来禁用它。

--use-stderr¶: 忽略。在 CMake >= 3.0 中，此行为是默认的。

-v, --verbose¶

启用详细输出（如果支持），包括要执行的构建命令。

如果设置了 VERBOSE 环境变量或 CMAKE_VERBOSE_MAKEFILE 缓存变量，则可以省略此选项。

--¶: 将剩余选项传递给原生工具。

运行 cmake --build 不带任何选项以获取快速帮助。

特定生成器的构建工具行为¶

cmake --build 在某些生成器上具有特殊行为

Xcode

版本 4.1 新增: 如果第三方工具在 CMake 生成的 .xcodeproj 旁边写入了 .xcworkspace，则 cmake --build 会通过工作区驱动构建。

安装项目¶

CMake 提供了一个命令行签名来安装已生成的项目二进制树

cmake --install <dir> [<options>]

这可以在构建项目后使用，以便在不使用生成的构建系统或原生构建工具的情况下运行安装。选项如下：

--install <dir>¶: 要安装的项目二进制目录。这是必需的，并且必须是第一个。

--config <cfg>¶: 对于多配置生成器，选择配置 <cfg>。

--component <comp>¶: 基于组件的安装。只安装组件 <comp>。

--default-directory-permissions <permissions>¶: 默认目录安装权限。权限格式为 <u=rwx,g=rx,o=rx>。

--prefix <prefix>¶: 覆盖安装前缀，CMAKE_INSTALL_PREFIX。

--strip¶: 安装前剥离。

-v, --verbose¶

启用详细输出。

如果设置了 VERBOSE 环境变量，则可以省略此选项。

-j <jobs>, --parallel <jobs>¶: 在版本 3.31 中添加。

使用给定数量的作业并行安装。仅当启用 INSTALL_PARALLEL 时才可用。CMAKE_INSTALL_PARALLEL_LEVEL 环境变量在未提供此选项时指定默认并行级别。

运行 cmake --install 不带任何选项以获取快速帮助。

打开项目¶

cmake --open <dir>

在关联的应用程序中打开生成的项目。这只受某些生成器支持。

运行脚本¶

cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]

-D <var>=<value>¶: 为脚本模式定义变量。

-P <cmake-script-file>¶: 将给定的 cmake 文件作为用 CMake 语言编写的脚本进行处理。不执行配置或生成步骤，也不修改缓存。如果使用 -D 定义变量，则必须在 -P 参数之前完成此操作。

-- 之后的所有选项都不会由 CMake 解析，但它们仍包含在传递给脚本的 CMAKE_ARGV<n> 变量集中（包括 -- 本身）。

运行命令行工具¶

CMake 通过签名提供内置命令行工具

cmake -E <command> [<options>]

-E [help]¶: 运行 cmake -E 或 cmake -E help 以获取命令摘要。

可用命令有

capabilities¶

3.7 版本中新增。

以 JSON 格式报告 CMake 功能。输出是一个 JSON 对象，包含以下键：

版本

一个包含版本信息的 JSON 对象。键为

字符串: 完整的版本字符串，如 cmake --version 所显示。
主要版本: 主版本号的整数形式。
次要版本: 次版本号的整数形式。
补丁版本: 补丁级别的整数形式。
后缀: cmake 版本后缀字符串。
isDirty: 如果 cmake 构建来自一个“脏”树，则设置为 true 的布尔值。

生成器

可用生成器列表。每个生成器都是一个 JSON 对象，包含以下键

名称: 一个包含生成器名称的字符串。
工具集支持: 如果生成器支持工具集，则为 true，否则为 false。
平台支持: 如果生成器支持平台，则为 true，否则为 false。
支持的平台: 3.21 版本新增。

可选成员，当生成器支持通过 CMAKE_GENERATOR_PLATFORM (-A ...) 指定平台时，可能会出现此成员。该值是已知支持的平台列表。
额外生成器: 一个字符串列表，包含与生成器兼容的所有额外生成器。

文件 API

可选成员，当 cmake-file-api(7) 可用时存在。该值是一个 JSON 对象，包含一个成员

请求

一个 JSON 数组，包含零个或多个支持的文件 API 请求。每个请求都是一个 JSON 对象，包含成员

种类: 指定一个受支持的对象类型。
版本: 一个 JSON 数组，其元素均为 JSON 对象，包含指定非负整数版本组件的 major 和 minor 成员。

服务器模式

如果 cmake 支持服务器模式，则为 true，否则为 false。自 CMake 3.20 起始终为 false。

TLS

在 3.25 版本中新增。

如果启用了 TLS 支持，则为 true，否则为 false。

调试器

在 3.27 版本中新增。

如果支持 --debugger 模式，则为 true，否则为 false。

cat [--] <files>...¶

在 3.18 版本中新增。

连接文件并打印到标准输出。

--¶: 在 3.24 版本中添加。

新增对双破折号参数 -- 的支持。这个 cat 的基本实现不支持任何选项，因此使用以 - 开头的选项将导致错误。如果文件名以 - 开头，则使用 -- 来表示选项的结束。

版本 3.29 新增: cat 现在可以通过传递 - 参数来打印标准输入。

chdir <dir> <cmd> [<arg>...]¶: 更改当前工作目录并运行命令。

compare_files [--ignore-eol] <file1> <file2>¶

检查 <file1> 是否与 <file2> 相同。如果文件相同，则返回 0；如果不同，则返回 1。如果参数无效，则返回 2。

--ignore-eol¶: 3.14 版新增。

此选项表示按行比较，并忽略 LF/CRLF 差异。

copy <file>... <destination>, copy -t <destination> <file>...¶: 将文件复制到 <destination>（可以是文件或目录）。如果指定了多个文件，或者指定了 -t，则 <destination> 必须是目录且必须存在。如果未指定 -t，则最后一个参数被假定为 <destination>。不支持通配符。copy 会跟随符号链接。这意味着它不会复制符号链接，而是复制它们指向的文件或目录。

版本 3.5 新增: 支持多个输入文件。

版本 3.26 新增: 支持 -t 参数。

copy_directory <dir>... <destination>¶: 将 <dir>... 目录的内容复制到 <destination> 目录。如果 <destination> 目录不存在，它将被创建。copy_directory 会跟随符号链接。

版本 3.5 新增: 支持多个输入目录。

版本 3.15 新增: 当源目录不存在时，该命令现在会失败。以前它会通过创建一个空的目录来成功。

copy_directory_if_different <dir>... <destination>¶

3.26 版新增。

将 <dir>... 目录中已更改的内容复制到 <destination> 目录。如果 <destination> 目录不存在，它将被创建。

copy_directory_if_different 会跟随符号链接。当源目录不存在时，该命令会失败。

copy_if_different <file>... <destination>¶: 如果文件已更改，则将其复制到 <destination>（可以是文件或目录）。如果指定了多个文件，则 <destination> 必须是目录且必须存在。copy_if_different 会跟随符号链接。

版本 3.5 新增: 支持多个输入文件。

create_symlink <old> <new>¶: 创建一个名为 <new> 的符号链接，指向 <old>。

版本 3.13 新增: 支持在 Windows 上创建符号链接。

注意

创建 <new> 符号链接的路径必须事先存在。

create_hardlink <old> <new>¶: 3.19 版本新增。

创建名为 <new> 的硬链接，指向 <old>。

注意

创建 <new> 硬链接的路径必须事先存在。<old> 必须事先存在。

echo [<string>...]¶: 将参数显示为文本。

echo_append [<string>...]¶: 将参数显示为文本，但不换行。

env [<options>] [--] <command> [<arg>...]¶

版本 3.1 中新增。

在修改后的环境中运行命令。选项有

NAME=VALUE¶: 将 NAME 的当前值替换为 VALUE。

--unset=NAME¶: 取消设置 NAME 的当前值。

--modify ENVIRONMENT_MODIFICATION¶

在 3.25 版本中新增。

对修改后的环境应用单个 ENVIRONMENT_MODIFICATION 操作。

NAME=VALUE 和 --unset=NAME 选项分别等同于 --modify NAME=set:VALUE 和 --modify NAME=unset:。请注意，--modify NAME=reset: 会将 NAME 重置为 cmake 启动时（或未设置时）的值，而不是最近的 NAME=VALUE 选项。

--¶: 在 3.24 版本中添加。

新增对双破折号参数 -- 的支持。使用 -- 停止解释选项/环境变量，并将下一个参数视为命令，即使它以 - 开头或包含 =。

environment¶: 显示当前环境变量。

false¶: 3.16 版新增。

不执行任何操作，退出代码为 1。

make_directory <dir>...¶: 创建 <dir> 目录。如有必要，也创建父目录。如果目录已存在，则会静默忽略。

版本 3.5 新增: 支持多个输入目录。

md5sum <file>...¶

以 md5sum 兼容格式创建文件 MD5 校验和

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

sha1sum <file>...¶

3.10 版本新增。

以 sha1sum 兼容格式创建文件 SHA1 校验和

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

sha224sum <file>...¶

3.10 版本新增。

以 sha224sum 兼容格式创建文件 SHA224 校验和

b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

sha256sum <file>...¶

3.10 版本新增。

以 sha256sum 兼容格式创建文件 SHA256 校验和

76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

sha384sum <file>...¶

3.10 版本新增。

以 sha384sum 兼容格式创建文件 SHA384 校验和

acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

sha512sum <file>...¶

3.10 版本新增。

以 sha512sum 兼容格式创建文件 SHA512 校验和

2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

remove [-f] <file>...¶

自 3.17 版本起已弃用。

删除文件。预期的行为是，如果任何列出的文件已经不存在，命令将返回非零退出代码，但不记录消息。-f 选项将行为更改为在这种情况下返回零退出代码（即成功）。remove 不跟随符号链接。这意味着它只删除符号链接，而不删除它指向的文件。

实现存在 bug，始终返回 0。在不破坏向后兼容性的情况下无法修复。请改用 rm。

remove_directory <dir>...¶: 自 3.17 版本起已弃用。

删除 <dir> 目录及其内容。如果目录不存在，它将被静默忽略。请改用 rm。

版本 3.15 新增: 支持多个目录。

版本 3.16 新增: 如果 <dir> 是指向目录的符号链接，则只删除符号链接。

rename <oldname> <newname>¶: 重命名文件或目录（在同一卷上）。如果已存在名为 <newname> 的文件，则会静默替换它。

rm [-rRf] [--] <file|dir>...¶: 在 3.17 版本中添加。

删除文件 <file> 或目录 <dir>。使用 -r 或 -R 以递归方式删除目录及其内容。如果任何列出的文件/目录不存在，命令将返回非零退出代码，但不记录消息。-f 选项将行为更改为在这种情况下返回零退出代码（即成功）。使用 -- 停止解释选项，并将所有剩余参数视为路径，即使它们以 - 开头。

sleep <number>¶

新增于 3.0 版本。

休眠 <number> 秒。<number> 可以是浮点数。由于启动/停止 CMake 可执行文件的开销，实际最小值约为 0.1 秒。这在 CMake 脚本中可能很有用，用于插入延迟。

# Sleep for about 0.5 seconds
execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5)

tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]¶

创建或提取 tar 或 zip 档案。选项有

c¶: 创建一个包含指定文件的新档案。如果使用此选项，则 <pathname>... 参数是强制性的。

x¶: 从档案中提取到磁盘。

版本 3.15 新增: <pathname>... 参数可用于仅提取选定的文件或目录。提取选定的文件或目录时，您必须提供它们的精确名称，包括路径，如 list (-t) 所打印。

t¶: 列出档案内容。

版本 3.15 新增: <pathname>... 参数可用于仅列出选定的文件或目录。

v¶: 生成详细输出。

z¶: 使用 gzip 压缩生成的档案。

j¶: 使用 bzip2 压缩生成的档案。

J¶: 版本 3.1 中新增。

使用 XZ 压缩生成的档案。

--zstd¶: 版本 3.15 新增。

使用 Zstandard 压缩生成的档案。

--files-from=<file>¶: 版本 3.1 中新增。

从给定文件读取文件名，每行一个。忽略空行。行不能以 - 开头，除了 --add-file=<name> 用于添加名称以 - 开头的文件。

--format=<format>¶: 3.3 版本中新增。

指定要创建的档案格式。支持的格式有：7zip、gnutar、pax、paxr（受限 pax，默认）和 zip。

--mtime=<date>¶: 版本 3.1 中新增。

指定记录在 tarball 条目中的修改时间。

--touch¶: 在 3.24 版本中添加。

使用当前本地时间戳而不是从档案中提取文件时间戳。

--¶: 版本 3.1 中新增。

停止解释选项，并将所有剩余参数视为文件名，即使它们以 - 开头。

版本 3.1 新增: LZMA (7zip) 支持。

版本 3.15 新增: 该命令现在即使某些文件不可读，也会继续将文件添加到档案中。此行为与经典 tar 工具更一致。该命令现在还会解析所有标志，如果提供了无效标志，则会发出警告。

time <command> [<args>...]¶: 运行 <command> 并显示经过时间（包括 CMake 前端的开销）。

版本 3.5 新增: 该命令现在可以正确地将带有空格或特殊字符的参数传递给子进程。这可能会破坏那些通过自己的额外引用或转义来解决此错误的脚本。

touch <file>...¶: 如果文件不存在，则创建 <file>。如果 <file> 存在，则更改 <file> 的访问和修改时间。

touch_nocreate <file>...¶: 如果文件存在则触摸文件，但不创建它。如果文件不存在，则会静默忽略。

true¶: 3.16 版新增。

不执行任何操作，退出代码为 0。

Windows 特有的命令行工具¶

以下 cmake -E 命令仅在 Windows 上可用

delete_regv <key>¶: 删除 Windows 注册表值。

env_vs8_wince <sdkname>¶: 版本 3.2 中新增。

显示一个批处理文件，该文件设置了在 VS2005 中安装的给定 Windows CE SDK 的环境。

env_vs9_wince <sdkname>¶: 版本 3.2 中新增。

显示一个批处理文件，该文件设置了在 VS2008 中安装的给定 Windows CE SDK 的环境。

write_regv <key> <value>¶: 写入 Windows 注册表值。

运行查找包工具¶

CMake 为基于 Makefile 的项目提供了一个类似于 pkg-config 的助手

cmake --find-package [<options>]

注意

由于一些技术限制，此模式不受良好支持。它被保留用于兼容性，但不应在新项目中使用。

--find-package¶

它使用 find_package() 命令搜索包，并将结果标志打印到标准输出。这可以替代 pkg-config，用于在基于 Makefile 的纯项目中或在基于 Autoconf 的项目中使用系统上安装在 share/aclocal/cmake.m4 中的辅助宏查找已安装的库。

使用此选项时，需要以下变量：

名称

在 find_package(<PackageName>) 中调用的包名。

COMPILER_ID

用于搜索包的 Compiler ID，即 GNU/Intel/Clang/MSVC 等。

语言

用于搜索包的语言，即 C/CXX/Fortran/ASM 等。

模式

包搜索模式。值可以是以下之一：

存在: 仅检查给定包是否存在。
编译: 打印用于编译使用给定包的目标文件所需的标志。
链接: 打印使用给定包时链接所需的标志。

SILENT

（可选）如果为 TRUE，则不打印查找结果消息。

例如

cmake --find-package -DNAME=CURL -DCOMPILER_ID=GNU -DLANGUAGE=C -DMODE=LINK

运行工作流预设¶

在 3.25 版本中新增。

CMake 预设 提供了一种按顺序执行多个构建步骤的方法

cmake --workflow <options>

选项包括

--workflow¶: 使用以下选项之一选择工作流预设。

--preset <preset>, --preset=<preset>¶

使用工作流预设来指定工作流。项目二进制目录是从初始配置预设推断的。当前工作目录必须包含 CMake 预设文件。有关更多详细信息，请参见 preset。

版本 3.31 中有改动: 在 --workflow 选项之后紧接着，可以省略 --preset 参数，只给定 <preset> 名称。这意味着以下语法是有效的

$ cmake --workflow my-preset

--list-presets¶: 列出可用的工作流预设。当前工作目录必须包含 CMake 预设文件。

--fresh¶: 对构建树执行全新配置，效果与 cmake --fresh 相同。

查看帮助¶

要打印 CMake 文档的选定页面，请使用

cmake --help[-<topic>]

并带以下选项之一

-version [<file>], --version [<file>], /V [<file>]¶: 显示程序名称/版本横幅并退出。如果给定，输出将打印到指定 <file>。

-h, -H, --help, -help, -usage, /?¶

打印使用信息并退出。

使用说明描述了基本的命令行界面及其选项。

--help <keyword> [<file>]¶

打印一个 CMake 关键字的帮助。

<keyword> 可以是属性、变量、命令、策略、生成器或模块。

将 <keyword> 的相关手册条目以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

3.28 版本变更：在 CMake 3.28 之前，此选项仅支持命令名称。

--help-full [<file>]¶

打印所有帮助手册并退出。

所有手册都以人类可读的文本格式打印。如果给定，输出将打印到指定 <file>。

--help-manual <man> [<file>]¶

打印一个帮助手册并退出。

指定的手册以人类可读的文本格式打印。如果给定，输出将打印到指定 <file>。

--help-manual-list [<file>]¶

列出可用的帮助手册并退出。

该列表包含所有可通过使用 --help-manual 选项后跟手册名称来获取帮助的手册。如果给定 <file>，则输出将打印到该命名文件。

--help-command <cmd> [<file>]¶

打印一个命令的帮助并退出。

将 <cmd> 的 cmake-commands(7) 手册条目以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-command-list [<file>]¶

列出可获取帮助的命令并退出。

该列表包含所有可通过使用 --help-command 选项后跟命令名称来获取帮助的命令。如果给定 <file>，则输出将打印到该命名文件。

--help-commands [<file>]¶

打印 cmake-commands 手册并退出。

将 cmake-commands(7) 手册以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-module <mod> [<file>]¶

打印一个模块的帮助并退出。

将 <mod> 的 cmake-modules(7) 手册条目以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-module-list [<file>]¶

列出可获取帮助的模块并退出。

该列表包含所有模块，可通过使用 --help-module 选项后跟模块名称来获取帮助。如果给定 <file>，则输出将打印到该命名文件。

--help-modules [<file>]¶

打印 cmake-modules 手册并退出。

将 cmake-modules(7) 手册以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-policy <cmp> [<file>]¶

打印一个策略的帮助并退出。

将 <cmp> 的 cmake-policies(7) 手册条目以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-policy-list [<file>]¶

列出可获取帮助的策略并退出。

该列表包含所有策略，可通过使用 --help-policy 选项后跟策略名称来获取帮助。如果给定 <file>，则输出将打印到该命名文件。

--help-policies [<file>]¶

打印 cmake-policies 手册并退出。

将 cmake-policies(7) 手册以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-property <prop> [<file>]¶

打印一个属性的帮助并退出。

将 <prop> 的 cmake-properties(7) 手册条目以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-property-list [<file>]¶

列出可获取帮助的属性并退出。

该列表包含所有属性，可通过使用 --help-property 选项后跟属性名称来获取帮助。如果给定 <file>，则输出将打印到该命名文件。

--help-properties [<file>]¶

打印 cmake-properties 手册并退出。

将 cmake-properties(7) 手册以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-variable <var> [<file>]¶

打印一个变量的帮助并退出。

将 <var> 的 cmake-variables(7) 手册条目以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

--help-variable-list [<file>]¶

列出可获取帮助的变量并退出。

该列表包含所有变量，可通过使用 --help-variable 选项后跟变量名称来获取帮助。如果给定 <file>，则输出将打印到该命名文件。

--help-variables [<file>]¶

打印 cmake-variables 手册并退出。

将 cmake-variables(7) 手册以人类可读的文本格式打印出来。如果给定 <file>，则输出将打印到该命名文件。

要查看项目可用的预设，请使用

cmake <source-dir> --list-presets

返回值（退出代码）¶

正常终止时，cmake 可执行文件返回退出代码 0。

如果终止是由命令 message(FATAL_ERROR) 或其他错误条件引起的，则返回非零退出代码。

另请参阅¶

以下资源可用于获取使用 CMake 的帮助

主页

https://cmake.com.cn

学习 CMake 的主要起点。

在线文档和社区资源

https://cmake.com.cn/documentation

此网页上可以找到可用文档和社区资源的链接。

论坛

https://discourse.cmake.org

论坛用于讨论和提问 CMake。

cmake(1)¶

概要¶

描述¶

CMake 构建系统简介¶

生成项目构建系统¶

选项¶

构建项目¶

特定生成器的构建工具行为¶

安装项目¶

打开项目¶

运行脚本¶

运行命令行工具¶

Windows 特有的命令行工具¶

运行查找包工具¶

运行工作流预设¶

查看帮助¶

返回值（退出代码）¶

另请参阅¶

目录

上一主题

下一主题

本页