CMake最全实践3

CMake 常⽤指令

前⾯我们讲到了cmake 常⽤的变量，相信“cmake 即编程”的感觉会越来越明显，⽆论如何，我们仍然可以看到cmake ⽐autotools 要简单很多。接下来我们就要集中的看⼀看 cmake 所提供的常⽤指令。在前⾯的章节我们已经讨论了很多指令的⽤法，如

PROJECT，ADD_EXECUTABLE，INSTALL，ADD_SUBDIRECTORY，SUBDIRS，INCLUDE_DIRECTORIES，LINK_DIRECTORIES，TARGET_LINK_LIBRARIES，SET 等。

本节会引⼊更多的cmake 指令，为了编写的⽅便，我们将按照 cmake man page 的顺序来介绍各种指令，不再推荐使⽤的指令将不再介绍，INSTALL 系列指令在安装部分已经做了⾮常详细的说明，本节也不在提及。

基本指令

(1)ADD_DEFINITIONS

向C/C++编译器添加-D 定义，⽐如:

ADD_DEFINITIONS(-DENABLE_DEBUG -DABC)，参数之间⽤空格分割。另外，也可以定义变量，这个变量可以在代码中直接使用，如ADD_DEFINITIONS(-DARG="abc")，在程序中就可以使用ARG这个变量。

如果你的代码中定义了#ifdef ENABLE_DEBUG #endif，这个代码块就会⽣效。如果要添加其他的编译器开关，可以通过 CMAKE_C_FLAGS 变量和CMAKE_CXX_FLAGS 变量设置。

(2)ADD_DEPENDENCIES

定义target 依赖的其他target，确保在编译本target 之前，其他的target 已经被构建。

ADD_DEPENDENCIES(target-name depend-target1 depend-target2 ...)

(3)ADD_EXECUTABLE、ADD_LIBRARY、ADD_SUBDIRECTORY 前⾯已经介绍过了，这⾥不再说。

(4)ADD_TEST 与ENABLE_TESTING 指令

ENABLE_TESTING 指令⽤来控制 Makefile 是否构建test ⽬标，涉及⼯程所有⽬录。语法很简单，没有任何参数，ENABLE_TESTING()，⼀般情况这个指令放在⼯程的主 CMakeLists.txt 中。

ADD_TEST 指令的语法是:

ADD_TEST(testname Exename arg1 arg2 ...)

testname 是⾃定义的test 名称，Exename 可以是构建的⽬标⽂件也可以是外部脚本等等。后⾯连接传递给可执⾏⽂件的参数。如果没有在同⼀个 CMakeLists.txt 中打开ENABLE_TESTING()指令，任何 ADD_TEST 都是⽆效的。

⽐如我们前⾯的Helloworld 例⼦，可以在⼯程主CMakeLists.txt 中添加 ADD_TEST(mytest ${PROJECT_BINARY_DIR}/bin/main)和 ENABLE_TESTING()

⽣成Makefile 后，就可以运⾏ make test 来执⾏测试了。

(5)AUX_SOURCE_DIRECTORY

基本语法是：

AUX_SOURCE_DIRECTORY(dir VARIABLE)

作⽤是发现⼀个⽬录下所有的源代码⽂件并将列表存储在⼀个变量中，这个指令临时被⽤来⾃动构建源⽂件列表。因为⽬前cmake 还不能⾃动发现新添加的源⽂件。

⽐如

AUX_SOURCE_DIRECTORY(. SRC_LIST)

ADD_EXECUTABLE(main ${SRC_LIST})

也可以通过后⾯提到的FOREACH 指令来处理这个LIST。

(6)CMAKE_MINIMUM_REQUIRED

其语法为CMAKE_MINIMUM_REQUIRED(VERSION versionNumber [FATAL_ERROR])，⽐如CMAKE_MINIMUM_REQUIRED(VERSION 2.5 FATAL_ERROR)。如果cmake 版本⼩与2.5，则出现严重错误，整个过程中⽌。

(7)EXEC_PROGRAM

在 CMakeLists.txt 处理过程中执⾏命令，并不会在⽣成的 Makefile 中执⾏。具体语法为：

⽤于在指定的⽬录运⾏某个程序，通过 ARGS 添加参数，如果要获取输出和返回值，可通过OUTPUT_VARIABLE 和RETURN_VALUE 分别定义两个变量。这个指令可以帮助你在CMakeLists.txt 处理过程中⽀持任何命令，⽐如根据系统情况去修改代码⽂件等。

举个简单的例⼦，我们要在src ⽬录执⾏ ls 命令，并把结果和返回值存下来。

可以直接在src/CMakeLists.txt 中添加：

在 cmake ⽣成 Makefile 的过程中，就会执⾏ls 命令，如果返回0，则说明成功执⾏，那么就输出ls *.c的结果。关于IF 语句，后⾯的控制指令会提到。这⾥的语法都⽐较简单，不在展开介绍了。

(8)FILE 指令

⽂件操作指令，基本语法为:

FILE(WRITE filename "message to write"... )

FILE(APPEND filename "message to write"... )

FILE(READ filename variable)

FILE(GLOB variable [RELATIVE path] [globbing expressions]...)

FILE(GLOB_RECURSE variable [RELATIVE path] [globbing expressions]...)

FILE(REMOVE [directory]...)

FILE(REMOVE_RECURSE [directory]...)

FILE(MAKE_DIRECTORY [directory]...)

FILE(RELATIVE_PATH variable directory file)

FILE(TO_CMAKE_PATH path result)

FILE(TO_NATIVE_PATH path result)

(9)INCLUDE 指令，⽤来载⼊CMakeLists.txt ⽂件，也⽤于载⼊预定义的cmake 模块. INCLUDE(file1[OPTIONAL])

INCLUDE(module [OPTIONAL])

OPTIONAL 参数的作⽤是⽂件不存在也不会产⽣错误。

你可以指定载⼊⼀个⽂件，如果定义的是⼀个模块，那么将在 CMAKE_MODULE_PATH 中搜索这个模块并载⼊。载⼊的内容将在处理到INCLUDE 语句是直接执⾏。

FIND_指令

FIND_系列指令主要包含⼀下指令：

VAR 变量代表找到的⽂件全路径，包含⽂件名:

FIND_FILE(<VAR> name1 path1 path2 ...)

VAR 变量表示找到的库全路径，包含库⽂件名:

FIND_LIBRARY(<VAR> name1 path1 path2 ...)

VAR 变量代表包含这个⽂件的路径:

FIND_PATH(<VAR> name1 path1 path2 ...)

VAR 变量代表包含这个程序的全路径:

FIND_PROGRAM(<VAR> name1 path1 path2 ...)

FIND_PACKAGE(<name> [major.minor] [QUIET] [NO_MODULE] [[REQUIRED|COMPONENTS]

[componets...]])

⽤ 来 调 ⽤ 预 定 义 在 CMAKE_MODULE_PATH 下 的 Find<name>.cmake 模 块 ， 你 也 可 以 ⾃ ⼰ 定 义Find<name>模块，通过SET(CMAKE_MODULE_PATH dir)将其放⼊⼯程的某个⽬录中供⼯程使⽤，我们在后⾯的章节会详细介绍 FIND_PACKAGE 的使⽤⽅法和 Find 模块的编写。

FIND_LIBRARY 示例：

FIND_LIBRARY(libX X11 /usr/lib)

IF(NOT libX)

MESSAGE(FATAL_ERROR “libX not found”)

ENDIF(NOT libX)

控制指令

(1)IF 指令，基本语法为：

另外⼀个指令是ELSEIF，总体把握⼀个原则，凡是出现IF 的地⽅⼀定要有对应的ENDIF。出现 ELSEIF 的地⽅，ENDIF 是可选的。

表达式的使⽤⽅法如下:

IF(var)，如果变量不是：空，0，N, NO, OFF, FALSE, NOTFOUND 或 <var>_NOTFOUND 时，表达式为真。

IF(NOT var )，与上述条件相反。

IF(var1 AND var2)，当两个变量都为真是为真。

IF(var1 OR var2)，当两个变量其中⼀个为真时为真。

IF(COMMAND cmd)，当给定的 cmd 确实是命令并可以调⽤是为真

IF(EXISTS dir)或者IF(EXISTS file)，当⽬录名或者⽂件名存在时为真。

IF(file1 IS_NEWER_THAN file2)，当file1 ⽐file2 新，或者file1/file2 其中有⼀个不存在时为真，⽂件名请使⽤完整路径。

IF(IS_DIRECTORY dirname)，当 dirname 是⽬录时，为真。

IF(variable MATCHES regex)

IF(string MATCHES regex)

当给定的变量或者字符串能够匹配正则表达式 regex 时为真。⽐如：

数字⽐较表达式

IF(DEFINED variable)，如果变量被定义，为真。

⼀个⼩例⼦，⽤来判断平台差异：

上述代码⽤来控制在不同的平台进⾏不同的控制，但是，阅读起来却并不是那么舒服，ELSE(WIN32)之类的语句很容易引起歧义。

这就⽤到了我们在“常⽤变量”⼀节提到的 CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS 开关。可以SET(CMAKE_ALLOW_LOOSE_LOOP_CONSTRUCTS ON)

这时候就可以写成:

如果配合ELSEIF 使⽤，可能的写法是这样:

(2).WHILE

WHILE 指令的语法是：

其真假判断条件可以参考IF 指令。

(3)FOREACH

FOREACH 指令的使⽤⽅法有三种形式：

像我们前⾯使⽤的AUX_SOURCE_DIRECTORY 的例⼦ AUX_SOURCE_DIRECTORY(. SRC_LIST)。

范围

 

 

范围和步进

FOREACH(loop_var RANGE start stop [step])

ENDFOREACH(loop_var)

从 start 开始到stop 结束，以step 为步进

这个指令需要注意的是，知道遇到ENDFOREACH 指令，整个语句块才会得到真正的执⾏。

模块的使⽤和⾃定义模块

本章我们将着重介绍系统预定义的Find 模块的使⽤以及⾃⼰编写Find 模块，系统中提供了其他各种模块，⼀般情况需要使⽤INCLUDE 指令显式的调⽤，FIND_PACKAGE 指令是⼀个特例，可以直接调⽤预定义的模块。

使⽤FindCURL 模块

在cmake ⽬录建⽴ t5 ⽬录，⽤于存放我们的CURL 的例⼦。建⽴src ⽬录，并建⽴src/main.c，内容如下：

 

这段代码的作⽤是通过curl 取回www.linux-ren.org 的⾸⻚并写⼊/tmp/curl-test⽂件中。

建⽴主⼯程⽂件CMakeLists.txt

PROJECT(CURLTEST)

ADD_SUBDIRECTORY(src)

建⽴src/CMakeLists.txt

ADD_EXECUTABLE(curltest main.c)

现在⾃然是没办法编译的，我们需要添加 curl 的头⽂件路径和库⽂件。

⽅法1：

直接通过INCLUDE_DIRECTORIES 和TARGET_LINK_LIBRARIES 指令添加：我们可以直接在

src/CMakeLists.txt 中添加：

INCLUDE_DIRECTORIES(/usr/include)

TARGET_LINK_LIBRARIES(curltest curl)

然后建⽴build ⽬录进⾏外部构建即可。现在我们要探讨的是使⽤cmake 提供的 FindCURL 模块。

⽅法2:使⽤FindCURL 模块

向 src/CMakeLists.txt 中添加：

对于系统预定义的Find<name>.cmake 模块，使⽤⽅法⼀般如上例所示。

每⼀个模块都会定义以下⼏个变量。

(1)<name>_FOUND

(2)<name>_INCLUDE_DIR or <name>_INCLUDES

(3)<name>_LIBRARY or <name>_LIBRARIES

可以通过<name>_FOUND 来判断模块是否被找到，如果没有找到，按照⼯程的需要关闭某些特性、给出提醒或者中⽌编译，上⾯的例⼦就是报出致命错误并终⽌构建。

如果<name>_FOUND 为真，则将<name>_INCLUDE_DIR 加⼊INCLUDE_DIRECTORIES，将<name>_LIBRARY 加⼊ TARGET_LINK_LIBRARIES 中。

我们再来看⼀个复杂的例⼦，通过<name>_FOUND 来控制⼯程特性：

ADD_EXECUTABLE(viewer ${mySources} ${optionalSources} )

TARGET_LINK_LIBRARIES(viewer${optionalLibs}

通过判断系统是否提供了JPEG 库来决定程序是否⽀持JPEG 功能。

编写FindHello 模块

构建动态库、静态库的过程并进⾏了安装。如何⾃定义FindHELLO 模块并使⽤这个模块构建⼯程：

请在建⽴cmake/中建⽴t6 ⽬录，并在其中建⽴cmake⽬录⽤于存放我们⾃⼰定义的FindHELLO.cmake模块，同时建⽴src ⽬录，⽤于存放我们的源⽂件。

(1)定义 cmake/FindHELLO.cmake 模块

针对上⾯的模块让我们再来回顾⼀下FIND_PACKAGE 指令：

前⾯的CURL 例⼦中我们使⽤了最简单的FIND_PACKAGE 指令，其实他可以使⽤多种参数，QUIET 参数，对应与我们编写的 FindHELLO 中的 HELLO_FIND_QUIETLY，如果不指定这个参数，就会执⾏：

MESSAGE(STATUS "Found Hello: ${HELLO_LIBRARY}")

REQUIRED 参数，其含义是指这个共享库是否是⼯程必须的，如果使⽤了这个参数，说明这个链接库是必备库，如果找不到这个链接库，则⼯程不能编译。对应于 FindHELLO.cmake 模块中的HELLO_FIND_REQUIRED 变量。

同样，我们在上⾯的模块中定义了HELLO_FOUND, HELLO_INCLUDE_DIR,HELLO_LIBRARY 变量供开发者在FIND_PACKAGE 指令中使⽤。

下⾯建⽴src/main.c，内容为：

#include <hello.h>
int main()
{
  HelloFunc();
  return 0;
}

建⽴src/CMakeLists.txt ⽂件，内容如下：

为了能够让⼯程找到FindHELLO.cmake 模块(存放在⼯程中的 cmake ⽬录)。在主⼯程⽂件CMakeLists.txt 中加⼊：

SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)

⾃定义的FindHELLO 模块构建⼯程

仍然采⽤外部编译的⽅式，建⽴build ⽬录，进⼊⽬录运⾏：

cmake ..

可以从输出中看到：

Found Hello: /usr/lib/libhello.so

把上⾯的FIND_PACKAGE(HELLO)修改为FIND_PACKAGE(HELLO QUIET),则不会看到上⾯的输出。QUIET是防止输出。

接下来就可以使⽤make 命令构建⼯程，运⾏:

./src/hello 可以得到输出。

Hello World

说明⼯程成功构建。

没有找到hello library 呢？

可以尝试将/usr/lib/libhello.x 移动到/tmp ⽬录，这样，按照 FindHELLO 模块的定义，就找不到hello library 了，我们再来看⼀下构建结果：

cmake ..

仍然可以成功进⾏构建，但是这时候是没有办法编译的。修改FIND_PACKAGE(HELLO)为FIND_PACKAGE(HELLO REQUIRED)，将hello library 定义为⼯程必须的共享库。REQUIRED表示必须的共享库。

再次运⾏

cmake ..

得到如下输出：

CMake Error: Could not find hello library.

因为找不到libhello.x，所以，整个Makefile ⽣成过程被出错中⽌。

学习了如何使⽤系统提供的 Find<NAME>模块并学习了⾃⼰编写Find<NAME>模块以及如何在⼯程中使⽤这些模块。