CMake 入门实战

什么是 CMake

cmake.jpg

CMake是个一个开源的跨平台自动化建构系统，用来管理软件建置的程序，并不相依于某特定编译器。

并可支持多层目录、多个应用程序与多个库。 它用配置文件控制建构过程（build process）的方式和Unix的make相似，只是CMake的配置文件取名为CMakeLists.txt。

CMake并不直接建构出最终的软件，而是产生标准的建构档（如Unix的Makefile或Windows Visual C++的projects/workspaces），然后再依一般的建构方式使用。

这使得熟悉某个集成开发环境（IDE）的开发者可以用标准的方式建构他的软件，这种可以使用各平台的原生建构系统的能力是CMake和SCons等其他类似系统的区别之处。

它首先允许开发者编写一种平台无关的CMakeList.txt 文件来定制整个编译流程，然后再根据目标用户的平台进一步生成所需的本地化 Makefile 和工程文件，如 Unix的 Makefile 或 Windows 的 Visual Studio 工程。从而做到“Write once, run everywhere”。显然，CMake 是一个比上述几种 make 更高级的编译配置工具。

“CMake”这个名字是"Cross platform MAke"的缩写。虽然名字中含有"make"，但是CMake和Unix上常见的“make”系统是分开的，而且更为高端。 它可与原生建置环境结合使用，例如：make、苹果的Xcode与微软的Visual Studio。

CMake维基百科地址

文中代码github地址

本文采用 JetBrains CLion 与 CMake 作为 开发与编译工具，和大家一起走进CMake，了解CMake。

单个源文件

首先创建项目，选择如下图：

20190121093117.png

项目创建侯如下图所示目录：

20190121093324.png 20190121093307.png

对于简单的项目，只需要写几行代码就可以了。现在我们的项目中只有一个源文件 main.cc，该程序的用途是计打印出Hello, World!。

编写 CMakeLists.txt

CMakeLists.txt 文件，保存在与 main.cc源文件同个目录下：

# CMake 最低版本号要求
cmake_minimum_required(VERSION 3.10.2)
# 项目信息
project(CMakeDemo C)
# 设置C语言标准
set(CMAKE_C_STANDARD 99)
# 指定生成目标
add_executable(CMakeDemo main.c)

CMakeLists.txt 的语法比较简单，由命令、注释和空格组成，其中命令是不区分大小写的。符号 # 后面的内容被认为是注释。命令由命令名称、小括号和参数组成，参数之间使用空格进行间隔。

对于上面的 CMakeLists.txt 文件，依次出现了几个命令：

1. cmake_minimum_required：指定运行此配置文件所需的 CMake 的最低版本；

2. project：参数值是 CMakeDemo，该命令表示项目的名称是 `CMakeDemo。

3. add_executable： 将名为 main.cc 的源文件编译成一个名称为 CMakeDemo的可执行文件。

运行程序，看打印结果：

20190121094108.png

我们还可以手动编译项目（下面示例皆可以此方法编译。Linux环境下，Windows配置较为麻烦）

在当前目录执行 cmake . ，得到 Makefile 后再使用 make 命令编译得到 CMakeDemo可执行文件。

cmakemake.png

大家可以看到相关编译过程与运行结果。

多个源文件

同一目录，多个源文件

下面我们新建MathUtils.c，将一些常用数学运算加入其中，并在main.c中调用。

cmaketwo.png

唯一的改动只是在 add_executable 命令中增加了一个 MathUtils.c 源文件。这样写当然没什么问题，但是如果源文件很多，把所有源文件的名字都加进去将是一件烦人的工作。更省事的方法是使用 aux_source_directory 命令，该命令会查找指定目录下的所有源文件，然后将结果存进指定变量名。其语法如下：

aux_source_directory(<dir> <variable>)

cmakethree.png

这样，CMake 会将当前目录所有源文件的文件名赋值给变量 DIR_SRCS ，再指示变量 DIR_SRCS 中的源文件需要编译成一个名称为 CMakeDemo的可执行文件。

多个目录，多个源文件

一，CMake添加动态链接库

现在进一步将 MathUtils.h 和 MathUtils.c文件移动到 math 目录下。

cmakefour.png

运行报错，我们未将转移的C和H文件添加到CMakeLists.txt

对于这种情况，需要分别在项目根目录 CMakeDemo和 math 目录里各编写一个 CMakeLists.txt 文件。为了方便，我们可以先将 math 目录里的文件编译成静态库再由 main 函数调用。

根目录中的 CMakeLists.txt ：

cmakefive.png

cmake_minimum_required(VERSION 3.13)
project(CMakeDemo C)

set(CMAKE_C_STANDARD 99)

# 查找当前目录下的所有源文件
# 并将名称保存到 DIR_SRCS 变量
aux_source_directory(. DIR_SRCS)
# 指定生成目标
add_executable(CMakeDemo ${DIR_SRCS})

# 添加 math 子目录
add_subdirectory(math)

# 添加链接库
target_link_libraries(CMakeDemo MathUtils)

math/CMakeLists.txt如下：

# 查找当前目录下的所有源文件
# 并将名称保存到 DIR_LIB_SRCS 变量
aux_source_directory(. DIR_LIB_SRCS)
# 指定生成 MathUtils 链接库
add_library (MathUtils ${DIR_LIB_SRCS})#命令 add_library 将 src 目录中的源文件编译为静态链接库。

该文件添加了下面的内容: 使用命令 add_subdirectory 指明本项目包含一个子目录 math，这样 math 目录下的 CMakeLists.txt 文件和源代码也会被处理 。使用命令 target_link_libraries 指明可执行文件 main 需要连接一个名为 MathUtils 的链接库 。

二，add_executable添加相对路径（单个简单项目推荐，不需要再配置其他CMakeLists）

# CMake 最低版本号要求
cmake_minimum_required(VERSION 3.10.2)
# 项目信息
project(CMakeDemo C)
# 设置C语言标准
set(CMAKE_C_STANDARD 99)
# 指定生成目标和源码路径
add_executable(CMakeDemo main.c math/MathUtils.c math/MathUtils.h)

cmakesix.png

三，添加其他第三方开源库（以cjson为示例）

cmakeeight.png

set(CJSON_LIBRARY "-cJSON")
find_package(cJSON REQUIRED)
include_directories(${cJSON_INCLUDE_DIR})
target_link_libraries(CCodes ${CJSON_LIBRARIES})

char *post_str = NULL;
    cJSON *root = cJSON_CreateObject();

cJSON_AddStringToObject(root, "user", "为所欲为");
    cJSON_AddStringToObject(root, "pwd", "hkcw3cjbc");
    post_str = cJSON_Print(root);
    cJSON_Delete(root);
    root = NULL;
    printf("post_str is %s \n",post_str);

自定义编译选项

CMake 允许为项目增加编译选项，从而可以根据用户的环境和需求选择最合适的编译方案。

例如，可以将 MathUtils 库设为一个可选的库，如果该选项为 ON ，就使用该库定义的数学函数来进行运算。否则就调用标准库中的数学函数库。

修改 CMakeLists 文件

我们要做的第一步是在顶层的 CMakeLists.txt 文件中添加该选项：

cmake_minimum_required(VERSION 3.13)

project(CMakeDemo C)

set(CMAKE_C_STANDARD 99)

# 加入一个配置头文件，用于处理 CMake 对源码的设置
configure_file (
        "${PROJECT_SOURCE_DIR}/config.h.in"
        "${PROJECT_BINARY_DIR}/config.h"
)

# 是否使用自己的 MathUtils 库
option (USE_MATH_LIB
        "Use provided math implementation" ON)
# 是否加入 MathUtils 库
if (USE_MATH_LIB)
    include_directories ("${PROJECT_SOURCE_DIR}/math")
    add_subdirectory (math)
    set (EXTRA_LIBS ${EXTRA_LIBS} MathUtils)
endif (USE_MATH_LIB)


# 查找当前目录下的所有源文件
# 并将名称保存到 DIR_SRCS 变量
aux_source_directory(. DIR_SRCS)
# 指定生成目标
add_executable(CMakeDemo ${DIR_SRCS})

target_link_libraries (CMakeDemo  ${EXTRA_LIBS})

其中：

1. configure_file 命令用于加入一个配置头文件 config.h ，这个文件由 CMake 从 config.h.in生成，通过这样的机制，将可以通过预定义一些参数和变量来控制代码的生成。
2. option 命令添加了一个 USE_MATH_LIB选项，并且默认值为ON。
3. 根据 USE_MATH_LIB变量的值来决定是否使用我们自己编写的 MathUtils库。

修改 main.c 文件

之后修改 main.c文件，让其根据 USE_MYMATH 的预定义值来决定是否调用标准库还是 MathUtils库：

#include <stdio.h>
#include <config.h>

#ifdef USE_MATH_LIB

#include <MathUtils.h>

#else
#include <math.h>
#endif

int main(int argc, char *argv[]) {

#ifdef USE_MATH_LIB
    printf("Now we use our own Math library. \n");
    hello();
#else
    printf("Now we use the standard library. \n");
     printf("Hello, World !\n");
#endif
    printf("Hello, World Ending!\n");
    return 0;
}

编写 config.h.in文件

上面的程序值得注意的是第2行，这里引用了一个 config.h 文件，这个文件预定义了 USE_MATH_LIB的值。但我们并不直接编写这个文件，为了方便从 CMakeLists.txt 中导入配置，我们编写一个 config.h.in文件，内容如下：

#cmakedefine USE_MATH_LIB

这样 CMake 会自动根据 CMakeLists 配置文件中的设置自动生成 config.h 文件。

cmakeseven.png

安装和测试

CMake 也可以指定安装规则，以及添加测试。这两个功能分别可以通过在产生 Makefile 后使用 make install 和 make test 来执行。在以前的 GNU Makefile 里，你可能需要为此编写 install 和 test 两个伪目标和相应的规则，但在 CMake 里，这样的工作同样只需要简单的调用几条命令。

首先先在 math/CMakeLists.txt 文件里添加下面两行：

# 指定 MathUtils 库的安装路径
install (TARGETS MathUtils DESTINATION bin)
install (FILES MathUtils.h DESTINATION include)

指明 MathUtils 库的安装路径。之后同样修改根目录的 CMakeLists 文件，在末尾添加下面几行：

# 指定安装路径
install (TARGETS CMakeDemo DESTINATION bin)
install (FILES "${PROJECT_BINARY_DIR}/config.h"
         DESTINATION include)

通过上面的定制，生成的 CMakeDemo文件和 MathUtils 函数库 libMathUtils .o 文件将会被复制到 /usr/local/bin 中，而 MathUtils .h 和生成的 config.h 文件则会被复制到 /usr/local/include 中。我们可以验证一下

顺带一提的是，这里的 /usr/local/ 是默认安装到的根目录，可以通过修改 CMAKE_INSTALL_PREFIX 变量的值来指定这些文件应该拷贝到哪个根目录。

[G490@ubuntu CMakeDemo]$ sudo make install
[ 50%] Built target MathUtils
[100%] Built target CMakeDemo
Install the project...
-- Install configuration: ""
-- Installing: /usr/local/bin/CMakeDemo
-- Installing: /usr/local/include/config.h
-- Installing: /usr/local/bin/MathUtils.a
-- Up-to-date: /usr/local/include/MathUtils.h
[G490@ubuntu CMakeDemo]$ ls /usr/local/bin
Demo  libMathUtils .a
[G490@ubuntu CMakeDemo]$ ls /usr/local/include
config.h  MathUtils .h

添加环境检查

有时候可能要对系统环境做点检查，例如要使用一个平台相关的特性的时候。在这个例子中，我们检查系统是否自带 pow 函数。如果带有 pow 函数，就使用它；否则使用我们定义的 power 函数。

添加 CheckFunctionExists 宏

首先在顶层 CMakeLists 文件中添加 CheckFunctionExists.cmake 宏，并调用 check_function_exists 命令测试链接器是否能够在链接阶段找到 pow 函数。

# 检查系统是否支持 pow 函数
include (${CMAKE_ROOT}/Modules/CheckFunctionExists.cmake)
check_function_exists (pow HAVE_POW)

#include <stdio.h>
#include <config.h>

#ifdef USE_MATH_LIB

#include <MathUtils.h>
#include <stdlib.h>

#else
#include <math.h>
#endif

int main(int argc, char *argv[]) {


#ifdef USE_MATH_LIB
    printf("Now we use our own Math library. \n");
    hello(argc);
#else
    printf("Now we use the standard library. \n");
     printf("Hello, World !\n");
#endif
    printf("Hello, World Ending!\n");


#ifdef HAVE_POW
    double result = power(7, 8);
    printf("Now we use our own Math library. Result is %f\n", result);
#else
    double result = power(6, 9);
    printf("Now we use our own Math library. Result is %f\n", result);

#endif
    return 0;
}

添加版本号

给项目添加和维护版本号是一个好习惯，这样有利于用户了解每个版本的维护情况，并及时了解当前所用的版本是否过时，或是否可能出现不兼容的情况。

首先修改顶层 CMakeLists 文件，在 project 命令之后加入如下两行：

set(VERSIONCODEMAJOR  1)
set(VERSIONCODEMINOR  0)

分别指定当前的项目的主版本号和副版本号。

之后，为了在代码中获取版本信息，我们可以修改 config.h.in 文件，添加两个预定义变量：

// the configured options and settings for Tutorial
#define VERSIONCODEMAJOR @VERSIONCODEMAJOR@
#define VERSIONCODEMINOR @VERSIONCODEMINOR@

 printf("%s Version %d.%d \n",argv[0],VERSIONCODEMAJOR,VERSIONCODEMINOR);

这样就可以直接在代码中打印版本信息了：

/home/shanlovana/CLionProjects/DailyCode/CMakeDemo/cmake-build-debug/CMakeDemo Version 1.0  

生成安装包

本节将学习如何配置生成各种平台上的安装包，包括二进制安装包和源码安装包。为了完成这个任务，我们需要用到 CPack ，它同样也是由 CMake 提供的一个工具，专门用于打包。

首先在顶层的 CMakeLists.txt 文件尾部添加下面几行：

# 构建一个 CPack 安装包
include (InstallRequiredSystemLibraries)
SET(CPACK_CMAKE_GENERATOR "Unix Makefiles")
SET(CPACK_GENERATOR "STGZ;TGZ;TZ")

set (CPACK_RESOURCE_FILE_LICENSE
        "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")

SET(CPACK_PACKAGE_NAME "CMakeDemo")
SET(CPACK_PACKAGE_VENDOR "Kitware")
SET(CPACK_PACKAGE_VERSION "2.5.0")
SET(CPACK_PACKAGE_VERSION_MAJOR "2")
SET(CPACK_PACKAGE_VERSION_MINOR "5")
SET(CPACK_PACKAGE_VERSION_PATCH "0")

SET(CPACK_SYSTEM_NAME "Linux-i686")
SET(CPACK_TOPLEVEL_TAG "Linux-i686")

include (CPack)

上面的代码做了以下几个工作：

1. 导入 InstallRequiredSystemLibraries 模块，以便之后导入 CPack 模块；
2. 设置一些 CPack 相关变量，包括版权信息和版本信息，其中版本信息用了上一节定义的版本号；
3. 导入 CPack 模块。

接下来的工作是像往常一样构建工程，并执行 cpack 命令。

• 生成二进制安装包：

  cpack -C CPackConfig.cmake
  

• 生成源码安装包：

`cpack -C CPackSourceConfig.cmake`

此次并未成功生成安装包，后续再进行调试，不多做演示。

文中代码github地址