CMake 手册详解（八）

上周正在准备转正答辩，手册翻译的事情暂时搁浅了一段时间；现在继续《CMake手册详解》之第八篇：

=======================================================

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命令时，对应的选项可以获取这些描述信息。