CMake官方文档翻译(2) 命令行-cmake

2020-02-13 本文已影响0人我思故我在2020

cmake

概要

# 生成构建系统
 cmake [<options>] <path-to-source>
 cmake [<options>] <path-to-existing-build>
 cmake [<options>] -S <path-to-source> -B <path-to-build

# 构建项目
 cmake --build <dir> [<options>] [-- <build-tool-options>]
 
# 安装项目
 cmake --install <dir> [<options>]

# 打开项目
 cmake --open <dir>

# 运行脚本
 cmake [{-D <var>=<value>}...] -P <cmake-script-file>
 
# 运行内建命令
 cmake -E <command> [<options>]

# 运行Find-Package工具
 cmake --find-package [<options>]

# 查看帮助
 cmake --help[-<topic>]

描述

cmake是CMake提供的命令行工具。上面的概要列出了这个工具的许多用法，将会在后面详细描述。

为了构建一个软件项目，需先使用cmake生成构建系统。然后使用cmake构建项目、安装项目，或直接运行相应的构建工具。

其他的用法是提供给CMake构建脚本的编写者使用的。

cmake的图形用户界面，请查看ccmake和cmake-gui。CMake的命令行测试、打包工具：ctest和cpack。

想要查看CMake的更多信息，请翻到文档底部的链接列表。

CMake构建系统介绍

构建系统使用构建工具把项目的源代码自动地生成可执行文件和库。例如，一个构建系统可以是一个用于make命令的Makefile，或IDE中的项目文件。为了避免面对多种构建系统，CMake项目通过CMake语言文件实现构建系统的抽象。通过这些文件，CMake为不同后端生成本地构建系统。

使用CMake生成一个构建系统，以下部分必须指定：

源码根目录（Source Tree）

项目源码的顶层目录。项目的构建文件通过CMake语言来编写，入口构建文件命名为“CMakeLists.txt”。这些构建文件中指定了需要构建的目标和他们的依赖关系，就像cmake-buildsystem(7)手册描述的那样。
构建根目录（Build Tree）

用于保存构建系统产生的文件以及产物（如可执行程序和库）的顶层目录。CMake将会写入一个“CMakeCache.txt"文件到该目录，以便以后识别该目录为一个构建根目录。也会在该目录下保存一些信息比如构建配置项。

为了保持一个未侵入的源码目录，应该在源码目录之外的建立一个专有的目录作为构建根目录执行构建。在源码目录内建立构建根目录执行构建也支持，但应该避免这么做。
生成器

用于指定目标构建系统的类型。查看cmake-generators(7)手册获取所有生成器的文档。运行”cmake --help“查看本地可用的生成器列表。使用-G选项可以指定一个生成器，或者不指定-G，直接让CMake基于当前平台选择一个默认的生成器。

当选择一个“命令行构建工具生成器”时，CMake假设编译工具链需要的环境已经在shell中配置完成。当选择“IDE构建工具生成器”时，不需要特殊的环境。

生成构建系统

运行CMake，在下面的方法中选择一个指定源码根目录和构建根目录，生成一个构建系统：

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>作为构建根目录，该目录必须之前已经用CMake执行过生成，可以为绝对路径或相对路径，CMake通过加载其中的CMakeCache.txt文件可找到源码根目录。例：
```
$ 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
```

在所有这些方法中，<options>可以不指定或者使用后面即将列出的选项。

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

$ make
$ make install

或者，可以使用cmake来构建项目，让cmake自动选择合适的原生构建工具。

Options

-S <path-to-source>

CMake项目源码根目录。
-B <path-to-build>

CMake以这个目录作为构建根目录。如果目录不存在将创建。
-C <initial-cache>

Pre-load a script to populate the cache.

When CMake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s CMake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing set() commands that use the CACHE option, not a cache-format file.

References to CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR within the script evaluate to the top-level source and build tree.
-D <var>:<type>=<value>, -D <var>=<value>

Create or update a CMake CACHE entry.

When CMake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a setting that takes priority over the project’s default value. The option may be repeated for as many CACHE entries as desired.

If the :<type> portion is given it must be one of the types specified by the set() command documentation for its CACHE signature. If the :<type> portion is omitted the entry will be created with no type if it does not exist with a type already. If a command in the project sets the type to PATH or FILEPATH then the <value> will be converted to an absolute path.

This option may also be given as a single argument: -D<var>:<type>=<value> or -D<var>=<value>.
-U <globbing_expr>

Remove matching entries from CMake CACHE.

This option may be used to remove one or more variables from the CMakeCache.txt file, globbing expressions using * and ? are supported. The option may be repeated for as many CACHE entries as desired.

Use with care, you can make your CMakeCache.txt non-working.
-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变量获取详情。
-Wno-dev

关闭开发者警告。

这些警告是显示给CMakeLists.txt编写者的，本选项关闭这些警告的显示。缺省情况下，也会关闭过时功能的警告。
-Wdev

打开开发者警告。

这些警告是显示给CMakeLists.txt编写者的，本选项打开这些警告的显示。缺省情况下，也会打开过时功能的警告。
-Werror=dev

将开发者警告当做错误处理。

这些警告是显示给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]

列出非高级的缓存变量。

运行CMake，列出CACHE中未标记为INTERNAL和ADVANCED的变量。用来快速显示当前的CMake设置。如果指定了A，高级的变量也会显示。如果指定了H，将会同时显示每个变量的帮助信息。
-N

查看模式。

仅仅加载缓存，并不是真正执行配置和生成。
--graphviz=[file]

生成graphviz的依赖关系。查看CMakeGraphVizOptions获取更多信息。

生成一个graphviz输入文件，其中包含项目中所有库和可执行文件的依赖关系。查看CMakeGraphVizOptions 获取更多细节。
--system-information [file]

转储当前构建系统的信息。

转储当前构建系统的各种信息。如果在构建根目录运行，将会转储更多信息，比如缓存、日志文件等。
--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>

设置日志级别。

使得message()命令只会输出日志级别高于或等于设置级别的日志。缺省的日志级别是STATUS。

为了提供向后兼容性，--loglevel选项作为本选项的同义词。
--debug-trycompile

Do not delete the try_compile() build tree. Only useful on one try_compile() at a time.

Do not delete the files and directories created for try_compile() calls. This is useful in debugging failed try_compiles. It may however change the results of the try-compiles as old junk from a previous try-compile may cause a different test to either pass or fail incorrectly. This option is best used for one try-compile at a time, and only when debugging.
--debug-output

以debug模式运行cmake。

在cmake运行过程中会打印更多信息，比如调用message(SEND_ERROR)时打印堆栈回溯。
--trace

以trace模式运行cmake。

打印所有的调用的位置。
--trace-expand

以trace模式运行cmake。

同--trace，但增加了变量相关的信息。
--trace-source=<file>

以trace模式运行cmake，但仅对指定的文件启用。

可以多次使用本选项指定多个文件。
--trace-redirect=<file>

Put cmake in trace mode and redirect trace output to a file instead of stderr.
--warn-uninitialized

对未初始化的变量显示警告。

当使用未初始化的变量的时候，打印警告。
--warn-unused-vars

对未使用的变量显示警告。

如果定义或设置了变量之后没有使用，打印警告。
--no-warn-unused-cli

Don’t warn about command line options.

Don’t find variables that are declared on the command line, but not used.
--check-system-vars

Find problems with variable usage in system files.

Normally, unused and uninitialized variables are searched for only in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to warn about other files as well.

构建项目

cmake提供了以下格式的命令构建一个项目：

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

这个命令行对原生构建工具的命令进行了抽象，提供以下选项：

--build <dir>

需要执行构建的根目录，这是必须指定的，而且必须写在最前面。
--parallel [<jobs>], -j [<jobs>]

执行构建时使用的并发数。如果没有指定jobs，将由原生构建系统决定缺省并发数。

当没有指定并发数的时候，如果设置了CMAKE_BUILD_PARALLEL_LEVEL环境变量，将使用环境变量作为并发数。

有些原生构建工具总是使用并发构建，设置<jobs>为1可以限制为一个并发。
--target <tgt>..., -t <tgt>...

指定要构建的目标，可以多次使用该选项指定多个构建目标。
--config <cfg>

For multi-configuration tools, choose configuration <cfg>.
--clean-first

在构建目标之前，先执行clean操作。如果只想执行clean操作，使用--target clean。
--use-stderr

忽略本选项，在CMake >= 3.0情况下是缺省行为。
--verbose, -v

开启啰嗦模式（如果支持的话），包括执行构建命令时也开启啰嗦模式。

如果设置了VERBOSE环境变量或者CMAKE_VERBOSE_MAKEFILE缓存变量，就不再需要指定这个选项了。
--

传递后续的参数到原生工具。

不带任何参数运行cmake --build，可用来获取帮助。

安装项目

cmake提供以下格式的命令安装一个已完成的构建：

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

在执行完构建后，可以执行本操作执行安装。安装操作不会再使用构建系统和原生构建工具。可以使用的选项有：

--install <dir>

指定要安装的构建根目录。这个必须指定，而且必须写在前面。
--config <cfg>

For multi-configuration generators, choose configuration <cfg>.
--component <comp>

仅安装指定的组件。
--prefix <prefix>

使用指定的值作为安装目录，覆盖CMAKE_INSTALL_PREFIX的值。
--strip

在执行安装之前执行strip操作。
-v, --verbose

开启啰嗦模式。

如果设置了VERBOSE环境变量，就不再需要指定本选项了。

不带任何参数运行cmake --install，可以用来获取帮助。

打开项目

cmake --open <dir>

使用相关的应用程序打开已生成的项目。只有某些生成器支持这个操作。

运行脚本

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

执行一个CMake语言编写的脚本。不会执行任何配置或生成操作，缓存文件也不会被修改。如果需要指定-D选项，必须在-P之前指定。

运行内建命令

cmake提供以下格式的命令行来执行内建命令：

cmake -E <command> [<options>]

运行make -E或cmake -E help可查看命令列表。可以使用的命令有：

capabilities

以JSON格式报告CMake的能力，输出的JSON包含以下键：
- version
  
  一个包含版本信息的JSON对象，包含键：
  - string
    
    一个完整的版本信息，和通过cmake --version显示的一样。
  - major
    
    主版本号，一个整数。
  - minor
    
    副版本号，一个整数。
  - patch
    
    修订号，一个整数。
  - suffix
    
    cmake版本的后缀，字符串。
  - isDirty
    
    标识cmake是否从一个dirty tree构建的布尔值。
- generators
  
  一个可用生成器列表。每个生成器是一个JSON对象，包含以下键：
  - name
    
    生成器名称字符串。
  - toolsetSupport
    
    值为true如果生成器支持工具集，否则false。
  - platformSupport
    
    值为true如果生成器支持platforms，否则false。
  - extraGenerators
    
    能够兼容本生成器的其他生成器的列表。
- fileApi
  
  Optional member that is present when the cmake-file-api(7) is available. The value is a JSON object with one member:
  - requests
    
    A JSON array containing zero or more supported file-api requests. Each request is a JSON object with members:
    - kind
      
      Specifies one of the supported Object Kinds.
    - version
      
      A JSON array whose elements are each a JSON object containing major and minor members specifying non-negative integer version components.
- serverMode
  
  值为true如果cmake支持server-mode，否则false。
chdir <dir> <cmd> [<arg>...]

Change the current working directory and run a command.
compare_files [--ignore-eol] <file1> <file2>

比较文件。如果文件相同返回0，否则1。--ignore-eol选项指定在比较时忽略行LF/CRLF的区别。
copy <file>... <destination>

Copy files to <destination> (either file or directory). If multiple files are specified, the <destination> must be directory and it must exist. Wildcards are not supported. copy does follow symlinks. That means it does not copy symlinks, but the files or directories it point to.
copy_directory <dir>... <destination>

Copy content of <dir>... directories to <destination> directory. If <destination> directory does not exist it will be created. copy_directory does follow symlinks.
copy_if_different <file>... <destination>

Copy files to <destination> (either file or directory) if they have changed. If multiple files are specified, the <destination> must be directory and it must exist. copy_if_different does follow symlinks.

create_symlink <old> <new>

创建一个符号链接<new>，链接到<old>。

Note Path to where <new> symbolic link will be created has to exist beforehand.

echo [<string>...]

以文本方式输出参数。
echo_append [<\string>...]

以文本方式输出参数，但不另起一行。
env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...

Run command in a modified environment.
environment

打印当前环境变量。
false

什么也不执行，仅仅返回1。
make_directory <dir>...

创建目录<dir>，如果需要的话，同时创建父目录。如果目录已存在的话，它静静的不执行任何操作。

md5sum <file>...

计算文件的的MD5校验和，以md5sum兼容格式：

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

sha1sum <file>...

计算文件的的SHA1校验和，以sha1sum兼容格式：

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

sha224sum <file>...

Create SHA224 checksum of files in sha224sum compatible format:

b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

sha256sum <file>...

Create SHA256 checksum of files in sha256sum compatible format:

76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

sha384sum <file>...

Create SHA384 checksum of files in sha384sum compatible format:

acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d

sha512sum <file>...

Create SHA512 checksum of files in sha512sum compatible format:

2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

remove [-f] <file>...

Remove the file(s). If any of the listed files already do not exist, the command returns a non-zero exit code, but no message is logged. The -f option changes the behavior to return a zero exit code (i.e. success) in such situations instead. remove does not follow symlinks. That means it remove only symlinks and not files it point to.
remove_directory <dir>...

Remove <dir> directories and their contents. If a directory does not exist it will be silently ignored. If <dir> is a symlink to a directory, just the symlink will be removed.
rename <oldname> <newname>

Rename a file or directory (on one volume). If file with the <newname> name already exists, then it will be silently replaced.
server

Launch cmake-server(7) mode.
sleep <number>...

Sleep for given number of seconds.
tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]

Create or extract a tar or zip archive. Options are:
- c
  
  Create a new archive containing the specified files. If used, the <pathname>... argument is mandatory.
- x
  
  Extract to disk from the archive. The ``<pathname>...argument could be used to extract only selected files or directories. When extracting selected files or directories, you must provide their exact names including the path, as printed by list (-t`).
- t
  
  List archive contents. The <pathname>... argument could be used to list only selected files or directories.
- v
  
  Produce verbose output.
- z
  
  Compress the resulting archive with gzip.
- j
  
  Compress the resulting archive with bzip2.
- J
  
  Compress the resulting archive with XZ.
- --zstd
  
  Compress the resulting archive with Zstandard.
- --files-from=<file>
  
  Read file names from the given file, one per line. Blank lines are ignored. Lines may not start in - except for --add-file=<name> to add files whose names start in -.
- --format=<format>
  
  Specify the format of the archive to be created. Supported formats are: 7zip, gnutar, pax, paxr (restricted pax, default), and zip.
- --mtime=<date>
  
  Specify modification time recorded in tarball entries.
- --
  
  Stop interpreting options and treat all remaining arguments as file names, even if they start with -.
time <command> [<args>...]

运行命令并显示持续的时间。
touch <file>...

Creates <file> if file do not exist. If <file> exists, it is changing <file> access and modification times.
touch_nocreate <file>...

Touch a file if it exists but do not create it. If a file does not exist it will be silently ignored.
true

Do nothing, with an exit code of 0.

运行Find-Package工具

CMake为查找基于Makefile的项目提供了pkg-config风格的帮助工具：

cmake --find-package [<options>]

它使用find_package()搜索一个package，然后把结果打印到标准输出。它可以被用于代替pkg-config来查找已安装的基于Makefile或autoconf的库。

Note: 因为某些技术方面的原因，这个工具还没有支持得很好。为了兼容性考虑而保留了这个工具，但在新项目中不要使用它。

查看帮助

使用下面格式的命令打印CMake文档的指定内容：

cmake --help[-<topic>]

可使用以下的参数：

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

打印文档然后退出。

usage仅描述基本的命令行接口和参数。
--version,-version,/V [<f>]

打印cmake程序版本然后退出。

如果指定了一个文件，版本将写入这个文件。如果指定了<f>，帮助信息将写入其中。
--help-full [<f>]

打印全部帮助手册然后退出。

将会以文本形式打印。如果指定了<f>，帮助信息将写入其中。
--help-manual <man> [<f>]

打印指定的帮助手册然后退出。

指定的手册将会以文本形式打印。如果指定了<f>，帮助信息将写入其中。
--help-manual-list [<f>]

打印手册列表然后退出。

列出的手册可以用作--help-manual的选项。如果指定了<f>，帮助信息将写入其中。
--help-command <cmd> [<f>]

打印指定命令的帮助然后退出。

cmake-commands手册中的<cmd>部分将会以文本形式打印。如果指定了<f>，帮助信息将写入其中。
--help-command-list [<f>]

打印命令列表然后退出。

列出的命令可以用作--help-command的选项。如果指定了<f>，帮助信息将写入其中。
--help-commands [<f>]

打印cmake命令手册然后退出。

将会以文本形式打印cmake-commands手册。如果指定了<f>，帮助信息将写入其中。
--help-module <mod> [<f>]

打印指定模块的帮助信息然后退出。

cmake-modules手册中的<mod>部分将会以文本形式打印。如果指定了<f>，帮助信息将写入其中。
--help-module-list [<f>]

打印模块列表然后退出。

列出的模块可以用作--help-module的选项。如果指定了<f>，帮助信息将写入其中。
--help-modules [<f>]

打印cmake-modules手册然后退出。

将会以文本形式打印cmake-modules手册。如果指定了<f>，帮助信息将写入其中。
--help-policy <cmp> [<f>]

打印指定的policy帮助然后退出。

cmake-policies手册中的<cmp>将会以文本形式打印。如果指定了<f>，帮助信息将写入其中。
--help-policy-list [<f>]

List policies with help available and exit.

The list contains all policies for which help may be obtained by using the --help-policy option followed by a policy name. The help is printed to a named <f>ile if given.
--help-policies [<f>]

Print cmake-policies manual and exit.

The cmake-policies(7) manual is printed in a human-readable text format. The help is printed to a named <f>ile if given.
--help-property <prop> [<f>]

Print help for one property and exit.

The cmake-properties(7) manual entries for <prop> are printed in a human-readable text format. The help is printed to a named <f>ile if given.
--help-property-list [<f>]

List properties with help available and exit.

The list contains all properties for which help may be obtained by using the --help-property option followed by a property name. The help is printed to a named <f>ile if given.
--help-properties [<f>]

Print cmake-properties manual and exit.

The cmake-properties(7) manual is printed in a human-readable text format. The help is printed to a named <f>ile if given.
--help-variable <var> [<f>]

Print help for one variable and exit.

The cmake-variables(7) manual entry for <var> is printed in a human-readable text format. The help is printed to a named <f>ile if given.
--help-variable-list [<f>]

List variables with help available and exit.

The list contains all variables for which help may be obtained by using the --help-variable option followed by a variable name. The help is printed to a named <f>ile if given.
--help-variables [<f>]

Print cmake-variables manual and exit.

The cmake-variables(7) manual is printed in a human-readable text format. The help is printed to a named <f>ile if given.

参阅

在使用CMake的时候可通过以下资源获取帮助:

主页

https://cmake.org

CMake学习的重要起点。
在线文档和社区资源

https://cmake.org/documentation

在这个页面可以找到文档和社区资源。
论坛

https://discourse.cmake.org