【构建】CMake 常用函数和命令清单

CMake 常用函数和命令清单

---

1 基本配置函数

命令	说明
cmake_minimum_required(VERSION 3.XX)	设置 CMake 最低版本要求
project(MyProject LANGUAGES C CXX)	设置工程名称和语言
set(VAR VALUE)	设置变量
message(STATUS "Text")	打印调试信息（也有 WARNING, FATAL_ERROR）

---

2 路径/文件相关

命令	说明
file(GLOB VAR "*.cpp")	匹配当前目录下所有 cpp 文件（不推荐用于源文件管理）
file(MAKE_DIRECTORY dir)	创建目录
file(READ path content)	读取文件内容到变量
file(WRITE path content)	写入文件内容
file(COPY src DESTINATION dst)	拷贝文件/目录
get_filename_component(var path NAME/EXT/DIRECTORY)	获取路径组件

---

3 编译相关（targets）

命令	说明
add_executable(target main.cpp)	添加可执行文件
add_library(libname STATIC src.cpp)	添加静态库
add_library(libname SHARED src.cpp)	添加动态库
target_sources(target PRIVATE src.cpp)	添加源文件到 target（推荐方式）
target_include_directories(target PUBLIC path)	添加头文件路径
target_compile_options(target PRIVATE -Wall)	添加编译器选项
target_compile_definitions(target PRIVATE MACRO)	添加宏定义
target_link_libraries(target PRIVATE lib)	链接依赖库
target_link_directories(target PRIVATE path)	链接库路径

---

4 依赖管理

命令	说明
find_package(Pkg REQUIRED)	查找系统/外部库
include(Foo.cmake)	引入其他 CMake 脚本
add_subdirectory(path)	添加子目录（可用于引入模块）
find_library(VAR name PATHS ...)	手动查找库文件

---

5 条件/循环控制

命令	说明
if(CONDITION) / elseif / else / endif()	条件判断
foreach(VAR list) / endforeach()	遍历循环
while(CONDITION) / endwhile()	循环

---

6 安装与导出

命令	说明
install(TARGETS ...)	安装目标（可执行文件/库）
install(FILES header DESTINATION include)	安装头文件等资源
export(TARGETS ... FILE cmakefile)	导出 CMake 配置用于其他项目
configure_file(in out @ONLY)	生成配置文件（自动替换变量）

---

7 编译选项和工具链

命令	说明
set(CMAKE_CXX_STANDARD 17)	设置 C++ 标准
set(CMAKE_BUILD_TYPE Debug)	设置构建类型
set(CMAKE_C_COMPILER gcc)	设置 C 编译器
set(CMAKE_CXX_FLAGS "-O2")	设置 C++ 编译选项（全局）

---

8 包与模块集成（现代 CMake 推荐）

命令	说明
FetchContent_Declare()	声明并拉取远程依赖库（CMake 3.11+）
FetchContent_MakeAvailable()	将 FetchContent 加入工程
include(FetchContent)	引入 FetchContent 模块
find_package(Pkg CONFIG REQUIRED)	优先使用包自带的 PkgConfig

---

9 测试支持

命令	说明
enable_testing()	启用测试功能
add_test(NAME test COMMAND ./bin)	添加测试
include(CTest)	集成 CTest 测试框架

---

10 宏/函数定义

命令	说明
function(NAME arg1 arg2)	定义函数（可作用域变量）
macro(NAME arg1 arg2)	定义宏（无作用域）
return()	从函数返回

function应用

主要涉及函数定义、参数传递、作用域、返回值模拟等，适合日常项目和中大型工程模块化构建。

• 基础语法

function(func_name [arg1 [arg2 [...]]])
    # 函数体
endfunction()

函数内部的变量默认是 局部作用域，与 macro() 不同（macro 无作用域）。

• 常用 CMake 函数示例清单

1. 打印变量值的通用调试函数

function(print_var VAR)
    message(STATUS "${VAR} = [${${VAR}}]")
endfunction()

调用：

set(MY_PATH "/usr/local")
print_var(MY_PATH)

---

2. 添加 include 目录（多模块项目常用）

function(add_my_include TARGET DIR)
    target_include_directories(${TARGET} PRIVATE ${DIR})
endfunction()

调用：

add_my_include(MyLib "${CMAKE_SOURCE_DIR}/include")

---

3. 递归添加子目录（自动添加所有子模块）

function(add_all_subdirs DIR)
    file(GLOB CHILDREN RELATIVE ${DIR} ${DIR}/*)
    foreach(child ${CHILDREN})
        if(IS_DIRECTORY ${DIR}/${child})
            add_subdirectory(${DIR}/${child})
        endif()
    endforeach()
endfunction()

调用：

add_all_subdirs(${CMAKE_SOURCE_DIR}/modules)

---

4. 模拟返回值：通过 PARENT_SCOPE

function(get_file_size FILE_PATH RETURN_VAR)
    file(SIZE ${FILE_PATH} SIZE_VAR)
    set(${RETURN_VAR} ${SIZE_VAR} PARENT_SCOPE)
endfunction()

调用：

get_file_size("main.cpp" FILE_SIZE)
message(STATUS "main.cpp size = ${FILE_SIZE}")

---

5. 添加一组源文件到 target（工程通用）

function(add_sources TARGET)
    foreach(src IN LISTS ARGN)
        target_sources(${TARGET} PRIVATE ${src})
    endforeach()
endfunction()

调用：

add_sources(MyApp main.cpp util.cpp net.cpp)

---

6. 条件设置 C++ 标准（可重用模块）

function(set_cpp_standard TARGET VERSION)
    target_compile_features(${TARGET} PUBLIC cxx_std_${VERSION})
endfunction()

调用：

set_cpp_standard(MyApp 20)

---

7. 设置编译选项（支持多个参数）

function(add_compile_flags TARGET)
    foreach(flag IN LISTS ARGN)
        target_compile_options(${TARGET} PRIVATE ${flag})
    endforeach()
endfunction()

调用：

add_compile_flags(MyApp -Wall -Wextra -Werror)

---

• 函数 vs 宏的区别

特性	function()	macro()
变量作用域	局部作用域（可使用 PARENT_SCOPE）	全局作用域（共享变量）
调用开销	较小（推荐）	更快但容易出错
推荐用途	所有模块化封装函数	极简快捷逻辑

---

构建 大型 C++ 项目、组件化中间件、跨平台库，建议把常用函数统一写入 cmake/functions.cmake 并 include() 引用。