一篇文章精通CMake

最新推荐文章于 2025-05-26 11:46:14 发布

Peter·Pan爱编程

最新推荐文章于 2025-05-26 11:46:14 发布

阅读量294

点赞数 5

文章标签： c++

本文链接：https://blog.youkuaiyun.com/weixin_42125125/article/details/144445529

版权

1. 前言

cmake是大型工程非常常见的软件集成工具，掌握cmake的用法，可以让我们在项目搭建过程中如鱼得水，更新详细的介绍，可以参考官方文档，本文主要总结一些我们项目构建过程中非常常用的一些功能。

2. cmake 安装

**方式一：**使用命令安装

sudo apt install cmake

**方式二：**使用安装包安装
使用指令安装，往往不能安装到最新版本，如果想体验较新的cmake，cmake官网下载。可以从根据自己的OS环境从cmake官网下载不同版本的安装包，并解压

wget https://github.com/Kitware/CMake/releases/download/v3.31.2/cmake-3.31.2-linux-x86_64.tar.gz
tar -zvxf cmake-3.31.2-linux-x86_64.tar.gz
cd cmake-3.31.2-linux-x86_64

进入安装包后，可以看到以下目录

bin: cmake的可执行存放目录
doc: cmake的帮助文档目录
man: cmake man指令帮助文档
share: 存放一些可供find_package查询的共享配置文件

我们只需要将这些目录copy到root下对应路径即可完成安装

cp -rf ./bin /usr/bin
cp -rf ./share /usr/share
cp -rf ./doc /usr/doc

安装完成后，可以通过查看cmake 版本号来判读是否安装成功

cmake --version

输出以下日志，说明安装成功

cmake version 3.31.2

CMake suite maintained and supported by Kitware (kitware.com/cmake).

2. 快速入门

安装成功cmake后，我们来一个快速入门吧！
先创建几个基础文件(main.cpp、 hello.h、 hello.cpp), 将两个cpp文件编译一个hello的可执行文件，那么cmake工程应该如何创建呢
首先我们要创建一个CMakeLists.txt，此文件是cmake的基础文件
main.cpp

#include "hello.h"

int main(int argv, char** argc) {
	hello_world();
	return 0;
}

hello.h

void hello_world();

hello.cpp

#include <iostream>

void hello_world() {
	std::cout << "Hello world!" << std::endl;
}

CMakeLists.txt

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)
 
add_executable(hello main.cpp hello.cpp)

cmake_minimum_required: 设置cmake的最低版本，有些工程不可以在较低的cmake版本下运行，我们可以用这个函数进行控制，当cmake版本较低时，cmake构建时，就会出现下面这样的报错提醒，当然如果你的工程用不到一些cmake新版本的功能，也可以通过降低这里的配置来适配本地的cmake版本
project：设置项目名称，可版本号，还可以设置支持的语言。这里除了项目名称是比填外，其他参数都是可选项
add_executable: 使用特定文件，生成一个可执行。这里第一个参数是可执行名字，后面生成该可执行所需要的源文件

文件创建完成后，我们可以创建一个build目录进行编译

mkdir -p build && cd build
cmake ..
make

编译完成后，就会在当前build目录下面生成一个可执行
以上是一个最简单的cmake工程，下面我们会不断来丰富此工程

3. message 打印日志

cmake 中message是一个重要的工具，用于cmake中的日志打印，方面我们在构建是遇到问题进行排查。
message([<mode>] “message text” …)
通用的日志打印接口，其中通过mode来配置日志等级，也可以不配置等级，会使用默认等级

FATAL_ERROR： cmake发生致命错误，cmake会打印并报错退出
SEND_ERROR： cmake发生错误，会打印错误并继续执行
WARNING：cmake打印告警信息
DEPRECATION：当编译CMAKE_ERROR_DEPRECATED或CMAKE_WARN_DEPRECATED使能时，打印报错或告警信息
NOTICE：重要通知打印，cmake会使用stderr来提醒用户，这个也是默认等级
STATUS：打印一些感兴趣的状态信息

message(<checkState> “message” …)
通过状态来打印信息，有三种状态

CHECK_START：记录开始检查的日志
CHECK_PASS：记录成功的日志
CHECK_FAIL：记录是吧的日志

4. CMake 变量

在cmake中，我可以可以定义一些变量来做一些复杂管理，我们可以使用set函数来设置变量的值,通过$来获取变量的值，引入变量后，我们可以优化上面的CMakeLists.txt

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

set(BIN_NAME hello)

set(SRC main.cpp hello.cpp)
 
add_executable(${BIN_NAME} ${SRC})

cmake中，也有一些非常好用的默认变量

CMAKE_INSTALL_PREFIX: 配置工程的安装路径，我们可以在cmake …时来设置该变量的值，如果不设置，在ubuntu下默认是/usr/local，在windows下，默认是c:/Program Files/${PROJECT_NAME}
CMAKE_BUILD_TYPE: 配置cmake模式类型，有Debug和Release两种模式可以选，默认是空字符串，当设置成Debug模式后，编译时会加速-g，这也是cpu gdb常用的配置
PROJECT_NAME: 配置的项目名称，比如本文使用的时learn_cmake
PROJECT_BINARY_DIR: 指向build目录的完整路径
PROJECT_SOURCE_DIR：指向最后一次调用project()命令的路径
CMAKE_INSTALL_BINDIR: 默认是./bin
CMAKE_INSTALL_LIBDIR：默认是./lib
CMAKE_INSTALL_INCLUDEDIR：默认是./include
CMAKE_EXPORT_COMPILE_COMMANDS：是否输出command.json用来打印编译指令

5. INCLUDE_DIRECTORIES

在我们的工程中，可能头文件并不是放在当前目录的，此时就需要我们使用INCLUDE_DIRECTORIES或者include_directories来引入头文件目录，比如上面的例子如果hello放在include下面的话，我们CMakeLists.txt就变成了下面这样

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

set(BIN_NAME hello)

set(SRC main.cpp hello.cpp)
 
add_executable(${BIN_NAME} ${SRC})

6. add_definitions

有时，我们需要在编译时，加上宏，此时就需要使用add_definitions命令来处理，比如我们希望在编译时加上宏ENABLE_PRINT来控制是否hello.cpp打印，那么
hello.cpp

#include <iostream>

void hello_world() {
#ifdef ENABLE_PRINT
    std::cout << "Hello world!" << std::endl;
#endif
}

CMakeLists.txt

project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

add_definitions(-DENABLE_PRINT)

set(BIN_NAME hello)

set(SRC main.cpp hello.cpp)
 
add_executable(${BIN_NAME} ${SRC})

加上add_definitions(-DENABLE_PRINT)就可以打印Hello world，不定义就不会打印

7. option

cmake提供了一个布尔option指令，它是一个非常有用和常用的指令，它主要用于在cmake里面做一些控制按钮，通过option可以设置一个变量的默认值，当cmake构建阶段没有设置该变量时，则该变量就是option设置的默认值，如果用户cmake构建时传入设置了该变量，则值就是用户设置的变量，所以此指令常常用于一些cmake的动态管理，比如：
CMakeLists.txt

project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

option(ENABLE_PRINT "Open the print" ON)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

if (ENABLE_PRINT)
	add_definitions(-DENABLE_PRINT)
endif()

set(BIN_NAME hello)

set(SRC main.cpp hello.cpp)
 
add_executable(${BIN_NAME} ${SRC})

默认cmake ..构建时, 则ENABLE_PRINT的值就是ON, 而当使用cmake .. -DENABLE_PRINT=OFF构建时，则ENABLE_PRINT的值就是OFF,此时就不会定义宏ENABLE_PRINT，使用此方法，我们就实现了一个动态控制的cmake构建策略

8. add_library

add_library是一个将源文件编译成库文件的指令，他的格式是：
add_library(<name> [<type>] [EXCLUDE_FROM_ALL] <sources>...)

name: 库的名字
type: 通过type可以用来控制是编译静态库还是动态库，STATIC表示静态库，SHARED表示动态库，MODULE表示生成一个plugin(这个目前本人还未使用过)
sources：编译该目标文件所需要的源文件

示例：如果上面的hello.cpp编译成库

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

option(ENABLE_PRINT "Open the print" ON)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

if (ENABLE_PRINT)
	add_definitions(-DENABLE_PRINT)
endif()

set(BIN_NAME test_hello)

set(SRC main.cpp)

add_library(hello SHARED src/hello.cpp)
 
add_executable(${BIN_NAME} ${SRC})

则make hello就会生成一个libhello.so

9. set_target_properties

也许我们对库做一个加上一个版本号，此时我们需要使用set_target_properties功能

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

option(ENABLE_PRINT "Open the print" ON)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

if (ENABLE_PRINT)
	add_definitions(-DENABLE_PRINT)
endif()

set(BIN_NAME test_hello)

set(SRC main.cpp)

add_library(hello SHARED src/hello.cpp)

set_target_properties(hello PROPERTIES VERSION 1.0.0 SOVERSION 1)
add_executable(${BIN_NAME} ${SRC})

此时我们执行make hello就会得到下来三个文件

libhello.so -> libhello.so.1
libhello.so.1 -> libhello.so.1.0.0
libhello.so.1.0.0

10. install

有时，除了可执行需要安装外，对他文件也需要做一些安装处理，此时，就是需要我们使用install指令，常见的install指令格式如下：

install(TARGETS <target>... [...]): 安装目标文件
install({FILES | PROGRAMS} <file>... [...]): 安装文件
install(DIRECTORY … …): 安装目录

示例：假如上面的例子我们要将include和lib进行安装，就会使用如下配置

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

option(ENABLE_PRINT "Open the print" ON)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

if (ENABLE_PRINT)
	add_definitions(-DENABLE_PRINT)
endif()

set(BIN_NAME test_hello)

set(SRC main.cpp)

add_library(hello SHARED src/hello.cpp)
set_target_properties(hello PROPERTIES VERSION 1.0.0 SOVERSION 1)

add_executable(${BIN_NAME} ${SRC})

include(GNUInstallDirs)

install(TARGETS hello LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

通过

install(TARGETS hello LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

就完成了include目录和动态库的安装，需要注意的是需要先使用include(GNUInstallDirs)来引入CMAKE_INSTALL_*这些变量的默认值，如果不include，这些变量的默认值都是空的

11. target_link_libraries

此时我们惊讶地发make test_hello会报错了undefined reference to "hello_world()"'，原因是在文章开头时，我们时直接将hello.cpp编译成binary，而现在是把hello.cpp编译成了库文件，此时如果我们的还想使用的话，就需要使用target_link_libraries来讲库文件链接过来，于是CMakeLists.txt就成了如下这样：

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

option(ENABLE_PRINT "Open the print" ON)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

if (ENABLE_PRINT)
	add_definitions(-DENABLE_PRINT)
endif()

set(BIN_NAME test_hello)

set(SRC main.cpp)

add_library(hello SHARED src/hello.cpp)
set_target_properties(hello PROPERTIES VERSION 1.0.0 SOVERSION 1)

add_executable(${BIN_NAME} ${SRC})
target_link_libraries(${BIN_NAME} hello)

include(GNUInstallDirs)

install(TARGETS hello LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

12. add_dependencies

开发到现在就结束了吗？聪明的你马上就会发现，当使用make -j8这种并行编译的时候，还是偶尔出现函数未定义的报错，重新编译就又好了，那又是什么原因呢？
聪明的你马上就发现了，我们经常会出现先编译可执行，再编译库文件的情况。那如果处理这种依赖关系呢，就需要使用到add_dependencies, 此时示例如下：

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

option(ENABLE_PRINT "Open the print" ON)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

if (ENABLE_PRINT)
	add_definitions(-DENABLE_PRINT)
endif()

set(BIN_NAME test_hello)

set(SRC main.cpp)

add_library(hello SHARED src/hello.cpp)
set_target_properties(hello PROPERTIES VERSION 1.0.0 SOVERSION 1)

add_executable(${BIN_NAME} ${SRC})
add_dependencies(${BIN_NAME} hello)
target_link_libraries(${BIN_NAME} hello)

include(GNUInstallDirs)

install(TARGETS hello LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

13. ADD_SUBDIRECTORY

随着我们的工程越来越大，我们很快发现我们的CMakeLists.txt变得越来越长，此时我们就需要来将一个大工程拆分成很多的子工程，而使用ADD_SUBDIRECTORY就可以很好的将各个工程的编译关系链接起来，ADD_SUBDIRECTORY会去检查子目录下是否存在CMakeLists.txt，如果存在则会根据子目录下的规则来编译子目录，如果不存在则会报错。比如上面的例子，想将lib开发成子目录进行管理，我们就主CMakeLists.txt就变成了如下所示：

cmake_minimum_required (VERSION 3.5)
 
project (learn_cmake VERSION 1.0.0 DESCRIPTION "这是一个cmake的学习工程" LANGUAGES CXX)

option(ENABLE_PRINT "Open the print" ON)

INCLUDE_DIRECTORIES("${PROJECT_SOURCE_DIR}/include")

if (ENABLE_PRINT)
	add_definitions(-DENABLE_PRINT)
endif()

ADD_SUBDIRECTORY(src)

set(BIN_NAME test_hello)
set(SRC main.cpp)

add_executable(${BIN_NAME} ${SRC})
add_dependencies(${BIN_NAME} hello)
target_link_libraries(${BIN_NAME} hello)

src/CMakeLists.txt

file(GLOB_RECURSE LIBSRC ${CMAKE_CURRENT_SOURCE_DIR} *.cpp)

add_library(hello SHARED ${LIBSRC})
set_target_properties(hello PROPERTIES VERSION 1.0.0 SOVERSION 1)

include(GNUInstallDirs)

install(TARGETS hello LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

可以看出分成两个CMakeLists.txt后，逻辑变得更加清晰，其实，我们可以通过多个ADD_SUBDIRECTORY实现出非常复杂的工程构建体系，所以一些大工程的管理经常会使用到此功能

14. include

当有很多的ADD_SUBDIRECTORY时，就会发现他们子目录之间的变量并不能很好的共享，而我们在构建时，重复设置一些变量总归不是程序员思维，并且维护起来也很不方便。此时我们就可以使用include指令来很好的解决这个问题，include指令可以在当前的CMakeLists.txt中引入另一个.cmake文件里面的配置，比如我们前面看到的include(GNUInstallDirs)就是引入了GNU标准按照目录。比如我们需要定义一些公共的编译选项，我们就可以定义一个common.cmake，然后通过include被起来子目录引用，我们可以创建一个cmake目录来管理这些公共cmake文件
cmake/common.cmake

add_compile_options(-Wall -Wextra -Werror)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

src/CMakeLists.txt

include(${PROJECT_SOURCE_DIR}/cmake/common.cmake)

file(GLOB_RECURSE LIBSRC ${CMAKE_CURRENT_SOURCE_DIR} *.cpp)

add_library(hello SHARED ${LIBSRC})
set_target_properties(hello PROPERTIES VERSION 1.0.0 SOVERSION 1)

include(GNUInstallDirs)

install(TARGETS hello LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

15. add_compile_options & add_link_options

add_compile_options: 添加编译.o的指令，比如我们编译.o时需要c++11，就可以使用add_compile_options(-std=c++11)
add_link_options：添加编译可执行link阶段的指令，比如我们要假如-O3的优化器，就可以使用add_link_options(-O3)

16. find_program

find_program可以根据hints路(路径可以是多个，用空格隔开)径来查找一个可执行程序，示例：

find_program(CMAKE_AR NAMES ar HINTS /usr/bin)

就是在/usr/bin下查找ar这个可执行

17. find_package

find_package是来查找一个cmake模块，示例：

find_package(Git QUIET)

就是查找一个git模块，并且标记问QUIET，表示如果没有找到就报错

18. execute_process & add_custom_command

cmake还可以也可以执行shell指令
execute_process：表示在做cmake配置时执行shell指令
add_custom_command:则是在编译阶段执行shell指令
示例：
cmake/version.cpp

find_package(Git QUIET)

SET(COMMIT_ID 0)
SET(COMMIT_COUNT 0)
SET(CUR_BRANCH master)

if(GIT_FOUND)
    execute_process(
        COMMAND ${GIT_EXECUTABLE} log -1 --pretty=format:%H
        OUTPUT_VARIABLE COMMIT_ID
        OUTPUT_STRIP_TRAILING_WHITESPACE
        ERROR_QUIET
        WORKING_DIRECTORY
        ${CMAKE_CURRENT_SOURCE_DIR}
    )
    execute_process(
        COMMAND ${GIT_EXECUTABLE} log --oneline
        COMMAND wc -l
        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
        OUTPUT_VARIABLE COMMIT_COUNT
        OUTPUT_STRIP_TRAILING_WHITESPACE
    )

    execute_process(
        COMMAND ${GIT_EXECUTABLE} branch --show-current
        OUTPUT_VARIABLE CUR_BRANCH
        OUTPUT_STRIP_TRAILING_WHITESPACE
        ERROR_QUIET
        WORKING_DIRECTORY
        ${CMAKE_CURRENT_SOURCE_DIR}
    )
endif()
message(STATUS "commit id: " ${COMMIT_ID})
message(STATUS "branch: " ${CUR_BRANCH})

上面表示在cmake中获取git的commit和branch信息，并打印

add_custom_command(TARGET hello PRE_BUILD COMMAND echo "Start building hello library")
add_custom_command(TARGET hello POST_BUILD COMMAND echo "Finished building hello library")

上面表示会在目标hello编译前打印Start building hello library，在编译完成后打印Finished building hello library，除了这两个常用的外，还有PRE_LINK来表示在link之前执行指令

19. 其他功能

1.自定义函数或者宏
cmake还支持自定义函数或者宏来对cmake里做一些批处理。函数使用function进行声明，而宏使用macro进行声明，他们有相似的功能，不同的地方在于宏是字符替换，所以在宏定义里面，可以直接使用外部变量，而函数无法直接使用，需要通过参数进行传递。示例：
cmake/common.cmake

add_compile_options(-Wall -Wextra -Werror)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

function(make_library name src)
    add_library(${name} SHARED ${src})
    set_target_properties(${name} PROPERTIES VERSION 1.0.0 SOVERSION 1)

    include(GNUInstallDirs)

    install(TARGETS ${name} LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})

endfunction(make_library)

make_library(hello ${LIBSRC})

cmake/CMakeLists.cmake

include(${PROJECT_SOURCE_DIR}/cmake/common.cmake)

file(GLOB_RECURSE LIBSRC ${CMAKE_CURRENT_SOURCE_DIR} *.cpp)

make_library(hello ${LIBSRC})

install(DIRECTORY ${PROJECT_SOURCE_DIR}/include DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

add_custom_command(TARGET hello PRE_BUILD COMMAND echo "Start building hello library")
add_custom_command(TARGET hello POST_BUILD COMMAND echo "Finished building hello library")

使用宏的话更加简单就是简单的字符替换，此处就不重复赘述，大家可以体验一下，使用宏需要注意的是避免在宏中有变量重复，导致一些意想不到的结果发生

2. file用于文件遍历
file函数也是一个在做文件遍历时非常常用的一个函数，它的常用格式如下：
file({GLOB | GLOB_RECURSE} <out-var> [...] <globbing-expr>...)

功能：根据globbing-expr规则遍历目录下的文件，结果输出到out-var
GLOB: 表示仅遍历当前目录，不会递归遍历
GLOB_RECURSE: 表示递归遍历当前目录所有文件
out-var: 遍历的输出结果变量
globbing-expr: 遍历的匹配规则，比如*.cpp表示遍历所有以.cpp后缀的文件

比如我们上面写到的file(GLOB_RECURSE LIBSRC ${CMAKE_CURRENT_SOURCE_DIR} *.cpp), 就表示递归遍历src下面所有的文件，并将结果存放在变量LIBSRC中
3. list列表处理函数
它有多种格式

list(LENGTH <list> <output variable>): 返回list的长度
list(GET <list> <element index> [<element index> ...] <output variable>): 获取列表中特定位置的元素
list(JOIN <list> <glue> <output variable>): 使用<glue>拼接所有的list元素
list(FIND <list> <value> <output variable>): 找到固定元素，并返回起index
list(APPEND <list> [<element> ...]): 在末尾添加元素
list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>): 通过正则表达式过滤元素
list(REMOVE_ITEM <list> <value> [<value> ...]): 移除特定元素