目录
一、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#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#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
当cmake在一个空的构建树上第一次运行时,它会创建一个CMakeCache.txt文件,然后向其中写入可定制的项目设置数据。-C选项可以用来指定一个文件,在第一次解析这个工程的cmake清单文件时,从这个文件加载缓存的条目(cache entries)信息。被加载的缓存条目比项目默认的值有更高的优先权。参数中给定的那个文件应该是一个CMake脚本,其中包含有使用CACHE选项的SET命令;而不是一个缓存格式的文件。
-D :
当cmake第一次运行于一个空的构建数时,它会创建一个CMakeCache.txt文件,并且使用可定制的工程设置来填充这个文件。这个选项可以用来指定优先级高于工程的默认值的工程设置值。这个参数可以被重复多次,用来填充所需要数量的缓存条目(cache entries)。
-U
该选项可以用来删除CMakeCache.txt文件中的一或多个变量。文件名匹配表达式(globbing expression)支持通配符*和?的使用。该选项可以重复多次以删除期望数量的缓存条目。使用它时要小心,你可能因此让自己的CMakeCache.txt罢工。
-G
在具体的平台上,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
该选项用以下的选项概括了内置构建工具的命令行界面
--target
--config
--clean-first = 首先构建目标的clean伪目标,然后再构建。
(如果仅仅要clean掉,使用--target 'clean'选项。) -- = 向内置工具(native tools)传递剩余的选项。
运行不带选项的cmake --build来获取快速帮助信息。
-N: 查看模式。
仅仅加载缓存信息,并不实际运行配置和生成步骤。
-P
将给定的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
为生成的构建系统添加一条自定义的构建规则。
ad d_custom_comma nd命令有两种主要的功能;第一种是为了生成输出文件,添加
一条自定义命令。
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[MAIN_DEPENDENCY depend]
[DEPENDS [depends...]]
[IMPLICIT_DEPENDS
[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(
[EXCLUDE_FROM_ALL]
source1 source2 ... sourceN)
引入一个名为
默认情况下,可执行文件将会在构建树的路径下被创建,对应于该命令被调用的源文件树的路径。如果要改变这个位置,查看RUNTIME_OUTPUT_DIRECTORY目标属性的相关文档。如果要改变最终文件名的
如果指定了MACOSX_BUNDLE选项,对应的属性会附加在创建的目标上。查看MACOSX_BUNDLE目标属性的文档可以找到更多的细节。
如果指定了EXCLUDE_FROM_ALL选项,对应的属性将会设置在被创建的目标上。查看EXCLUDE_FROM_ALL目标属性的文档可以找到更多的细节。
使用下述格式,add_executable命令也可以用来创建导入的(IMPORTED)可执行目标:
add_executable(
一个导入的可执行目标引用了一个位于工程之外的可执行文件。该格式不会生成构建这个目标的规则。该目标名字的作用域在它被创建的路径以及底层路径有效。它可以像在该工程内的其他任意目标一样被引用。导入可执行文件为类似于add_custom_command之类的命令引用它提供了便利。
关于导入的可执行文件的细节可以通过设置以IMPORTED_开头的属性来指定。这类属性中最重要的是IMPORTED_LOCATION(以及它对应于具体配置的版本
IMPORTED_LOCATION_
CMD#6:add_library
使用指定的源文件向工程中添加一个库。
add_library(
[EXCLUDE_FROM_ALL]
source1 source2 ... sourceN)
添加一个名为
实际文件名根据对应平台的命名约定来构造(比如lib
默认状态下,库文件将会在于源文件目录树的构建目录树的位置被创建,该命令也会在这里被调用。查阅ARCHIVE_OUTPUT_DIRECTORY,LIBRARY_OUTPUT_DIRECTORY,和RUNTIME_OUTPUT_DIRECTORY这三个目标属性的文档来改变这一位置。查阅
OUTPUT_NAME目标属性的文档来改变最终文件名的
如果指定了EXCLUDE_FROM_ALL属性,对应的一些属性会在目标被创建时被设置。查
阅EXCLUDE_FROM_ALL的文档来获取该属性的细节。
使用下述格式,add_library命令也可以用来创建导入的库目标:
add_library(
导入的库目标是引用了在工程外的一个库文件的目标。没有生成构建这个库的规则。这个目标名字的作用域在它被创建的路径及以下有效。他可以向任何在该工程内构建的目标一样被引用。导入库为类似于target_link_libraries命令中引用它提供了便利。关于导入库细节可以通过指定那些以IMPORTED_的属性设置来指定。其中最重要的属性是IMPORTED_LOCATION(以及它的具体配置版本,IMPORTED_LOCATION_
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
COMMAND
如果COMMAND选项指定了一个可执行目标(用add_executable创建),它会自动被在构建时创建的可执行文件所替换。如果指定了CONFIGURATIONS选项,那么该测试只有在列出的某一个配置下才会运行。
在COMMAND选项后的参数可以使用“生成器表达式”,它的语法是"$<...>"。这些表达式会在构建系统生成期间,以及构建配置的专有信息的产生期间被评估。合法的表达式是:
$
$
$
$
其中,"tgt"是目标的名称。目标文件表达式TARGET_FILE生成了一个完整的路径,但是它的_DIR和_NAME版本可以生成目录以及文件名部分:
$
$
$
用例:
1 add_test(NAME mytest
2 COMMAND testDriver --config $
3 --exe $
这段代码创建了一个名为mytest的测试,它执行的命令是testDriver工具,传递的参数包括配置名,以及由目标生成的可执行文件myexe的完整路径。
CMD#9:aux_source_directory
查找在某个路径下的所有源文件。
aux_source_directory(
搜集所有在指定路径下的源文件的文件名,将输出结果列表储存在指定的
使用该命令来避免为一个库或可执行目标写源文件的清单,是非常具有吸引力的。但是如果该命令貌似可以发挥作用,那么CMake就不需要生成一个感知新的源文件何时被加进来的构建系统了(也就是说,新文件的加入,并不会导致CMakeLists.txt过时,从而不能引起CMake 重新运行。——译注)。正常情况下,生成的构建系统能够感知它何时需要重新运行CMake,因为需要修改CMakeLists.txt来引入一个新的源文件。当源文件仅仅是加到了该路径下,但是没有修改这个CMakeLists.txt文件,使用者只能手动重新运行CMake来产生一个包含这个新文件的构建系统。
CMD#10:break
从一个包围该命令的foreach或while循环中跳出。
break()
从包围它的foreach循环或while循环中跳出。
CMD#11:build_command
获取构建该工程的命令行。
build_command(
[CONFIGURATION
[PROJECT_NAME
[TARGET
把给定的变量
CMAKE_GENERATOR确定的项目构建工具,去构建某一个工程的某一个目标配置的命令行。
对于多配置生成器,如果忽略CONFIGURATION选项,CMake将会选择一个合理的默认值;而对于单配置生成器,该选项会被忽略。
如果PROJECT_NAME选项被忽略,得到的命令行用来构建当前构建树上的顶层工程。
如果TARGET选项被忽略,得到的命令行可以用来构建所有目标,比较高效的用法是构建目标all或者ALL_BUILD。
build_command(
不推荐使用以上的这种格式,但对于后相兼容还是有用的。只要可以,就要使用第一种格式。
这种格式将变量
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
cmake_policy是用来设置“新行为”或“旧行为”的命令。如果支持单独设置策略,我们鼓励各项目根据CMake的版本来设置策略。
cmake_policy(VERSION major.minor[.patch[.tweak]])