📚 课程目录第3章 CMake核心语法与变量

3、CMake核心语法与变量：注释、命令调用、变量定义与引用、列表、字符串操作、数学表达式、条件判断（if/elseif/else）、循环（foreach/while）

CMake 的构建系统描述能力，本质上建立在一套简洁但完整的脚本语言之上。这套语言既不像 C/C++ 那样需要编译，也不像 Python 那样强调动态类型，而是以“命令调用 + 参数解析”为核心，以“变量缓存”为状态存储，以“生成器表达式”为延迟求值手段。理解这一章的内容，是后续掌握目标构建、依赖管理、打包配置的基石。本章将系统拆解 CMake 的语法骨架，从最基础的注释与命令调用，到变量与列表的存储模型，再到字符串与数学运算，最后深入条件判断与循环控制，帮助你建立对 CMake 语言层的完整认知。

上图展示了 CMake 语法体系的整体架构。从最底层的基础语法（注释、命令调用）出发，向上构建变量与列表的存储模型，再叠加字符串与数学运算能力，最终由条件判断和循环构成完整的控制流。右侧的作用域与缓存机制则决定了变量在不同层级之间的可见性和生命周期。下面我们将逐层深入，通过具体代码示例和实战场景，掌握每一个语法要素的精确用法。

3.1 注释与命令调用：构建脚本的“标点符号”

任何一门脚本语言，注释都是代码可读性的生命线。CMake 提供两种注释方式：行注释使用 #，块注释使用 #[[ ]]。块注释在 CMake 3.0 之后引入，特别适合临时屏蔽大段调试代码或书写多行说明。命令调用是 CMake 的基本执行单元，其格式为 command(arg1 arg2 ...)，参数之间用空格分隔，参数本身可以是不带引号的裸字符串，也可以是带引号的字符串或变量引用。

# 这是行注释，说明下面命令的作用
set(MY_VAR "hello world")  # 行尾注释也可以

#[[ 这是一个块注释
可以跨越多行，
常用于临时禁用一段逻辑
set(TEMP_VAR 42)
]]

# 命令调用示例：参数可以是裸字符串、引号字符串、变量引用
message(STATUS "当前变量值为: ${MY_VAR}")
add_executable(myapp main.cpp utils.cpp)  # 裸字符串参数

命令调用的参数解析遵循“先展开变量，再分割参数”的规则。这意味着如果变量值包含空格，必须用引号包裹才能作为一个整体参数传递。例如 set(NAME "John Doe") 后，message(${NAME}) 会输出 John 和 Doe 两个参数，而 message("${NAME}") 才会输出完整的 John Doe。这是初学者最容易踩的坑之一。

参数类型	示例	解析结果	适用场景
裸字符串	`add_executable(app main.cpp)`	按空格分割为多个参数	文件列表、目标名称
引号字符串	`message("hello world")`	作为一个整体参数	包含空格的路径、描述信息
变量引用	`${VAR}`	先展开变量值再参与分割	动态参数传递
转义序列	`"line1\nline2"`	解析为换行符	生成文件内容、格式化输出

3.2 变量定义与引用：存储与取用的核心机制

CMake 中的变量本质上是“字符串到字符串”的映射。使用 set() 命令定义变量，使用 ${VAR} 语法引用变量。变量名区分大小写，且不能包含空格和特殊字符。除了普通变量，还有环境变量（通过 $ENV{NAME} 访问）和缓存变量（通过 CACHE 关键字定义）。缓存变量存储在 CMakeCache.txt 中，可以在多次配置之间保持值，也可以通过命令行 -D 参数覆盖。

# 普通变量定义
set(PROJECT_VERSION_MAJOR 2)
set(PROJECT_VERSION_MINOR 1)
set(PROJECT_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}")

# 缓存变量定义（带类型和描述）
set(USE_OPENMP ON CACHE BOOL "是否启用OpenMP并行支持")
set(INSTALL_PREFIX "/usr/local" CACHE PATH "安装路径前缀")

# 环境变量访问
message(STATUS "当前用户: $ENV{USER}")
message(STATUS "系统路径: $ENV{PATH}")

# 变量引用的嵌套
set(BASE_DIR "/opt/myproject")
set(INCLUDE_DIR "${BASE_DIR}/include")
message(STATUS "头文件目录: ${INCLUDE_DIR}")

变量引用的一个重要特性是“嵌套展开”。CMake 会从左到右、从内到外依次展开 ${}。例如 ${OUTER_${INNER}} 会先展开 ${INNER} 得到变量名，再展开外层变量。这种机制在动态构造变量名时非常有用，但也容易造成混淆，建议仅在必要时使用。

经验提醒：在 if 语句中判断变量时，推荐使用 if(DEFINED VAR) 而不是 if(${VAR})。前者检查变量是否被定义，后者会先展开变量值再判断真假，如果变量未定义会展开为空字符串，导致判断结果不准确。

3.3 列表操作：分号分隔的字符串数组

CMake 中的列表（List）并不是独立的数据类型，而是以分号（;）作为分隔符的字符串。例如 set(MY_LIST "a;b;c") 定义了一个包含三个元素的列表。列表操作主要通过 list() 命令完成，支持追加、删除、查找、排序、反转等操作。理解列表的字符串本质，有助于避免许多隐蔽的错误。

# 定义列表
set(SOURCES src/main.cpp src/utils.cpp src/network.cpp)

# 追加元素
list(APPEND SOURCES src/logger.cpp)

# 在开头插入
list(INSERT SOURCES 0 src/init.cpp)

# 获取列表长度
list(LENGTH SOURCES src_count)
message(STATUS "源文件数量: ${src_count}")

# 获取指定索引元素（索引从0开始）
list(GET SOURCES 1 first_source)
message(STATUS "第二个源文件: ${first_source}")

# 查找元素索引
list(FIND SOURCES "src/network.cpp" net_index)
message(STATUS "network.cpp 的索引: ${net_index}")

# 删除元素
list(REMOVE_ITEM SOURCES "src/logger.cpp")

# 排序（按字典序）
list(SORT SOURCES)

# 列表转字符串（用空格连接）
list(JOIN SOURCES " " sources_string)
message(STATUS "所有源文件: ${sources_string}")

列表操作中一个常见的误区是混淆“空列表”和“未定义变量”。set(EMPTY_LIST "") 定义了一个空字符串，此时 list(LENGTH EMPTY_LIST len) 会得到 0。但如果直接使用未定义的变量，list(LENGTH UNDEFINED len) 会报错。因此，在操作列表前，建议先用 if(DEFINED VAR) 检查变量是否存在。

3.4 字符串操作与数学表达式：数据处理工具箱

字符串操作是 CMake 脚本中最常用的功能之一。string() 命令提供了丰富的子命令，包括大小写转换、查找替换、正则匹配、子串提取、长度计算等。数学运算则通过 math() 命令实现，支持基本的算术运算和位运算。这些功能在版本号处理、路径拼接、编译选项生成等场景中发挥着重要作用。

# 字符串操作示例
set(FILENAME "MyProject-2.1.0.tar.gz")

# 大小写转换
string(TOLOWER "${FILENAME}" lower_name)
string(TOUPPER "${FILENAME}" upper_name)

# 查找子串
string(FIND "${FILENAME}" "tar" tar_pos)
message(STATUS "tar 的位置: ${tar_pos}")

# 替换
string(REPLACE ".tar.gz" ".zip" new_name "${FILENAME}")

# 正则匹配
if(FILENAME MATCHES "([0-9]+)\\.([0-9]+)\\.([0-9]+)")
  set(MAJOR "${CMAKE_MATCH_1}")
  set(MINOR "${CMAKE_MATCH_2}")
  set(PATCH "${CMAKE_MATCH_3}")
  message(STATUS "版本号: ${MAJOR}.${MINOR}.${PATCH}")
endif()

# 子串提取（从位置0开始，长度5）
string(SUBSTRING "${FILENAME}" 0 5 prefix)

# 数学运算
math(EXPR NEXT_VERSION "${MAJOR} + 1")
math(EXPR FLAGS "(${MAJOR} << 16) | (${MINOR} << 8) | ${PATCH}")

# 字符串比较
if("${MAJOR}" VERSION_GREATER_EQUAL "3")
  message(STATUS "主版本号大于等于3")
endif()

字符串操作中，正则表达式是最强大但也最容易出错的部分。CMake 使用 POSIX 扩展正则表达式，CMAKE_MATCH_<n> 变量保存匹配结果。需要注意的是，正则表达式中的反斜杠需要转义，例如匹配点号要写成 \\.。在复杂的正则场景下，建议先在独立的小脚本中测试验证。

3.5 条件判断：if/elseif/else 的分支逻辑

条件判断是 CMake 配置逻辑的核心。if 语句支持多种条件表达式：常量真值（ON/OFF/TRUE/FALSE）、变量判断、字符串比较、版本比较、文件系统判断、存在性检查等。CMake 的真假判断规则与 C/C++ 不同，空字符串、0、OFF、NO、FALSE、NOTFOUND 等都被视为假，其他值视为真。

# 基本条件判断
if(USE_OPENMP)
  message(STATUS "启用OpenMP支持")
  find_package(OpenMP REQUIRED)
elseif(USE_TBB)
  message(STATUS "启用TBB支持")
  find_package(TBB REQUIRED)
else()
  message(STATUS "使用默认线程库")
endif()

# 变量定义检查
if(DEFINED CMAKE_BUILD_TYPE)
  message(STATUS "构建类型: ${CMAKE_BUILD_TYPE}")
else()
  set(CMAKE_BUILD_TYPE "Release" CACHE STRING "构建类型" FORCE)
endif()

# 字符串比较
if("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux")
  message(STATUS "检测到Linux系统")
elseif("${CMAKE_SYSTEM_NAME}" STREQUAL "Windows")
  message(STATUS "检测到Windows系统")
endif()

# 版本比较
if(CMAKE_VERSION VERSION_LESS "3.16")
  message(WARNING "CMake版本过低，建议升级到3.16以上")
endif()

# 文件系统判断
if(EXISTS "${PROJECT_SOURCE_DIR}/config.h.in")
  configure_file(config.h.in config.h)
endif()

# 逻辑组合
if((USE_OPENMP AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR USE_CLANG)
  message(STATUS "使用GCC或Clang编译器")
endif()

条件判断中一个常见的陷阱是变量展开后的真假判断。例如 if(${VAR}) 如果 VAR 的值是 ON，展开后变成 if(ON)，这是正确的。但如果 VAR 的值是 ON;OFF（列表），展开后变成 if(ON;OFF)，CMake 会将其视为一个包含分号的字符串，判断结果可能不符合预期。因此，对于列表变量，应使用 if(VAR) 而不是 if(${VAR})。

风险提示：在 if 条件中直接使用 ${VAR} 展开，如果变量值包含特殊字符（如分号、引号），可能导致语法错误或逻辑错误。推荐使用 if(VAR) 形式，CMake 会自动处理变量展开。只有在需要比较变量值与字符串时，才使用 if("${VAR}" STREQUAL "expected") 的引号包裹形式。

3.6 循环控制：foreach 与 while 的迭代逻辑

循环是处理列表和重复任务的利器。foreach 支持多种迭代方式：遍历列表、遍历范围、同时遍历多个列表、遍历字典等。while 循环则适用于需要条件控制的场景。循环中可以使用 break() 提前退出，使用 continue() 跳过当前迭代。

# foreach 遍历列表
set(LANGUAGES C CXX Python)
foreach(lang IN LISTS LANGUAGES)
  message(STATUS "支持语言: ${lang}")
endforeach()

# foreach 遍历范围（从1到10，步长2）
foreach(i RANGE 1 10 2)
  message(STATUS "奇数: ${i}")
endforeach()

# foreach 同时遍历多个列表
set(NAMES Alice Bob Charlie)
set(AGES 25 30 35)
foreach(name age IN ZIP_LISTS NAMES AGES)
  message(STATUS "${name} 年龄: ${age}")
endforeach()

# foreach 遍历字典（CMake 3.17+）
set(OPTIONS "debug" "release" "relwithdebinfo")
foreach(opt IN LISTS OPTIONS)
  string(TOUPPER "${opt}" opt_upper)
  message(STATUS "构建选项: ${opt_upper}")
endforeach()

# while 循环：计数器控制
set(counter 0)
while(counter LESS 5)
  message(STATUS "计数器: ${counter}")
  math(EXPR counter "${counter} + 1")
  if(counter EQUAL 3)
    message(STATUS "跳过第3次迭代")
    continue()
  endif()
  if(counter GREATER 4)
    break()
  endif()
endforeach()

# 循环中处理文件列表
file(GLOB SOURCE_FILES "src/*.cpp")
foreach(src IN LISTS SOURCE_FILES)
  get_filename_component(name "${src}" NAME_WE)
  message(STATUS "处理源文件: ${name}")
endforeach()

循环中一个值得注意的性能问题是 file(GLOB) 的使用。虽然它很方便，但 CMake 官方并不推荐在构建配置中使用 GLOB 收集源文件，因为新增文件不会自动触发重新配置。更推荐的做法是显式列出所有源文件，或者使用 CONFIGURE_DEPENDS 选项让 CMake 自动检测文件变化。

3.7 实战案例：构建一个多模块项目的配置脚本

下面我们通过一个完整的案例，将本章所有语法要素串联起来。假设我们要构建一个包含核心库、工具程序和测试模块的项目，需要根据平台和编译选项动态调整配置。

# CMakeLists.txt - 综合案例
cmake_minimum_required(VERSION 3.16)
project(ComplexProject VERSION 2.1.0 LANGUAGES C CXX)

# 定义项目元数据
set(PROJECT_DESCRIPTION "一个综合性的CMake示例项目")
set(PROJECT_ORGANIZATION "Example Corp")

# 构建类型配置（带缓存变量）
if(NOT CMAKE_BUILD_TYPE)
  set(CMAKE_BUILD_TYPE "Release" CACHE STRING "构建类型" FORCE)
endif()

# 平台检测与配置
if(WIN32)
  set(PLATFORM_LIBS ws2_32 winmm)
  add_compile_definitions(_WIN32_WINNT=0x0601)
elseif(UNIX AND NOT APPLE)
  set(PLATFORM_LIBS pthread dl)
  find_package(Threads REQUIRED)
elseif(APPLE)
  set(PLATFORM_LIBS pthread)
endif()

# 可选功能开关
option(ENABLE_TESTS "构建测试模块" ON)
option(ENABLE_LOGGING "启用日志功能" ON)

# 收集源文件（使用显式列表而非GLOB）
set(CORE_SOURCES
  src/core/engine.cpp
  src/core/parser.cpp
  src/core/registry.cpp
)

# 根据选项添加额外源文件
if(ENABLE_LOGGING)
  list(APPEND CORE_SOURCES src/core/logger.cpp)
  add_compile_definitions(ENABLE_LOGGING=1)
endif()

# 版本号处理
string(REPLACE "." ";" VERSION_PARTS "${PROJECT_VERSION}")
list(GET VERSION_PARTS 0 VERSION_MAJOR)
list(GET VERSION_PARTS 1 VERSION_MINOR)
list(GET VERSION_PARTS 2 VERSION_PATCH)
math(EXPR VERSION_BUILD "${VERSION_PATCH} + 100")

# 生成配置文件
configure_file(config.h.in config.h @ONLY)

# 构建核心库
add_library(core STATIC ${CORE_SOURCES})
target_include_directories(core PUBLIC
  ${PROJECT_BINARY_DIR}
  ${PROJECT_SOURCE_DIR}/include
)
target_link_libraries(core PUBLIC ${PLATFORM_LIBS})

# 构建工具程序
add_executable(tool src/tool/main.cpp)
target_link_libraries(tool PRIVATE core)

# 测试模块
if(ENABLE_TESTS)
  enable_testing()
  add_executable(test_runner tests/test_main.cpp tests/test_engine.cpp)
  target_link_libraries(test_runner PRIVATE core)
  add_test(NAME unit_tests COMMAND test_runner)
  
  # 遍历测试文件
  file(GLOB TEST_SOURCES CONFIGURE_DEPENDS "tests/test_*.cpp")
  foreach(test_src IN LISTS TEST_SOURCES)
    get_filename_component(test_name "${test_src}" NAME_WE)
    message(STATUS "发现测试: ${test_name}")
  endforeach()
endif()

# 安装规则
install(TARGETS core tool
  RUNTIME DESTINATION bin
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib
)
install(FILES include/core/engine.h include/core/parser.h
  DESTINATION include/core
)

这个案例展示了如何综合运用变量定义、列表操作、字符串处理、条件判断和循环控制。通过 option() 定义可配置开关，通过 list(APPEND) 动态调整源文件列表，通过 string(REPLACE) 解析版本号，通过 if/elseif 处理平台差异，通过 foreach 遍历测试文件。整个配置脚本结构清晰，易于维护和扩展。

3.8 常见误区与总结复盘

在学习 CMake 语法的过程中，有几个高频误区需要特别警惕。第一个误区是混淆变量展开时机。普通变量 ${VAR} 在配置阶段立即展开，而生成器表达式 $<...> 在生成阶段才求值。例如 target_compile_definitions(app PRIVATE VERSION=$<TARGET_PROPERTY:core,VERSION>) 中的生成器表达式不能与普通变量混用。第二个误区是忽略引号的作用。在传递包含空格的路径或字符串时，必须使用引号包裹，否则会被分割成多个参数。第三个误区是过度使用 file(GLOB)，这会导致新增文件不触发重新配置。

误区	错误示例	正确做法	原因分析
变量展开时机	`if(${VAR} STREQUAL "ON")`	`if(VAR STREQUAL "ON")`	前者先展开变量，若VAR未定义会变成空字符串比较
引号使用	`message(${MY_PATH})`	`message("${MY_PATH}")`	路径含空格时，无引号会被拆分为多个参数
列表操作	`set(LIST "a b c")`	`set(LIST "a;b;c")`	空格不构成列表分隔符，分号才是
缓存变量	`set(VAR value)`	`set(VAR value CACHE STRING "" FORCE)`	普通变量每次配置都会重置，缓存变量持久化
循环修改列表	foreach中直接修改列表	先复制列表再遍历	foreach遍历的是列表的快照，修改不影响迭代

总结本章的核心要点：CMake 的语法体系以命令调用为基础，变量是字符串映射，列表是分号分隔的字符串，字符串和数学运算提供了数据处理能力，条件判断和循环构成了控制流。掌握这些基础语法后，你就能读懂绝大多数 CMakeLists.txt 文件，并能够编写出结构清晰、可维护性强的构建脚本。在实际项目中，建议遵循“显式优于隐式”的原则，避免过度依赖 GLOB 和隐式变量，让构建配置更加透明和可控。