Cmake开发手册详解

目录
一、CMake2.8.3 选项 ....................................................................................................... 4 用法 ....................................................................................................................................... 4 描述 ....................................................................................................................................... 5 选项 ....................................................................................................................................... 5 生成器 ................................................................................................................................. 10 二、CMake 命令 ................................................................................................................... 12 CMD#1 : add_custom_command ..................................................................................... 12

CMD#2: add_custom_target ............................................................................................... 14 CMD#3:add_definitions....................................................................................................... 15 CMD#4:add_dependencies ................................................................................................. 15 CMD#5:add_executable: ..................................................................................................... 16 CMD#6:add_library ............................................................................................................. 16 CMD#7:add_subdirectory ................................................................................................... 17 CMD#8:add_test.................................................................................................................. 18 CMD#9:aux_source_directory ............................................................................................. 19 CMD#10:break..................................................................................................................... 19 CMD#11:build_command ................................................................................................... 19 CMD#12:cmake_minimum_required .................................................................................. 20 CMD#13:cmake_policy ........................................................................................................ 20 CMD#14:configure_file: ...................................................................................................... 21 CMD#15:create_test_sourcelist: ......................................................................................... 22 CMD#16:define_property: .................................................................................................. 22 CMD#17: else ...................................................................................................................... 23 CMD#18: elseif .................................................................................................................... 23 CMD#19: enable_language ................................................................................................. 23 CMD#20: enable_testing ..................................................................................................... 23 CMD#21: endforeach .......................................................................................................... 24 CMD#22: endfunction ......................................................................................................... 24

CMD#23: endif..................................................................................................................... 24 CMD#24: endmacro ............................................................................................................ 24 CMD#25: endwhile .............................................................................................................. 24 CMD#26: execute_process .................................................................................................. 25 CMD#27:export ................................................................................................................... 25 CMD#28: file ........................................................................................................................ 26 CMD#29:find_file................................................................................................................. 28 CMD#30:find_library ........................................................................................................... 30 CMD#31:find_package ........................................................................................................ 33 CMD#32 : find_path ............................................................................................................ 38 CMD#33:find_program........................................................................................................ 40 CMD#34:fltk_wrap_ui ......................................................................................................... 42 CMD#35 : foreach................................................................................................................ 42 CMD#36 : function .............................................................................................................. 43 CMD#37 : get_cmake_property .......................................................................................... 43 CMD#38 : get_directory_property ...................................................................................... 44 CMD#39 : get_filename_component .................................................................................. 44 CMD#40 : get_property ....................................................................................................... 44 CMD#41 : get_source_file_property ................................................................................... 45 CMD#42 : get_target_property ........................................................................................... 45 CMD#43 : get_test_property .............................................................................................. 46 CMD#44 : if .......................................................................................................................... 46 CMD#45 : include ................................................................................................................ 49 CMD#46 : include_directories ............................................................................................. 50 CMD#47 : include_external_msproject............................................................................... 50 CMD#48 : include_regular_expression ............................................................................... 50 CMD#49 : install .................................................................................................................. 50 CMD#50 : link_directories 指定连接器查找库的路径。 ................................................. 55 CMD#51: list ........................................................................................................................ 55 CMD#52:load_cache......................................................................................................... 56

CMD#53:load_command.................................................................................................. 56 CMD#54:macro ................................................................................................................. 57 CMD#55:mark_as_advanced............................................................................................ 57 CMD#56:math .................................................................................................................. 57 CMD#57:message ............................................................................................................. 58 CMD#58: option .................................................................................................................. 58 CMD#59: output_required_files ......................................................................................... 58 CMD#60: project ................................................................................................................. 58 CMD#61: qt_wrap_cpp ....................................................................................................... 59 CMD#62: qt_wrap_ui .......................................................................................................... 59 CMD#63: remove_definitions ............................................................................................. 59 CMD#64: return................................................................................................................... 59 CMD#65: separate_arguments ........................................................................................... 60 CMD#66: set ........................................................................................................................ 60 CMD#67: set_directory_properties..................................................................................... 61 CMD#68: set_property ........................................................................................................ 61 CMD#69: set_source_files_properties ................................................................................ 62 CMD#70: set_target_properties ......................................................................................... 62 CMD#71: set_tests_properties ........................................................................................... 64 CMD#72: site_name ............................................................................................................ 64 CMD#73: source_group....................................................................................................... 64 CMD#74: string .................................................................................................................... 64 CMD#75: target_link_libraries ............................................................................................ 66 CMD#76: try_compile.......................................................................................................... 67 CMD#77: try_run ................................................................................................................. 68 CMD#78 unset ..................................................................................................................... 69 CMD#79 : variable_watch ................................................................................................... 69 CMD#80: while .................................................................................................................... 69

公司的一个项目使用 CMake 作为跨平台构建工具;业务有需求,当然要好好研读一下官方的 技术手册。目前的计划是先把官方手册翻译一下,了解清楚 CMake 中的各种命令、属性和变量 的用法。同时在工作中也会阅读 CMake 的真实源码,后续会基于此陆续写一些工程中使用 CMake 的心得。 CMake 的版本也在不停更新, 有些新的命令和变量会随着版本更新添加进来, 这是后事了,暂且不管;现在锁定 CMake 2.8.3 作为手册翻译的版本。 作为园子里的新丁,文章在术语和表达等等方面会有欠缺的地方,还请大侠们慷慨指点。 另外,罗马不是一天建成的,长长的手册翻译完也不知道要经历多少日升月落;不过还是希望自 己能够坚持下去:-)。

一、CMake2.8.3
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ?

选项

命令名称 用法 描述 命令选项 生成器 命令 属性 全局域属性 目录属性 目标属性 测试属性 源代码属性 Cache Entries 属性 兼容性命令 CMake 标准模块 CMake 策略 变量 改变行为的变量 描述系统的变量 语言变量 控制构建的变量 提供信息的变量 版权 其他参考资料

命令名称 cmake - 跨平台 Makefile 生成工具。 用法
cmake [选项] <源码路径>

cmake [选项] <现有构建路径>

描述
cmake 可执行程序是 CMake 的命令行界面。它可以用脚本对工程进行配置。工程配 置设置可以在命令行中使用-D 选项指定。 使用-i 选项, cmake 将通过提示交互式地完成该 设置。 CMake 是一个跨平台的构建系统生成工具。它使用平台无关的 CMake 清单文件 CMakeLists.txt,指定工程的构建过程;源码树的每个路径下都有这个文件。CMake 产生 一个适用于具体平台的构建系统,用户使用这个系统构建自己的工程。

选项

-C <initial-cache>: 预加载一个脚本填充缓存文件。
当 cmake 在一个空的构建树上第一次运行时,它会创建一个 CMakeCache.txt 文件,然 后向其中写入可定制的项目设置数据。-C 选项可以用来指定一个文件,在第一次解析这个工程 的 cmake 清单文件时,从这个文件加载缓存的条目(cache entries)信息。被加载的缓存条目 比项目默认的值有更高的优先权。参数中给定的那个文件应该是一个 CMake 脚本,其中包含有 使用 CACHE 选项的 SET 命令;而不是一个缓存格式的文件。

-D <var>:<type>=<value>: 创建一个 CMake 的缓存条目。
当 cmake 第一次运行于一个空的构建数时,它会创建一个 CMakeCache.txt 文件, 并且使用可定制的工程设置来填充这个文件。 这个选项可以用来指定优先级高于工程的默认 值的工程设置值。这个参数可以被重复多次,用来填充所需要数量的缓存条目(cache entries)。

-U <globbing_expr>: 从 CMake 的缓存文件中删除一条匹配的条目。
该选项可以用来删除 CMakeCache.txt 文件中的一或多个变量。文件名匹配表达式 (globbing expression)支持通配符*和?的使用。该选项可以重复多次以删除期望数量的缓存 条目。使用它时要小心,你可能因此让自己的 CMakeCache.txt 罢工。

-G <generator-name>: 指定一个 makefile 生成工具。
在具体的平台上,CMake 可以支持多个原生的构建系统。makefile 生成工具的职责是生 成特定的构建系统。可能的生成工具的名称将在生成工具一节给出。

-Wno-dev: 抑制开发者警告。
抑制那些为 CMakeLists.txt 文件的作者准备的警告信息。

-Wdev: 使能开发者警告信息输出功能。
允许那些为 CMakeLists.txt 文件的作者准备的警告信息。

-E: CMake 命令行模式。
为了真正做到与平台无关,CMake 提供了一系列可以用于所有系统上的的命令。以-E 参数 运行 CMake 会帮助你获得这些命令的用法。可以使用的命令有:chdir, copy, copy_if_different copy_directory, compare_files, echo, echo_append, environment,

make_directory, md5sum, remove_directory, remove, tar, time, touch, touch_nocreate, write_regv, delete_regv, comspec, create_symlink 。

-i: 以向导模式运行 CMake。
向导模式是在没有 GUI 时,交互式地运行 cmake 的模式。cmake 会弹出一系列的提示, 要求用户回答关于工程配置的一行问题。这些答复会被用来设置 cmake 的缓存值。

-L[A][H]: 列出缓存的变量中的非高级的变量。 -L 选项会列出缓存变量会运行 CMake,并列出所有 CMake 的内有被标记为 INTERNAL
或者 ADVANCED 的缓存变量。这会显示当前的 CMake 配置信息,然后你可以用-D 选项改变 这些选项。修改一些变量可能会引起更多的变量被创建出来。如果指定了 A 选项,那么命令也 会显示高级变量。如果指定了 H 选项,那么命令会显示每个变量的帮助信息。

--build <dir>: 构建由 CMake 生成的工程的二进制树。(这个选项的含义我不是很清楚—
译注) 该选项用以下的选项概括了内置构建工具的命令行界面

<dir> = 待创建的工程二进制路径。 --target <tgt> = 构建<tgt>,而不是默认目标。 --config <cfg> = 对于多重配置工具,选择配置<cfg>。 --clean-first = 首先构建目标的 clean 伪目标,然后再构建。 (如果仅仅要 clean 掉, 使用--target 'clean'选项。 ) -= 向内置工具(native tools)传递剩余的选项。

运行不带选项的 cmake --build 来获取快速帮助信息。

-N: 查看模式。
仅仅加载缓存信息,并不实际运行配置和生成步骤。

-P <file>: 处理脚本模式。
将给定的 cmake 文件按照 CMake 语言编写的脚本进行处理。不执行配置和生成步骤, 不修改缓存信息。如果要使用-D 选项定义变量,-D 选项必须在-P 选项之前。

--graphviz=[file]: 生成依赖的 graphviz 图。
生成一个 graphviz 软件的输入文件,其中包括了项目中所有库和可执行文件之间的依 赖关系。

--system-information [file]: 输出与该系统相关的信息。

输出范围比较广的、与当前使用的系统有关的信息。如果在一个 CMake 工程的二进制 构建树的顶端运行该命令,它还会打印一些附加信息,例如缓存,日志文件等等。

--debug-trycompile: 不删除“尝试编译”路径。
不删除那些为 try_compile 调用生成的路径。这在调试失败的 try_compile 文件时比 较有用。不过,因为上一次“尝试编译”生成的旧的垃圾输出文件也许会导致一次不正确 通过/不通过,且该结果与上次测试的结果不同,所以该选项可能会改变“尝试编译”的结 果。对于某一次“尝试编译”,该选项最好只用一次;并且仅仅在调试时使用。

--debug-output: 将 cmake 设置为调试模式。
在 cmake 运行时,打印额外的信息;比如使用 message(send_error)调用得到的栈 跟踪信息。

--trace: 将 cmake 设置为跟踪模式。
用 message(send_error )调用,打印所有调用生成的跟踪信息,以及这些调用发生的 位置。(这句话含义不是很确定—译注。)

--help-command cmd [file]: 打印单个命令 cmd 的帮助信息,然后退出。
显示给定的命令的完整的文档。如果指定了[file]参数,该文档会写入该文件,其输出格 式由该文件的后缀名确定。支持的文件类型有:man page,HTML,DocBook 以及纯 文本。

--help-command-list [file]: 列出所有可用命令的清单,然后退出。
该选项列出的信息含有所有命令的名字;其中,每个命令的帮助信息可以使用 --help-command 选项后跟一个命令名字得到。如果指定了[file]参数,帮助信息会写 到 file 中,输出格式依赖于文件名后缀。支持的文件格式包括:man page,HTML, DocBook 以及纯文本。

--help-commands [file]: 打印所有命令的帮助文件,然后退出。
显示所有当前版本的命令的完整文档。如果指定了[file]参数,帮助信息会写到 file 中, 输出格式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以 及纯文本。

--help-compatcommands [file]: 打印兼容性命令 (过时的命令—译注) 的帮助信息。
显示所有关于兼容性命令的完整文档。如果指定了[file]参数,帮助信息会写到 file 中, 输出格式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以 及纯文本。

--help-module module [file]: 打印某单一模块的帮助信息,然后退出。

打印关于给定模块的完整信息。如果指定了[file]参数,帮助信息会写到 file 中,且输出 格式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以及纯 文本。

--help-module-list [file]: 列出所有可用模块名,然后退出。
列出的清单包括所有模块的名字;其中,每个模块的帮助信息可以使用--help-module 选项,后跟模块名的方式得到。如果指定了[file]参数,帮助信息会写到 file 中,且输出 格式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以及纯 文本。

--help-modules [file]: 打印所有模块的帮助信息,然后退出。
显示关于所有模块的完整文档。如果指定了[file]参数,帮助信息会写到 file 中,且输出 格式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以及纯 文本。

--help-custom-modules [file]: 打印所有自定义模块名,然后退出。
显示所有自定义模块的完整文档。如果指定了[file]参数,帮助信息会写到 file 中,且输 出格式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以及 纯文本。

--help-policy cmp [file]: 打印单个策略的帮助信息,然后退出。
显示给定的策略的完整文档。如果指定了[file]参数,帮助信息会写到 file 中,且输出格 式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以及纯文 本。

--help-policies [file]: 打印所有策略的帮助信息,然后退出。
显示所有策略的完整文档。如果指定了[file]参数,帮助信息会写到 file 中,且输出格式 依赖于文件名后缀。 支持的文件格式包括: man page, HTML, DocBook 以及纯文本。

--help-property prop [file]: 打印单个属性的帮助信息,然后退出。
显示指定属性的完整文档。如果指定了[file]参数,帮助信息会写到 file 中,且输出格式 依赖于文件名后缀。 支持的文件格式包括: man page, HTML, DocBook 以及纯文本。

--help-property-list [file]: 列出所有可用的属性,然后退出。
该命令列出的清单包括所有属性的名字;其中,每个属性的帮助信息都可以通过 --help-property 选项后跟一个属性名的方式获得。如果指定了[file]参数,帮助信息会 写到 file 中, 且输出格式依赖于文件名后缀。 支持的文件格式包括: man page, HTML, DocBook 以及纯文本。

--help-properties [file]: 打印所有属性的帮助信息,然后退出。
显示所有属性的完整文档。如果指定了[file]参数,帮助信息会写到 file 中,且输出格式 依赖于文件名后缀。 支持的文件格式包括: man page, HTML, DocBook 以及纯文本。

--help-variable var [file]: 打印单个变量的帮助信息,然后退出。
显示指定变量的完整文档。如果指定了[file]参数,帮助信息会写到 file 中,且输出格式 依赖于文件名后缀。 支持的文件格式包括: man page, HTML, DocBook 以及纯文本。

--help-variable-list [file]: 列出文档中有记录的变量,然后退出。
该命令列出的清单包括所有变量的名字;其中,每个变量的帮助信息都可以通过 --help-variable 选项后跟一个变量名的方式获得。如果指定了[file]参数,帮助信息会 写到 file 中, 且输出格式依赖于文件名后缀。 支持的文件格式包括: man page, HTML, DocBook 以及纯文本。

--help-variables [file]: 打印所有变量的帮助信息,然后退出。
显示所有变量的完整帮助文档。如果指定了[file]参数,帮助信息会写到 file 中,且输出 格式依赖于文件名后缀。支持的文件格式包括:man page,HTML,DocBook 以及纯 文本。

--copyright [file]: 打印 CMake 的版权信息,然后退出。
如果指定了[file]参数,版权信息会写到这个文件中。

--help: 打印用法信息,然后退出。
用法信息描述了基本的命令行界面及其选项。

--help-full [file]: 打印完整的帮助信息,然后退出。
显示大多数 UNIX man page 提供的帮助信息。该选项是为非 UNIX 平台提供的;但是 如果 man 手册页没有安装,它也能提供便利。如果制定了[file]参数,帮助信息会写到 这个文件中。

--help-html [file]: 以 HTML 格式打印完整的帮助信息,然后退出。
CMake 的作者使用该选来帮助生成 web 页面。如果指定了[file]参数,帮助信息会写到 这个文件中。

--help-man [file]: 以 UNIX 的 man 手册页格式打印完整的帮助信息,然后退出。
cmake 使用该选生成 UNIX 的 man 手册页。如果指定了[file]参数,帮助信息会写到 这个文件中。

--version [file]: 显示程序名/版本信息行,然后退出。
如果指定了[file]参数,版本信息会写到这个文件中。 ================================================== ========= 对于 CMake 的语言要素,比如命令,属性和变量,帮助命令选项也是很有规律的,一般是用 --help-xxx-list 查看所有值的名字,找出感兴趣的项,然后用--help-xxx name 查看该名字 的详细信息;也可以用--help-xxxs 获得相关语言要素的完整帮助信息。

生成器

生成器这一节确实没有很多料,纯粹的流水账;不过为了完整,也还是给它一点篇幅吧。下 一章将开始我们真正的主题:-) ================================================ =
在 CMake 2.8.3 平台上,CMake 支持下列生成器:

Borland Makefiles: 生成 Borland makefile。 MSYS Makefiles: 生成 MSYS makefile。
生成的 makefile 用 use /bin/sh 作为它的 shell。在运行 CMake 的机器上需要安装 msys。

MinGW Makefiles: 生成供 mingw32-make 使用的 make file。
生成的 makefile 使用 cmd.exe 作为它的 shell。 生成它们不需要 msys 或者 unix shell。

NMake Makefiles: 生成 NMake makefile。 NMake Makefiles JOM: 生成 JOM makefile。 Unix Makefiles: 生成标准的 UNIX makefile。
在构建树上生成分层的 UNIX makefile。任何标准的 UNIX 风格的 make 程序都可以 通过默认的 make 目标构建工程。生成的 makefile 也提供了 install 目标。

Visual Studio 10: 生成 Visual Studio 10 工程文件。 Visual Studio 10 Win64: 生成 Visual Studio 10 Win64 工程文件。

Visual Studio 6: 生成 Visual Studio 6 工程文件。 Visual Studio 7: 生成 Visual Studio .NET 2002 工程文件。 Visual Studio 7 .NET 2003: 生成 Visual Studio .NET 2003 工程文件。 Visual Studio 8 2005: 生成 Visual Studio .NET 2005 工程文件。 Visual Studio 8 2005 Win64: 生成 Visual Studio .NET 2005 Win64 工程文件。 Visual Studio 9 2008: 生成 Visual Studio 9 2008 工程文件。 Visual Studio 9 2008 Win64: 生成 Visual Studio 9 2008 Win64 工程文件。 Watcom WMake: 生成 Watcom WMake makefiles。 CodeBlocks - MinGW Makefiles: 生成 CodeBlock 工程文件。
在顶层目录以及每层子目录下为 CodeBlocks 生成工程文件,生成的 CMakeList.txt 的特点是都包含一个 PROJECT()调用。除此之外还会在构建树上生成一套层次性的 makefile。通过默认的 make 目标,正确的 make 程序可以构建这个工程。makefile 还提供了 install 目标。

CodeBlocks - NMake Makefiles: 生成 CodeBlocks 工程文件。
在顶层目录以及每层子目录下为 CodeBlocks 生成工程文件,生成的 CMakeList.txt 的特点是都包含一个 PROJECT()调用。除此之外还会在构建树上生成一套层次性的 makefile。通过默认的 make 目标,正确的 make 程序可以构建这个工程。makefile 还提供了 install 目标。

CodeBlocks - Unix Makefiles: 生成 CodeBlocks 工程文件。
在顶层目录以及每层子目录下为 CodeBlocks 生成工程文件,生成的 CMakeList.txt 的特点是都包含一个 PROJECT()调用。除此之外还会在构建树上生成一套层次性的 makefile。通过默认的 make 目标,正确的 make 程序可以构建这个工程。makefile 还提供了 install 目标。

Eclipse CDT4 - MinGW Makefiles: 生成 Eclipse CDT 4.0 工程文件。
在顶层目录下为 Eclipse 生成工程文件。在运行源码外构建时,一个连接到顶层源码路 径的资源文件会被创建。除此之外还会在构建树上生成一套层次性的 makefile。通过默 认的 make 目标,正确的 make 程序可以构建这个工程。makefile 还提供了 install 目标。

Eclipse CDT4 - NMake Makefiles: 生成 Eclipse CDT 4.0 工程文件。

在顶层目录下为 Eclipse 生成工程文件。在运行源码外构建时,一个连接到顶层源码路 径的资源文件会被创建。除此之外还会在构建树上生成一套层次性的 makefile。通过默 认的 make 目标,正确的 make 程序可以构建这个工程。makefile 还提供了 install 目标。

Eclipse CDT4 - Unix Makefiles: 生成 Eclipse CDT 4.0 工程文件。
在顶层目录下为 Eclipse 生成工程文件。在运行源码外构建时,一个连接到顶层源码路 径的资源文件会被创建。除此之外还会在构建树上生成一套层次性的 makefile。通过默 认的 make 目标,正确的 make 程序可以构建这个工程。makefile 还提供了 install 目标。

二、CMake 命令

CMake 手册的客套话总算说完了,开始进入正题。第一部分是 CMake 命令。命令就相当于命 令行下操作系统提供的各种命令,重要性不言而喻;可以说,这些命令是 CMake 构建系统的骨 架。 CMake 2.8.3 共有 80 条命令, 分别是: add_custom_command, add_custom_target, add_definitions, add_dependencies, add_executable, add_library, add_subdirectory, add_test, aux_source_directory, break, build_command, cmake_minimum_required, cmake_policy, configure_file, create_test_sourcelist, define_property, else, elseif, enable_language, enable_testing, endforeach, endfunction, endif, endmacro, endwhile, execute_process, export, file, find_file, find_library, find_package, find_path, find_program, fltk_wrap_ui, foreach, function, get_cmake_property, get_directory_property, get_filename_component, get_property, get_source_file_property, get_target_property, get_test_property, if, include, include_directories, include_external_msproject, include_regular_expression, install, link_directories, list, load_cache, load_command, macro, mark_as_advanced, math, message, option, output_required_files, project, qt_wrap_cpp, qt_wrap_ui, remove_definitions, return, separate_arguments, set, set_directory_properties, set_property, set_source_files_properties, set_target_properties, set_tests_properties, site_name, source_group, string, target_link_libraries, try_compile, try_run, unset, variable_watch, while。这些命令在手册中是字典序排列的;为了便于查找,翻译也按照字典 序来组织。但是在翻译结束后,会对命令进行小结,与大家讨论一下这些命令的使用方法和使用 时机。 ================================================== ================

CMD#1

:

add_custom_command

为生成的构建系统添加一条自定义的构建规则。

add_custom_command 命令有两种主要的功能;第一种是为了生成输出文件,添加
一条自定义命令。 add_custom_command(OUTPUT output1 [output2 ...] COMMAND command1 [ARGS] [args1...] [COMMAND command2 [ARGS] [args2...] ...] [MAIN_DEPENDENCY depend] [DEPENDS [depends...]] [IMPLICIT_DEPENDS <lang1> depend1 ...] [WORKING_DIRECTORY dir] [COMMENT comment] [VERBATIM] [APPEND]) 这种命令格式定义了一条生成指定的文件(文件组)的生成命令。在相同路径下创建的目标 (CMakeLists.txt 文件) ——任何自定义命令的输出都作为它的源文件——被设置了一条规则: 在构建的时候,使用指定的命令来生成这些文件。如果一个输出文件名是相对路径,它将被解释 成相对于构建树路径的相对路径, 并且与当前源码路径是对应的。 注意, MAIN_DEPENDENCY 完全是可选的, 它用来向 visual studio 建议在何处停止自定义命令。 对于各种类型的 makefile 而言,这条命令创建了一个格式如下的新目标: OUTPUT: MAIN_DEPENDENCY DEPENDS COMMAND 如果指定了多于一条的命令,它们会按顺序执行。ARGS 参数是可选的,它的存在是为了 保持向后兼容,以后会被忽略掉。 第二种格式为一个目标——比如一个库文件或者可执行文件——添加一条自定义命令。 这种 格式可以用于目标构建前或构建后的一些操作。 这条命令会成为目标的一部分, 并且只有目标被 构建时才会执行。如果目标已经构建了,该目标将不会执行。 add_custom_command(TARGET target PRE_BUILD | PRE_LINK | POST_BUILD COMMAND command1 [ARGS] [args1...] [COMMAND command2 [ARGS] [args2...] ...] [WORKING_DIRECTORY dir] [COMMENT comment] [VERBATIM]) 这条命令定义了一个与指定目标的构建过程相关的新命令。 新命令在何时执行, 由下述的选 项决定: PRE_BUILD PRE_LINK - 在所有其它的依赖之前执行; - 在所有其它的依赖之后执行;

POST_BUILD - 在目标被构建之后执行; 注意,只有 Visual Studio 7 或更高的版本才支持 PRE_BUILD。对于其他的生成器, PRE_BUILD 会被当做 PRE_LINK 来对待。 如果指定了 WORKING_DIRECTORY 选项,这条命令会在给定的路径下执行。如果设置 了 COMMENT 选项,后跟的参数会在构建时、以构建信息的形式、在命令执行之前显示出来。

如果指定了 APPEND 选项,COMMAND 以及 DEPENDS 选项的值会附加到第一个输出文件的 自定义命令上。在此之前,必须有一次以相同的输出文件作为参数的对该命令的调用。在当前版 本下,如果指定了 APPEND 选项,COMMENT, WORKING_DIRECTORY 和 MAIN_DEPENDENCY 选项会被忽略掉,不过未来有可能会用到。 如果指定了 VERBATIM 选项,所有该命令的参数将会合适地被转义,以便构建工具能够以 原汁原味的参数去调用那些构建命令。注意,在 add_custom_command 能看到这些参数之 前,CMake 语言处理器会对这些参数做一层转义处理。推荐使用 VERBATIM 参数,因为它能 够保证正确的行为。当 VERBATIM 未指定时,CMake 的行为依赖于平台,因为 CMake 没有 针对某一种工具的特殊字符采取保护措施。 如果自定义命令的输出并不是实际的磁盘文件,应该使用 SET_SOURCE_FILES_PROPERTIES 命令将该输出的属性标记为 SYMBOLIC。 IMPLICIT_DEPENDS 选项请求扫描一个输入文件的隐含依赖关系。给定的语言参数(文 中的 lang1—译注)指定了应该使用哪种编程语言的依赖扫描器。目前为止,仅支持 C 和 CXX 语言扫描器。扫描中发现的依赖文件将会在编译时添加到自定义命令中。注意, IMPLICIT_DEPENDS 选项目前仅仅直至 Makefile 生成器,其它的生成器会忽略之。 如果 COMMAND 选项指定了一个可执行目标 (由 ADD_EXECUTABLE 命令创建的目标) , 在构建时,它会自动被可执行文件的位置所替换。而且,一个目标级的依赖性将会被添加进去, 这样这个可执行目标将会在所有依赖于该自定义命令的结果的目标之前被构建。 不过, 任何时候 重编译这个可执行文件,这种特性并不会引入一个会引起自定义命令重新运行的文件级依赖。 DEPENDS 选项指定了该命令依赖的文件。如果依赖的对象是同一目录(CMakeLists.txt 文件)下另外一个自定义命令的输出,CMake 会自动将其它自定义命令带到这个命令中来。如 果 DEPENDS 指定了任何类型的目标(由 ADD_*命令创建),一个目标级的依赖性将会被创 建, 以保证该目标在任何其它目标使用这个自定义命令的输出之前, 该目标已经被创建了。 而且, 如果该目标是可执行文件或库文件, 一个文件级依赖将会被创建, 用来引发自定义命令在目标被 重编译时的重新运行。 ================================================== ===== 在 Unix Makefile 中,这条命令相当于增加了一个依赖关系和一条显式生成命令。

CMD#2: add_custom_target
添加一个目标,它没有输出;这样它就总是会被构建。 add_custom_target(Name [ALL] [command1 [args1...]] [COMMAND command2 [args2...] ...] [DEPENDS depend depend depend ... ] [WORKING_DIRECTORY dir] [COMMENT comment] [VERBATIM] [SOURCES src1 [src2...]])

用 Name 选项给定的名字添加一个目标,这个目标会引发给定的那些命令。这个目标没有 输出文件,并且总是被认为是过时的,即使那些命令试图去创建一个与该目标同名的文件。使用 ADD_CUSTOM_COMMAND 命令可以生成一个带有依赖性的文件。默认情况下,没有目标会 依赖于自定义目标。使用 ADD_DEPENDENCIES 命令可以添加依赖于该目标或者被该目标依 赖的目标。如果指定了 ALL 选项,这表明这个目标应该被添加到默认的构建目标中,这样它每 次都会被构建(命令的名字不能是 ALL)。命令和选项是可选的;如果它们没有被指定,将会 产生一个空目标。如果设定了 WORKING_DIRECTORY 参数,该命令会在它指定的路径下执 行。如果指定了 COMMENT 选项,后跟的参数将会在构件的时候,在命令执行之前,被显示出 来。DEPENDS 选项后面列出来的依赖目标可以引用 add_custom_command 命令在相同路 径下(CMakeLists.txt)生成的输出和文件。 如果指定了 VERBATIM 选项,所有传递到该命令的选项将会被合适地转义;这样,该命令 调用的构建工具会接收到未经改变的参数。 注意, CMake 语言处理器会在 add_custom_target 命令在看到这些参数之前对它们进行一层转义。推荐使用该参数,因为它保证了正确的行为。当 未指定该参数时,转义的行为依赖于平台,因为 CMake 没有针对于特定工具中特殊字符的保护 措施。 SOURCES 选项指定了会被包含到自定义目标中的附加的源文件。指定的源文件将会被添 加到 IDE 的工程文件中,方便在没有构建规则的情况下能够编辑。

CMD#3:add_definitions
为源文件的编译添加由-D 引入的 define flag。

add_definitions(-DFOO -DBAR ...)
在编译器的命令行上,为当前路径以及下层路径的源文件加入一些 define flag。这个命令 可以用来引入任何 flag,但是它的原意是用来引入预处理器的定义。那些以-D 或/D 开头的、 看起来像预处理器定义的 flag,会被自动加到当前路径的 COMPILE_DEFINITIONS 属性中。 为了后向兼容, 非简单值 (non-trival, 指的是什么?——译注) 的定义会被留在 flags 组 (flags set)里,而不会被转换。关于在特定的域以及配置中增加预处理器的定义,参考路径、目标以 及源文件的 COMPILE_DEFINITIONS 属性来获取更多的细节。

CMD#4:add_dependencies
为顶层目标引入一个依赖关系。

add_dependencies(target-name depend-target1 depend-target2 ...)
让一个顶层目标依赖于其他的顶层目标。一个顶层目标是由命令 ADD_EXECUTABLE, ADD_LIBRARY,或者 ADD_CUSTOM_TARGET 产生的目标。为这些命令的输出引入依赖性 可以保证某个目标在其他的目标之前被构建。查看 ADD_CUSTOM_TARGET 和 ADD_CUSTOM_COMMAND 命令的 DEPENDS 选项, 可以了解如何根据自定义规则引入文件 级的依赖性。查看 SET_SOURCE_FILES_PROPERTIES 命令的 OBJECT_DEPENDS 选项, 可以了解如何为目标文件引入文件级的依赖性。

CMD#5:add_executable:
使用给定的源文件,为工程引入一个可执行文件。

add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] source1 source2 ... sourceN)
引入一个名为<name>的可执行目标,该目标会由调用该命令时在源文件列表中指定的源 文件来构建。<name>对应于逻辑目标名字,并且在工程范围内必须是全局唯一的。被构建的 可执行目标的实际文件名将根据具体的本地平台创建出来(比如<name>.exe 或者仅仅是 <name>)。 默认情况下, 可执行文件将会在构建树的路径下被创建, 对应于该命令被调用的源文件树的 路径。如果要改变这个位置,查看 RUNTIME_OUTPUT_DIRECTORY 目标属性的相关文档。 如果要改变最终文件名的<name>部分,查看 OUTPUT_NAME 目标属性的相关文档。 如果指定了 MACOSX_BUNDLE 选项,对应的属性会附加在创建的目标上。查看 MACOSX_BUNDLE 目标属性的文档可以找到更多的细节。 如果指定了 EXCLUDE_FROM_ALL 选项,对应的属性将会设置在被创建的目标上。查看 EXCLUDE_FROM_ALL 目标属性的文档可以找到更多的细节。 使用下述格式, add_executable 命令也可以用来创建导入的 (IMPORTED) 可执行目标:

add_executable(<name> IMPORTED)
一个导入的可执行目标引用了一个位于工程之外的可执行文件。该格式不会生成构建这个 目标的规则。 该目标名字的作用域在它被创建的路径以及底层路径有效。 它可以像在该工程内的 其他任意目标一样被引用。导入可执行文件为类似于 add_custom_command 之类的命令引 用它提供了便利。 关于导入的可执行文件的细节可以通过设置以 IMPORTED_开头的属性来指定。这类属性 中最重要的是 IMPORTED_LOCATION(以及它对应于具体配置的版本 IMPORTED_LOCATION_<CONFIG>);该属性指定了执行文件主文件在磁盘上的位置。查

看 IMPORTED_*属性的文档来获得更多信息。 CMD#6:add_library
使用指定的源文件向工程中添加一个库。

add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] source1 source2 ... sourceN)
添加一个名为<name>的库文件,该库文件将会根据调用的命令里列出的源文件来创建。 <name>对应于逻辑目标名称,而且在一个工程的全局域内必须是唯一的。待构建的库文件的

实际文件名根据对应平台的命名约定来构造(比如 lib<name>.a 或者<name>.lib)。指定 STATIC,SHARED,或者 MODULE 参数用来指定要创建的库的类型。STATIC 库是目标文件 的归档文件,在链接其它目标的时候使用。SHARED 库会被动态链接,在运行时被加载。 MODULE 库是不会被链接到其它目标中的插件,但是可能会在运行时使用 dlopen-系列的函数 动态链接。如果没有类型被显式指定,这个选项将会根据变量 BUILD_SHARED_LIBS 的当前 值是否为真决定是 STATIC 还是 SHARED。 默认状态下, 库文件将会在于源文件目录树的构建目录树的位置被创建, 该命令也会在这里 被调用。查阅 ARCHIVE_OUTPUT_DIRECTORY,LIBRARY_OUTPUT_DIRECTORY,和 RUNTIME_OUTPUT_DIRECTORY 这三个目标属性的文档来改变这一位置。查阅 OUTPUT_NAME 目标属性的文档来改变最终文件名的<name>部分。 如果指定了 EXCLUDE_FROM_ALL 属性,对应的一些属性会在目标被创建时被设置。查 阅 EXCLUDE_FROM_ALL 的文档来获取该属性的细节。 使用下述格式,add_library 命令也可以用来创建导入的库目标:

add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED)
导入的库目标是引用了在工程外的一个库文件的目标。 没有生成构建这个库的规则。 这个目 标名字的作用域在它被创建的路径及以下有效。 他可以向任何在该工程内构建的目标一样被引用。 导入库为类似于 target_link_libraries 命令中引用它提供了便利。关于导入库细节可以通过指 定那些以 IMPORTED_的属性设置来指定。其中最重要的属性是 IMPORTED_LOCATION(以 及它的具体配置版本,IMPORTED_LOCATION_<CONFIG>),它指定了主库文件在磁盘上 的位置。查阅 IMPORTED_*属性的文档获取更多的信息。

CMD#7:add_subdirectory
为构建添加一个子路径。
add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
这条命令的作用是为构建添加一个子路径。source_dir 选项指定了 CMakeLists.txt 源文 件和代码文件的位置。如果 source_dir 是一个相对路径,那么 source_dir 选项会被解释为相 对于当前的目录,但是它也可以是一个绝对路径。binary_dir 选项指定了输出文件的路径。如 果 binary_dir 是相对路径,它将会被解释为相对于当前输出路径,但是它也可以是一个绝对路 径。 如果没有指定 binary_dir, binary_dir 的值将会是没有做任何相对路径展开的 source_dir, 这也是通常的用法。在 source_dir 指定路径下的 CMakeLists.txt 将会在当前输入文件的处理 过程执行到该命令之前,立即被 CMake 处理。 如果指定了 EXCLUDE_FROM_ALL 选项,在子路径下的目标默认不会被包含到父路径的 ALL 目标里,并且也会被排除在 IDE 工程文件之外。用户必须显式构建在子路径下的目标,比 如一些示范性的例子工程就是这样。典型地,子路径应该包含它自己的 project()命令调用,这 样会在子路径下产生一份完整的构建系统(比如 VS IDE 的 solution 文件)。注意,目标间的

依赖性要高于这种排除行为。 如果一个被父工程构建的目标依赖于在这个子路径下的目标, 被依 赖的目标会被包含到父工程的构建系统中,以满足依赖性的要求。

CMD#8:add_test
以指定的参数为工程添加一个测试。

add_test(testname Exename arg1 arg2 ... )
如果已经运行过了 ENABLE_TESTING 命令,这个命令将为当前路径添加一个测试目标。 如果 ENABLE_TESTING 还没有运行过,该命令啥事都不做。测试是由测试子系统运行的,它 会以指定的参数执行 Exename 文件。 Exename 或者是由该工程构建的可执行文件, 也可以是 系统上自带的任意可执行文件(比如 tclsh)。该测试会在 CMakeList.txt 文件的当前工作路径 下运行,这个路径与二进制树上的路相对应。

add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]] COMMAND <command> [arg1 [arg2 ...]])
如果 COMMAND 选项指定了一个可执行目标(用 add_executable 创建),它会自动被 在构建时创建的可执行文件所替换。如果指定了 CONFIGURATIONS 选项,那么该测试只有在 列出的某一个配置下才会运行。 在 COMMAND 选项后的参数可以使用“生成器表达式”,它的语法是"$<...>"。这些表达 式会在构建系统生成期间,以及构建配置的专有信息的产生期间被评估。合法的表达式是:

$<CONFIGURATION> $<TARGET_FILE:tgt> $<TARGET_LINKER_FILE:tgt> $<TARGET_SONAME_FILE:tgt>

= = = =

配置名称 主要的二进制文件(.exe, .so.1.2, .a) 用于链接的文件(.a, .lib, .so) 带有.so.的文件(.so.3)

其中,"tgt"是目标的名称。目标文件表达式 TARGET_FILE 生成了一个完整的路径,但是 它的_DIR 和_NAME 版本可以生成目录以及文件名部分:

$<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt> $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt> $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
用例:

1 add_test(NAME mytest 2 COMMAND testDriver --config $<CONFIGURATION> 3 --exe $<TARGET_FILE:myexe>)
这段代码创建了一个名为 mytest 的测试,它执行的命令是 testDriver 工具,传递的参数 包括配置名,以及由目标生成的可执行文件 myexe 的完整路径。

CMD#9:aux_source_directory
查找在某个路径下的所有源文件。

aux_source_directory(<dir> <variable>)
搜集所有在指定路径下的源文件的文件名,将输出结果列表储存在指定的<variable>变量 中。 该命令主要用在那些使用显式模板实例化的工程上。 模板实例化文件可以存储在 Templates 子目录下,然后可以使用这条命令自动收集起来;这样可以避免手工罗列所有的实例。 使用该命令来避免为一个库或可执行目标写源文件的清单, 是非常具有吸引力的。 但是如果 该命令貌似可以发挥作用, 那么 CMake 就不需要生成一个感知新的源文件何时被加进来的构建 系统了(也就是说,新文件的加入,并不会导致 CMakeLists.txt 过时,从而不能引起 CMake 重新运行。——译注)。正常情况下,生成的构建系统能够感知它何时需要重新运行 CMake, 因为需要修改 CMakeLists.txt 来引入一个新的源文件。当源文件仅仅是加到了该路径下,但是 没有修改这个 CMakeLists.txt 文件,使用者只能手动重新运行 CMake 来产生一个包含这个新 文件的构建系统。

CMD#10:break
从一个包围该命令的 foreach 或 while 循环中跳出。

break()
从包围它的 foreach 循环或 while 循环中跳出。

CMD#11:build_command
获取构建该工程的命令行。

build_command(<variable> [CONFIGURATION <config>] [PROJECT_NAME <projname>] [TARGET <target>])
把给定的变量<variable>设置成一个字符串,其中包含使用由变量 CMAKE_GENERATOR 确定的项目构建工具,去构建某一个工程的某一个目标配置的命令行。 对于多配置生成器,如果忽略 CONFIGURATION 选项,CMake 将会选择一个合理的默认 值;而对于单配置生成器,该选项会被忽略。 如果 PROJECT_NAME 选项被忽略,得到的命令行用来构建当前构建树上的顶层工程。 如果 TARGET 选项被忽略,得到的命令行可以用来构建所有目标,比较高效的用法是构建 目标 all 或者 ALL_BUILD。

build_command(<cachevariable> <makecommand>)
不推荐使用以上的这种格式, 但对于后相兼容还是有用的。 只要可以, 就要使用第一种格式。 这种格式将变量<cachevariable>设置为一个字符串,其中包含从构建树的根目录,用 <makecommand>指定的构建工具构建这个工程的命令。<makecommand>应该是指向 msdev,devenv,nmake,make 或者是一种最终用户指定的构建工具的完整路径。

CMD#12:cmake_minimum_required
设置一个工程所需要的最低 CMake 版本。

cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]] [FATAL_ERROR])
如果 CMake 的当前版本低于指定的版本,它会停止处理工程文件,并报告错误。当指定的 版本高于 2.4 时,它会隐含调用:

cmake_policy(VERSION major[.minor[.patch[.tweak]]])
从而将 cmale 的策略版本级别设置为指定的版本。当指定的版本是 2.4 或更低时,这条命 令隐含调用:

cmake_policy(VERSION 2.4)
这将会启用对于 CMake 2.4 及更低版本的兼容性。 FATAL_ERROR 选项是可以接受的,但是 CMake 2.6 及更高的版本会忽略它。如果它被 指定,那么 CMake 2.4 及更低版本将会以错误告终而非仅仅给出个警告。

CMD#13:cmake_policy
管理 CMake 的策略设置。 随着 CMake 的演变,有时为了搞定 bug 或改善现有特色的实现方法,改变现有的行为是 必须的。CMake 的策略机制是在新的 CMake 版本带来行为上的改变时,用来帮助保持现有项 目的构建的一种设计。每个新的策略(行为改变)被赋予一个 "CMP<NNNN>"格式的识别符, 其中"<NNNN>"是一个整数索引。每个策略相关的文档都会描述“旧行为”和“新行为”,以及引 入该策略的原因。工程可以设置各种策略来选择期望的行为。当 CMake 需要了解要用哪种行为 的时候,它会检查由工程指定的一种设置。如果没有可用的设置,工程假定使用“旧行为”,并且 会给出警告要求你设置工程的策略。 cmake_policy 是用来设置“新行为”或“旧行为”的命令。如果支持单独设置策略,我们鼓励 各项目根据 CMake 的版本来设置策略。

cmake_policy(VERSION major.minor[.patch[.tweak]])

上述命令指定当前的 CMakeLists.txt 是为给定版本的 CMake 书写的。所有在指定的版本 或更早的版本中引入的策略会被设置为使用“新行为”。 所有在指定的版本之后引入的策略将会变 为无效(unset)。该命令有效地为一个指定的 CMake 版本请求优先采用的行为,并且告知更 新的 CMake 版本给出关于它们新策略的警告。命令中指定的策略版本必须至少是 2.4,否则命 令会报告一个错误。为了得到支持早于 2.4 版本的兼容性特性,查阅策略 CMP0001 的相关文 档。

cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD) 对于某种给定的策略,该命令要求 CMake 使用新的或者旧的行为。对于一个指定的策略, 那些依赖于旧行为的工程,通过设置策略的状态为 OLD,可以禁止策略的警告。或者,用户可 以让工程采用新行为,并且设置策略的状态为 NEW。

cmake_policy(GET CMP<NNNN> <variable>)
该命令检查一个给定的策略是否设置为旧行为或新行为。 如果策略被设置, 输出的变量值会 是“OLD”或“NEW”,否则为空。 CMake 将策略设置保存在一个栈结构中,因此,cmake_policy 命令产生的改变仅仅影响 在栈顶端的元素。 在策略栈中的一个新条目由各子路径自动管理, 以此保护它的父路径及同层路 径的策略设置。CMake 也管理通过 include()和 find_package()命令加载的脚本中新加入的 条目, 除非调用时指定了 NO_POLICY_SCOPE 选项 (另外可参考 CMP0011) 。 cmake_policy 命令提供了一种管理策略栈中自定义条目的接口:

cmake_policy(PUSH) cmake_policy(POP)
每个 PUSH 必须有一个配对的 POP 来去掉撤销改变。这对于临时改变策略设置比较有用。 函数和宏会在它们被创建的时候记录策略设置, 并且在它们被调用的时候使用记录前的策略。 如果函数或者宏实现设置了策略,这个变化会通过调用者(caller)一直上传,自动传递到嵌套的 最近的策略栈条目。

CMD#14:configure_file:
将一份文件拷贝到另一个位置并修改它的内容。

configure_file(<input> <output> [COPYONLY] [ESCAPE_QUOTES] [@ONLY])
将文件<input>拷贝到<output>然后替换文件内容中引用到的变量值。如果<input>是 相对路径,它被评估的基础路径是当前源码路径。<input>必须是一个文件,而不是个路径。 如果<output>是一个相对路径,它被评估的基础路径是当前二进制文件路径。如果<output> 是一个已有的路径,那么输入文件将会以它原来的名字放到那个路径下。 该命令替换掉在输入文件中,以${VAR}格式或@VAR@格式引用的任意变量,如同它们 的值是由 CMake 确定的一样。 如果一个变量还未定义,它会被替换为空。如果指定了 COPYONLY 选项,那么变量就不会展开。如果指定了 ESCAPE_QUOTES 选项,那么所有被替

换的变量将会按照 C 语言的规则被转义。 该文件将会以 CMake 变量的当前值被配置。 如果指定 了@ONLY 选项, 只有@VAR@格式的变量会被替换而${VAR}格式的变量则会被忽略。 这对于 配置使用${VAR}格式的脚本文件比较有用。任何类似于#cmakedefine VAR 的定义语句将会 被替换为#define VAR 或者/* #undef VAR */,视 CMake 中对 VAR 变量的设置而定。任何 类似于#cmakedefine01 VAR 的定义语句将会被替换为#define VAR 1 或#define VAR 0, 视 VAR 被评估为 TRUE 或 FALSE 而定。 (configure_file 的作用是让普通文件也能使用 CMake 中的变量。——译注)

CMD#15:create_test_sourcelist:
为构建测试程序创建一个测试驱动器和源码列表。

create_test_sourcelist(sourceListName driverName test1 test2 test3 EXTRA_INCLUDE include.h FUNCTION function)
测试驱动器是一个将很多小的测试代码连接为一个单一的可执行文件的程序。 这在为了缩减 总的需用空间而用很多大的库文件去构建静态可执行文件的时候, 特别有用。 构建测试驱动所需 要的源文件列表会在变量 sourceListName 中。DriverName 变量是测试驱动器的名字。其它 的参数还包括一个测试源代码文件的清单, 中间可以用分号隔开。 每个测试源码文件中应该有一 个与去掉扩展名的文件名同名的函数 (比如 foo.cxx 文件里应该有 int foo(int, char*[]);) (和 main 的函数签名一样——译注) 。 DriverName 可以在命令行中按名字调用这些测试中的每一 个。如果指定了 EXTRA_INCLUDE,那么它后面的参数(即 include.h——译注)会被包含到 生成的文件里。如果指定了 FUNCTION 选项,那么它后面的参数(即 function——译注)会 被认为是一个函数名,传递给它的参数是一个指向 argc 的指针和 argv。这个选项可以用来为 每个测试函数添加额外的命令行参数处理过程。CMake 变量 CMAKE_TESTDRIVER_BEFORE_TESTMAIN 用来设置在调用测试的 main 函数之前调用的 代码。

CMD#16:define_property:
定义并描述(Document)自定义属性。

define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | TEST | VARIABLE | CACHED_VARIABLE> PROPERTY <name> [INHERITED] BRIEF_DOCS <brief-doc> [docs...] FULL_DOCS <full-doc> [docs...]) 在一个域(scope)中定义一个可以用 set_property 和 get_property 命令访问 的属性。这个命令对于把文档和可以通过 get_property 命令得到的属性名称关联起来非 常有用。第一个参数确定了这个属性可以使用的范围。它必须是下列值中的一个:

GLOBAL = 与全局命名空间相关联 DIRECTORY = 与某一个目录相关联 TARGET = 与一个目标相关联 SOURCE = 与一个源文件相关联 TEST = 与一个以 add_test 命名的测试相关联 VARIABLE = 描述(document)一个 CMake 语言变量 CACHED_VARIABLE = 描述(document)一个 CMake 语言缓存变量
注意,与 set_property 和 get_property 不相同,不需要给出实际的作用域;只有作用域 的类型才是重要的。PROPERTY 选项必须有,它后面紧跟要定义的属性名。如果指定了 INHERITED 选项, 那么如果 get_property 命令所请求的属性在该作用域中未设置, 它会沿着 链条向更高的作用域去搜索。DIRECTORY 域向上是 GLOBAL。TARGET,SOURCE 和 TEST 向上是 DIRECTORY。 BRIEF_DOCS 和 FULL_DOCS 选项后面的参数是和属性相关联的字符串,分别作为变量 的简单描述和完整描述。在使用 get_property 命令时,对应的选项可以获取这些描述信息。

CMD#17: else
开始一个 if 语句块的 else 部分。
else(expression)
参见 if 命令。

CMD#18: elseif
开始 if 块的 elseif 部分。
elseif(expression)
参见 if 命令。

CMD#19: enable_language
支持某种语言(CXX/C/Fortran/等)
enable_language(languageName [OPTIONAL] )
该命令打开了 CMake 对参数中指定的语言的支持。这与 project 命令相同,但是不会创建 任何 project 命令会产生的额外变量。可以选用的语言的类型有 CXX,C,Fortran 等。如果指 定了 OPTIONAL 选项, 用 CMAKE_<languageName>_COMPILER_WORKS 变量来判断该 语言是否被成功支持。

CMD#20:

enable_testing

打开当前及以下目录中的测试功能。

enable_testing() 为当前及其下级目录打开测试功能。也可参见 add_test 命令。注意,ctest 需要在 构建跟目录下找到一个测试文件。因此,这个命令应该在源文件目录的根目录下。

CMD#21: endforeach
结束 foreach 语句块中的一系列命令。

endforeach(expression)
参见 FOREACH 命令。

CMD#22: endfunction
结束一个 function 语句块中的一系列命令。

endfunction(expression)
参见 function 命令。

CMD#23: endif
结束一个 if 语句块中的一系列命令。

endif(expression)
参见 if 命令。

CMD#24: endmacro
结束一个 macro 语句块中的一系列命令。

endmacro(expression)
参见 macro 命令。

CMD#25: endwhile
结束一个 while 语句块中的一系列命令。

endwhile(expression)
参见 while 命令。

CMD#26: execute_process
执行一个或更多个子进程。 execute_process(COMMAND <cmd1> [args1...]] [COMMAND <cmd2> [args2...] [...]] [WORKING_DIRECTORY <directory>] [TIMEOUT <seconds>] [RESULT_VARIABLE <variable>] [OUTPUT_VARIABLE <variable>] [ERROR_VARIABLE <variable>] [INPUT_FILE <file>] [OUTPUT_FILE <file>] [ERROR_FILE <file>] [OUTPUT_QUIET] [ERROR_QUIET] [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE])
运行一条或多条命令, 使得前一条命令的标准输出以管道的方式成为下一条命令的标准输入。 所有进程公用一个单独的标准错误管道。如果指定了 WORKING_DIRECTORY 选项,后面的 路径选项将会设置为子进程的当前工作路径。如果指定了 TIMEOUT 选项,如果子进程没有在 指定的秒数(允许分数)里完成,子进程会自动终止。如果指定了 RESULT_VARIABLE 选项, 该变量将保存为正在运行的进程的结果; 它可以是最后一个子进程的整数返回代码, 也可以是一 个描述错误状态的字符串。如果指定了 OUTPUT_VARIABLE 或者 ERROR_VARIABLE,后面 的变量将会被分别设置为标准输出和标准错误管道的值。 如果两个管道都是用了相同的变量, 它 们的输出将会按产生的顺序被合并。如果指定了 INPUT_FILE,OUTPUT_FILE 或 ERROR_FILE 选项,其后的文件将会分别被附加到第一个进程的标准输入、最后一个进程的标 准输出, 或者所有进程的标准错误管道上。 如果指定了 OUTPUT_QUIET 后者 ERROR_QUIET 选项, 那么标准输出或标准错误的结果将会被静静的忽略掉。 如果为同一个管道指定了多于一个 的 OUTPUT_*或 ERROR_* 选项,优先级是没有指定的。如果没有指定 OUTPUT_*或者 ERROR_*选项,输出将会与 CMake 进程自身对应的管道共享。 execute_process 命令是 exec_program 命令的一个较新的功能更加强大的版本。但是 为了兼容性的原因,旧的 exec_program 命令还会继续保留。

CMD#27:export
从构建树中导出目标供外部使用。

export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>] [APPEND] FILE <filename>)
创建一个名为<filename>的文件,它可以被外部工程包含进去, 从而外部工程可以从当前 工程的构建树中导入目标。这对于交叉编译那些可以运行在宿主平台的的 utility 可执行文件,

然后将它们导入到另外一个编译成目标平台代码的工程中的情形,特别有用。如果指定了 NAMESPACE 选项,<namespace>字符串将会被扩展到输出文件中的所有目标的名字中。如 果指定了 APPEND 选项,生成的代码将会续接在文件之后,而不是覆盖它。如果一个库目标被 包含在 export 中,但是连接成它的目标没有被包含,行为没有指定。 由该命令创建的文件是与指定的构建树一致的, 并且绝对不应该被安装。 要从一个安装树上 导出目标,参见 install(EXPORT)命令。

export(PACKAGE <name>)
在 CMake 的用户包注册表中,为<name>包(package)存储当前的构建目录。这将有助 于依赖于它的工程从当前工程的构建树中查找并使用包而不需要用户的介入。 注意, 该命令在包 注册表中创建的条目,仅仅在与跟构建树一起运行的包配置文件(<name>Config.cmake)一 起使用时才会起作用。

CMD#28: file
文件操作命令

file(WRITE filename "message to write"... ) file(APPEND filename "message to write"... ) file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX]) file(STRINGS filename variable [LIMIT_COUNT num] [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes] [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes] [NEWLINE_CONSUME] [REGEX regex] [NO_HEX_CONVERSION]) file(GLOB variable [RELATIVE path] [globbing expressions]...) file(GLOB_RECURSE variable [RELATIVE path] [FOLLOW_SYMLINKS] [globbing expressions]...) file(RENAME <oldname> <newname>) file(REMOVE [file1 ...]) file(REMOVE_RECURSE [file1 ...]) file(MAKE_DIRECTORY [directory1 directory2 ...]) file(RELATIVE_PATH variable directory file) file(TO_CMAKE_PATH path result) file(TO_NATIVE_PATH path result) file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log] [EXPECTED_MD5 sum] [SHOW_PROGRESS])
WRITE 选项将会写一条消息到名为 filename 的文件中。如果文件已经存在,该命令会覆 盖已有的文件;如果文件不存在,它将创建该文件。 APPEND 选项和 WRITE 选项一样, 将会写一条消息到名为 filename 的文件中, 只是该消 息会附加到文件末尾。

READ 选项将会读一个文件中的内容并将其存储在变量里。读文件的位置从 offset 开始, 最多读 numBytes 个字节。 如果指定了 HEX 参数, 二进制代码将会转换为十六进制表达方式, 并存储在变量里。 STRINGS 将会从一个文件中将一个 ASCII 字符串的 list 解析出来,然后存储在 variable 变量中。文件中的二进制数据会被忽略。回车换行符会被忽略。它也可以用在 Intel 的 Hex 和 Motorola 的 S-记录文件;读取它们时,它们会被自动转换为二进制格式。可以使用 NO_HEX_CONVERSION 选项禁止这项功能。LIMIT_COUNT 选项设定了返回的字符串的最 大数量。LIMIT_INPUT 设置了从输入文件中读取的最大字节数。LIMIT_OUTPUT 设置了在输 出变量中存储的最大字节数。LENGTH_MINIMUM 设置了要返回的字符串的最小长度;小于该 长度的字符串会被忽略。 LENGTH_MAXIMUM 设置了返回字符串的最大长度; 更长的字符串会 被分割成不长于最大长度的字符串。NEWLINE_CONSUME 选项允许新行被包含到字符串中, 而不是终止它们。REGEX 选项指定了一个待返回的字符串必须满足的正则表达式。典型的使用 方式是:

file(STRINGS myfile.txt myfile)
该命令在变量 myfile 中存储了一个 list,该 list 中每个项是输入文件中的一行文本。 GLOB 选项将会为所有匹配查询表达式的文件生成一个文件 list,并将该 list 存储进变量 variable 里。文件名查询表达式与正则表达式类似,只不过更加简单。如果为一个表达式指定 了 RELATIVE 标志,返回的结果将会是相对于给定路径的相对路径。文件名查询表达式的例子 有:

*.cxx - 匹配所有扩展名为 cxx 的文件。 *.vt? - 匹配所有扩展名是 vta,...,vtz 的文件。 f[3-5].txt - 匹配文件 f3.txt, f4.txt, f5.txt。
GLOB_RECURSE 选项将会生成一个类似于通常的 GLOB 选项的 list,只是它会寻访所有 那些匹配目录的子路径并同时匹配查询表达式的文件。作为符号链接的子路径只有在给定 FOLLOW_SYMLINKS 选项或者 cmake 策略 CMP0009 被设置为 NEW 时,才会被寻访到。 参见 cmake --help-policy CMP0009 查询跟多有用的信息。 使用递归查询的例子有:

/dir/*.py - 匹配所有在/dir 及其子目录下的 python 文件。
MAKE_DIRECTORY 选项将会创建指定的目录,如果它们的父目录不存在时,同样也会创 建。(类似于 mkdir 命令——译注) RENAME 选项对同一个文件系统下的一个文件或目录重命名。 (类似于 mv 命令——译注) REMOVE 选项将会删除指定的文件, 包括在子路径下的文件。 (类似于 rm 命令——译注) REMOVE_RECURSE 选项会删除给定的文件以及目录, 包括非空目录。 (类似于 rm -r 命 令——译注) RELATIVE_PATH 选项会确定从 direcroty 参数到指定文件的相对路径。 TO_CMAKE_PATH 选项会把 path 转换为一个以 unix 的 / 开头的 cmake 风格的路径。 输入可以是一个单一的路径,也可以是一个系统路径,比如"$ENV{PATH}"。注意,在调用 TO_CMAKE_PATH 的 ENV 周围的双引号只能有一个参数(Note the double quotes around

the ENV call TO_CMAKE_PATH only takes one argument. 原文如此。quotes 和后面的 takes 让人后纠结,这句话翻译可能有误。欢迎指正——译注)。 TO_NATIVE_PATH 选项与 TO_CMAKE_PATH 选项很相似,但是它会把 cmake 风格的 路径转换为本地路径风格:windows 下用\,而 unix 下用/。 DOWNLOAD 将给定的 URL 下载到指定的文件中。如果指定了 LOG var 选项,下载日志 将会被输出到 var 中。如果指定了 STATUS var 选项,下载操作的状态会被输出到 var 中。该 状态返回值是一个长度为 2 的 list。list 的第一个元素是操作的数字返回值,第二个返回值是错 误的字符串值。错误信息如果是数字 0,操作中没有发生错误。如果指定了 TIMEOUT time 选 项,在 time 秒之后,操作会超时退出;time 应该是整数。如果指定了 EXPECTED_MD5 sum 选项,下载操作会认证下载的文件的实际 MD5 和是否与期望值匹配。如果不匹配,操作将返回 一个错误。如果指定了 SHOW_PROGRESS 选项,进度信息会以状态信息的形式被打印出来, 直到操作完成。 file 命令还提供了 COPY 和 INSTALL 两种格式:

file(<COPY|INSTALL> files... DESTINATION <dir> [FILE_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS permissions...] [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] [FILES_MATCHING] [[PATTERN <pattern> | REGEX <regex>] [EXCLUDE] [PERMISSIONS permissions...]] [...])
COPY 版本把文件、 目录以及符号连接拷贝到一个目标文件夹。 相对输入路径的评估是基于 当前的源代码目录进行的, 相对目标路径的评估是基于当前的构建目录进行的。 复制过程将保留 输入文件的时间戳;并且如果目标路径处存在同名同时间戳的文件,复制命令会把它优化掉。赋 值过程将保留输入文件的访问权限,除非显式指定权限或指定 NO_SOURCE_PERMISSIONS 选项(默认是 USE_SOURCE_PERMISSIONS)。参见 install(DIRECTORY)命令中关于权 限(permissions),PATTERN,REGEX 和 EXCLUDE 选项的文档。 INSTALL 版本与 COPY 版本只有十分微小的差别:它会打印状态信息,并且默认使用 NO_SOURCE_PERMISSIONS 选项。install 命令生成的安装脚本使用这个版本(它会使用一 些没有在文档中涉及的内部使用的选项。)

CMD#29:find_file
查找一个文件的完整路径。

find_file(<VAR> name1 [path1 path2 ...])
这是该命令的精简格式, 对于大多数场合它都足够了。 它与命令 find_file(<VAR> name1 [PATHS path1 path2 ...])是等价的。 find_file( <VAR> name | NAMES name1 [name2 ...]

[HINTS path1 [path2 ... ENV var]] [PATHS path1 [path2 ... ENV var]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_CMAKE_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_SYSTEM_PATH] [CMAKE_FIND_ROOT_PATH_BOTH | ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH] ) 这条命令用来查找指定文件的完整路径。一个名字是<VAR>的缓存条目(参见 CMakeCache.txt 的介绍——译注)变量会被创建,用来存储该命令的结果。如果发现了文件 的一个完整路径,该结果会被存储到该变量里并且搜索过程不会再重复,除非该变量被清除。如 果什么都没发现,搜索的结果将会是<VAR>-NOTFOUND;并且在下一次以相同的变量调用 find_file 时,该搜索会重新尝试。被搜索的文件的文件名由 NAMES 选项后的名字列表指定。 附加的其他搜索位置可以在 PATHS 选项之后指定。 如果 ENV var 在 HINTS 或 PATHS 段中出 现,环境变量 var 将会被读取然后被转换为一个系统级环境变量,并存储在一个 cmake 风格的 路径 list 中。比如,使用 ENV PATH 将会将系统的 path 变量列出来。在 DOC 之后的变量将 会用于 cache 中的文档字符串(documentation string)。PATH_SUFFIXES 指定了在每个 搜索路径下的需要搜索的子路径。 如果指定了 NO_DEFAULT_PATH 选项,那么在搜索时不会附加其它路径。如果没有指定 NO_DEFAULT_PATH 选项,搜索过程如下: 1、在 cmake 特有的 cache 变量中指定的搜索路径搜索。这些路径用于在命令行里用 -DVAR=value 被设置。如果使用了 NO_CMAKE_PATH 选项,该路径会被跳过。(此句翻译 可能有误——译注。)搜索路径还包括:

对于每个在 CMAKE_PREFIX_PATH 中的路径<prefix>,<prefix>/include 变量:CMAKE_INCLUDE_PATH 变量:CMAKE_FRAMEWORK_PATH
2、在 cmake 特定的环境变量中指定的搜索路径搜索。该路径会在用户的 shell 配置中被 设置。如果指定了 NO_CMAKE_ENVIRONMENT_PATH 选项,该路径会被跳过。搜索路径还 包括: 对于每个在 CMAKE_PREFIX_PATH 中的路径<prefix>,<prefix>/include

变量:CMAKE_INCLUDE_PATH 变量:CMAKE_FRAMEWORK_PATH
3、由 HINTS 选项指定的搜索路径。这些路径是由系统内省(introspection)时计算出来 的路径,比如已经发现的其他项的位置所提供的痕迹。硬编码的参考路径应该使用 PATHS 选项 指定。(HINTS 与 PATHS 有何不同?比后者的优先级高?有疑问。——译注)

4、搜索标准的系统环境变量。如果指定 NO_SYSTEM_ENVIRONMENT_PATH 选项,搜 索路径将跳过其后的参数。搜索路径包括环境变量 PATH 个 INCLUDE。 5、查找在当前系统的平台文件中定义的 cmake 变量。如果指定了 NO_CMAKE_SYSTEM_PATH 选项,该路径会被跳过。其他的搜索路径还包括: 对于每个在 CMAKE_PREFIX_PATH 中的路径<prefix>,<prefix>/include

变量:CMAKE_SYSTEM_INCLUDE_PATH 变量:CMAKE_SYSTEM_FRAMEWORK_PATH
6、搜索由 PATHS 选项指定的路径或者在命令的简写版本中指定的路径。这一般是一些硬 编码的参考路径。在 Darwin 后者支持 OS X 框架的系统上,cmake 变量 CMAKE_FIND_FRAMWORK 可以设置为空或者下述值之一: "FIRST" "LAST" "ONLY" - 在标准库或者头文件之前先查找框架。对于 Darwin 系统,这是默认的。 - 在标准库或头文件之后再查找框架。 - 只查找框架。

"NEVER" - 从不查找框架。 在 Darwin 或者支持 OS X Application Bundles 的系统上,cmake 变量 CMAKE_FIND_APPBUNDLE 可以被设置为空,或者下列值之一: "FIRST" "LAST" "ONLY" - 在标准程序之前查找 application bundles,这也是 Darwin 系统的默认选项。 - 在标准程序之后查找 application bundlesTry。 - 只查找 application bundles。

"NEVER" - 从不查找 application bundles。 CMake 的变量 CMAKE_FIND_ROOT_PATH 指定了一个或多个在所有其它搜索路径之前 的搜索路径。 该选项很有效地将给定位置下的整个搜索路径的最优先路径进行了重新指定。 默认 情况下,它是空的。当交叉编译一个指向目标环境下的根目录中的目标时,CMake 也会搜索那 些路径;该变量这时显得非常有用。默认情况下,首先会搜索在 CMAKE_FIND_ROOT_PATH 变量中列出的路径, 然后才是非根路径。 设置 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE 变量可以调整该默认行为。该行为可以在每次调用时被手动覆盖。通过使用 CMAKE_FIND_ROOT_PATH_BOTH 变量,搜索顺序将会是上述的那样。如果使用了 NO_CMAKE_FIND_ROOT_PATH 变量,那么 CMAKE_FIND_ROOT_PATH 将不会被用到。 如果使用了 ONLY_CMAKE_FIND_ROOT_PATH 变量,那么只有 CMAKE_FIND_ROOT_PATH 中的路径(即 re-rooted 目录——译注)会被搜索。

一般情况下, 默认的搜索顺序是从最具体的路径到最不具体的路径。 只要用 NO_*选项 多次调用该命令,工程就可以覆盖该顺序。
find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) find_file(<VAR> NAMES name) 只要这些调用中的一个成功了,返回变量就会被设置并存储在 cache 中;然后该命令就不 会再继续查找了。

CMD#30:find_library

查找一个库文件 find_library(<VAR> name1 [path1 path2 ...]) 这是该命令的简写版本,在大多数场合下都已经够用了。它与命令 find_library(<VAR> name1 [PATHS path1 path2 ...])等价。 find_library( <VAR> name | NAMES name1 [name2 ...] [HINTS path1 [path2 ... ENV var]] [PATHS path1 [path2 ... ENV var]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_CMAKE_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_SYSTEM_PATH] [CMAKE_FIND_ROOT_PATH_BOTH | ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH] ) 该命令用来查找一个库文件。一个名为<VAR>的 cache 条目会被创建来存储该命令的结 果。如果找到了该库文件,那么结果会存储在该变量里,并且搜索过程将不再重复,除非该变量 被清空。如果没有找到,结果变量将会是<VAR>-NOTFOUND,并且在下次使用相同变量调用 find_library 命令时,搜索过程会再次尝试。在 NAMES 参数后列出的文件名是要被搜索的库 名。 附加的搜索位置在 PATHS 参数后指定。 如果再 HINTS 或者 PATHS 字段中设置了 ENV 变 量 var, 环境变量 var 将会被读取并从系统环境变量转换为一个 cmake 风格的路径 list。 例如, 指定 ENV PATH 是获取系统 path 变量并将其转换为 cmake 的 list 的一种方式。在 DOC 之后 的参数用来作为 cache 中的注释字符串。 PATH_SUFFIXES 选项指定了每个搜索路径下待搜索 的子路径。 如果指定了 NO_DEFAULT_PATH 选项,那么搜索的过程中不会有其他的附加路径。如果 没有指定该选项,搜索过程如下: 1、搜索 cmake 特有的 cache 变量指定的路径。这些变量是在用 cmake 命令行时,通过 -DVAR=value 指定的变量。如果指定了 NO_CMAKE_PATH 选项,这些路径会被跳过。搜索 的路径还包括: 对于每个在 CMAKE_PREFIX_PATH 中的<prefix>,路径<prefix>/lib CMAKE_LIBRARY_PATH CMAKE_FRAMEWORK_PATH 2、 搜索 cmake 特有的环境变量指定的路径。 这些变量是用户的 shell 配置中设置的变量。 如果指定了 NO_CMAKE_ENVIRONMENT_PATH 选项,这些路径会被跳过。搜索的路径还包 括:

对于每个在 CMAKE_PREFIX_PATH 中的<prefix>,路径<prefix>/lib CMAKE_LIBRARY_PATH CMAKE_FRAMEWORK_PATH 3、 搜索由 HINTS 选项指定的路径。 这些路径是系统内省 (introspection) 估算出的路径, 比如由另一个已经发现的库文件的地址提供的参考信息。 硬编码的推荐路径应该通过 PATHS 选 项指定。 4、查找标准的系统环境变量。如果指定了 NO_SYSTEM_ENVIRONMENT_PATH 选项, 这些路径会被跳过。搜索的路径还包括: PATH LIB 5、查找在为当前系统的平台文件中定义的 cmake 变量。如果指定了 NO_CMAKE_SYSTEM_PATH 选项,该路径会被跳过。搜索的路径还包括: 对于每个在 CMAKE_SYSTEM_PREFIX_PATH 中的<prefix>,路径<prefix>/lib CMAKE_SYSTEM_LIBRARY_PATH CMAKE_SYSTEM_FRAMEWORK_PATH 6、搜索 PATHS 选项或者精简版命令指定的路径。这些通常是硬编码的推荐搜索路径。 在 Darwin 或者支持 OS X 框架的系统上,cmake 变量 CMAKE_FIND_FRAMEWORK 可以用来设置为空,或者下述值之一: "FIRST" "LAST" "ONLY" - 在标准库或头文件之前查找框架。在 Darwin 系统上这是默认选项。 - 在标准库或头文件之后查找框架。 - 仅仅查找框架。

"NEVER" - 从不查找框架。 在 Darwin 或者支持 OS X Application Bundles 的系统,cmake 变量 CMAKE_FIND_APPBUNDLE 可以被设置为空或者下面这些值中的一个: "FIRST" 选项。 "LAST" "ONLY" - 在标准库或头文件之后查找 application bundles。 - 仅仅查找 application bundles。 - 在标准库或头文件之前查找 application bundles。在 Darwin 系统上这是默认

"NEVER" - 从不查找 application bundles。 CMake 变量 CMAKE_FIND_ROOT_PATH 指定了一个或者多个优先于其他搜索路径的搜 索路径。该变量能够有效地重新定位在给定位置下进行搜索的根路径。该变量默认为空。当使用 交叉编译时, 该变量十分有用: 用该变量指向目标环境的根目录, 然后 CMake 将会在那里查找。 默认情况下, 在 CMAKE_FIND_ROOT_PATH 中列出的路径会首先被搜索, 然后是“非根”路径。 该默认规则可以通过设置 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY 做出调整。在每次 调用该命令之前,都可以通过设置这个变量来手动覆盖默认行为。如果使用了 NO_CMAKE_FIND_ROOT_PATH 变量,那么只有重定位的路径会被搜索。 默认的搜索顺序的设计逻辑是按照使用时从最具体到最不具体。 通过多次调用 find_library 命令以及 NO_*选项,可以覆盖工程的这个默认顺序:

find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) find_library(<VAR> NAMES name) 只要这些调用中的一个成功返回,结果变量就会被设置并且被存储到 cache 中;这样随后 的调用都不会再行搜索。如果那找到的库是一个框架,VAR 将会被设置为指向框架“<完整路 径>/A.framework” 的完整路径。当一个指向框架的完整路径被用作一个库文件,CMake 将 使用-framework A,以及-F<完整路径>这两个选项将框架连接到目标上。

CMD#31:find_package
为外部工程加载设置。
find_package(<package> [version] [EXACT] [QUIET] [[REQUIRED|COMPONENTS] [components...]] [NO_POLICY_SCOPE]) 查找并加载外来工程的设置。该命令会设置<package>_FOUND 变量,用来指示要找的 包是否被找到了。如果这个包被找到了,与它相关的信息可以通过包自身记载的变量中得到。 QUIET 选项将会禁掉包没有被发现时的警告信息。 REQUIRED 选项表示如果报没有找到的话, cmake 的过程会终止,并输出警告信息。在 REQUIRED 选项之后,或者如果没有指定 REQUIRED 选项但是指定了 COMPONENTS 选项,在它们的后面可以列出一些与包相关的部 件清单(components list)。[version]参数需要一个版本号,它是正在查找的包应该兼容的 版本号(格式是 major[.minor[.patch[.tweak]]])。EXACT 选项要求该版本号必须精确匹 配。如果在 find-module 内部对该命令的递归调用没有给定[version]参数,那么[version]和 EXACT 选项会自动地从外部调用前向继承。 对版本的支持目前只存在于包和包之间 (详见下文) 。 用户代码总体上应该使用上述的简单调用格式查询需要的包。 本命令文档的剩余部分则详述 了 find_package 的完整命令格式以及具体的查询过程。期望通过该命令查找并提供包的项目 维护人员,我们鼓励你能继续读下去。 该命令在搜索包时有两种模式:“模块”模式和“配置”模式。当该命令是通过上述的精简格式 调用的时候,合用的就是模块模式。在该模式下,CMake 搜索所有名为 Find<package>.cmake 的文件,这些文件的路径由变量由安装 CMake 时指定的 CMAKE_MODULE_PATH 变量指定。如果查找到了该文件,它会被 CMake 读取并被处理。该 模式对查找包,检查版本以及生成任何别的必须信息负责。许多查找模块(find-module)仅 仅提供了有限的,甚至根本就没有对版本化的支持;具体信息查看该模块的文档。如果没有找到 任何模块,该命令会进入配置模式继续执行。 完整的配置模式下的命令格式是: find_package(<package> [version] [EXACT] [QUIET] [[REQUIRED|COMPONENTS] [components...]] [NO_MODULE] [NO_POLICY_SCOPE] [NAMES name1 [name2 ...]] [CONFIGS config1 [config2 ...]] [HINTS path1 [path2 ... ]] [PATHS path1 [path2 ... ]]

[PATH_SUFFIXES suffix1 [suffix2 ...]] [NO_DEFAULT_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_CMAKE_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_PACKAGE_REGISTRY] [NO_CMAKE_BUILDS_PATH] [NO_CMAKE_SYSTEM_PATH] [CMAKE_FIND_ROOT_PATH_BOTH | ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH]) NO_MODULE 可以用来明确地跳过模块模式。 它也隐含指定了不使用在精简格式中使用的 那些选项。 配置模式试图查找一个由待查找的包提供的配置文件的位置。 包含该文件的路径会被存储在 一个名为<package>_DIR 的 cache 条目里。 默认情况下, 该命令搜索名为<package>的包。 如果指定了 NAMES 选项,那么其后的 names 参数会取代<package>的角色。该命令会为每 个在 names 中的 name 搜索名为<name>Config.cmake 或者<name 全小 写>-config.cmake 的文件。通过使用 CONFIGS 选项可以改变可能的配置文件的名字。以下 描述搜索的过程。如果找到了配置文件,它将会被 CMake 读取并处理。由于该文件是由包自身 提供的,它已经知道包中内容的位置。配置文件的完整地址存储在 cmake 的变量 <package>_CONFIG 中。 所有 CMake 要处理的配置文件将会搜索该包的安装信息, 并且将该安装匹配的适当版本号 (appropriate version)存储在 cmake 变量<package>_CONSIDERED_CONFIGS 中, 与之相关的版本号(associated version)将被存储在 <package>_CONSIDERED_VERSIONS 中。 如果没有找到包配置文件,CMake 将会生成一个错误描述文件,用来描述该问题——除非 指定了 QUIET 选项。如果指定了 REQUIRED 选项,并且没有找到该包,将会报致命错误,然 后配置步骤终止执行。如果设置了<package>_DIR 变量被设置了,但是它没有包含配置文件 信息,那么 CMake 将会直接无视它,然后重新开始查找。 如果给定了[version]参数,那么配置模式仅仅会查找那些在命令中请求的版本(格式是 major[.minor[.patch[.tweak]]])与包请求的版本互相兼容的那些版本的包。如果指定了 EXACT 选项,一个包只有在它请求的版本与[version]提供的版本精确匹配时才能被找到。 CMake 不会对版本数的含义做任何的转换。包版本号由包自带的版本文件来检查。对于一个备 选的包配置文件<config-file>.cmake,对应的版本文件的位置紧挨着它,并且名字或者是 <config-file>-version.cmake 或者是<config-file>Version.cmake。如果没有这个版本文 件,那么配置文件就会认为不兼容任何请求的版本。当找到一个版本文件之后,它会被加载然后 用来检查 (find_package) 请求的版本号。 版本文件在一个下述变量被定义的嵌套域中被加载: PACKAGE_FIND_NAME PACKAGE_FIND_VERSION = <package> 名字。 = 请求的完整版本字符串

PACKAGE_FIND_VERSION_MAJOR = 如果被请求了,那么它是 major 版本号,否则是 0。 PACKAGE_FIND_VERSION_MINOR = 如果被请求了,那么它是 minor 版本号,否则是 0。

PACKAGE_FIND_VERSION_PATCH = 如果被请求了,那么它是 patch 版本号,否则是 0。 PACKAGE_FIND_VERSION_TWEAK = 如果被请求了,那么它是 tweak 版本号,否则是 0。 PACKAGE_FIND_VERSION_COUNT = 版本号包含几部分,0 到 4。 版本文件会检查自身是否满足请求的版本号,然后设置了下面这些变量: PACKAGE_VERSION PACKAGE_VERSION_EXACT = 提供的完整的版本字符串。 = 如果版本号精确匹配,返回 true。

PACKAGE_VERSION_COMPATIBLE = 如果版本号相兼容,返回 true。 PACKAGE_VERSION_UNSUITABLE = 如果不适合任何版本,返回 true。 下面这些变量将会被 find_package 命令检查,用以确定配置文件是否提供了可接受的版 本。在 find_package 命令返回后,这些变量就不可用了。如果版本可接受,下述的变量会被 设置: <package>_VERSION = 提供的完整的版本字符串。

<package>_VERSION_MAJOR = 如果被请求了,那么它是 major 版本号,否则是 0。 <package>_VERSION_MINOR = 如果被请求了,那么它是 minor 版本号,否则是 0。 <package>_VERSION_PATCH = 如果被请求了,那么它是 patch 版本号,否则是 0。 <package>_VERSION_TWEAK = 如果被请求了,那么它是 tweak 版本号,否则是 0。 <package>_VERSION_COUNT = 版本号包含几部分,0 到 4。 然后,对应的包配置文件才会被加载。当多个包配置文件都可用时,并且这些包的版本文件都与 请求的版本兼容,选择哪个包将会是不确定的。不应该假设 cmake 会选择最高版本或者是最低 版本。(以上的若干段是对 find_package 中版本匹配步骤的描述,并不需要用户干预——译 注。) 配置模式提供了一种高级接口和搜索步骤的接口。 这些被提供的接口的大部分是为了完整性 的要求, 以及在模块模式下, 包被 find-module 加载时供内部使用。 大多数用户仅仅应该调用: find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET]) 来查找包。鼓励那些需要提供 CMake 包配置文件的包维护人员应该命名这些文件并安装它们, 这样下述的整个过程将会找到它们而不需要使用附加的选项。 CMake 为包构造了一组可能的安装前缀。在每个前缀下,若干个目录会被搜索,用来查找 配置文件。下述的表格展示了待搜索的路径。每个条目都是专门为 Windows(W),UNIX(U) 或者 Apple(A)约定的安装树指定的。 <prefix>/ <prefix>/(cmake|CMake)/ <prefix>/<name>*/ <prefix>/<name>*/(cmake|CMake)/ <prefix>/(share|lib)/cmake/<name>*/ <prefix>/(share|lib)/<name>*/ <prefix>/(share|lib)/<name>*/(cmake|CMake)/ (W) (W) (W) (W) (U) (U) (U)

在支持 OS X 平台和 Application Bundles 的系统上,包含配置文件的框架或者 bundles 会在下述的路径中被搜索:

<prefix>/<name>.framework/Resources/ <prefix>/<name>.framework/Resources/CMake/ <prefix>/<name>.framework/Versions/*/Resources/ <prefix>/<name>.framework/Versions/*/Resources/CMake/ <prefix>/<name>.app/Contents/Resources/ <prefix>/<name>.app/Contents/Resources/CMake/

(A) (A) (A) (A) (A) (A)

在所有上述情况下, <name>是区分大小写的, 并且对应于在<package>或者由 NAMES 给定的任何一个名字。 这些路径集用来与那些在各自的安装树上提供了配置文件的工程协作。 上述路径中被标记为 (W)的是专门为 Windows 上的安装设置的,其中的<prefix>部分可能是一个应用程序的顶层 安装路径。那些被标记为(U)的是专门为 UNIX 平台上的安装设置的,其中的<prefix>被多个 包共用。这仅仅是个约定,因此,所有(W)和(U)路径在所有平台上都仍然会被搜索。那些被标 记为(A)的路径是专门为 Apple 平台上的安装设置的。CMake 变量 CMAKE_FIND_FRAMEWORK 和 CMAKE_FIND_APPBUNDLE 确定了偏好的顺序, 如下所示: 安装前缀是通过以下步骤被构建出来的。如果指定了 NO_DEFAULT_PATH 选项,所有 NO_*选项都会被激活。 1、搜索在 cmake 特有的 cache 变量中指定的搜索路径。这些变量是为了在命令行中用 -DVAR=value 选项指定而设计的。通过指定 NO_CMAKE_PATH 选项可以跳过该搜索路径。 搜索路径还包括: CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH 2、搜索 cmake 特有的环境变量。这些变量是为了在用户的 shell 配置中进行配置而设计 的。通过指定 NO_CMAKE_ENVIRONMENT_PATH 选项可以跳过该路径。搜索的路径包括: <package>_DIR CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH 3、搜索 HINTS 选项指定的路径。这些路径应该是由操作系统内省时计算产生的,比如由 其它已经找到的项的位置而提供的线索。硬编码的参考路径应该在 PATHS 选项中指定。 4、搜索标准的系统环境变量。如果指定了 NO_SYSTEM_ENVIRONMENT_PATH 选项, 这些路径会被跳过。以"/bin"或"/sbin"结尾的路径条目会被自动转换为它们的父路径。搜索的 路径包括: PATH 5、搜索在 CMake GUI 中最新配置过的工程的构建树。可以通过设置 NO_CMAKE_BUILDS_PATH 选项来跳过这些路径。 这是为了在用户正在依次构建多个相互依 赖的工程时而准备的。

6、搜索存储在 CMake 用户包注册表中的路径。通过设置 NO_CMAKE_PACKAGE_REGISTRY 选项可以跳过这些路径。当 CMake 嗲用 export(PACKAGE<name>)配置一个工程时,这些路径会被存储在注册表中。参见 export(PACKAGE)命令的文档阅读更多细节。 7、搜索在当前系统的平台文件中定义的 cmake 变量。可以用 NO_CMAKE_SYSTEM_PATH 选项跳过这些路径。 CMAKE_SYSTEM_PREFIX_PATH CMAKE_SYSTEM_FRAMEWORK_PATH CMAKE_SYSTEM_APPBUNDLE_PATH 8、搜索由 PATHS 选项指定的路径。这些路径一般是硬编码的参考路径。

在 Darwin 或者支持 OS X 框架的系统上,cmake 变量 CMAKE_FIND_FRAMEWORK 可以用来 设置为空,或者下述值之一:
"FIRST" "LAST" "ONLY" - 在标准库或头文件之前查找框架。在 Darwin 系统上这是默认选项。 - 在标准库或头文件之后查找框架。 - 仅仅查找框架。

"NEVER" - 从不查找框架。 在 Darwin 或者支持 OS X Application Bundles 的系统,cmake 变量 CMAKE_FIND_APPBUNDLE 可以被设置为空或者下面这些值中的一个: "FIRST" 默认选项。 "LAST" "ONLY" - 在标准库或头文件之后查找 application bundles。 - 仅仅查找 application bundles。 - 在标准库或头文件之前查找 application bundles。在 Darwin 系统上这是

"NEVER" - 从不查找 application bundles。 CMake 变量 CMAKE_FIND_ROOT_PATH 指定了一个或者多个优先于其他搜索路径的搜 索路径。该变量能够有效地重新定位在给定位置下进行搜索的根路径。该变量默认为空。当使用 交叉编译时, 该变量十分有用: 用该变量指向目标环境的根目录, 然后 CMake 将会在那里查找。 默认情况下, 在 CMAKE_FIND_ROOT_PATH 中列出的路径会首先被搜索, 然后是“非根”路径。 该默认规则可以通过设置 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY 做出调整。在每次 调用该命令之前,都可以通过设置这个变量来手动覆盖默认行为。如果使用了 NO_CMAKE_FIND_ROOT_PATH 变量,那么只有重定位的路径会被搜索。 默认的搜索顺序的设计逻辑是按照使用时从最具体到最不具体。 通过多次调用 find_library 命令以及 NO_*选项,可以覆盖工程的这个默认顺序: find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) find_library(<VAR> NAMES name) 只要这些调用中的一个成功返回,结果变量就会被设置并且被存储到 cache 中;这样随后 的调用都不会再行搜索。如果那找到的库是一个框架,VAR 将会被设置为指向框架“<完整路

径>/A.framework” 的完整路径。当一个指向框架的完整路径被用作一个库文件,CMake 将 使用-framework A,以及-F<完整路径>这两个选项将框架连接到目标上。 参见 cmake_policy()命令的文档中关于 NO_POLICY_SCOPE 选项讨论。

CMD#32 : find_path
搜索包含某个文件的路径 find_path(<VAR> name1 [path1 path2 ...]) 在多数情况下,使用上述的精简命令格式就足够了。它与命令 find_path(<VAR> name1 [PATHS path1 path2 ...])等价。 find_path( <VAR> name | NAMES name1 [name2 ...] [HINTS path1 [path2 ... ENV var]] [PATHS path1 [path2 ... ENV var]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_CMAKE_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_SYSTEM_PATH] [CMAKE_FIND_ROOT_PATH_BOTH | ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH] ) 该命令用于给定名字文件所在的路径。一条名为<VAR>的 cache 条目会被创建,并存储 该命令的执行结果。如果在某个路径下发现了该文件,该结果会被存储到该变量中;除非该变量 被清除,该次搜索不会继续进行。如果没有找到,存储的结果将会是<VAR>-NOTFOUND,并 且当下一次以相同的变量名调用 find_path 命令时,该命令会再一次尝试搜索该文件。需要搜 索的文件名通过在 NAMES 选项后面的列出来的参数来确定。 附加的搜索位置可以在 PATHS 选 项之后指定。如果在 PATHS 或者 HINTS 命令中还指定了 ENV var 选项,环境变量 var 将会 被读取并从一个系统环境变量转换为一个 cmake 风格的路径 list。比如,ENV PATH 是列出系 统 path 变量的一种方法。 参数 DOC 将用来作为该变量在 cache 中的注释。 PATH_SUFFIXES 指定了在每个搜索路径下的附加子路径。 如果指定了 NO_DEFAULT_PATH 选项,那么没有其它附加的路径会被加到搜索过程中。 如果并未指定 NO_DEFAULT_PATH 选项,搜索的过程如下: 1、搜索 cmake 专有的 cache 变量中的路径。这种用法是为了在命令行中用选项 -DVAR=value 指定搜索路径。如果指定了 NO_CMAKE_PATH 选项,该路径会被跳过。搜索 路径还包括:

对于每个在 CMAKE_PREFIX_PATH 中的<prefix>/,路径<prefix>/include CMAKE_INCLUDE_PATH CMAKE_FRAMEWORK_PATH 2、搜索 cmake 专有的环境变量中指定的路径。这种用法是为了在用户的 shell 配置中设 置指定的搜索路径。 如果指定了 NO_CMAKE_ENVIRONMENT_PATH 选项, 该路径会被跳过。 搜索路径还包括: 对于每个在 CMAKE_PREFIX_PATH 中的<prefix>/,路径<prefix>/include CMAKE_INCLUDE_PATH CMAKE_FRAMEWORK_PATH 3、搜索由 HINTS 选项指定的路径。这些路径应该是由系统内省时计算得出的路径,比如 由其它已经发现的项目提供的线索。硬编码的参考路径应该在 PATHS 选项中指定。 4、搜索标准的系统环境变量。通过指定选项 NO_SYSTEM_ENVIRONMENT_PATH 可以 跳过搜索环境变量。搜索的路径还包括: PATH INCLUDE 5、查找在为当前系统的平台文件中定义的 cmake 变量。如果指定了 NO_CMAKE_SYSTEM_PATH 选项,该路径会被跳过。搜索的路径还包括: 对于每个在 CMAKE_SYSTEM_PREFIX_PATH 中的<prefix>,路径<prefix>/include CMAKE_SYSTEM_LIBRARY_PATH CMAKE_SYSTEM_FRAMEWORK_PATH 6、搜索 PATHS 选项或者精简版命令指定的路径。这些通常是硬编码的推荐搜索路径。 在 Darwin 或者支持 OS X 框架的系统上,cmake 变量 CMAKE_FIND_FRAMEWORK 可以用来设置为空,或者下述值之一: "FIRST" "LAST" "ONLY" - 在标准库或头文件之前查找框架。在 Darwin 系统上这是默认选项。 - 在标准库或头文件之后查找框架。 - 仅仅查找框架。

"NEVER" - 从不查找框架。 在 Darwin 或者支持 OS X Application Bundles 的系统,cmake 变量 CMAKE_FIND_APPBUNDLE 可以被设置为空或者下面这些值中的一个: "FIRST" 选项。 "LAST" "ONLY" - 在标准库或头文件之后查找 application bundles。 - 仅仅查找 application bundles。 - 在标准库或头文件之前查找 application bundles。在 Darwin 系统上这是默认

"NEVER" - 从不查找 application bundles。 CMake 变量 CMAKE_FIND_ROOT_PATH 指定了一个或者多个优先于其他搜索路径的搜 索路径。该变量能够有效地重新定位在给定位置下进行搜索的根路径。该变量默认为空。当使用 交叉编译时, 该变量十分有用: 用该变量指向目标环境的根目录, 然后 CMake 将会在那里查找。

默认情况下, 在 CMAKE_FIND_ROOT_PATH 中列出的路径会首先被搜索, 然后是“非根”路径。 该默认规则可以通过设置 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY 做出调整。在每次 调用该命令之前,都可以通过设置这个变量来手动覆盖默认行为。如果使用了 NO_CMAKE_FIND_ROOT_PATH 变量,那么只有重定位的路径会被搜索。 默认的搜索顺序的设计逻辑是按照使用时从最具体到最不具体的路径。通过多次调用 find_path 命令以及 NO_*选项,可以覆盖工程的这个默认顺序: find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) find_path(<VAR> NAMES name) 只要这些调用中的一个成功返回,结果变量就会被设置并且被存储到 cache 中;这样随后 的调用都不会再行搜索。在搜索框架时,如果以 A/b.h 的格式指定文件,那么该框架搜索过程 会搜索 A.framework/Headers/b.h。 如果找到了该路径, 它将会被设置为框架的路径。 CMake 将把它转换为正确的-F 选项来包含该文件。

CMD#33:find_program
查找可执行程序 find_program(<VAR> name1 [path1 path2 ...]) 这是该命令的精简格式,它在大多数场合下都够用了。命令 find_program(<VAR> name1 [PATHS path1 path2 ...])是它的等价形式。 find_program( <VAR> name | NAMES name1 [name2 ...] [HINTS path1 [path2 ... ENV var]] [PATHS path1 [path2 ... ENV var]] [PATH_SUFFIXES suffix1 [suffix2 ...]] [DOC "cache documentation string"] [NO_DEFAULT_PATH] [NO_CMAKE_ENVIRONMENT_PATH] [NO_CMAKE_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_SYSTEM_PATH] [CMAKE_FIND_ROOT_PATH_BOTH | ONLY_CMAKE_FIND_ROOT_PATH | NO_CMAKE_FIND_ROOT_PATH] ) 该命令用于查找程序。一个名为<VAR>的 cache 条目会被创建用来存储该命令的结果。 如果该程序被找到了,结果会存储在该变量中,搜索过程将不会再重复,除非该变量被清除。如 果没有找到,结果将会是<VAR>-NOTFOUND,并且下次以相同的变量调用该命令时,还会做 搜索的尝试。被搜索的程序的名字由 NAMES 选项后列出的参数指定。附加的搜索位置可以在 PATHS 参数后指定。如果在 HINTS 或者 PATHS 选项后有 ENV var 参数,环境变量 var 将会

被读取并从系统环境变量转换为 cmake 风格的路径 list。比如 ENV PATH 是一种列出所有系 统 path 变量的方法。DOC 后的参数将会被用作 cache 中的注释字符串。PATH_SUFFIXES 指定了在每个搜索路径下要检查的附加子路径。 如果指定了 NO_DEFAULT_PATH 选项,那么搜索的过程中不会有其他的附加路径。如果 没有指定该选项,搜索过程如下: 1、搜索 cmake 特有的 cache 变量指定的路径。这些变量是在用 cmake 命令行时,通过 -DVAR=value 指定的变量。如果指定了 NO_CMAKE_PATH 选项,这些路径会被跳过。搜索 的路径还包括: 对于每个在 CMAKE_PREFIX_PATH 中的<prefix>,路径<prefix>/[s]bin CMAKE_PROGRAM_PATH CMAKE_APPBUNDLE_PATH 2、 搜索 cmake 特有的环境变量指定的路径。 这些变量是用户的 shell 配置中设置的变量。 如果指定了 NO_CMAKE_ENVIRONMENT_PATH 选项,这些路径会被跳过。搜索的路径还包 括: 对于每个在 CMAKE_PREFIX_PATH 中的<prefix>,路径<prefix>/[s]bin CMAKE_PROGRAM_PATH CMAKE_APPBUNDLE_PATH 3、 搜索由 HINTS 选项指定的路径。 这些路径是系统内省 (introspection) 估算出的路径, 比如由另一个已经发现的程序的地址提供的参考信息。 硬编码的推荐路径应该通过 PATHS 选项 指定。 4、查找标准的系统环境变量。如果指定了 NO_SYSTEM_ENVIRONMENT_PATH 选项, 这些路径会被跳过。搜索的路径还包括: PATH 5、查找在为当前系统的平台文件中定义的 cmake 变量。如果指定了 NO_CMAKE_SYSTEM_PATH 选项,该路径会被跳过。搜索的路径还包括: 对于每个在 CMAKE_SYSTEM_PREFIX_PATH 中的<prefix>,路径<prefix>/[s]bin CMAKE_SYSTEM_PROGRAM_PATH CMAKE_SYSTEM_APPBUNDLE_PATH 6、搜索 PATHS 选项或者精简版命令指定的路径。这些通常是硬编码的推荐搜索路径。 在 Darwin 或者支持 OS X 框架的系统上,cmake 变量 CMAKE_FIND_FRAMEWORK 可以设置为空,或者下述值之一: "FIRST" "LAST" "ONLY" - 在标准库或头文件之前查找框架。在 Darwin 系统上这是默认选项。 - 在标准库或头文件之后查找框架。 - 仅仅查找框架。

"NEVER" - 从不查找框架。 在 Darwin 或者支持 OS X Application Bundles 的系统,cmake 变量 CMAKE_FIND_APPBUNDLE 可以被设置为空或者下面这些值中的一个:

"FIRST" "LAST" "ONLY"

- 在标准程序之前查找 application bundles。在 Darwin 系统上这是默认选项。 - 在标准程序之后查找 application bundles。 - 仅仅查找 application bundles。

"NEVER" - 从不查找 application bundles。 CMake 变量 CMAKE_FIND_ROOT_PATH 指定了一个或者多个优先于其他搜索路径的搜 索路径。该变量能够有效地重新定位在给定位置下进行搜索的根路径。该变量默认为空。当使用 交叉编译时, 该变量十分有用: 用该变量指向目标环境的根目录, 然后 CMake 将会在那里查找。 默认情况下, 在 CMAKE_FIND_ROOT_PATH 中列出的路径会首先被搜索, 然后是“非根”路径。 该默认规则可以通过设置 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY 做出调整。在每次 调用该命令之前,都可以通过设置这个变量来手动覆盖默认行为。如果使用了 NO_CMAKE_FIND_ROOT_PATH 变量,那么只有重定位的路径会被搜索。 默认的搜索顺序的设计逻辑是按照使用时从最具体到最不具体。通过多次以 NO_*选项调 用 find_program 命令,可以覆盖工程的这个默认顺序: find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH) find_library(<VAR> NAMES name) 只要这些调用中的一个成功返回,结果变量就会被设置并且被存储到 cache 中;这样随后 的调用都不会再行搜索。

CMD#34:fltk_wrap_ui
创建 FLTK 用户界面包装器。 fltk_wrap_ui(resultingLibraryName source1 source2 ... sourceN ) 为所有列出的.fl 和.fld 文件生成.h 和.cxx 文件。这些生成的.h 和.cxx 文件将会加到变量 resultingLibraryName_FLTK_UI_SRCS 中,它也会加到你的库中。 如果现在有同一个工程构建出的 Debug 版和 Release 版可执行文件 projectD 和 projectR, 如下的命令可以帮助你把 Debug 版中的符号表加到 Release 版中, 实现对 Release 版的调试。 1、objcopy --only-keep-debug projectD projectsymbol.dbg #生成符号表; 2、gdb -q --symbol=projectsymbol.dbg -exec=projectR #加载符号表; 这下在 gdb 中就可以看到源代码了。

CMD#35 : foreach
对一个 list 中的每一个变量执行一组命令。 foreach(loop_var arg1 arg2 ...) COMMAND1(ARGS ...)

COMMAND2(ARGS ...) ... endforeach(loop_var) 所有的 foreach 和与之匹配的 endforeach 命令之间的命令会被记录下来而不会被调用。 等到遇到 endforeach 命令时,先前被记录下来的命令列表中的每条命令都会为 list 中的每个 变量调用一遍。在每次迭代中,循环变量${loop_var}将会被设置为 list 中的当前变量值。 foreach(loop_var RANGE total) foreach(loop_var RANGE start stop [step]) foreach 命令也可以遍历一个人为生成的数据区间。遍历的方式有三种: *如果指定了一个数字,区间是[0, total]。 *如果指定了两个数字,区间将会是第一个数字到第二个数字。 *第三个数字是从第一个数字遍历到第二个数字时的步长。 foreach(loop_var IN [LISTS [list1 [...]]] [ITEMS [item1 [...]]]) 该命令的含义是:精确遍历一个项组成的 list。LISTS 选项后面是需要被遍历的 list 变量的 名字,包括空元素(一个空字符串是一个零长度 list)。ITEMS 选项结束了 list 参数的解析, 然后在迭代中引入所有在其后出现的项。(猜测是用 list1 中的项 item1,依次类推,为循环变 量赋值。——译注)

CMD#36 :

function

开始记录一个函数,为以后以命令的方式调用它做准备。 function(<name> [arg1 [arg2 [arg3 ...]]]) COMMAND1(ARGS ...) COMMAND2(ARGS ...) ... endfunction(<name>) 定义一个名为<name>的函数,它以 arg1 arg2 arg3 (...)为参数。在 function 之后, 对应的 endfunction 之前列出的命令, 在函数被调用之前, 是不会被调用的。 当函数被调用时, 在函数中记录的那些命令首先会用传进去的参数替换掉形参(${arg1});然后跟正常命令一 样去调用这些命令。 除了形参, 你还可以引用这些变量: ARGC 为传递给函数的变量个数, ARGV0 ARGV1 ARGV2 ...表示传到函数中的实参值。 这些变量为编写可选参数函数提供了便利。 此外, ARGV 保留了一个该函数所有实参的 list,ARGN 保留了函数形参列表以后的所有参数列表。 参见 cmake_policy()命令文档中 function 内部策略行为的相关行为。

CMD#37 :

get_cmake_property

获取一个 CMake 实例的属性。 get_cmake_property(VAR property) 从指定的 CMake 实例中获取属性。 属性的值存储在变量 VAR 中。 如果属性不存在, CMake 会报错。 一些会被支持的属性包括: VATIABLES, COMMANDS, MACROS 以及 COMPONENTS。

CMD#38 :

get_directory_property

获取 DIRECTORY 域中的某种属性。 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>) 在指定的变量中存储路径(directory)域中的某种属性。如果该属性没有被定义,将会返 回空字符串。DIRECTORY 参数指定了要取出的属性值的另一个路径。指定的路径必须已经被 CMake 遍历过了。 get_directory_property(<variable> [DIRECTORY <dir>] DEFINITION <var-name>) 该命令从一个路径中获取一个变量的定义。 这种格式在从另一个路径中获取变量的定义时比 较有用。

CMD#39 :

get_filename_component

得到一个完整文件名中的特定部分。 get_filename_component(<VAR> FileName PATH|ABSOLUTE|NAME|EXT|NAME_WE|REALPATH [CACHE]) 将变量<VAR>设置为路径(PATH),文件名(NAME),文件扩展名(EXT),去掉扩展名的文 件名(NAME_WE),完整路径(ABSOLUTE),或者所有符号链接被解析出的完整路径 (REALPATH)。注意,路径会被转换为 Unix 的反斜杠(/),并且没有结尾的反斜杠。该命令已 经考虑了最长的文件扩展名。如果指定了 CACHE 选项,得到的变量会被加到 cache 中。 get_filename_component(<VAR> FileName PROGRAM [PROGRAM_ARGS <ARG_VAR>] [CACHE]) 在 FileName 中的程序将会在系统搜索路径中被查找,或者是一个完整路径。如果与 PRPGRAM 一起给定了 PROGRAM_ARGS 选项,那么任何在 Filename 字符串中出现的命令 行中选项将会从程序名中分割出来并存储在变量<ARG_VAR>中。这可以用来从一个命令行字 符串中分离程序名及其选项。

CMD#40 :

get_property

获取一个属性值
get_property(<variable> <GLOBAL DIRECTORY [dir] TARGET SOURCE TEST CACHE VARIABLE> PROPERTY <name> [SET | DEFINED | BRIEF_DOCS | FULL_DOCS]) 获取在某个域中一个对象的某种属性值。 第一个参数指定了存储属性值的变量。 第二个参数 确定了获取该属性的域。域的选项仅限于: ? ? ? ? ? ? ? GLOBAL 域是唯一的,它不接受域名字。 DIRECTORY 域默认为当前目录,但是其他的路径(已经被 CMake 处理过)可以以相 对路径或完整路径的方式跟在该域后面。 TARGET 域后面必须跟有一个已有的目标名。 SOURCE 域后面必须跟有一个源文件名。 TEST 域后面必须跟有一个已有的测试。 CACHE 域后面必须跟有一个 cache 条目。 VARIABLE 域是唯一的,它不接受域名字。 | | <target> | <source> | <test> <entry> | |

PROPERTY 选项是必须的,它后面紧跟要获取的属性名。如果该属性没有被设置,该命令 将返回空值。如果给定了 SET 选项,那么返回值会被设置为一个布尔值,用来指示该属性是否 被设置过。如果给定了 DEFINED 选项,那么返回值会被设置为一个布尔值,用来指示该属性 是否被类似于 define_property 的命令定义过。 如果指定了 BRIEF_DOCS 或者 FULL_DOCS 选项, 那么该变量将会被设置为被查询属性的文档的字符串。 如果被请求的属性的文档没有被定 义,将返回 NOTFOUND。

CMD#41 :

get_source_file_property

为一个源文件获取一种属性值。 get_source_file_property(VAR file property) 从一个源文件中获取某种属性值。 这个属性值存储在变量 VAR 中。 如果该属性没有被找到, VAR 会被设置为 NOTFOUND。使用 set_source_files_proterties 命令来设置属性值。源文 件属性通常用来控制文件如何被构建。一个必定存在的属性是 LOCATION。

CMD#42 : get_target_property
从一个目标中获取一个属性值。

get_target_property(VAR target property) 从一个目标中获取属性值。 属性的值会被存储在变量 VAR 中。 如果该属性没有被发现, VAR 会被设置为 NOTFOUND。使用 set_target_properties 命令来设置属性值。属性值一般用于 控制如何去构建一个目标, 但是有些属性用来查询目标的信息。 该命令可以获取当前已经被构建 好的任意目标的属性。该目标不一定存在于当前的 CMakeLists.txt 文件中。

CMD#43 : get_test_property
获取一个测试的属性。 get_test_property(test VAR property) 从指定的测试中获取某种属性。属性值会被存储到变量 VAR 中。如果没有找到该属性, CMake 将会报错。你可以使用命令 cmake --help-property-list 来获取标准属性的清单。

CMD#44 :

if

条件执行一组命令。 if(expression) # then section. COMMAND1(ARGS ...) COMMAND2(ARGS ...) ... elseif(expression2) # elseif section. COMMAND1(ARGS ...) COMMAND2(ARGS ...) ... else(expression) # else section. COMMAND1(ARGS ...) COMMAND2(ARGS ...) ... endif(expression) 评估给定的表达式。如果结果是 true,在 THEN 段的命令就会被调用。否则,在 ELSE 区 段的命令会被调用。 ELSEIF 和 ELSE 区段是可选的 。 可以有多个 ELSEIF 子句。 注意, 在 else 和 elseif 子句中的表达式也是可选的。判断条件可以用长表达式,并且表达式有约定的优先级 顺序。括号中的表达式会首先被调用;然后是一元运算符,比如 EXISTS,COMMAND 以及 DEFINED;然后是 EQUAL,LESS,GREATER,STRLESS,STRGREATER,STREQUAL, MATCHES;然后是 NOT 运算符,最后是 AND,OR 运算符。几种可能的表达式是: if(<常量>)

如果<常量>是 1,ON,YES,TRUE,Y 或者非 0 数值,那么表达式为真;如果<常量> 是 0,OFF,NO,FALSE,N,IGNORE,"",或者以'-NOTFOUND'为后缀,那么表达式为假。 这些布尔常量值是大小写无关的。 if(<变量>) 如果<变量>的值不是一个 false 常量,表达式为真。 if(NOT <表达式>) 如果<表达式>的值是 false 的话,真个表达式为真。 if(<表达式 1> AND <表达式 2>) 如果两个表达式都为真,整个表达式为真。 if(<表达式 1> OR <表达式 2>) 只要有一个表达式为真,整个表达式为真。 if(COMMAND command-name) 如果给出的名字是一个可以被调用的命令,宏,或者函数的话,整个表达式的值为真。 if(POLICY policy-id) 如果给出的名字是一个已有的策略(格式是 CMP<NNNN>),表达式为真。 if(TARGET 目标名) 如果给出的名字是一个已有的构建目标或导入目标的话,表达式为真。 if(EXISTS 文件名) if(EXISTS 路径名) 如果给出的文件名或路径名存在,表达式为真。该命令只对完整路径有效。 if(file1 IS_NEWER_THAN file2) 如果 file1 比 file2 更新或者其中的一个文件不存在,那么表达式为真。该命令只对完整路 径有效。 if(IS_DIRECTORY directory-name) 如果给定的名字是一个路径,表达式返回真。该命令只对完整路径有效。 if(IS_SYMLINK file-name) 如果给定的名字十一个符号链接的话,表达式返回真。该命令只对完整路径有效。 if(IS_ABSOLUTE path) 如果给定的路径是一个绝对路径的话,表达式返回真。 if(variable MATCHES regex)

if(string MATCHES regex) 如果给定的字串或变量值域给定的正则表达式匹配的话,表达式返回真。 if(variable LESS number) if(string LESS number) if(variable GREATER number) if(string GREATER number) if(variable EQUAL number) if(string EQUAL number) 如果给定的字串或变量值是一个有效的数字并且不等号或等号满足的话,表达式返回真。 if(variable STRLESS string) if(string STRLESS string) if(variable STRGREATER string) if(string STRGREATER string) if(variable STREQUAL string) if(string STREQUAL string) 如果给定的字串或变量值依字典序小于(或者大于,或者等于)右边给出的字串或变量值的 话,表达式返回真。 if(version1 VERSION_LESS version2) if(version1 VERSION_EQUAL version2) if(version1 VERSION_GREATER version2) 对版本号的各部分依次比较 (版本号格式是 major[.minor[.patch[.tweak]]]) version1 和 version2 的大小。 if(DEFINED variable) 如果给定的变量被定义了的话,该表达式为真。如果变量被设置了,它的值是真是假都无所 谓。 if((expression) AND (expression OR (expression))) 在小括号内的表达式会首先被计算,然后才按照先前介绍的运算来计算。有内嵌的括号时, 最里的括号会作为包含它们的表达式的计算过程的一部分。IF 语句在 CMake 的历史上出现的 相当早,它拥有一些需要特殊介绍的便捷特性。IF 表达式只有在其中有一个单一的保留值的时 候,才会精简操作(即不做变量展开——译注);这些保留值包括:如果是大小写无关的 ON, 1, YES, TRUE, Y, 它返回真; 如果是 OFF, 0, NO, FALSE, N, NOTFOUND, *-NOTFOUND, IGNORE, 它返回假。 这种特性非常合理, 它为新作者提供了一种不需要精确匹配 true 或者 false 的便利性。这些值会被当做变量处理,即使它们没有使用${}语法的时候,也会被解引用。这意 味着,如果你写下了这样的语句: if (boobah) CMake 将会把它当做你写了 if (${boobah})

来处理。类似地,如果你写了 if (fubar AND sol) CMake 将会便捷地把它解释为 if ("${fubar}" AND "${sol}") 上述两例的后者确实是正确的书写方式,但是前者也是可行的。if 语句中只有某些操作有这 种特殊的变量处理方式。这些特殊的语句包括: 对于 MATCHES 运算符,待匹配的左边的参数首先被检查,用来确认它是否是一个已经定 义的变量;如果是,该变量的值会被使用,否则就会用它的原始值。 如果 MATCHES 运算符没有左边的参数,它返回 false,但不产生错误。 LESS,GREATER,EQUAL 运算符的左边的参数和右边的参数会被独立测试,用来确认它 们是否是被定义的变量;如果是,使用它们被定义的值,否则使用它们的原始值。 STRLESS, STRGREATER, STREQUAL 运算符的左边的参数和右边的参数会被独立测试, 用来确认它们是否是被定义的变量; 如果是, 使用它们被定义的值, 否则使用它们的原始值。 VERSIONLESS,VERSIONGREATER,VERSIONEQUAL 运算符的左边的参数和右边的 参数会被独立测试,用来确认它们是否是被定义的变量;如果是,使用它们被定义的值,否 则使用它们的原始值。 NOT 运算符右边的参数会被测试用来确定它是否是布尔常量,如果是,就用这个常量;否 则它会被当做一个变量然后被解引用。 AND 和 OR 运算符的左边的参数和右边的参数会被独立测试,用来确认它们是否是布尔常 量;如果是,就用这个常量,否则它们会被当做变量然后被解引用。

CMD#45

:

include

从给定的文件中读取 CMake 的列表文件。 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>] [NO_POLICY_SCOPE]) 从给定的文件中读取 CMake 的清单文件代码。在清单文件中的命令会被立即处理,就 像它们是写在这条 include 命令展开的地方一样。如果指定了 OPTIONAL 选项,那么如果 被包含文件不存在的话,不会报错。如果指定了 RESULT_VARIABLE 选项,那么 var 或者 会被设置为被包含文件的完整路径,或者是 NOTFOUND,表示没有找到该文件。 如果指定的是一个模块(module)而不是一个文件,查找的对象会变成路径 CMAKE_MODULE_PATH 下的文件<modulename>.camke。 参考 cmake_policy()命令文档中关于 NO_POLICY_SCOPE 选项的讨论。

CMD#46 : include_directories
为构建树添加包含路径。 include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...) 将给定的路径添加到编译器搜索包含文件(.h 文件)的路径列表中。缺省情况下,该 路径会被附加在当前路径列表的后面。这种缺省行为可以通过设置 CMAKE_include_directories_BEFORE 变量为 ON 被改变。通过将该变量改变为 BEFORE 或 AFTER, 你可以在追加和附加在前端这两种方式中选择, 而不用理会缺省设置。 如果指定了 SYSTEM 选项,编译器将会认为该路径是某种平台上的系统包含路径。

CMD#47

:

include_external_msproject

在一个 workspace 中包含一个外部的 Microsoft 工程。 include_external_msproject(projectname location dep1 dep2 ...) 在生成的 workspace 文件中包含一个外部的 Microsoft 工程。它会创建一个名为 [projectname]的目标。这个目标可以用在 add_dependencies 命令中让其他工程依赖 于这个外部工程。当前版本下,该命令在 UNIX 平台上不会做任何事情。

CMD#48 : include_regular_expression
设置用于依赖性检查的正则表达式。
include_regular_expression(regex_match [regex_complain]) 设置依赖性检查的正则表达式。 这有匹配正则表达式 regex_match 的文件会成为依赖 性跟踪的对象。 只有匹配 regex_complain 的文件, 在找不到它们的时候才会给出警告 (标 准头文件不会被搜索)。正则表达式的默认值是: regex_match = "^.*$" (匹配所有文件)

regex_complain = "^$" (仅匹配空字符串)

CMD#49 :

install

指定在安装时要运行的规则。
该命令为一个工程生成安装规则。在某一源文件路径中,调用这条命令所指定的规则会 在安装时按顺序执行。在不同路径之间的顺序未定义。 该命令有诸多版本。其中的一些版本定义了文件以及目标的安装属性。这多个版本的公 共属性都有所涉及,但是只有在指定它们的版本中,这些属性才是合法的(下面的 DESTIONATION 到 OPTIONAL 的选项列表是公共属性。——译注)。

DESTINATION 选项指定了一个文件会安装到磁盘的哪个路径下。若果给出的是全路 径(以反斜杠或者驱动器名开头),它会被直接使用。如果给出的是相对路径,它会被解释 为相对于 CMAKE_INSTALL_PREFIX 的值的相对路径。 PERMISSIONS 选项制定了安装文件需要的权限。合法的权限有:OWNER_READ, OWNER_WRITE,OWNER_EXECUTE,GROUP_READ,GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID 和 SETGID。对于在某些特定的平台上没有意义的权限,在这些平台上会忽略这些选项。 CONFIGURATIONS 选项指定了该安装规则将会加诸之上的一系列的构建配置 (Debug,Release,等等)。 COMPONENT 选项指定了该安装规则相关的一个安装部件的名字,比如“runtime”或 “development”。对于那些指定安装部件的安装过程来说,在安装时只有与给定的部件名 相关的安装规则会被执行。对于完整安装,所有部件都会被安装。 RENAME 选项为一个可能不同于原始文件的已经安装的文件指定另一个名字。重命名 只有在该命令正在安装一个单一文件时才被允许 (猜测是为了防止文件名冲突时覆盖掉旧文 件。——译注)。 OPTIONAL 选项表示要安装的文件不存在不会导致错误。 TARGETS 版本的 install 命令 install(TARGETS targets... [EXPORT <export-name>] [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE| PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] [DESTINATION <dir>] [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [OPTIONAL] [NAMELINK_ONL