cmake：命令行工具cmake

最新推荐文章于 2024-05-20 08:00:00 发布

OceanStar的学习笔记

最新推荐文章于 2024-05-20 08:00:00 发布

阅读量8.7k

点赞数 3

分类专栏： C++

原文链接：https://cmake.org/cmake/help/v3.15/manual/cmake.1.html#synopsis

版权

C++ 专栏收录该内容

1059 篇文章 284 订阅

订阅专栏

概要

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

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

描述

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

要使用 CMake 构建软件项目，请参考目录【生成项目构建系统】。

可以选择使用 cmake 来【构建项目】、【安装项目】或直接运行相应的构建工具（例如 make）。 cmake 也可用于【查看帮助】。

其他操作旨在供软件开发人员使用 CMake language编写脚本来支持他们的构建。

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

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

CMake构建系统简介

[构建系统]描述了如何使用构建工具从源代码构建项目的可执行文件和库，从而实现该过程的自动化。举个例子

构建系统可以是与命令行make工具一起使用的Makefile
也可以是集成开发环境(IDE)的项目文件

为了避免维护多个这样的构建系统，项目可以使用CMake语言编写的文件抽象地指定其构建系统。从这些文件中，CMake通过一个名为generator的后端在本地为每个用户生成一个首选[构建系统]。

要用CMake生成一个构建系统，必须选择以下选项:

源码树
- 包含项目提供的源文件的顶级目录。
- 该项目使用cmake-language(7)手册中描述的文件指定其构建系统，从名为CMakeLists.txt的顶级文件开始。
- 这些文件指定构建目标和它们的依赖项，如cmake-buildsystem(7)手册所述。
构建树
- 存储构建系统文件和构建输出工件（如可执行文件和库）的顶层目录。
- CMake将编写一个CMakeCache.txt文件，以将目录标识为构建树，并存储持久性信息，如buildsystem配置选项。
- 要维护原始的源代码树，请使用单独的专用生成树执行源代码外生成。也支持将生成树放置在与源树相同的目录中的源内生成，但不鼓励这样做。
Generator
- 这选择了要生成的构建系统的类型。
- 请参阅cmake-generators(7)手册，了解所有生成器的文档。
- 运行cmake --help查看本地可用的生成器列表。
- 可以选择使用下面的-G选项来指定一个生成器，或者简单地接受当前平台的默认CMake选项。

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

生成项目构建系统

使用以下命令签名之一运行CMake来指定源代码和构建树并生成一个构建系统:

cmake [<options>] <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 .

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

使用< path to build>作为构建树，使用< path to source>作为源树。
指定的路径可以是绝对路径，也可以是相对于当前工作目录的路径。
源树必须包含CMakeLists.txt文件。如果生成树不存在，则会自动创建它。
例如：

$ cmake -S src -B build

在所有情况下，可以是下面的0个或多个【options】。

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

$ make
$ make install

或者，可以使用cmake自动选择并调用适当的本地构建工具来构【构建项目】。

Options

-S <path-to-source>

-B <path-to-build>

-C <initial-cache>

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

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

创建或更新CMake缓存项。
当CMake第一次在空生成树中运行时，它会创建一个CMakeCache.txt文件，并用项目的可自定义设置填充该文件。此选项可用于指定优先于项目默认值的设置。可以根据需要对任意多个缓存条目重复该选项。
如果给定:<type>部分，则它必须是set()命令文档为其缓存签名指定的类型之一。
如果省略了:<type>部分，那么如果条目不存在且已经存在类型，则将不使用类型创建条目。
如果项目中的命令将类型设置为PATH或FILEPATH，则<value>将转换为绝对路径。
此选项也可以作为单个参数提供：-D<var>:<type>=<value>或-D<var>=<value>。

-U <globbing_expr>

从CMake CACHE中删除匹配的条目。
此选项可用于从CMakeCache.txt文件中删除一个或多个变量，使用*和?都受支持。该选项可以对任意多个CACHE条目重复使用。
小心使用，你可以使你的CMakeCache.txt不起作用。

-G <generator-name>

指定build system generator.
CMake可能在某些平台上支持多个本机构建系统。生成器负责生成特定的构建系统。可能的生成器名称在cmake-generators(7)手册中指定。
如果没有指定，CMake检查CMAKE_GENERATOR环境变量，否则返回内置的默认选择。

-T <toolset-spec>

生成器的工具集规范（如果支持）。
一些CMake生成器支持一个工具集规范来告诉本机构建系统如何选择编译器。详细信息请参见CMAKE_GENERATOR_TOOLSET变量。

-A <platform-name>

如果生成器支持，请指定平台名称。
有些CMake生成器支持给原生构建系统一个平台名来选择编译器或SDK。详细信息请参见CMAKE_GENERATOR_PLATFORM变量。

-Wno-dev

抑制开发人员警告。

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

-Wdev

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

-Wno-error=dev

对开发人员发出警告而不是错误。

对CMakeLists.txt文件的作者发出警告，而不是错误。默认情况下，这也会将已弃用的警告作为错误关闭。

-Wdeprecated

启用不推荐使用的功能警告。
启用针对不推荐使用的功能的警告，这些功能针对CMakeLists.txt文件的作者。

-Wno-deprecated

取消不推荐使用的功能警告。
禁止使用针对CMakeLists.txt文件作者的已弃用功能的警告。

-Werror=deprecated

生成不推荐使用的宏和函数警告错误。
对不推荐使用的宏和函数（针对CMakeLists.txt文件的作者）发出警告，并指出错误。.

-Wno-error=deprecated

使不推荐使用的宏和函数出现警告而不是错误。
对不推荐使用的宏和函数发出警告，这些宏和函数是针对CMakeLists.txt文件的作者，而不是针对错误

-L[A][H]·

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

-N

视图模式。
只加载缓存。不要实际运行配置和生成步骤。

--graphviz=[file]

生成依赖的graphviz，参见CMakeGraphVizOptions了解更多。
生成一个graphviz输入文件，该文件将包含项目中的所有库和可执行依赖项。更多细节请参见CMakeGraphVizOptions的文档。

--system-information [file]

转储此系统信息。
转储关于当前系统的大量信息。如果从CMake项目的二叉树顶部运行，它将转储额外的信息，如缓存，日志文件等。

设置日志级别。
message()命令只输出指定日志级别或更高级别的消息。缺省情况下，日志级别为STATUS。

--debug-trycompile

不要删除try_compile()构建树。一次只对一个try_compile()有用。
不要删除为try_compile()调用创建的文件和目录。这在调试失败的try_compiles时很有用。但是，它可能会将try-compile的结果更改为旧垃圾，可能导致不同的测试通过或错误失败。此选项最好用于一次只进行一次试编译，且仅在调试时使用。

--debug-output

将cmake置于调试模式。
在cmake运行期间打印额外的信息，就像使用message(SEND_ERROR)调用进行堆栈跟踪一样。

--trace

将cmake置于跟踪模式。
打印出所有的调用记录和调用地点。

--trace-expand

将cmake置于跟踪模式。
类似–trace，但是扩展了变量。

--trace-source=<file>

将cmake置于跟踪模式，但只输出指定文件的行。
允许有多个选项。

--warn-uninitialized

对未初始化的值发出警告。
当使用未初始化的变量时，打印警告。

--warn-unused-vars

警告未使用的变量。
查找已声明或设置但未使用的变量。

--no-warn-unused-cli

不要对命令行选项发出警告。
不要找到在命令行上声明但没有使用的变量。

--check-system-vars

查找系统文件中变量使用的问题。
通常，只在CMAKE_SOURCE_DIR和CMAKE_BINARY_DIR中搜索未使用和未初始化的变量。这个标志也告诉CMake对其他文件发出警告。

构建项目

CMake提供了一个命令行签名来构建已经生成的项目二叉树

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

这将使用以下选项抽象本机构建工具的命令行界面：

--install <dir>
- 要安装的项目二进制目录。这是必须的，也必须是第一。
--config <cfg>
- 对于多配置生成器，选择配置<cfg>
--component <comp>
- 基于组件的安装。仅安装组件<comp> 。
--prefix <prefix>
- 覆盖安装前缀CMAKE_INSTALL_PREFIX。
--strip
- Strip before installing
-v, --verbose
- 启用详细输出。
- 如果设置了https://cmake.org/cmake/help/v3.15/envvar/VERBOSE.html#envvar:VERBOSE环境变量，则可以省略此选项。

运行cmake–install，没有快速帮助选项。

打开项目

cmake --open <dir>

在关联的应用程序中打开生成的项目。只有某些生成器支持此功能

运行脚本

cmake [{-D <var>=<value>}...] -P <cmake-script-file>

以cmake语言编写的脚本的形式处理给定的cmake文件。不执行配置或生成步骤，缓存不会被修改。如果使用-D定义变量，则必须在-P参数之前完成。

运行命令行工具

CMake通过签名提供了内置的命令行工具
cmake -E <command> [<options>]

执行cmake -E或cmake -E help查看命令汇总。可用的命令是:

capabilities：以JSON格式报告cmake功能。输出是一个JSON对象，包含以下键:
- version：一个带有版本信息的JSON对象。键是:
  - string：由cmake–version显示的完整版本字符串。
  - major：整数形式的主版本号。
  - minor：整数形式的次要版本号。
  - patch：整数形式的补丁级别。
  - suffix：cmake版本后缀字符串。
  - isDirty：如果cmake生成来自 dirty tree，则设置bool。
- generators：可用生成器列表。每个生成器都是一个带有以下键的JSON对象:
  - name：包含生成器名称的字符串。
  - toolsetSupport：如果生成器支持工具集，则为true，否则为false。
  - platformSupport：如果生成器支持平台，则为true，否则为false。
  - extraGenerators：包含与生成器兼容的所有额外生成器的字符串列表。
- fileApi：当cmake-file-api(7)可用时出现的可选成员。该值是一个包含一个成员的JSON对象:
  - requests：包含零个或多个受支持的文件api请求的JSON数组。每个请求都是一个JSON对象，其成员为：
    - kind：指定支持的对象类型之一。
    - version：一个JSON数组，其元素都是JSON对象，包含指定非负整数版本组件的主要和次要成员。
- serverMode：如果cmake支持服务器模式，则为true，否则为false。
chdir <dir> <cmd> [<arg>...]
- 更改当前工作目录并运行命令。
compare_files [--ignore-eol] <file1> <file2>
- 检查< file1>是否与< file2>相同。如果文件相同，则返回0，否则返回1。-ignore eol选项表示逐行比较并忽略LF/CRLF差异。
copy <file>... <destination>
- 将文件复制到< destination>（文件或目录）。
- 如果指定了多个文件，< destination>必须是目录并且必须存在。
- 不支持通配符。
- 复制遵循符号链接。这意味着它不复制符号链接，而是复制它指向的文件或目录。
copy_directory <dir>... <destination>
- 将目录复制到< destination>目录。
- 如果< destination>目录不存在，将创建它。
- 复制目录遵循符号链接。
copy_if_different <file>... <destination>
- 如果文件已更改，请将其复制到< destination>（文件或目录）。
- 如果指定了多个文件，< destination>必须是目录并且必须存在。
- 遵循符号链接。
echo [<string>...]
- 将参数显示为文本。
echo_append [<string>...]
- 将参数显示为文本，但不显示新行。
env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...
- 在修改后的环境中运行命令。
environment
- 显示当前环境变量。
make_directory <dir>...
- 创建< dir>目录。
- 如果需要，也可以创建父目录。
- 如果一个目录已经存在，它将被忽略
md5sum <file>...
- 为兼容md5sum格式的文件创建MD5校验和:

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

sha1sum <file>...
- 创建sha1sum兼容格式的文件校验和:

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

运行Find-Package工具

CMake为基于Makefile的项目提供类似pkg config的帮助程序：

cmake --find-package [<options>]

它使用find_package()搜索包，并将结果标记打印到stdout。它可以代替pkg-config在基于普通makefile的项目或基于autoconf的项目中找到已安装的库(通过share/aclocal/cmake.m4)。\

注意:由于某些技术限制，此模式不受很好的支持。保留它是为了兼容性，但不应该在新项目中使用。

查看帮助

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

cmake --help[-<topic>]

使用以下选项之一：

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

打印使用信息并退出。
用法描述基本命令行界面及其选项。

--version,-version,/V [<f>]

显示程序名称/版本标题并退出。
如果指定了一个文件，则将版本写入其中。如果给出帮助，将打印到指定的ile。

--help-full [<f>]

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

OceanStar的学习笔记

关注

3
点赞
踩
18

收藏

觉得还不错? 一键收藏
0
评论
cmake：命令行工具cmake

概要Generate a Project Buildsystem cmake [<options>] <path-to-source> cmake [<options>] <path-to-existing-build> cmake [<options>] -S <path-to-source> -B <path-to-build>Build a Project cmake --build <dir&gt
复制链接

扫一扫