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 文件以将该目录标识为构建树，并存储持久信息，例如构建系统配置选项。

要维护干净的源树，请通过使用单独的专用构建树来执行外部构建。也支持内部构建，其中构建树与源树放置在同一目录中，但不建议这样做。

生成器

这选择要生成的构建系统的种类。请参阅 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`	cwd	`build`
`cmake -B build src`	`src`	`build`
`cmake -B build -S src`	`src`	`build`
`cmake src`	`src`	cwd
`cmake build` (已存在)	已加载	`build`
`cmake -S src`	`src`	cwd
`cmake -S src build`	`src`	`build`
`cmake -S src -B build`	`src`	`build`

在 3.23 版本中更改: 当指定多个源路径时，CMake 会发出警告。这从未被正式记录或支持过，但旧版本意外地接受了多个源路径并使用了最后一个指定的路径。避免传递多个源路径参数。

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

$ make
$ make install

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

选项¶

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

-B <path-to-build>¶

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

-C <initial-cache>¶

预加载脚本以填充缓存。

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

脚本中对 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 参数设置了相同的变量，则由于非 FORCE set(... CACHE ...) 调用的性质，-D 参数将优先，而与顺序无关。

-U <globbing_expr>¶

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

此选项可用于从 CMakeCache.txt 文件中删除一个或多个变量，支持使用 * 和 ? 的 glob 表达式。可以根据需要多次重复该选项以用于多个 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> 必须是以下之一

dev

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

将旨在给 CMakeLists.txt 文件作者的警告视为错误。默认情况下，这也会将弃用警告作为错误打开。

deprecated

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

将使用已弃用的宏和函数的警告（这些警告旨在给 CMakeLists.txt 文件的作者）视为错误。

-Wno-error=<what>¶

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

dev: 将旨在给 CMakeLists.txt 文件作者的警告不视为错误。默认情况下，这也会关闭弃用警告作为错误。
deprecated: 将使用已弃用的宏和函数的警告（这些警告旨在给 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 版本中添加。

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

有关更多详细信息，请参见 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() 命令的 query the current message logging level。

--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-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 版本新增。

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

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

--trace¶

将 cmake 置于跟踪模式。

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

--trace-expand¶

将 cmake 置于跟踪模式。

与 --trace 类似，但会扩展变量。

--trace-format=<format>¶

3.17 版本新增。

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

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

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

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
}
成员包括

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

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

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

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

cmd
调用的函数的名称。

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

time
函数调用的时间戳（自 epoch 以来的秒数）。

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

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

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

version
指示 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 的管道上公开一个调试接口，该接口符合调试适配器协议规范，并具有以下修改。

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

调试器初始化响应¶

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

成员包括

major: 一个整数，指定主版本号。
minor: 一个整数，指定次版本号。
patch: 一个整数，指定补丁版本号。
full: 一个字符串，指定完整的 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 预设文件。有关更多详细信息，请参阅 预设。

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

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

3.12 版本新增。

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

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

某些本机构建工具始终并行构建。<jobs> 值为 1 可用于限制为单个作业。

-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 提供了一个命令行签名，用于安装已生成的项目二进制树

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 对象，包含以下键

version

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

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

generators

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

name: 包含生成器名称的字符串。
toolsetSupport: 如果生成器支持工具集，则为 true，否则为 false。
platformSupport: 如果生成器支持平台，则为 true，否则为 false。
supportedPlatforms: 在 3.21 版本中添加。

可选成员，当生成器支持通过 CMAKE_GENERATOR_PLATFORM (-A ...) 进行平台规范时可能存在。该值是已知支持的平台列表。
extraGenerators: 包含与生成器兼容的所有额外生成器的字符串列表。

fileApi

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

requests

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

kind: 指定受支持的对象种类之一。
version: 一个 JSON 数组，其元素都是 JSON 对象，包含 major 和 minor 成员，用于指定非负整数版本组件。

serverMode

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

tls

在版本 3.25 中添加。

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

debugger

在版本 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 中添加: 当源目录不存在时，该命令现在会失败。以前，它通过创建一个空的 destination 目录而成功。

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>¶: 创建一个名为 <old> 的符号链接 <new>。

在版本 3.13 中添加: 支持在 Windows 上创建符号链接。

注意

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

create_hardlink <old> <new>¶: 在版本 3.19 中添加。

创建一个名为 <old> 的硬链接 <new>。

注意

将在其中创建 <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 不遵循符号链接。这意味着它仅删除符号链接，而不删除它指向的文件。

该实现存在错误，并且始终返回 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 中添加。

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

Added in version 3.1: LZMA (7zip) 支持。

Added in version 3.15: 该命令现在会继续向归档文件添加文件，即使某些文件不可读。此行为与经典的 tar 工具更加一致。该命令现在还会解析所有标志，如果提供了无效的标志，则会发出警告。

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

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

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

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

true¶: 在 3.16 版本中添加。

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

Windows 特定命令行工具¶

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

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

env_vs8_wince <sdkname>¶: Added in version 3.2.

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

env_vs9_wince <sdkname>¶: Added in version 3.2.

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

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

运行 Find-Package 工具¶

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

cmake --find-package [<options>]

它使用 find_package() 搜索包，并将结果标志打印到 stdout。这可以用来代替 pkg-config，以便在纯粹基于 Makefile 的项目或基于 autoconf 的项目（通过 share/aclocal/cmake.m4）中查找已安装的库。

注意

由于一些技术限制，此模式支持不佳。它保留下来是为了兼容性，但不应在新项目中使用。

运行工作流程预设¶

在版本 3.25 中添加。

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

cmake --workflow <options>

选项包括

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

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

使用工作流程预设来指定工作流程。项目二进制目录从初始配置预设中推断出来。当前工作目录必须包含 CMake 预设文件。请参阅 preset 了解更多详情。

Changed in version 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> 文件（如果给定）。

Changed in version 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>]¶

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

以人类可读的文本格式打印 cmake-commands(7) 手册中关于 <cmd> 的条目。输出将打印到指定的 <file> 文件（如果给定）。

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

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

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

--help-commands [<file>]¶

打印 cmake-commands 手册并退出。

以人类可读的文本格式打印 cmake-commands(7) 手册。输出将打印到指定的 <file> 文件（如果给定）。

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

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

以人类可读的文本格式打印 cmake-modules(7) 手册中关于 <mod> 的条目。输出将打印到指定的 <file> 文件（如果给定）。

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

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

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

--help-modules [<file>]¶

打印 cmake-modules 手册并退出。

以人类可读的文本格式打印 cmake-modules(7) 手册。输出将打印到指定的 <file> 文件（如果给定）。

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

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

以人类可读的文本格式打印 cmake-policies(7) 手册中关于 <cmp> 的条目。输出将打印到指定的 <file> 文件（如果给定）。

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

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

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

--help-policies [<file>]¶

打印 cmake-policies 手册并退出。

以人类可读的文本格式打印 cmake-policies(7) 手册。输出将打印到指定的 <file> 文件（如果给定）。

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

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

以人类可读的文本格式打印 cmake-properties(7) 手册中关于 <prop> 的条目。输出将打印到指定的 <file> 文件（如果给定）。

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

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

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

--help-properties [<file>]¶

打印 cmake-properties 手册并退出。

以人类可读的文本格式打印 cmake-properties(7) 手册。输出将打印到指定的 <file> 文件（如果给定）。

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

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

以人类可读的文本格式打印 cmake-variables(7) 手册中关于 <var> 的条目。输出将打印到指定的 <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

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

Discourse 论坛

https://discourse.cmake.org

Discourse 论坛托管关于 CMake 的讨论和问题。

cmake(1)¶

概要¶

描述¶

CMake 构建系统简介¶

生成项目构建系统¶

选项¶

构建项目¶

安装项目¶

打开项目¶

运行脚本¶

运行命令行工具¶

Windows 特定命令行工具¶

运行 Find-Package 工具¶

运行工作流程预设¶

查看帮助¶

返回值（退出代码）¶

参见¶

目录

上一主题

下一主题

本页