CMake3.18官方教程：全面解析与实践指南

需积分: 10 43 浏览量更新于2024-07-15 收藏 883KB PDF 举报

"这是关于cmake 3.18版本的英文官方文档，涵盖了所有cmake命令的使用方法，包括Scripting Commands、Project Commands、CTest Commands和Deprecated Commands等部分，是学习和掌握cmake的权威资料。为了便于查阅，文档已整理成PDF格式，并添加了书签，有助于快速定位相关内容。" 在cmake中，了解和熟练运用各种命令是至关重要的，这些命令构成了cmake构建系统的基础。以下是对标题和描述中提到的一些关键知识点的详细说明： 1. **ScriptingCommands**：这些命令在任何情况下都可以使用，包括`break`、`cmake_language`、`cmake_minimum_required`、`cmake_parse_arguments`、`cmake_policy`等。例如，`cmake_minimum_required`用于设置cmake的最低版本要求，确保项目能在符合要求的cmake版本上构建。 2. **ProjectCommands**：这些命令只在CMake项目中可用，如`add_compile_definitions`、`add_executable`、`add_library`等。`add_compile_definitions`用于添加预处理器宏定义，`add_executable`用于创建可执行文件目标，而`add_library`则用于创建库目标。 3. **CTestCommands**：这部分涉及与测试相关的命令，如`add_test`，它允许你将测试集成到构建流程中，使用CTest框架进行自动化测试。 4. **DeprecatedCommands**：这些命令在较新版本的cmake中可能已经被废弃，但仍保留以保持向后兼容性。开发者应避免使用这些命令，转而使用推荐的替代选项。 5. **cmake_policy**：此命令用于管理cmake的行为策略，允许用户选择遵循较新的行为或者保持与旧版本的兼容。 6. **configure_file**：这个命令用于在配置阶段处理输入文件，可以替换文本模板中的变量，生成最终的输出文件。 7. **find_xxx**系列命令：如`find_file`、`find_library`、`find_path`和`find_package`等，它们用于搜索系统上的特定文件、库或软件包，以便在构建过程中正确链接依赖。 8. **include**：包含其他cmake脚本，使脚本模块化。 9. **target_xxx**系列命令：如`add_dependencies`、`add_link_options`等，用于管理构建目标间的依赖关系以及链接选项。 10. **set`和`get`命令：`set`用于设置变量的值，而`get`用于获取变量的值，是cmake中变量操作的核心。 11. **条件语句和循环语句**：`if`、`else`、`elseif`、`foreach`、`while`等用于构建复杂的逻辑控制流程。 12. **函数`和`macro`：定义可重用的代码块，`function`创建局部作用域的函数，`macro`则没有作用域限制。 13. **execute_process`：在cmake构建过程中执行外部命令。 14. **message`：用于在构建过程中打印信息，帮助调试。 15. **option`：创建用户可配置的项目选项。 16. **返回和跳转命令**：`return`用于结束当前的cmake脚本，`break`和`continue`用于控制循环结构。通过深入理解和熟练应用这些cmake命令，开发者能够构建出灵活、可维护的跨平台构建系统，有效管理项目依赖，优化编译过程，并确保代码正确地链接到相应的库和资源。这份cmake 3.18的官方文档是学习和参考的宝贵资料，无论是初学者还是经验丰富的cmake用户，都能从中受益。

List of post-exclude regexes through which to filter the names of resolved dependencies.

These arguments can be used to blacklist unwanted system libraries when resolving the dependencies, or to whitelist

libraries from a specific directory. The filtering works as follows:

1. If the not-yet-resolved dependency matches any of the PRE_INCLUDE_REGEXES, steps 2 and 3 are skipped, and the

dependency resolution proceeds to step 4.

2. If the not-yet-resolved dependency matches any of the PRE_EXCLUDE_REGEXES, dependency resolution stops for that

dependency.

3. Otherwise, dependency resolution proceeds.

4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency according to the linking rules of the platform

(see below).

5. If the dependency is found, and its full path matches one of the POST_INCLUDE_REGEXES, the full path is added to the

resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves that library’s own

dependencies. Otherwise, resolution proceeds to step 6.

6. If the dependency is found, but its full path matches one of the POST_EXCLUDE_REGEXES, it is not added to the

resolved dependencies, and dependency resolution stops for that dependency.

7. If the dependency is found, and its full path does not match either POST_INCLUDE_REGEXES or

POST_EXCLUDE_REGEXES, the full path is added to the resolved dependencies, and

file(GET_RUNTIME_DEPENDENCIES) recursively resolves that library’s own dependencies.

Different platforms have different rules for how dependencies are resolved. These specifics are described here.

On Linux platforms, library resolution works as follows:

1. If the depending file does not have any RUNPATH entries, and the library exists in one of the depending file’s RPATH

entries, or its parents’, in that order, the dependency is resolved to that file.

2. Otherwise, if the depending file has any RUNPATH entries, and the library exists in one of those entries, the

dependency is resolved to that file.

3. Otherwise, if the library exists in one of the directories listed by ldconfig, the dependency is resolved to that file.

4. Otherwise, if the library exists in one of the DIRECTORIES entries, the dependency is resolved to that file. In this case,

a warning is issued, because finding a file in one of the DIRECTORIES means that the depending file is not complete

(it does not list all the directories from which it pulls dependencies).

5. Otherwise, the dependency is unresolved.

On Windows platforms, library resolution works as follows:

1. The dependent DLL name is converted to lowercase. Windows DLL names are case-insensitive, and some linkers

mangle the case of the DLL dependency names. However, this makes it more difficult for PRE_INCLUDE_REGEXES,

PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and POST_EXCLUDE_REGEXES to properly filter DLL names -

every regex would have to check for both uppercase and lowercase letters. For example:

file(GET_RUNTIME_DEPENDENCIES

# ...

PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"

)

Converting the DLL name to lowercase allows the regexes to only match lowercase names, thus simplifying the

regex. For example:

file(GET_RUNTIME_DEPENDENCIES

# ...

PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"

)

This regex will match mylibrary.dll regardless of how it is cased, either on disk or in the depending file. (For

example, it will match mylibrary.dll, MyLibrary.dll, and MYLIBRARY.DLL.)

Please note that the directory portion of any resolved DLLs retains its casing and is not converted to lowercase. Only

the filename portion is converted.

2. (Not yet implemented) If the depending file is a Windows Store app, and the dependency is listed as a dependency

in the application’s package manifest, the dependency is resolved to that file.

3. Otherwise, if the library exists in the same directory as the depending file, the dependency is resolved to that file.

4. Otherwise, if the library exists in either the operating system’s system32 directory or the Windows directory, in that

order, the dependency is resolved to that file.

5. Otherwise, if the library exists in one of the directories specified by DIRECTORIES, in the order they are listed, the

dependency is resolved to that file. In this case, a warning is not issued, because searching other directories is a

normal part of Windows library resolution.

6. Otherwise, the dependency is unresolved.

On Apple platforms, library resolution works as follows:

1. If the dependency starts with @executable_path/, and an EXECUTABLES argument is in the process of being

resolved, and replacing @executable_path/ with the directory of the executable yields an existing file, the

dependency is resolved to that file.

2. Otherwise, if the dependency starts with @executable_path/, and there is a BUNDLE_EXECUTABLE argument, and

replacing @executable_path/ with the directory of the bundle executable yields an existing file, the dependency is

resolved to that file.

3. Otherwise, if the dependency starts with @loader_path/, and replacing @loader_path/ with the directory of the

depending file yields an existing file, the dependency is resolved to that file.

4. Otherwise, if the dependency starts with @rpath/, and replacing @rpath/ with one of the RPATH entries of the

depending file yields an existing file, the dependency is resolved to that file. Note that RPATH entries that start with

@executable_path/ or @loader_path/ also have these items replaced with the appropriate path.

5. Otherwise, if the dependency is an absolute file that exists, the dependency is resolved to that file.

6. Otherwise, the dependency is unresolved.

This function accepts several variables that determine which tool is used for dependency resolution:

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

Determines which operating system and executable format the files are built for. This could be one of several values:

linux+elf

windows+pe

macos+macho

If this variable is not specified, it is determined automatically by system introspection.

CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

Determines the tool to use for dependency resolution. It could be one of several values, depending on the value of

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

linux+elf objdump

windows+pe dumpbin

windows+pe objdump

macos+macho otool

If this variable is not specified, it is determined automatically by system introspection.

CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

Determines the path to the tool to use for dependency resolution. This is the actual path to objdump, dumpbin, or

otool.

If this variable is not specified, it is determined by the value of CMAKE_OBJDUMP if set, else by system introspection.

Writing

file(WRITE <filename> <content>...)

file(APPEND <filename> <content>...)

Write <content> into a file called <filename>. If the file does not exist, it will be created. If the file already exists, WRITE

mode will overwrite it and APPEND mode will append to the end. Any directories in the path specified by <filename> that

do not exist will be created.

If the file is a build input, use the configure_file() command to update the file only when its content changes.
file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])
Create a file with no content if it does not yet exist. If the file already exists, its access and/or modification will be updated to 
the time when the function call is executed.
Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file does not exist it will be silently ignored.
With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be modified.
file(GENERATE OUTPUT output-file
     <INPUT input-file|CONTENT content>
     [CONDITION expression])
Generate  an  output  file  for each  build  configuration  supported  by  the  current CMake  Generator.  Evaluate generator 
expressions from the input content to produce the output content. The options are:
CONDITION <condition>
Generate the output file for a particular configuration only if the condition is true. The condition must be either 0 or 1 
after evaluating generator expressions.
CONTENT <content>
Use the content given explicitly as input.
INPUT <input-file>
Use  the  content  from  a  given  file  as  input.  A  relative  path  is  treated  with  respect  to  the  value  of 
CMAKE_CURRENT_SOURCE_DIR. See policy CMP0070.
OUTPUT <output-file>
Specify the output file name to generate. Use generator expressions such as $<CONFIG> to specify a configuration-
specific output file name. Multiple configurations may generate the same output file only if the generated content is 
identical.  Otherwise, the <output-file> must evaluate to an unique name for each configuration. A relative path 
(after evaluating generator expressions) is treated with respect to the value of CMAKE_CURRENT_BINARY_DIR. See 
policy CMP0070.
Exactly one CONTENT or INPUT option must be given. A specific OUTPUT file may be named by at most one invocation of 
file(GENERATE).  Generated  files  are  modified  and  their  timestamp  updated  on  subsequent  cmake  runs  only  if  their 
content is changed.
Note also that file(GENERATE) does not create the output file until the generation phase. The output file will not yet have 
been  written  when  the file(GENERATE)  command  returns,  it  is  written  only  after  processing  all  of  a  project’s 
CMakeLists.txt files.
file(CONFIGURE OUTPUT output-file
     CONTENT content
     [ESCAPE_QUOTES] [@ONLY]
     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Generate an output file using the input given by CONTENT and substitute variable values referenced as @VAR@  or ${VAR} 
contained  therein.  The  substitution  rules  behave  the  same  as  the configure_file()  command.  In  order  to  match 
configure_file()’s behavior, generator expressions are not supported for both OUTPUT and CONTENT.
The arguments are:
OUTPUT <output-file>
Specify  the  output  file  name  to  generate.  A  relative  path  is  treated  with  respect  to  the  value  of 
CMAKE_CURRENT_BINARY_DIR. <output-file> does not support generator expressions.
CONTENT <content>
Use the content given explicitly as input. <content> does not support generator expressions.
ESCAPE_QUOTES
Escape any substituted quotes with backslashes (C-style).
@ONLY
Restrict variable replacement to references of the form @VAR@. This is useful for configuring scripts that use ${VAR} 

syntax.

NEWLINE_STYLE <style>

Specify the newline style for the output file. Specify UNIX or LF for \n newlines, or specify DOS, WIN32, or CRLF for

\r\n newlines.

Filesystem

file(GLOB <variable>

[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]

[<globbing-expressions>...])

file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]

[LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]

[<globbing-expressions>...])

Generate a list of files that match the <globbing-expressions> and store it into the <variable>. Globbing expressions

are similar to regular expressions, but much simpler. If RELATIVE flag is specified, the results will be returned as relative

paths to the given path. The results will be ordered lexicographically.

On Windows and macOS, globbing is case-insensitive even if the underlying filesystem is case-sensitive (both filenames

and globbing expressions are converted to lowercase before matching). On other platforms, globbing is case-sensitive.

If the CONFIGURE_DEPENDS flag is specified, CMake will add logic to the main build system check target to rerun the

flagged GLOB commands at build time. If any of the outputs change, CMake will regenerate the build system.

By default GLOB lists directories - directories are omitted in result if LIST_DIRECTORIES is set to false.

Note

We do not recommend using GLOB to collect a list of source files from your source tree. If no CMakeLists.txt file changes

when a source is added or removed then the generated build system cannot know when to ask CMake to regenerate. The

CONFIGURE_DEPENDS flag may not work reliably on all generators, or if a new generator is added in the future that cannot

support it, projects using it will be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a cost to perform the

check on every rebuild.

Examples of globbing expressions include:

*.cxx - match all files with extension cxx

*.vt? - match all files with extension vta,...,vtz

f[3-5].txt - match files f3.txt, f4.txt, f5.txt

The GLOB_RECURSE mode will traverse all the subdirectories of the matched directory and match the files. Subdirectories

that are symlinks are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009 is not set to NEW.

By default GLOB_RECURSE omits directories from result list - setting LIST_DIRECTORIES to true adds directories to result

list. If FOLLOW_SYMLINKS is given or policy CMP0009 is not set to NEW then LIST_DIRECTORIES treats symlinks as

directories.

Examples of recursive globbing include:

/dir/*.py - match all python files in /dir and subdirectories

file(RENAME <oldname> <newname>)

Move a file or directory within a filesystem from <oldname> to <newname>, replacing the destination atomically.

file(REMOVE [<files>...])

file(REMOVE_RECURSE [<files>...])

Remove the given files. The REMOVE_RECURSE mode will remove the given files and directories, also non-empty

directories. No error is emitted if a given file does not exist. Relative input paths are evaluated with respect to the current

source directory. Empty input paths are ignored with a warning.

file(MAKE_DIRECTORY [<directories>...])

Create the given directories and their parents as needed.

file(<COPY|INSTALL> <files>... DESTINATION <dir>

[FILE_PERMISSIONS <permissions>...]

[DIRECTORY_PERMISSIONS <permissions>...]

[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]

[FOLLOW_SYMLINK_CHAIN]

[FILES_MATCHING]

[[PATTERN <pattern> | REGEX <regex>]

[EXCLUDE] [PERMISSIONS <permissions>...]] [...])

The COPY signature copies files, directories, and symlinks to a destination folder. Relative input paths are evaluated with

respect to the current source directory, and a relative destination is evaluated with respect to the current build directory.

Copying preserves input file timestamps, and optimizes out a file if it exists at the destination with the same timestamp.

Copying preserves input permissions unless explicit permissions or NO_SOURCE_PERMISSIONS are given (default is

USE_SOURCE_PERMISSIONS).

If FOLLOW_SYMLINK_CHAIN is specified, COPY will recursively resolve the symlinks at the paths given until a real file is

found, and install a corresponding symlink in the destination for each symlink encountered. For each symlink that is

installed, the resolution is stripped of the directory, leaving only the filename, meaning that the new symlink points to a file in

the same directory as the symlink. This feature is useful on some Unix systems, where libraries are installed as a chain of

symlinks with version numbers, with less specific versions pointing to more specific versions. FOLLOW_SYMLINK_CHAIN will

install all of these symlinks and the library itself into the destination directory. For example, if you have the following directory

structure:

/opt/foo/lib/libfoo.so.1.2.3

/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3

/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2

/opt/foo/lib/libfoo.so -> libfoo.so.1

and you do:

file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

This will install all of the symlinks and libfoo.so.1.2.3 itself into lib.

See the install(DIRECTORY) command for documentation of permissions, FILES_MATCHING, PATTERN, REGEX, and

EXCLUDE options. Copying directories preserves the structure of their content even if options are used to select a subset of

files.

The INSTALL signature differs slightly from COPY: it prints status messages (subject to the CMAKE_INSTALL_MESSAGE

variable), and NO_SOURCE_PERMISSIONS is default. Installation scripts generated by the install() command use this

signature (with some undocumented options for internal use).

file(SIZE <filename> <variable>)

Determine the file size of the <filename> and put the result in <variable> variable. Requires that <filename> is a valid

path pointing to a file and is readable.

file(READ_SYMLINK <linkname> <variable>)

This subcommand queries the symlink <linkname> and stores the path it points to in the result <variable>. If

<linkname> does not exist or is not a symlink, CMake issues a fatal error.

Note that this command returns the raw symlink path and does not resolve a relative path. The following is an example of

how to ensure that an absolute path is obtained:

set(linkname "/path/to/foo.sym")

file(READ_SYMLINK "${linkname}" result)

if(NOT IS_ABSOLUTE "${result}")

get_filename_component(dir "${linkname}" DIRECTORY)

set(result "${dir}/${result}")

endif()

file(CREATE_LINK <original> <linkname>

[RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

Create a link <linkname> that points to <original>. It will be a hard link by default, but providing the SYMBOLIC option

results in a symbolic link instead. Hard links require that original exists and is a file, not a directory. If <linkname>

already exists, it will be overwritten.

The <result> variable, if specified, receives the status of the operation. It is set to 0 upon success or an error message

otherwise. If RESULT is not specified and the operation fails, a fatal error is emitted.

Specifying COPY_ON_ERROR enables copying the file as a fallback if creating the link fails. It can be useful for handling

situations such as <original> and <linkname> being on different drives or mount points, which would make them unable

to support a hard link.

剩余109页未读，继续阅读

qianqing13579

粉丝: 1000
资源: 86

CMake3.18官方教程：全面解析与实践指南

cmake实践 修订版 pdf

CMake实践PDF

CMake官方中文手册1

cmake参考手册_中文.pdf pan.baidu.com

安装cmake3.18 ubuntu

如何在Ubuntu系统中安装cmake 3.18以上的版本

cmake——入门到精通.pdf

CMake Error at CMakeLists.txt:5 (cmake_minimum_required): CMake 3.18 or higher is required. You are running version 3.16.3

cmake .和cmake ..的区别

hip_cmake_macros.h.in如何获取

最新资源

cmake实践修订版 pdf