CMake入门教程：让跨平台构建变得简单

前言

还在为不同平台的编译环境头疼吗？Windows上写的代码搬到Linux就各种报错？编译选项记不清楚？项目依赖太复杂导致每次配置环境都要半天？如果你有这些困扰，那么CMake绝对是你不可错过的救星！

作为一个在跨平台开发中摸爬滚打多年的程序员，我不得不说：掌握CMake是提升工作效率的关键技能！ CMake让我从繁琐的编译配置中解脱出来，把更多精力放在代码设计和功能实现上。

今天就让我们一起揭开CMake的神秘面纱，看看这个强大的工具如何让跨平台构建变得轻而易举。

CMake是什么？

简单来说，CMake是一个开源的跨平台自动化构建系统。它不直接构建最终的软件，而是生成标准的构建文件（比如Windows上的Visual Studio项目文件，Linux上的Makefile），然后再由本地的构建工具完成最终编译。

这种"元构建系统"的设计非常巧妙：

• 你只需要编写一套CMake脚本
• CMake负责生成各平台的本地构建配置
• 本地构建工具负责最终的编译链接

这样，无论你在Windows、Linux还是macOS上开发，项目的构建过程都能保持一致！（这就是为什么那么多大型开源项目都选择CMake作为构建系统）

为什么要学习CMake？

你可能会想："编译不就是点一下按钮的事吗？为什么要学这个？"

让我告诉你几个不得不学CMake的理由：

1. 跨平台兼容性 - 同一套构建脚本，适用于所有主流平台
2. 依赖管理 - 自动查找、配置第三方库依赖
3. 灵活性 - 条件编译、自定义构建配置变得简单
4. 行业标准 - 大量开源项目使用CMake（Qt、OpenCV、Boost等）
5. 减少重复工作 - 告别手动维护不同IDE的项目文件

对于任何规模稍大的C/C++项目来说，合适的构建系统不再是可选项，而是必需品！

安装CMake

开始实践前，需要先安装CMake。这个过程相当简单：

Windows: - 访问CMake官网下载安装包 - 运行安装程序，并确保勾选"添加CMake到系统PATH"选项 - 安装完成后，打开命令提示符输入cmake --version验证

Linux: ```bash

Ubuntu/Debian

sudo apt-get install cmake

CentOS/RHEL

sudo yum install cmake

验证安装

cmake --version ```

macOS: ```bash

使用Homebrew

brew install cmake

验证安装

cmake --version ```

安装完成后，你应该能看到类似这样的输出： cmake version 3.23.1

只要版本号在3.10以上，对于入门学习来说就足够了。（个人建议使用最新版本，因为每个版本都会引入有用的新功能）

CMake基础：Hello World项目

让我们从最简单的例子开始 - 一个打印"Hello World"的C++程序。

首先，创建如下的项目结构： hello_cmake/ ├── CMakeLists.txt └── main.cpp

main.cpp文件内容： ```cpp

include

int main() { std::cout << "Hello, CMake!" << std::endl; return 0; } ```

CMakeLists.txt文件内容： ```cmake

指定CMake最低版本要求

cmake_minimum_required(VERSION 3.10)

设置项目名称

project(HelloCMake)

创建可执行文件

add_executable(hello_cmake main.cpp) ```

这个简单的CMakeLists.txt文件已经包含了三个基本命令： 1. cmake_minimum_required - 声明所需的最低CMake版本 2. project - 定义项目名称（和可选的版本、描述等） 3. add_executable - 创建一个可执行文件目标，并指定源文件

现在，让我们构建这个项目：

```bash

创建构建目录（推荐的做法是使用单独的构建目录）

mkdir build cd build

生成构建系统

cmake ..

执行构建

cmake --build . ```

成功构建后，你会在build目录中找到可执行文件hello_cmake（Linux/macOS）或hello_cmake.exe（Windows）。运行它，你应该能看到输出：

Hello, CMake!

恭喜！你已经成功创建并构建了第一个CMake项目！

构建库和链接

大多数实际项目会有多个源文件，并被组织成库和可执行文件。让我们看看如何用CMake处理这种情况。

假设我们有这样的项目结构： my_project/ ├── CMakeLists.txt ├── include/ │ └── my_lib.h ├── src/ │ ├── my_lib.cpp │ └── main.cpp

include/my_lib.h: ```cpp

pragma once

int add(int a, int b); ```

src/my_lib.cpp: ```cpp

include "my_lib.h"

int add(int a, int b) { return a + b; } ```

src/main.cpp: ```cpp

include

include "my_lib.h"

int main() { int result = add(5, 3); std::cout << "5 + 3 = " << result << std::endl; return 0; } ```

现在，我们可以编写CMakeLists.txt： ```cmake cmake_minimum_required(VERSION 3.10) project(MyProject VERSION 1.0)

添加库

add_library(my_lib src/my_lib.cpp) target_include_directories(my_lib PUBLIC include)

添加可执行文件并链接库

add_executable(my_app src/main.cpp) target_link_libraries(my_app PRIVATE my_lib) ```

这个例子引入了几个新概念：

1. add_library - 创建一个库目标
2. target_include_directories - 指定目标的包含目录
3. PUBLIC表示这些目录同时对库本身和使用该库的目标可见
4. target_link_libraries - 将目标与库进行链接
5. PRIVATE表示这些库仅用于目标的内部实现

构建过程与之前相同： bash mkdir build && cd build cmake .. cmake --build .

设置编译选项

CMake允许你为项目和特定目标设置编译选项。这对于控制警告级别、优化级别或启用特定语言特性非常有用。

例如，为所有目标启用C++17标准和警告： ```cmake

设置C++标准

set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF)

启用警告

if(MSVC) add_compile_options(/W4) else() add_compile_options(-Wall -Wextra -Wpedantic) endif() ```

对于特定目标，你可以使用target_compile_options： cmake target_compile_options(my_lib PRIVATE -fPIC)

还可以为调试和发布模式设置不同的选项： ```cmake

设置优化级别

set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -O0") set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3") ```

构建时指定配置类型： bash cmake -DCMAKE_BUILD_TYPE=Release ..

使用第三方库

在实际项目中，我们常常需要使用第三方库。CMake提供了find_package命令来查找和使用已安装的库。

例如，使用Boost库： ```cmake

查找Boost库

find_package(Boost 1.65 REQUIRED COMPONENTS filesystem system)

将Boost链接到我们的目标

target_link_libraries(my_app PRIVATE Boost::filesystem Boost::system) ```

当然，库必须以CMake能够识别的方式安装在系统上。对于不使用CMake的库，你可能需要编写Find模块或使用pkg-config。

条件编译

CMake允许你根据各种条件调整构建过程。例如，根据平台或选项启用/禁用代码：

```cmake

平台检测

if(WIN32) # Windows特定代码 target_sources(my_app PRIVATE src/windows_specific.cpp) elseif(APPLE) # macOS特定代码 target_sources(my_app PRIVATE src/macos_specific.cpp) elseif(UNIX) # Linux/Unix特定代码 target_sources(my_app PRIVATE src/linux_specific.cpp) endif()

选项

option(USE_FEATURE "启用特定功能" OFF) if(USE_FEATURE) target_compile_definitions(my_app PRIVATE ENABLE_FEATURE) endif() ```

用户可以在命令行中启用选项： bash cmake -DUSE_FEATURE=ON ..

创建配置头文件

有时，你需要在代码中使用CMake变量。configure_file命令可以将CMake变量注入到头文件中：

config.h.in: ```c

pragma once

define PROJECT_NAME "@PROJECT_NAME@"

define PROJECT_VERSION "@PROJECT_VERSION@"

cmakedefine USE_FEATURE

```

CMakeLists.txt: ```cmake option(USE_FEATURE "启用特定功能" OFF)

configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/config.h.in ${CMAKE_CURRENT_BINARY_DIR}/config.h )

target_include_directories(my_app PRIVATE ${CMAKE_CURRENT_BINARY_DIR}) ```

现在，你的C++代码可以包含生成的config.h文件并使用其中的定义。

测试

CMake通过CTest模块支持测试。首先，在顶层CMakeLists.txt中启用测试：

```cmake

启用测试

enable_testing() ```

然后，添加测试： ```cmake

添加一个简单的测试

add_test( NAME test_app COMMAND my_app arg1 arg2 )

设置测试属性

set_tests_properties(test_app PROPERTIES PASS_REGULAR_EXPRESSION "All tests passed" ) ```

你也可以使用像GoogleTest这样的测试框架，CMake对其有很好的支持。

运行测试： bash cd build ctest

安装规则

定义如何安装你的项目也很重要。CMake通过install命令支持这一点：

```cmake

安装可执行文件

install(TARGETS my_app DESTINATION bin)

安装库

install(TARGETS my_lib LIBRARY DESTINATION lib ARCHIVE DESTINATION lib RUNTIME DESTINATION bin )

安装头文件

install(DIRECTORY include/ DESTINATION include)

安装配置文件

install(FILES ${CMAKE_CURRENT_BINARY_DIR}/config.h DESTINATION include ) ```

执行安装： bash cmake --build . --target install

或者： bash cd build cmake --install .

你可以通过CMAKE_INSTALL_PREFIX变量指定安装位置： bash cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..

进阶技巧与最佳实践

随着对CMake的深入了解，这里有一些进阶技巧和最佳实践：

1. 使用现代CMake - 避免使用过时的命令（如link_directories）和变量操作，而应使用目标属性（如target_link_libraries）
2. 创建包配置文件 - 使其他CMake项目能够轻松使用你的库 cmake include(CMakePackageConfigHelpers) write_basic_package_version_file(...) configure_package_config_file(...)
3. 使用生成器表达式 - 在构建时评估的表达式，提供强大的条件逻辑 cmake target_compile_options(my_lib PUBLIC $<$<CXX_COMPILER_ID:MSVC>:/W4> $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra> )
4. 使用预设 - CMake 3.19引入的CMakePresets.json文件，允许定义和共享构建配置 json { "version": 3, "configurePresets": [ { "name": "debug", "displayName": "Debug", "generator": "Ninja", "binaryDir": "${sourceDir}/build/debug", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" } } ] }
5. 模块化CMake文件 - 对于大型项目，将CMake逻辑分散到多个文件中 cmake add_subdirectory(src) add_subdirectory(tests)

使用现代CMake - 避免使用过时的命令（如link_directories）和变量操作，而应使用目标属性（如target_link_libraries）

创建包配置文件 - 使其他CMake项目能够轻松使用你的库 cmake include(CMakePackageConfigHelpers) write_basic_package_version_file(...) configure_package_config_file(...)

使用生成器表达式 - 在构建时评估的表达式，提供强大的条件逻辑 cmake target_compile_options(my_lib PUBLIC $<$<CXX_COMPILER_ID:MSVC>:/W4> $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra> )

使用预设 - CMake 3.19引入的CMakePresets.json文件，允许定义和共享构建配置 json { "version": 3, "configurePresets": [ { "name": "debug", "displayName": "Debug", "generator": "Ninja", "binaryDir": "${sourceDir}/build/debug", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" } } ] }

模块化CMake文件 - 对于大型项目，将CMake逻辑分散到多个文件中 cmake add_subdirectory(src) add_subdirectory(tests)

常见问题与解决方案

在使用CMake时，你可能会遇到一些常见问题：

问题：找不到库 CMake Error: Could not find package Boost 解决方案：指定库的位置 bash cmake -DBOOST_ROOT=/path/to/boost ..

问题：构建类型未设置 解决方案：明确指定构建类型 bash cmake -DCMAKE_BUILD_TYPE=Debug ..

问题：不兼容的库版本 解决方案：在CMakeLists.txt中明确要求的版本 cmake find_package(Boost 1.70 REQUIRED)

问题：不同编译器的警告处理 解决方案：使用生成器表达式 cmake target_compile_options(my_app PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/W4 /WX> $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Werror> )

总结

CMake是一个强大的跨平台构建系统，掌握它可以极大地提升你的C/C++开发效率。从简单的项目到复杂的多组件系统，CMake都能很好地处理。

在这篇教程中，我们探讨了： - CMake的基本概念和工作原理 - 创建和构建简单项目 - 管理库和依赖关系 - 设置编译选项 - 使用第三方库 - 条件编译和配置 - 测试和安装

希望这篇入门教程能帮助你开始使用CMake！记住，像所有工具一样，熟能生巧。随着你构建更多项目，你会越来越熟悉CMake并发现它的强大之处。

学习资源： - CMake官方文档 - CMake教程 - 现代CMake实践

祝你构建愉快！