📚 课程目录第2章 CMake基础入门

2、CMake基础入门：CMake是什么、为什么需要CMake、安装与版本选择、CMakeLists.txt基本结构、cmake命令与构建流程（configure、build、install）

CMake是一个跨平台的开源构建系统生成器，它并不直接编译代码，而是通过读取名为CMakeLists.txt的脚本文件，生成目标平台所需的原生构建文件（如Linux下的Makefile、Windows下的Visual Studio解决方案、macOS下的Xcode工程）。在嵌入式、C/C++服务端、图形引擎、科学计算等几乎所有现代C/C++项目中，CMake已经成为事实上的工程组织标准。本章将从CMake的定位出发，厘清它解决的核心痛点，并完整演示从安装、编写CMakeLists.txt到执行configure、build、install的完整链路。

2.1 核心原理：CMake是什么，为什么需要它

CMake（Cross-platform Make）由Kitware公司开发，最初是为了解决VTK库跨平台编译的痛点。它的本质是一个构建系统生成器：你编写一份与平台无关的CMakeLists.txt描述工程结构，CMake根据当前操作系统、编译器、依赖库位置，生成对应的原生构建文件。例如在Linux上生成Makefile，在Windows上生成Visual Studio的.sln工程，在macOS上生成Xcode工程。

为什么需要CMake？直接编写Makefile或Visual Studio工程存在三个致命问题：跨平台重复劳动（同一项目要为Linux、Windows、macOS分别维护构建脚本）、依赖管理困难（手动指定头文件路径、库路径、链接顺序极易出错）、配置选项无法统一（Debug/Release切换、是否启用某个特性、安装路径等）。CMake通过find_package()、option()、target_link_libraries()等命令，将这些问题抽象为声明式描述，一次编写，处处构建。

CMake与Make的关系：Make是构建工具，读取Makefile执行编译命令；CMake是生成Makefile（或其他构建文件）的工具。CMake并不替代编译器，也不替代Make，而是位于“工程描述”与“实际构建”之间的桥梁。你可以把CMakeLists.txt理解为“构建的源代码”，而Makefile是“构建的可执行文件”。

2.2 安装与版本选择：从2.8到3.27的演进

CMake版本选择直接影响可用命令和语法。2.8系列已完全过时，3.0引入了目标导向设计（target-based），3.12之后cmake -S -B成为推荐用法，3.16+对CUDA支持更完善，3.24+支持file(SET)等新特性。建议新项目使用3.16及以上版本，并设置最低版本要求：

cmake_minimum_required(VERSION 3.16...3.27)
project(MyProject VERSION 1.0.0 LANGUAGES C CXX)

安装方式因平台而异：

平台	推荐安装方式	验证命令
Ubuntu/Debian	`sudo apt install cmake` 或从Kitware APT源安装最新版	`cmake --version`
Windows	下载官方安装包（.msi），勾选“Add to PATH”	`cmake --version`（需新开终端）
macOS	`brew install cmake`	`cmake --version`
通用源码编译	从cmake.org下载源码，`./bootstrap && make && sudo make install`	`cmake --version`

版本陷阱：系统自带的CMake可能较旧（如Ubuntu 20.04自带3.16，CentOS 7自带2.8）。若项目使用了target_sources()、install(TARGETS)等较新特性，旧版本会直接报错。建议在CMakeLists.txt第一行声明最低版本，并在CI中固定CMake版本。

2.3 CMakeLists.txt基本结构：从零搭建一个可执行程序

一个最小但完整的CMakeLists.txt包含以下核心元素：

cmake_minimum_required(VERSION 3.16)          # 1. 版本要求
project(HelloCMake VERSION 1.0 LANGUAGES CXX) # 2. 工程名、版本、语言

add_executable(hello main.cpp)                # 3. 定义可执行目标
target_compile_features(hello PRIVATE cxx_std_17) # 4. 指定C++标准
target_include_directories(hello PRIVATE src) # 5. 头文件路径

install(TARGETS hello RUNTIME DESTINATION bin) # 6. 安装规则

这段脚本的逻辑是：要求CMake最低3.16版本，定义工程名为HelloCMake，使用C++语言；将main.cpp编译为名为hello的可执行文件；要求使用C++17标准；将src目录加入头文件搜索路径；安装时将hello放到bin目录。每一行都有明确职责，目标（target）是CMake 3.0之后的核心抽象，所有编译选项、依赖、安装规则都挂在目标上。

2.4 cmake命令与构建流程：configure、build、install全解析

CMake的构建流程分为三个独立阶段，每个阶段对应一个命令。以实际项目为例：

配置阶段（Configure）：cmake -S . -B build。其中-S指定源码根目录（包含CMakeLists.txt），-B指定构建目录。此阶段CMake会检查编译器、解析CMakeLists.txt、查找依赖库、生成构建文件。首次配置会生成CMakeCache.txt缓存所有变量。
构建阶段（Build）：cmake --build build。此命令会自动调用底层构建工具（make、ninja或MSBuild），执行编译和链接。支持-j并行加速，如cmake --build build -j8。
安装阶段（Install）：cmake --install build --prefix /usr/local。将构建产物复制到指定前缀目录，默认前缀是/usr/local（Linux/macOS）或C:\Program Files（Windows）。

推荐实践：永远使用-S和-B显式指定目录，不要进入源码目录直接运行cmake .，这会把构建文件混入源码，污染工程结构。构建目录可以随时删除重建，不影响源码。

2.5 实战案例：一个带库和可执行文件的完整工程

下面通过一个实际案例串联全部知识点。假设我们要构建一个数学库mathlib和一个使用它的命令行工具calc，并支持安装到系统。

工程结构：

math_project/
├── CMakeLists.txt
├── mathlib/
│   ├── CMakeLists.txt
│   ├── include/mathlib/add.h
│   └── src/add.cpp
└── app/
    ├── CMakeLists.txt
    └── main.cpp

顶层CMakeLists.txt：

cmake_minimum_required(VERSION 3.16)
project(MathProject VERSION 1.0 LANGUAGES CXX)

add_subdirectory(mathlib)
add_subdirectory(app)

mathlib/CMakeLists.txt：

add_library(mathlib STATIC src/add.cpp)
target_include_directories(mathlib PUBLIC include)
install(TARGETS mathlib ARCHIVE DESTINATION lib)
install(FILES include/mathlib/add.h DESTINATION include/mathlib)

app/CMakeLists.txt：

add_executable(calc main.cpp)
target_link_libraries(calc PRIVATE mathlib)
install(TARGETS calc RUNTIME DESTINATION bin)

执行流程与结果：

cmake -S . -B build          # 配置：生成Makefile
cmake --build build -j4      # 构建：编译libmathlib.a和calc
cmake --install build --prefix ./install  # 安装到./install目录

安装后目录结构：

install/
├── bin/calc
├── include/mathlib/add.h
└── lib/libmathlib.a

这个案例展示了三个关键点：add_subdirectory组织多模块工程；PUBLIC/PRIVATE控制依赖传递（mathlib的头文件路径通过PUBLIC传递给calc）；install规则分别处理可执行文件、静态库和头文件。实际项目中，你还可以通过option()添加开关（如option(BUILD_TESTING "Build tests" ON)），通过find_package()引入第三方库。

2.6 常见误区与总结复盘

初学者在使用CMake时经常陷入以下误区，需要特别注意：

在源码目录执行cmake：导致构建文件与源码混杂，无法干净地切换构建类型。正确做法是始终使用-B指定独立构建目录。
滥用include_directories()和link_directories()：这是旧式全局命令，会影响所有目标，导致依赖关系混乱。应使用target_include_directories()和target_link_libraries()将属性限定在目标上。
忽略CMAKE_BUILD_TYPE：单配置生成器（如Makefile）默认不设置优化级别，需要显式指定-DCMAKE_BUILD_TYPE=Release或Debug。多配置生成器（如Visual Studio）则无需此变量。
忘记安装规则：只写了add_executable和add_library，没有写install()，导致cmake --install无产物可装。
硬编码路径：在CMakeLists.txt中写死/usr/local/lib等路径，破坏可移植性。应使用find_package()或target_link_libraries()自动解析。

总结本章核心：CMake是构建系统的生成器，通过CMakeLists.txt声明工程结构，使用cmake -S -B配置、cmake --build构建、cmake --install安装。掌握目标导向的设计思想，理解PUBLIC/PRIVATE的传递规则，是进阶的关键。下一阶段，我们将深入探讨变量、缓存、条件逻辑和函数封装，让CMakeLists.txt具备真正的编程能力。