文章目录
- CMake 常用函数和命令清单
- 1 基本配置函数
- 2 路径/文件相关
- 3 编译相关（targets）
- 4 依赖管理
- 5 条件/循环控制
- 6 安装与导出
- 7 编译选项和工具链
- 8 包与模块集成（现代 CMake 推荐）
- 9 测试支持
- 10 宏/函数定义
-
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 无作用域）。
- 打印变量值的通用调试函数
function(print_var VAR)message(STATUS "${VAR} = [${${VAR}}]")
endfunction()
调用：
set(MY_PATH "/usr/local")
print_var(MY_PATH)
- 添加 include 目录（多模块项目常用）
function(add_my_include TARGET DIR)target_include_directories(${TARGET} PRIVATE ${DIR})
endfunction()
调用：
add_my_include(MyLib "${CMAKE_SOURCE_DIR}/include")
- 递归添加子目录（自动添加所有子模块）
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)
- 模拟返回值：通过
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}")
- 添加一组源文件到 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)
- 条件设置 C++ 标准（可重用模块）
function(set_cpp_standard TARGET VERSION)target_compile_features(${TARGET} PUBLIC cxx_std_${VERSION})
endfunction()
调用：
set_cpp_standard(MyApp 20)
- 设置编译选项（支持多个参数）
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)
| 特性 | function() | macro() |
|---|
| 变量作用域 | 局部作用域（可使用 PARENT_SCOPE） | 全局作用域（共享变量） |
| 调用开销 | 较小（推荐） | 更快但容易出错 |
| 推荐用途 | 所有模块化封装函数 | 极简快捷逻辑 |
构建 大型 C++ 项目、组件化中间件、跨平台库，建议把常用函数统一写入 cmake/functions.cmake 并 include() 引用。
