CMake基础指南

目录

CMake我是在CLion上第一次用的,CLion里编译程序前都要在一个叫CMamkeLists.txt的文件夹里写下面这样的代码:

1
2
3
4
5
6
cmake_minimum_required(VERSION 4.2)
project(MyCpp)

set(CMAKE_CXX_STANDARD 23)

add_executable(MyCpp main.cpp)

然后就可以运行编译了,VSCode里也是,安装上CMakeTools的插件,也是一样的流程。

在开发C/C++项目时,完成代码后需要对源文件进行编译,这个环节由编译器负责。那我手动输入编译命令不就行了吗?但是在有多个源文件或者引入了多个第三方库时,需要每次手动输入很长的编译命令,每个文件之间还有复杂的依赖关系,很容易写错,还需要把编译指令记录下来。这样很不方便项目的管理,所以需要一套工具根据我们的需求去指挥编译器完成编译任务。

那CMake是个什么东西?用来做什么的?

CMake是一个跨平台的开源构建工具,和编译器不同,它并不是一个直接的“编译器”,而是一个构建系统的生成器,一般用于C/C++项目的构建。使用CMake可以更自动化更标准更方便地完成C/C++的项目编译和构建。这篇文章介绍一下CMake主要的基本用法,不会涉及太多进阶的内容。

先理一下在C/C++项目的构建环节里各个工具的作用:

  • 编译器(如GCC/MSVC):负责把C/C++代码翻译成机器能懂的二进制程序。
  • Make/Ninja :负责指挥编译器先翻译哪个文件、后翻译哪个,并协调依赖关系。
  • CMake :而是根据CMakeLists.txt文件和不同平台(Windows、Linux、macOS),生成相应的“构建方案”(Makefile或VS工程文件)。

编译器除外,CMake这套工具是包含两部分的:CMake和Make/ninja,CMake的作用仅仅是生成一套构建方案,而不直接调用编译器,需要Make/Ninja去调用。我们只跟CMake进行直接的交互,这个关键文件就是CMakeLists.txt。

注:平常我们说用 ”CMake构建 ”,其实准确说指的是这套工具链。就像用 “GCC编译 ”,这也是指一套工具链,除了编译器还有链接器等,只不过我们在非必要情况下不需要关心过多的底层细节。

一. 命令行工作流

IDE里一般会使用图形化界面代替,这部分可以选择跳过。 在创建好项目根文件夹后,在根目录下打开终端,输入如下命令:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
#注意Cmake版本,CMake3.13+推荐的命令行一体化构建:
# 1. 配置:让CMake生成构建方案,-B 指定构建目录名,自动创建目录 
cmake -B build

# 2. 构建:这一步需要先写完CMakeLists.txt,再让Ninja/Make开始编译,--build 指定目录名
cmake --build build

#需要指定模式时:Debug调试(默认) / Release发布
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

二. CMakeLists.txt基本命令

首先提一点,CMake 是一门解释型脚本语言,它的解析器是顺序执行的(从上往下读),所以代码顺序是有严格要求的。

假设项目只有一个main文件(单文件且没有外部库的情况),用CMake构建项目,CMakeLists.txt是唯一要写的文件,它有专门的语法,CMakeLists.txt里需要写下面这样的命令:

1
2
3
cmake_minimum_required(VERSION 3.10) # 项目使用的CMake的最低版本要求
project(MyApp)                       # 项目名称
add_executable(app main.cpp)         # 声明可执行文件名与需要编译的源文件

这是最简单的可使用的CMakeLists.txt,不能再省了。

假设项目目录结构是这样的(多文件且没有第三方库的情况):

1
2
3
4
5
6
7
MyProject/
├── CMakeLists.txt
├── main.cpp
├── include/
│   └── module.h
└── src/
    └── module.cpp

CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
cmake_minimum_required(VERSION 3.10) # 项目使用的CMake的最低版本要求
project(MyApp)                       # 项目名称
set(CMAKE_CXX_STANDARD 17)           # 项目使用的C++标准

# 1.生成一个静态库(把src里的cpp编成库)
add_library(module_lib src/module.cpp)

# 2.告诉module_lib,它的头文件在哪里(PUBLIC会让链接器自动找到)
target_include_directories(module_lib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)

# 3.生成主程序可执行文件,第一个参数是最后生成的exe文件的文件名
add_executable(my_app main.cpp)

# 4.将库链接给主程序(有了这行,my_app自动获得include路径)
target_link_libraries(my_app PRIVATE module_lib)

大概的顺序就是:版本第一,项目第二,设完标准再建目标(add_executable),最后才能链接(target_link_libraries)

解释一下基本的命令:

1. 固定头三句

1
2
3
cmake_minimum_required(VERSION 3.10)  # 锁定最低版本
project(MyProject)                    # 给工程命名
set(CMAKE_CXX_STANDARD 17)            # 声明C++标准

project():设置项目的基本信息

1
2
3
4
5
6
project(<项目名称> [语言...])
project(<项目名称>
        [VERSION <主版本号>[.<次版本号>[.<修订号>[.<构建号>]]]]
        [DESCRIPTION <项目描述>]
        [HOMEPAGE_URL <项目主页URL>]
        [LANGUAGES <语言>...])
  • 项目名称(必填):工程名称,会赋值给变量 PROJECT_NAME。
  • 语言(选填):指定启用的编程语言(如 C, CXX, Fortran 等)。如果不指定,默认启用 C 和 CXX。
  • VERSION:设置项目版本号,会生成 PROJECT_VERSION 等变量,关于版本号详细规则,参考
  • DESCRIPTION:项目描述文本。
  • HOMEPAGE_URL:项目主页 URL。

示例:

1
2
3
project(MyProject)                              # 仅名称,默认语言 C/C++
project(MyProject VERSION 1.2.3 LANGUAGES CXX)  # 指定版本和语言
project(MyProject DESCRIPTION "My awesome project" HOMEPAGE_URL "https://example.com")

注意:project 会设置一系列变量(如 PROJECT_SOURCE_DIR、CMAKE_PROJECT_NAME 等),并且会影响编译器的检查,这些是项目的元信息,要让项目看上去正规一些,那就严格设置。

set():设置语言标准

1
set(<变量> <值>... [PARENT_SCOPE])
  • <变量>:要设置的变量名。
  • <值>:要赋给变量的值(可以是多个,会被拼接成字符串,默认用分号分隔)。
  • [PARENT_SCOPE]:可选,将变量设置到父作用域(常用于函数或宏中)。

下面举设置C/C++标准的例子:

1
2
3
4
5
6
7
set(CMAKE_CXX_STANDARD 17)              # 要求使用 C++17
set(CMAKE_CXX_STANDARD_REQUIRED ON)     # 强制要求,不降级
set(CMAKE_CXX_EXTENSIONS OFF)           # 禁用编译器扩展

set(CMAKE_C_STANDARD 99)                # 设置 C 标准为 C99
set(CMAKE_C_STANDARD_REQUIRED ON)       # 强制要求,不降级
set(CMAKE_C_EXTENSIONS OFF)             # 禁用编译器扩展 

2. 生成库

不建议把所有的.c/.cpp文件都塞进一个add_executable里。推荐的做法是:把功能模块单独编成库,再让主程序去链接它。

比如生成一个名为 module 的静态库,这个库只包含一个源文件:

1
2
add_library(module STATIC src/module.cpp)
# 语法:add_library(<库名> <库类型> [EXCLUDE_FROM_ALL] [库文件路径列表...])

库类型参数:

  • STATIC:静态库 .a/.lib
  • SHARED:动态库 .so/.dll
  • INTERFACE:仅头文件库,如 header-only 的模板库
  • OBJECT:对象文件集合,较少直接用

EXCLUDE_FROM_ALL(选填):

  • 不带 EXCLUDE_FROM_ALL:该库会随着 make 命令被构建。
  • 带了 EXCLUDE_FROM_ALL:make 命令不会构建它。但是仍然可以通过**make明确指定目标名**来单独构建它

注:库文件路径默认是从CMakeLists.txt的所在目录开始的

3. 指定头文件路径

让编译器找得到头文件,同时控制路径依赖的传播。

1
2
3
# 告诉 module 这个目标:你的头文件在 ${CMAKE_CURRENT_SOURCE_DIR}/include 目录下
target_include_directories(module PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
# 语法:target_include_directories(<目标对象> [SYSTEM] [AFTER | BEFORE] [<作用域关键字> [目录路径列表...]...] )

目标对象:由 add_executable() 或 add_library() 创建的目标名称。

SYSTEM(可选):加在作用域关键字之前。告诉编译器这些目录是系统级目录,编译器会抑制该目录下头文件的警告(比如第三方库的警告不再干扰你的编译输出)。

AFTER | BEFORE(可选):控制目录添加到编译器搜索路径的顺序(默认是 AFTER,即追加到列表末尾)。除非有特殊的覆盖需求,否则极少使用。

作用域关键字(必填,至少一个):

  • PUBLIC:既用于该目标,也传递给依赖它的目标。

  • PRIVATE:只用于该目标自身,不传递给依赖它的其他目标

  • INTERFACE:不用于该目标,只传递给依赖它的目标。

目录路径列表(必填):要添加的目录路径。可以是绝对路径或相对路径。

CMake 官方建议:不要直接写裸的相对路径!

  • 不推荐的写法:target_include_directories(mylib PUBLIC include) 这种写法依赖于当前工作目录,极其不稳定(尤其是在 IDE 中或外部构建时)。
  • 推荐写法:使用变量将相对路径转换为绝对路径。
1
2
3
4
# ${CMAKE_CURRENT_SOURCE_DIR} 代表当前正在处理的 CMakeLists.txt 所在的目录
target_include_directories(mylib PUBLIC 
    ${CMAKE_CURRENT_SOURCE_DIR}/include
)

关于为什么 add_library 不需要加 ${CMAKE_CURRENT_SOURCE_DIR},而 target_include_directories 推荐加,核心区别在于:

  • add_library 的路径只在 CMake 配置时被解析,CMake 自己知道当前目录是哪里,拼接很稳。
  • target_include_directories 的路径是写给编译器看的字符串,编译器运行时不知道 CMake 的当前目录,所以必须指明它绝对路径才能找到文件。

再举一个有多个依赖项的例子:

1
2
3
4
5
6
7
target_include_directories(mylib
    PUBLIC
        ${CMAKE_CURRENT_SOURCE_DIR}/include          # 外部使用者也需要
    PRIVATE
        ${CMAKE_CURRENT_SOURCE_DIR}/src              # 仅内部编译需要
        ${CMAKE_CURRENT_SOURCE_DIR}/src/third_party  # 仅内部需要的第三方库
)

这有点像C++类的访问控制符区分字段

4. 生成可执行文件

1
2
add_executable(app main.cpp)
#语法:add_executable(<可执行文件名称> [源文件列表...])

如果有多个源文件,直接全部列出来。

源码文件很多怎么办? 用变量临时存一下:

1
2
set(SOURCES src/math.cpp src/other.cpp src/main.cpp)
add_executable(app ${SOURCES})

注意一定要区分大小写:CMake命令不区分大小写(ADD_EXECUTABLE也行),但变量和路径严格区分。

5. 链接库

可执行文件与库或者库与库之间可能会有调用依赖的关系,需要将它们链接到一起

1
2
3
# 告诉 app:你依赖 module 这个库
target_link_libraries(app PRIVATE module)
# 语法:target_link_libraries(<目标对象> [<作用域关键字> [依赖库列表...]...])

目标对象:

  • 可执行文件:由 add_executable() 创建。
  • 库:由 add_library() 创建

作用域关键字(控制依赖传播范围):

  • PRIVATE:依赖只用于该目标自身,不传递给依赖它的其他目标。
  • PUBLIC:依赖既用于该目标,也传递给依赖它的目标。
  • INTERFACE:依赖不用于该目标,只传递给依赖它的目标(常用于仅有头文件的接口库)

再举一个有多个依赖项的例子:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
target_link_libraries(my_lib
    PUBLIC
        core_api      # 外部用户也需要 core_api
        interface_cv  # 外部用户也需要 OpenCV接口
    PRIVATE
        internal_utils # 仅 my_lib 内部编译链接用
        logger         # 仅内部日志库
    INTERFACE
        header_only_lib # 仅头文件库,只影响外部接口
)

注:依赖关系我建议画个图来梳理会比较直观

三. 总结

掌握了上面这些CMake基础内容,用来构建单文件或者多文件项目够用了,多敲几遍就记得了。引入第三方库以及中大型项目分层,看进阶的内容。

更多详细的内容可以去看CMake的相关文档:

  • 官方主页地址:https://cmake.org/

  • 官方文档地址:https://cmake.org/documentation

  • 中文文档地址:https://cmake.com.cn/