2021-Cmake语法与实战入门

原文地址

CMake语法与实战入门

CMake

CMake是一个跨平台、开源的构建系统。它是一个集软件构建、测试、打包于一身的软件。它使用与平台和编译器独立的配置文件来对软件编译过程进行控制。

现如今，有各种各样的Make工具遵循着不同的规范和标准，所执行的Makefile格式也千差万别。这样就带来了一个严峻的问题：如果软件想跨平台，必须要保证能够在不同平台编译。针对每一种Make工具写一遍Makefile显然非常浪费时间。

CMake就是针对上面问题所设计的工具：首先，它允许开发者编写一种平台无关的CMakeList.txt文件来定制整个编译流程，然后再根据目标用户的平台进一步生成所需的本地化Makefile和工程文件。

在linux平台下使用CMake生成Makefile并编译的流程如下：

编写CMake配置文件CMakeLists.txt 。
执行命令 cmake PATH 或者 ccmake PATH 生成Makefile（ccmake 和 cmake 的区别在于前者提供了一个交互式的界面）。其中， PATH 是CMakeLists.txt所在的目录。
使用 make 命令进行编译。

语法

指定cmake最小版本

cmake_minimum_required(VERSION 3.4.1)

在有些情况下，如果CMakeLists.txt文件中使用了一些高版本cmake特有的一些命令的时候，就需要加上这样一行，提醒用户升级到该版本之后再执行cmake。

设置项目名称

project(demo)

最好写上，它会引入两个变量demo_BINARY_DIR和demo_SOURCE_DIR，同时，cmake自动定义了两个等价的变量PROJECT_BINARY_DIR和PROJECT_SOURCE_DIR。

设置编译类型

add_executable(demo demo.cpp) # 生成可执行文件
add_library(common STATIC util.cpp) # 生成静态库
add_library(common SHARED util.cpp) # 生成动态库或共享库

add_library默认生成是静态库，通过以上命令生成文件名字，

在Linux下是：demo libcommon.a libcommon.so

在Windows下是：demo.exe common.lib common.dll

指定编译包含的源文件

明确指出包含哪些源文件

add_library(demo demo.cpp test.cpp util.cpp)

\2.搜索所有的cpp文件

aux_source_directory(dir VAR)发现一个目录(dir)下所有的源代码文件并将列表存储在一个变量(VAR)中。

aux_source_directory(. SRC_LIST) # 搜索当前目录下的所有.cpp文件
add_library(demo ${SRC_LIST})

\3.自定义搜索规则

file(GLOB SRC_LIST "*.cpp" "protocol/*.cpp")
add_library(demo ${SRC_LIST})
# 或者
file(GLOB SRC_LIST "*.cpp")
file(GLOB SRC_PROTOCOL_LIST "protocol/*.cpp")
add_library(demo ${SRC_LIST} ${SRC_PROTOCOL_LIST})
# 或者
aux_source_directory(. SRC_LIST)
aux_source_directory(protocol SRC_PROTOCOL_LIST)
add_library(demo ${SRC_LIST} ${SRC_PROTOCOL_LIST})

查找指定的库文件

find_library(VAR name path)查找到指定的预编译库，并将它的路径存储在变量中。默认的搜索路径为cmake包含的系统库，因此如果是NDK的公共库只需要指定库的name即可（不需path）。

find_library(log-lib,log)

类似的命令还有find_file()、find_path()、find_program()、find_package()。

include_directories(
    ${CMAKE_CURRENT_SOURCE_DIR}
    ${CMAKE_CURRENT_BINARY_DIR}
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

设置target需要链接的库

target_link_libraries( # 目标库 demo # 目标库需要链接的库 ${log-lib} )

在Windows下，系统会根据链接库目录，搜索xxx.lib文件，Linux下会搜索xxx.so或者xxx.a文件，如果都存在会优先链接动态库（so后缀）。

指定链接动态库或静态库

target_link_libraries(demo libface.a) # 链接libface.a
target_link_libraries(demo libface.so) # 链接libface.so

指定全路径

target_link_libraries(demo ${CMAKE_CURRENT_SOURCE_DIR}/libs/libface.a)
target_link_libraries(demo ${CMAKE_CURRENT_SOURCE_DIR}/libs/libface.so)

指定链接多个库

target_link_libraries(demo
    ${CMAKE_CURRENT_SOURCE_DIR}/libs/libface.a
    boost_system.a
    boost_thread
    pthread)

设置变量

set直接设置变量的值

set(SRC_LIST main.cpp test.cpp)
add_executable(demo ${SRC_LIST})

\2. set追加设置变量的值

set(SRC_LIST main.cpp)
set(SRC_LIST ${SRC_LIST} test.cpp)
add_executable(demo ${SRC_LIST})

常用变量

PROJECT_SOURCE_DIR：工程的根目录

PROJECT_BINARY_DIR：运行cmake命令的目录，通常为${PROJECT_SOURCE_DIR}/build

PROJECT_NAME：返回通过project命令定义的项目名称

CMAKE_CURRENT_SOURCE_DIR：当前处理的CMakeLists.txt所在的路径

CMAKE_CURRENT_BINARY_DIR：target编译目录

CMAKE_CURRENT_LIST_DIR：CMakeLists.txt的完整路径

EXECUTABLE_OUTPUT_PATH：重新定义目标二进制可执行文件的存放位置

LIBRARY_OUTPUT_PATH：重新定义目标链接库文件的存放位置

实战

单个源文件

(源代码所在目录：Demo1)

假设现在我们的项目中只有一个源文件http://main.cc，该程序的用途是计算一个数的指数幂。

#include <stdio.h>
#include <stdlib.h>

/**
 * power - Calculate the power of number.
 * @param base: Base value.
 * @param exponent: Exponent value.
 *
 * @return base raised to the power exponent.
 */
double power(double base, int exponent)
{
    int result = base;
    int i;

    if (exponent == 0) {
        return 1;
    }

    for(i = 1; i < exponent; ++i){
        result = result * base;
    }

    return result;
}

int main(int argc, char *argv[])
{
    if (argc < 3){
        printf("Usage: %s base exponent \n", argv[0]);
        return 1;
    }
    double base = atof(argv[1]);
    int exponent = atoi(argv[2]);
    double result = power(base, exponent);
    printf("%g ^ %d is %g\n", base, exponent, result);
    return 0;
}

首先编写CMakeLists.txt文件，并保存在与http://mian.cc源文件同个目录下：

# CMake 最低版本号要求
cmake_minimum_required (VERSION 2.8)

# 项目信息
project (Demo1)

# 指定生成目标
add_executable(Demo main.cc)

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

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

cmake_minimum_required：指定运行此配置文件所需的CMake的最低版本；
project：参数值是 Demo1，该命令表示项目的名称是 Demo1 。
add_executable：将名为main.cc的源文件编译成一个名称为Demo的可执行文件。

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

[ehome@xman Demo1]$ cmake .
-- The C compiler identification is GNU 4.8.2
-- The CXX compiler identification is GNU 4.8.2
-- Check for working C compiler: /usr/sbin/cc
-- Check for working C compiler: /usr/sbin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: /usr/sbin/c++
-- Check for working CXX compiler: /usr/sbin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Configuring done
-- Generating done
-- Build files have been written to: /home/ehome/Documents/programming/C/power/Demo1
[ehome@xman Demo1]$ make
Scanning dependencies of target Demo
[100%] Building C object CMakeFiles/Demo.dir/main.cc.o
Linking C executable Demo
[100%] Built target Demo
[ehome@xman Demo1]$ ./Demo 5 4
5 ^ 4 is 625
[ehome@xman Demo1]$ ./Demo 7 3
7 ^ 3 is 343
[ehome@xman Demo1]$ ./Demo 2 10
2 ^ 10 is 1024

多个源文件

(源代码所在目录Demo2)

上面的例子只有单个源文件。现在假如把power函数单独写进一个名为MathFunctions.c的源文件里，使得这个工程变成如下的形式：

/Demo2
    |
    +--- main.cc
    |
    +--- MathFunctions.cc
    |
    +--- MathFunctions.h

这个时候，CMakeLists.txt可以改成如下的形式：

# CMake 最低版本号要求
cmake_minimum_required (VERSION 2.8)

# 项目信息
project (Demo2)

# 指定生成目标
add_executable(Demo main.cc MathFunctions.cc)

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

aux_source_directory(<dir> <variable>)

因此，可以修改CMakeLists.txt如下：

# CMake 最低版本号要求
cmake_minimum_required (VERSION 2.8)

# 项目信息
project (Demo2)

# 查找当前目录下的所有源文件
# 并将名称保存到 DIR_SRCS 变量
aux_source_directory(. DIR_SRCS)

# 指定生成目标
add_executable(Demo ${DIR_SRCS})

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

多个目录，多个源文件

(源代码所在目录Demo3)

现在进一步将MathFunctions.h和http://MathFunctions.cc文件移动到math目录下。

./Demo3
    |
    +--- main.cc
    |
    +--- math/
          |
          +--- MathFunctions.cc
          |
          +--- MathFunctions.h

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

根目录中的CMakeLists.txt ：

# CMake 最低版本号要求
cmake_minimum_required (VERSION 2.8)

# 项目信息
project (Demo3)

# 查找当前目录下的所有源文件
# 并将名称保存到 DIR_SRCS 变量
aux_source_directory(. DIR_SRCS)

# 添加 math 子目录
add_subdirectory(math)

# 指定生成目标
add_executable(Demo ${DIR_SRCS})

# 添加链接库
target_link_libraries(Demo MathFunctions)

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

子目录中的CMakeLists.txt：

# 查找当前目录下的所有源文件
# 并将名称保存到 DIR_LIB_SRCS 变量
aux_source_directory(. DIR_LIB_SRCS)

# 生成链接库
add_library (MathFunctions ${DIR_LIB_SRCS})

在该文件中使用命令add_library将src目录中的源文件编译为静态链接库。

自定义编译选项

(源代码所在目录Demo4)

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

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

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

# CMake 最低版本号要求
cmake_minimum_required (VERSION 2.8)

# 项目信息
project (Demo4)

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

# 是否使用自己的 MathFunctions 库
option (USE_MYMATH
       "Use provided math implementation" ON) # 设置为ON，或OFF

# 是否加入 MathFunctions 库
if (USE_MYMATH)
  include_directories ("${PROJECT_SOURCE_DIR}/math")
  add_subdirectory (math)
  set (EXTRA_LIBS ${EXTRA_LIBS} MathFunctions)
endif (USE_MYMATH)

# 查找当前目录下的所有源文件
# 并将名称保存到 DIR_SRCS 变量
aux_source_directory(. DIR_SRCS)

# 指定生成目标
add_executable(Demo ${DIR_SRCS})
target_link_libraries (Demo  ${EXTRA_LIBS})

其中：

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

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

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

#ifdef USE_MYMATH
  #include "math/MathFunctions.h"
#else
  #include <math.h>
#endif


int main(int argc, char *argv[])
{
    if (argc < 3){
        printf("Usage: %s base exponent \n", argv[0]);
        return 1;
    }
    double base = atof(argv[1]);
    int exponent = atoi(argv[2]);

#ifdef USE_MYMATH
    printf("Now we use our own Math library. \n");
    double result = power(base, exponent);
#else
    printf("Now we use the standard library. \n");
    double result = pow(base, exponent);
#endif
    printf("%g ^ %d is %g\n", base, exponent, result);
    return 0;
}

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

#cmakedefine USE_MYMATH

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

为了便于交互式的选择该变量的值，可以使用ccmake命令（也可以使用cmake -i命令，该命令会提供一个会话式的交互式配置界面）。

安装和测试

(源代码所在目录Demo5)

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

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

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

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

通过上面的定制，生成的Demo文件和MathFunctions函数库libMathFunctions.o文件将会被复制到/usr/local/bin中，而MathFunctions.h和生成的config.h文件则会被复制到/usr/local/include中。我们可以验证一下（顺带一提的是，这里的/usr/local/是默认安装到的根目录，可以通过修改CMAKE_INSTALL_PREFIX变量的值来指定这些文件应该拷贝到哪个根目录）：

[ehome@xman Demo5]$ sudo make install
[ 50%] Built target MathFunctions
[100%] Built target Demo
Install the project...
-- Install configuration: ""
-- Installing: /usr/local/bin/Demo
-- Installing: /usr/local/include/config.h
-- Installing: /usr/local/bin/libMathFunctions.a
-- Up-to-date: /usr/local/include/MathFunctions.h
[ehome@xman Demo5]$ ls /usr/local/bin
Demo  libMathFunctions.a
[ehome@xman Demo5]$ ls /usr/local/include
config.h  MathFunctions.h

添加测试同样很简单。CMake提供了一个称为CTest的测试工具。我们要做的只是在项目根目录的CMakeLists文件中调用一系列的add_test命令。

# 启用测试
enable_testing()

# 测试程序是否成功运行
add_test (test_run Demo 5 2)

# 测试帮助信息是否可以正常提示
add_test (test_usage Demo)
set_tests_properties (test_usage
  PROPERTIES PASS_REGULAR_EXPRESSION "Usage: .* base exponent")

# 测试 5 的平方
add_test (test_5_2 Demo 5 2)

set_tests_properties (test_5_2
 PROPERTIES PASS_REGULAR_EXPRESSION "is 25")

# 测试 10 的 5 次方
add_test (test_10_5 Demo 10 5)

set_tests_properties (test_10_5
 PROPERTIES PASS_REGULAR_EXPRESSION "is 100000")

上面的代码包含了三个测试。第一个测试test_run用来测试程序是否成功运行并返回0值。剩下的两个测试分别用来测试5的平方、10的5次方是否都能得到正确的结果。其中PASS_REGULAR_EXPRESSION用来测试输出是否包含后面跟着的字符串。

如果要测试更多的输入数据，像上面那样一个个写测试用例未免太繁琐。这时可以通过编写宏来实现：

# 定义一个宏，用来简化测试工作
macro (do_test arg1 arg2 result)
  add_test (test_${arg1}_${arg2} Demo ${arg1} ${arg2})
  set_tests_properties (test_${arg1}_${arg2}
    PROPERTIES PASS_REGULAR_EXPRESSION ${result})
endmacro (do_test)

# 使用该宏进行一系列的数据测试
do_test (5 2 "is 25")
do_test (10 5 "is 100000")

支持gdb

让CMake支持gdb的设置也很容易，只需要指定Debug模式下开启-g选项：

set(CMAKE_BUILD_TYPE "Debug")
set(CMAKE_CXX_FLAGS_DEBUG "$ENV{CXXFLAGS} -O0 -Wall -g -ggdb")
set(CMAKE_CXX_FLAGS_RELEASE "$ENV{CXXFLAGS} -O3 -Wall")

之后可以直接对生成的程序使用gdb来调试。

添加版本号

(源代码所在目录Demo7)

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

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

set (Demo_VERSION_MAJOR 1)
set (Demo_VERSION_MINOR 0)

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

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

// the configured options and settings for Tutorial
#define Demo_VERSION_MAJOR @Demo_VERSION_MAJOR@
#define Demo_VERSION_MINOR @Demo_VERSION_MINOR@

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

#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include "config.h"
#include "math/MathFunctions.h"

int main(int argc, char *argv[])
{
    if (argc < 3){
        // print version info
        printf("%s Version %d.%d\n",
            argv[0],
            Demo_VERSION_MAJOR,
            Demo_VERSION_MINOR);
        printf("Usage: %s base exponent \n", argv[0]);
        return 1;
    }
    double base = atof(argv[1]);
    int exponent = atoi(argv[2]);

#if defined (HAVE_POW)
    printf("Now we use the standard library. \n");
    double result = pow(base, exponent);
#else
    printf("Now we use our own Math library. \n");
    double result = power(base, exponent);
#endif

    printf("%g ^ %d is %g\n", base, exponent, result);
    return 0;
}

生成安装包

(源代码所在目录Demo8)

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

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

# 构建一个 CPack 安装包
include (InstallRequiredSystemLibraries)
set (CPACK_RESOURCE_FILE_LICENSE
  "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
set (CPACK_PACKAGE_VERSION_MAJOR "${Demo_VERSION_MAJOR}")
set (CPACK_PACKAGE_VERSION_MINOR "${Demo_VERSION_MINOR}")
include (CPack)

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

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

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

生成二进制安装包：

cpack -C CPackConfig.cmake

生成源码安装包

cpack -C CPackSourceConfig.cmake

我们可以试一下。在生成项目后，执行cpack -C CPackConfig.cmake命令：

[ehome@xman Demo8]$ cpack -C CPackSourceConfig.cmake
CPack: Create package using STGZ
CPack: Install projects
CPack: - Run preinstall target for: Demo8
CPack: - Install project: Demo8
CPack: Create package
CPack: - package: /home/ehome/Documents/programming/C/power/Demo8/Demo8-1.0.1-Linux.sh generated.
CPack: Create package using TGZ
CPack: Install projects
CPack: - Run preinstall target for: Demo8
CPack: - Install project: Demo8
CPack: Create package
CPack: - package: /home/ehome/Documents/programming/C/power/Demo8/Demo8-1.0.1-Linux.tar.gz generated.
CPack: Create package using TZ
CPack: Install projects
CPack: - Run preinstall target for: Demo8
CPack: - Install project: Demo8
CPack: Create package
CPack: - package: /home/ehome/Documents/programming/C/power/Demo8/Demo8-1.0.1-Linux.tar.Z generated.

此时会在该目录下创建3个不同格式的二进制包文件：

[ehome@xman Demo8]$ ls Demo8-*
Demo8-1.0.1-Linux.sh  Demo8-1.0.1-Linux.tar.gz  Demo8-1.0.1-Linux.tar.Z

这3个二进制包文件所包含的内容是完全相同的。我们可以执行其中一个。此时会出现一个由CPack自动生成的交互式安装界面：

[ehome@xman Demo8]$ sh Demo8-1.0.1-Linux.sh
Demo8 Installer Version: 1.0.1, Copyright (c) Humanity
This is a self-extracting archive.
The archive will be extracted to: /home/ehome/Documents/programming/C/power/Demo8

If you want to stop extracting, please press <ctrl-C>.
The MIT License (MIT)

Copyright (c) 2013 Joseph Pan(http://hahack.com)

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Do you accept the license? [yN]:
y
By default the Demo8 will be installed in:
  "/home/ehome/Documents/programming/C/power/Demo8/Demo8-1.0.1-Linux"
Do you want to include the subdirectory Demo8-1.0.1-Linux?
Saying no will install in: "/home/ehome/Documents/programming/C/power/Demo8" [Yn]:
y

Using target directory: /home/ehome/Documents/programming/C/power/Demo8/Demo8-1.0.1-Linux
Extracting, please wait...

Unpacking finished successfully

完成后提示安装到了Demo8-1.0.1-Linux子目录中，我们可以进去执行该程序：

[ehome@xman Demo8]$ ./Demo8-1.0.1-Linux/bin/Demo 5 2
Now we use our own Math library.
5 ^ 2 is 25

最近更新于0001-01-01