异常教程

CMake 构建实例（保姆级教程）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

  • 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;
  • 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 82w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 2900+ 小伙伴加入学习 ，欢迎点击围观

在软件开发中，构建系统是连接代码与可执行程序的桥梁，它决定了如何编译、链接和部署项目。对于初学者而言，手动管理编译命令既繁琐又容易出错，而 CMake 构建实例 正是为了简化这一过程而设计的工具。本文将以实际案例为核心，从基础到进阶，逐步展示如何通过 CMake 创建、优化和管理复杂的构建流程。无论是搭建小型工具还是大型系统，CMake 的灵活性和跨平台特性都能为开发者提供高效支持。

什么是 CMake？

CMake 是一个跨平台的构建系统生成器，它通过描述项目结构的配置文件（如 CMakeLists.txt），自动生成适用于不同操作系统的构建文件（如 Makefile、Visual Studio 项目文件等）。

比喻：
可以把 CMake 想象为一位“建筑设计师”。它不会直接“建造房屋”（即编译代码），而是根据你的需求设计蓝图（生成构建文件），然后由“施工队”（如 make、MSBuild 等编译工具）执行具体操作。这种分工使得项目配置更简洁，且能适配不同平台。

CMake 的核心概念与工作流程

1. 主要组成

  • CMakeLists.txt：项目的配置文件，定义编译规则、依赖项、编译选项等。
  • CMake 命令：如 project()、add_executable()、find_package() 等，用于描述构建逻辑。
  • 生成的构建文件：CMake 根据配置生成的平台特定文件（如 Makefile）。

2. 工作流程

  1. 配置阶段：运行 cmake 命令，解析 CMakeLists.txt，生成构建文件。
  2. 构建阶段：使用 make（Linux/macOS）或 msbuild（Windows）等工具，根据生成的构建文件执行编译和链接。

CMake 基础语法与配置文件

1. 最简单的 CMake 配置

假设有一个单文件的 C++ 程序 hello.cpp，其代码如下：

#include <iostream>  
int main() {  
    std::cout << "Hello CMake!" << std::endl;  
    return 0;  
}

对应的 CMakeLists.txt 配置如下：

cmake_minimum_required(VERSION 3.10)  
project(HelloCMake)  
add_executable(hello hello.cpp)

解释：

  • cmake_minimum_required(VERSION 3.10)：指定 CMake 的最低版本要求。
  • project(HelloCMake)：定义项目名称，生成的文件会带有此标识。
  • add_executable(hello hello.cpp)：声明一个可执行文件 hello，并指定源文件。

2. 构建步骤

在终端中执行以下命令：

mkdir build && cd build  
cmake ..  
cmake --build .

输出结果为可执行文件 hello，运行即可看到输出。

多文件项目与库的构建

1. 案例：分层项目结构

假设项目包含以下文件：

my_project/  
├── main.cpp  
├── utils/  
│   ├── math_utils.cpp  
│   └── math_utils.h  
└── CMakeLists.txt

main.cpp 调用 math_utils 中的函数，需通过 CMakeLists.txt 管理依赖关系。

2. 配置 CMakeLists.txt

cmake_minimum_required(VERSION 3.10)  
project(MyProject)  

add_executable(myapp  
    main.cpp  
    utils/math_utils.cpp  
)  

target_include_directories(myapp PRIVATE utils/)

关键点：

  • target_include_directories 指定了头文件的搜索路径。
  • 若项目规模扩大，可将 utils 目录封装为静态库（.a 或 .lib），提升复用性。

进阶功能：添加库与依赖管理

1. 创建静态库

假设 utils 目录需封装为静态库 libmath.a，修改 CMakeLists.txt：

add_library(math_utils STATIC utils/math_utils.cpp)  

target_link_libraries(myapp math_utils)

此时，myapp 会依赖 math_utils 库，编译时会自动链接。

2. 处理外部依赖（如 SQLite）

若项目需要使用第三方库（如 SQLite），可通过 find_package 自动定位：

find_package(Sqlite3 REQUIRED)  
include_directories(${SQLITE3_INCLUDE_DIR})  
add_executable(myapp main.cpp)  
target_link_libraries(myapp ${SQLITE3_LIBRARIES})

此配置会自动检测 SQLite 的路径，无需手动指定。

条件编译与可选功能

1. 根据平台或编译器调整代码

通过 if 条件语句，可针对不同环境启用特定代码：

if (UNIX)  
    add_definitions(-DUSE_UNIX_API)  
endif()

在代码中：

#ifdef USE_UNIX_API  
    // Linux/macOS 特有逻辑  
#else  
    // 其他平台逻辑  
#endif

2. 命令行参数控制编译选项

通过 option 命令，允许用户在配置时启用或禁用功能：

option(ENABLE_DEBUG "Enable debug mode" ON)  
if (ENABLE_DEBUG)  
    add_definitions(-DDEBUG)  
    set(CMAKE_BUILD_TYPE Debug)  
endif()

执行 cmake -DENABLE_DEBUG=OFF .. 可关闭调试模式。

高级技巧：跨平台与交叉编译

1. 跨平台配置

CMake 支持多平台构建，例如为 Windows 编译时，只需切换生成器：

cmake -G "Visual Studio 17 2022" ..

生成的 .sln 文件可直接在 Visual Studio 中打开。

2. 交叉编译示例（以 ARM 为目标）

假设需在 x86_64 主机上为 ARM 设备编译：

set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)  
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)

此配置会强制使用 ARM 工具链编译代码。

实战案例：构建一个完整的项目

1. 项目结构

calculator/  
├── CMakeLists.txt  
├── include/  
│   └── calculator.hpp  
├── src/  
│   ├── calculator.cpp  
│   └── main.cpp  
└── tests/  
    └── calculator_test.cpp

2. 完整的 CMakeLists.txt

cmake_minimum_required(VERSION 3.18)  
project(CalculatorProject)  

add_executable(calculator  
    src/main.cpp  
    src/calculator.cpp  
)  

target_include_directories(calculator PRIVATE include/)  

add_executable(calculator_test tests/calculator_test.cpp)  
target_link_libraries(calculator_test calculator)  

option(ENABLE_ASSERT "Enable assertions in release builds" OFF)  
if (ENABLE_ASSERT)  
    target_compile_definitions(calculator PRIVATE -DENABLE_ASSERT)  
endif()  

add_custom_target(format  
    COMMAND clang-format -i include/*.hpp src/*.cpp tests/*.cpp  
    COMMENT "Formatting code..."  
)

3. 构建与测试

cmake -DENABLE_ASSERT=ON ..  

cmake --build . --target calculator  
./calculator  

cmake --build . --target format

常见问题与解决方案

1. 编译时找不到头文件

原因：未正确设置 target_include_directories。
解决：确保头文件路径已添加到目标的 include 路径中。

2. 跨平台编译失败

原因：依赖库未安装或路径错误。
解决：使用 find_package 自动检测，或手动指定 CMAKE_PREFIX_PATH。

3. 构建速度慢

优化：

  • 使用 ccache 缓存编译结果。
  • 在 CMakeLists.txt 中添加： 
    set(CMAKE_CXX_COMPILER_LAUNCHER "ccache")

结论

通过本文的 CMake 构建实例，我们从基础语法到复杂项目配置，逐步探索了 CMake 的核心功能。无论是管理多文件项目、封装库、处理依赖，还是实现跨平台构建，CMake 都能提供简洁高效的解决方案。对于开发者而言，掌握 CMake 的配置逻辑，不仅能提升构建流程的自动化水平，还能显著减少因环境差异导致的兼容性问题。

下一步建议：

  1. 尝试将现有项目迁移到 CMake 管理。
  2. 探索 CMake GUI 工具，可视化配置选项。
  3. 参考官方文档学习更多高级功能（如 generator expressions）。

通过实践与持续学习，CMake 将成为你开发道路上不可或缺的得力工具。

最新发布

查看更多文章