主题
CMake 使用
C++ 项目的事实标准构建工具。记住一句话:CMake 是「生成构建系统」的工具——它读 CMakeLists.txt,生成 Makefile / Ninja / VS 工程,再由后者真正编译。
下面以本机 muduo_im(分布式视频平台)为例,从最小工程一路到多子目录项目。
一、最小可用的 CMakeLists.txt
cmake
cmake_minimum_required(VERSION 3.15) # CMake 最低版本,低于它直接报错
project(myapp CXX) # 工程名 + 语言(CXX 表示只启用 C++)
set(CMAKE_CXX_STANDARD 17) # 使用 C++17
set(CMAKE_CXX_STANDARD_REQUIRED ON) # 编译器不支持 C++17 就报错,而不是静默降级
set(CMAKE_CXX_EXTENSIONS OFF) # 关闭 GNU 扩展,写标准 C++
add_executable(app main.cpp src/list.cpp) # 从源文件生成可执行文件 app
target_include_directories(app PRIVATE include) # 只给 app 加头文件搜索路径
find_package(Threads REQUIRED) # 查找系统线程库
target_link_libraries(app PRIVATE Threads::Threads) # 链接线程库(现代写法)bash
cmake -S . -B build # -S 源码目录,-B 构建目录(源码/构建分离)
cmake --build build -j8 # 编译,-j8 八路并行
./build/app # 运行(add_executable 默认输出在 build/)
rm -rf build # 彻底重来(改了 CMakeLists 不生效时最省事)二、顶层工程:muduo_im 的写法
顶层 CMakeLists.txt 只负责「全局设置 + 引入子目录」,不直接编译任何文件:
cmake
cmake_minimum_required(VERSION 3.10) # 最低版本
project(mprpc_video_platform VERSION 1.0.0 LANGUAGES CXX) # 工程名、版本、语言
set(CMAKE_CXX_STANDARD 17) # 全局 C++17
set(CMAKE_CXX_STANDARD_REQUIRED ON) # 不支持则报错
set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # 生成 compile_commands.json,供 clangd 等使用
if(NOT CMAKE_BUILD_TYPE) # 用户没指定构建类型时
set(CMAKE_BUILD_TYPE Release) # 默认用 Release
endif()
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_SOURCE_DIR}/bin) # 可执行文件统一输出到 bin/
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${PROJECT_SOURCE_DIR}/lib) # 静态库输出到 lib/
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_SOURCE_DIR}/lib) # 动态库输出到 lib/
option(ENABLE_NATIVE_MARCH "Use -march=native for Release builds" ON)
# 自定义开关,可用 -D 覆盖
if(CMAKE_BUILD_TYPE STREQUAL "Release") # 只有 Release 才做这些
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -DNDEBUG -flto=auto")
# -O3 优化、去断言、LTO 链接优化
if(ENABLE_NATIVE_MARCH) # Docker/CI 构建时应关闭
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -march=native")
# 针对本机 CPU 生成指令,换机器可能跑不了
endif()
endif()
add_subdirectory(wevix_muduo) # 引入网络库子工程
add_subdirectory(mprpc) # 引入 RPC 框架子工程
add_subdirectory(video_platform) # 引入业务子工程
add_subdirectory(test) # 引入测试子工程
-march=native的坑:它让编译器用当前 CPU 的专有指令集。本机跑得快,但把二进制或镜像拿到别的机器可能直接Illegal instruction。所以 Dockerfile 里显式-DENABLE_NATIVE_MARCH=OFF。
三、子目录:库 + 多个可执行文件
video_platform/CMakeLists.txt 的典型结构:先编一个公共库,再让每个服务链接它。
cmake
project(video_platform VERSION 1.0.0 LANGUAGES CXX) # 子工程(顶层已设语言标准和版本)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(PROTO_GEN_DIR ${CMAKE_CURRENT_SOURCE_DIR}/proto/generated) # 生成的 pb.cc 目录
set(PROTO_SRCS # 列出要编进库的 pb 源文件
${PROTO_GEN_DIR}/common.pb.cc
${PROTO_GEN_DIR}/job.pb.cc
${PROTO_GEN_DIR}/scheduler.pb.cc
${PROTO_GEN_DIR}/worker.pb.cc
${PROTO_GEN_DIR}/result.pb.cc
)
add_custom_target(gen_protos # 自定义目标:需要时手动生成 proto 代码
COMMAND protoc # 调用 protoc
--cpp_out=${PROTO_GEN_DIR} # C++ 代码输出目录
-I${CMAKE_CURRENT_SOURCE_DIR}/proto # proto 的 import 搜索路径
${CMAKE_CURRENT_SOURCE_DIR}/proto/common.proto
${CMAKE_CURRENT_SOURCE_DIR}/proto/job.proto
COMMENT "Generating C++ from proto files..." # 构建时打印的提示
)
add_library(video_common # 静态库 video_common(默认 STATIC)
src/common_store.cpp # 业务公共逻辑
src/mysql_pool.cpp # MySQL 连接池
src/redis_client.cpp # Redis 客户端
src/mq_client.cpp # RabbitMQ 客户端
${PROTO_SRCS} # 上面列出的 protobuf 源文件
)
target_include_directories(video_common PUBLIC # PUBLIC:链接者也能用这些头文件路径
${CMAKE_CURRENT_SOURCE_DIR}/include # 自己的头文件
${PROTO_GEN_DIR} # 生成的 pb.h
)
target_link_libraries(video_common PUBLIC # PUBLIC:依赖传递给链接者
mprpc # 自研 RPC 库(来自另一个子目录)
protobuf # Protobuf
mysqlclient # MySQL 客户端
hiredis # Redis 客户端
rabbitmq # RabbitMQ 客户端
)
add_executable(job_service src/result_collector/job_service/job_service.cpp)
target_link_libraries(job_service video_common) # 只需要链接公共库,头文件路径自动继承
add_executable(scheduler_service src/scheduler_service/scheduler_service.cpp)
target_link_libraries(scheduler_service video_common)
add_executable(transcode_worker src/transcode_worker/transcode_worker.cpp)
target_link_libraries(transcode_worker video_common)PRIVATE / PUBLIC / INTERFACE 怎么选:
| 关键字 | 自己编译用 | 传给链接者 | 典型场景 |
|---|---|---|---|
PRIVATE | ✅ | ❌ | 内部实现依赖,如某个 .cpp 用的库 |
PUBLIC | ✅ | ✅ | 公共库的接口依赖,如 video_common 的头文件 |
INTERFACE | ❌ | ✅ | 纯头文件库、只做传递的依赖 |
四、标准构建命令
bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release # 配置:源码 . → 构建目录 build
cmake --build build -j8 # 编译,8 路并行
cmake --build build --target job_service # 只编某一个目标
cmake --build build --target clean # 清理构建产物
cmake -S . -B build -DENABLE_NATIVE_MARCH=OFF # 覆盖 option 开关
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr # 指定安装前缀
cmake --install build # 安装(需要工程写了 install 规则)
ctest --test-dir build --output-on-failure # 跑测试(需要 enable_testing)| 构建类型 | 编译选项 | 用途 |
|---|---|---|
Debug | -g -O0 | 调试,变量不被优化掉 |
Release | -O3 -DNDEBUG | 发布 |
RelWithDebInfo | -O2 -g | 线上 / 定位问题推荐 |
MinSizeRel | -Os | 追求最小体积 |
五、依赖查找
cmake
find_package(Threads REQUIRED) # REQUIRED:找不到直接报错
find_package(OpenSSL REQUIRED)
find_package(Protobuf REQUIRED)
target_link_libraries(app PRIVATE
Threads::Threads # 现代导入目标,自带头文件路径和编译选项
OpenSSL::SSL
OpenSSL::Crypto
${Protobuf_LIBRARIES} # 老式变量写法,兼容性更好
)
target_compile_definitions(app PRIVATE VERSION=\"1.0.0\") # 等价于命令行 -DVERSION=...优先用
find_package提供的命名空间::目标(如Threads::Threads),它会自动带上 include 路径和编译选项;老式${XXX_LIBRARIES}只是库文件,路径得自己加。
六、常见坑
- 改了
CMakeLists.txt不生效:cmake --build一般会自动重新 configure;仍不对就删build/重来。 - 头文件找不到:加
target_include_directories,别用全局include_directories(作用域太大)。 - 链接顺序问题:CMake 的
target_link_libraries会自动处理依赖顺序,比手写 Makefile 省心。 CMakeCache.txt缓存了旧路径:换了目录或工具链,删CMakeCache.txt或整个build/。- 交叉编译:
-DCMAKE_TOOLCHAIN_FILE=arm.cmake,且所有依赖库也必须是目标架构版本。 - 别把
build/提交进 Git:写进.gitignore。
CMake vs Make:
make是构建工具,描述「怎么编译」;cmake是构建系统生成器,描述「项目长什么样」,再生成 Makefile。搞清这层关系,两者就不会混。