Skip to content

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。搞清这层关系,两者就不会混。