Home

Posts

📌CMake 现代化配置完整指南

June 29, 2025

#cpp

#cmake

CMake 现代化配置完整指南

项目基础配置

最小版本要求与项目声明

cmake_minimum_required(VERSION 3.14)

project(VisionDemo VERSION 1.0.0 LANGUAGES CXX)

说明：

cmake_minimum_required：指定所需的最低CMake版本
project：定义项目名称、版本号和使用的语言
VERSION：设置项目版本，可通过 ${PROJECT_VERSION} 引用
LANGUAGES：明确指定使用的编程语言

C++ 编译标准设置

全局标准设置

# 设置 C++17 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

各参数含义：

参数	作用	说明
`CMAKE_CXX_STANDARD`	指定C++标准版本	告诉编译器使用哪个C++标准（如17、20、23）
`CMAKE_CXX_STANDARD_REQUIRED`	强制要求指定标准	ON：编译器必须支持指定标准，否则报错
`CMAKE_CXX_EXTENSIONS`	禁用编译器扩展	OFF：使用纯标准C++，提高跨平台兼容性

编译器参数映射：

GCC/Clang: -std=c++17
MSVC: /std:c++17

针对特定目标的标准设置

set_target_properties(VisionDemo PROPERTIES
    CXX_STANDARD 17
    CXX_STANDARD_REQUIRED ON
    CXX_EXTENSIONS OFF
)

使用场景：

项目中不同目标需要不同的C++标准
明确指定某个目标的编译标准
覆盖全局设置

编译器选项与警告配置

全局编译选项

if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
    add_compile_options(-Wall -Wextra -Wpedantic)
endif()

目标特定编译选项（推荐）

if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
    target_compile_options(VisionDemo PRIVATE
        -Wall
        -Wextra
        -Wpedantic
        -Wno-unused-parameter
        -Wno-unused-variable
    )
endif()

编译选项说明：

选项	作用
`-Wall`	启用所有常用警告
`-Wextra`	启用更多额外警告
`-Wpedantic`	强制标准兼容性检查
`-Wno-unused-parameter`	关闭未使用参数警告
`-Wno-unused-variable`	关闭未使用变量警告

多编译器支持

if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
    target_compile_options(${TARGET_NAME} PRIVATE
        -Wall -Wextra -Wpedantic
        -Wno-unused-parameter -Wno-unused-variable
    )
elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
    target_compile_options(${TARGET_NAME} PRIVATE
        /W4          # 高警告级别
        /WX          # 将警告视为错误
        /utf-8       # 使用UTF-8编码
    )
endif()

重要提醒： target_compile_options 必须在 add_executable 或 add_library 之后调用，否则会报错：

Cannot specify compile options for target "TargetName" which is not built by this project.

输出目录结构管理

构建阶段输出目录

# 设置构建阶段的输出目录
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)

目录类型说明：

变量	文件类型	示例
`CMAKE_RUNTIME_OUTPUT_DIRECTORY`	可执行文件	`.exe`, 无扩展名的二进制文件
`CMAKE_LIBRARY_OUTPUT_DIRECTORY`	动态链接库	`.so`, `.dylib`, `.dll`
`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`	静态库	`.a`, `.lib`

多配置生成器支持

# 为多配置生成器（如 MSVC）指定每个构建类型的输出路径
foreach(OUTPUT_CONFIG IN LISTS CMAKE_CONFIGURATION_TYPES)
    string(TOUPPER ${OUTPUT_CONFIG} OUTPUT_CONFIG)
    set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_${OUTPUT_CONFIG} ${CMAKE_RUNTIME_OUTPUT_DIRECTORY})
    set(CMAKE_LIBRARY_OUTPUT_DIRECTORY_${OUTPUT_CONFIG} ${CMAKE_LIBRARY_OUTPUT_DIRECTORY})
    set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY_${OUTPUT_CONFIG} ${CMAKE_ARCHIVE_OUTPUT_DIRECTORY})
endforeach()

构建结果示例：

build/
├── bin/
│   └── VisionDemo
└── lib/
    ├── libVisionDemo.a
    └── libVisionDemo.so

环境检测与路径配置

Anaconda 环境检测

# 检查是否在 Anaconda 环境中
if(DEFINED ENV{CONDA_PREFIX})
    set(CMAKE_PREFIX_PATH $ENV{CONDA_PREFIX})
    set(CMAKE_INCLUDE_PATH $ENV{CONDA_PREFIX}/include)
    set(CMAKE_LIBRARY_PATH $ENV{CONDA_PREFIX}/lib)
    message(STATUS "Detected Conda environment: $ENV{CONDA_PREFIX}")
endif()

环境变量说明：

CONDA_PREFIX：当前激活的Conda环境路径
CMAKE_PREFIX_PATH：CMake包查找路径前缀
CMAKE_INCLUDE_PATH：头文件查找路径
CMAKE_LIBRARY_PATH：库文件查找路径

路径优先级管理

# 设置查找路径优先级
list(INSERT CMAKE_PREFIX_PATH 0 ${CMAKE_CURRENT_SOURCE_DIR}/extern)
list(INSERT CMAKE_MODULE_PATH 0 ${CMAKE_CURRENT_SOURCE_DIR}/cmake)

第三方依赖管理

使用 FetchContent 自动下载依赖

include(FetchContent)

# 下载并构建 fmt 库
FetchContent_Declare(
    fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG 9.1.0
)
FetchContent_MakeAvailable(fmt)

# 下载并构建 spdlog 库
FetchContent_Declare(
    spdlog
    GIT_REPOSITORY https://github.com/gabime/spdlog.git
    GIT_TAG v1.11.0
)
FetchContent_MakeAvailable(spdlog)

FetchContent 优点：

📦 无需手动安装第三方库
🔒 可指定版本，避免兼容性问题
🔁 支持缓存和增量更新
🧩 与CMake依赖管理无缝集成

常用第三方库配置

# Google Test
FetchContent_Declare(
    googletest
    GIT_REPOSITORY https://github.com/google/googletest.git
    GIT_TAG release-1.12.1
)
FetchContent_MakeAvailable(googletest)

# JSON库
FetchContent_Declare(
    nlohmann_json
    GIT_REPOSITORY https://github.com/nlohmann/json.git
    GIT_TAG v3.11.2
)
FetchContent_MakeAvailable(nlohmann_json)

# Eigen 数学库
FetchContent_Declare(
    eigen
    GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
    GIT_TAG 3.4.0
)
FetchContent_MakeAvailable(eigen)

find_package 方式

# 查找系统安装的包
find_package(OpenCV REQUIRED)
find_package(Boost REQUIRED COMPONENTS system filesystem thread)
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK3 REQUIRED gtk+-3.0)

目标链接与可见性

链接可见性修饰符

target_link_libraries(MyTarget
    PRIVATE   privately_used_lib     # 仅当前目标使用
    PUBLIC    publicly_exposed_lib   # 当前目标和依赖者都使用
    INTERFACE interface_only_lib     # 仅依赖者使用
)

可见性对比：

修饰符	对当前目标生效	传播到依赖者	使用场景
`PRIVATE`	✅	❌	内部实现依赖
`PUBLIC`	✅	✅	公共API的一部分
`INTERFACE`	❌	✅	头文件库、接口库

实际应用示例

# 创建库
add_library(MyLib src/mylib.cpp)

target_link_libraries(MyLib
    PRIVATE spdlog::spdlog        # 内部日志，不对外暴露
    PUBLIC fmt::fmt               # 公共接口使用fmt格式化
    INTERFACE Eigen3::Eigen       # 头文件库，仅依赖者需要
)

# 创建应用程序
add_executable(MyApp src/main.cpp)
target_link_libraries(MyApp PRIVATE MyLib)

# MyApp 可以使用 fmt::fmt 和 Eigen，但不能直接使用 spdlog

接口库创建

# 创建纯头文件库
add_library(MyHeaderLib INTERFACE)
target_include_directories(MyHeaderLib INTERFACE 
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:include>
)
target_link_libraries(MyHeaderLib INTERFACE fmt::fmt)

安装配置与部署

基础安装配置

include(GNUInstallDirs)  # 提供标准安装路径

# 安装可执行文件
install(TARGETS VisionDemo
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

# 安装库文件
install(TARGETS VisionDemo
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}  # Windows DLL
)

完整安装配置

# 安装头文件
install(DIRECTORY include/VisionDemo
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
    FILES_MATCHING PATTERN "*.h" PATTERN "*.hpp"
)

# 安装配置文件
install(FILES config/VisionDemo.conf
    DESTINATION ${CMAKE_INSTALL_SYSCONFDIR}/VisionDemo
)

# 生成并安装版本文件
include(CMakePackageConfigHelpers)
write_basic_package_version_file(
    "${CMAKE_CURRENT_BINARY_DIR}/VisionDemoConfigVersion.cmake"
    VERSION ${PROJECT_VERSION}
    COMPATIBILITY AnyNewerVersion
)

install(FILES 
    "${CMAKE_CURRENT_BINARY_DIR}/VisionDemoConfigVersion.cmake"
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/VisionDemo
)

安装路径说明

GNUInstallDirs 提供的标准路径：

变量	默认值	说明
`CMAKE_INSTALL_BINDIR`	`bin`	可执行文件
`CMAKE_INSTALL_LIBDIR`	`lib`	库文件
`CMAKE_INSTALL_INCLUDEDIR`	`include`	头文件
`CMAKE_INSTALL_SYSCONFDIR`	`etc`	配置文件
`CMAKE_INSTALL_DATADIR`	`share`	数据文件

使用安装

# 配置并构建
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# 安装到指定目录
cmake --install build --prefix /opt/VisionDemo

# 或使用传统方式
cd build && make install

自定义构建目标

版本信息目标

add_custom_target(version_info
    COMMAND ${CMAKE_COMMAND} -E echo "Building ${PROJECT_NAME} version ${PROJECT_VERSION}"
    COMMAND ${CMAKE_COMMAND} -E echo "C++ compiler: ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION}"
    COMMAND ${CMAKE_COMMAND} -E echo "Build type: ${CMAKE_BUILD_TYPE}"
    COMMAND ${CMAKE_COMMAND} -E echo "Install prefix: ${CMAKE_INSTALL_PREFIX}"
    VERBATIM
)

# 让主目标依赖版本信息
add_dependencies(VisionDemo version_info)

代码格式化目标

find_program(CLANG_FORMAT clang-format)
if(CLANG_FORMAT)
    file(GLOB_RECURSE SOURCE_FILES 
        "${CMAKE_SOURCE_DIR}/src/*.cpp"
        "${CMAKE_SOURCE_DIR}/src/*.h"
        "${CMAKE_SOURCE_DIR}/include/*.h"
    )
    
    add_custom_target(format
        COMMAND ${CLANG_FORMAT} -i ${SOURCE_FILES}
        COMMENT "Formatting source code with clang-format"
        VERBATIM
    )
endif()

文档生成目标

find_package(Doxygen)
if(DOXYGEN_FOUND)
    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in)
    set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
    
    configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
    
    add_custom_target(docs
        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "Generating API documentation with Doxygen"
        VERBATIM
    )
endif()

完整示例项目

项目结构

VisionDemo/
├── CMakeLists.txt
├── cmake/
│   ├── Dependencies.cmake
│   └── CompilerOptions.cmake
├── include/
│   └── VisionDemo/
│       ├── VisionDemo.h
│       └── Config.h
├── src/
│   ├── main.cpp
│   ├── VisionDemo.cpp
│   └── Config.cpp
├── tests/
│   └── test_VisionDemo.cpp
├── docs/
│   └── Doxyfile.in
└── README.md

主 CMakeLists.txt

cmake_minimum_required(VERSION 3.14)

project(VisionDemo 
    VERSION 1.2.0 
    DESCRIPTION "Modern VisionDemo Management System"
    LANGUAGES CXX
)

# --- 编译标准设置 ---
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# --- 输出目录设置 ---
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)

# --- 环境检测 ---
if(DEFINED ENV{CONDA_PREFIX})
    set(CMAKE_PREFIX_PATH $ENV{CONDA_PREFIX})
    message(STATUS "Using Conda environment: $ENV{CONDA_PREFIX}")
endif()

# --- 包含子模块 ---
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
include(Dependencies)
include(CompilerOptions)

# --- 包含目录 ---
include_directories(${PROJECT_SOURCE_DIR}/include)

# --- 源文件收集 ---
file(GLOB_RECURSE SOURCES src/*.cpp)
file(GLOB_RECURSE HEADERS include/*.h)

# --- 创建库目标 ---
add_library(VisionDemoLib STATIC ${SOURCES} ${HEADERS})
target_include_directories(VisionDemoLib PUBLIC 
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:include>
)

# --- 创建可执行目标 ---
add_executable(VisionDemo src/main.cpp)
target_link_libraries(VisionDemo PRIVATE 
    VisionDemoLib
    fmt::fmt
    spdlog::spdlog
)

# --- 设置编译选项 ---
setup_compiler_options(VisionDemo)
setup_compiler_options(VisionDemoLib)

# --- 版本信息 ---
add_custom_target(version_info
    COMMAND ${CMAKE_COMMAND} -E echo "Building ${PROJECT_NAME} ${PROJECT_VERSION}"
    COMMAND ${CMAKE_COMMAND} -E echo "Compiler: ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION}"
    COMMAND ${CMAKE_COMMAND} -E echo "Build type: ${CMAKE_BUILD_TYPE}"
)
add_dependencies(VisionDemo version_info)

# --- 测试 ---
option(BUILD_TESTS "Build tests" ON)
if(BUILD_TESTS)
    enable_testing()
    add_subdirectory(tests)
endif()

# --- 安装配置 ---
include(GNUInstallDirs)

install(TARGETS VisionDemo VisionDemoLib
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

install(DIRECTORY include/VisionDemo
    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
    FILES_MATCHING PATTERN "*.h"
)

# --- 包配置 ---
include(CMakePackageConfigHelpers)
write_basic_package_version_file(
    "${CMAKE_CURRENT_BINARY_DIR}/VisionDemoConfigVersion.cmake"
    VERSION ${PROJECT_VERSION}
    COMPATIBILITY SameMajorVersion
)

install(FILES 
    "${CMAKE_CURRENT_BINARY_DIR}/VisionDemoConfigVersion.cmake"
    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/VisionDemo
)

cmake/Dependencies.cmake

include(FetchContent)

# fmt 库
FetchContent_Declare(
    fmt
    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
    GIT_TAG 9.1.0
)

# spdlog 库
FetchContent_Declare(
    spdlog
    GIT_REPOSITORY https://github.com/gabime/spdlog.git
    GIT_TAG v1.11.0
)

# 如果构建测试，添加 Google Test
option(BUILD_TESTS "Build tests" ON)
if(BUILD_TESTS)
    FetchContent_Declare(
        googletest
        GIT_REPOSITORY https://github.com/google/googletest.git
        GIT_TAG release-1.12.1
    )
    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
endif()

# 使所有依赖可用
FetchContent_MakeAvailable(fmt spdlog)
if(BUILD_TESTS)
    FetchContent_MakeAvailable(googletest)
endif()

cmake/CompilerOptions.cmake

function(setup_compiler_options target)
    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
        target_compile_options(${target} PRIVATE
            -Wall
            -Wextra
            -Wpedantic
            -Wno-unused-parameter
            -Wno-unused-variable
            $<$<CONFIG:Debug>:-g3 -O0>
            $<$<CONFIG:Release>:-O3 -DNDEBUG>
        )
    elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
        target_compile_options(${target} PRIVATE
            /W4
            /utf-8
            $<$<CONFIG:Debug>:/Od /RTC1>
            $<$<CONFIG:Release>:/O2 /DNDEBUG>
        )
    endif()
endfunction()

构建和使用

# 克隆项目
git clone <repository_url>
cd VisionDemo

# 配置构建
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

# 构建
cmake --build build --parallel

# 运行测试
cd build && ctest --verbose

# 安装
cmake --install build --prefix install

# 查看版本信息
cd build && make version_info

最佳实践总结

✅ 推荐做法

使用现代CMake语法 (3.14+)
明确指定目标属性 而非全局变量
使用 target_* 系列命令 而非废弃的全局命令
合理使用链接可见性 (PRIVATE/PUBLIC/INTERFACE)
组织化管理配置文件 (cmake/目录)
提供完整的安装配置
支持多平台编译器

❌ 避免的做法

不要使用过时的CMake语法
避免硬编码路径
不要忽略编译器差异
避免在 add_executable 前使用 target_* 命令
不要混用全局和目标特定的设置

🔧 调试技巧

# 打印变量值
message(STATUS "CMAKE_CXX_COMPILER_ID: ${CMAKE_CXX_COMPILER_ID}")
message(STATUS "PROJECT_VERSION: ${PROJECT_VERSION}")

# 打印所有变量
get_cmake_property(_variableNames VARIABLES)
foreach(_variableName ${_variableNames})
    message(STATUS "${_variableName}=${${_variableName}}")
endforeach()

# 详细构建输出
set(CMAKE_VERBOSE_MAKEFILE ON)

这份指南涵盖了现代CMake项目配置的所有重要方面，从基础设置到高级功能，可以作为实际项目开发的参考模板。