4、CMake语法基础：注释、命令、变量、字符串、列表、条件与循环控制结构

CMake 虽然被许多人视为“构建脚本语言”，但其本质是一门完整的、图灵完备的脚本语言。无论是构建可执行文件、配置编译选项，还是实现复杂的跨平台逻辑，都离不开对语法元素的精确掌控。本章将系统拆解 CMake 的六大核心语法单元：注释、命令、变量、字符串、列表以及条件与循环控制结构。理解这些基础语法，是编写可维护、可扩展的 CMakeLists.txt 的基石，也是从“能跑”迈向“精通”的第一步。

上图展示了 CMake 语法体系中各要素的协作关系：变量是数据存储的核心，字符串与列表是变量的两种主要形态，命令是操作这些数据的函数，而条件与循环控制结构则决定了脚本的执行路径。下面我们将逐一深入剖析每个语法要素的底层机制与实战用法。

4.1 注释：代码的“隐形护栏”

核心原理

CMake 支持两种注释形式：行注释与括号注释。行注释以 # 开头，直到该行结束；括号注释以 #[[ 开始，以 ]] 结束，可以跨越多行。注释在预处理阶段被完全移除，不会对构建产生任何影响，但它们是团队协作和代码维护的“隐形护栏”。

# 这是行注释，常用于单行说明
set(CMAKE_CXX_STANDARD 17)  # 设置 C++ 标准为 C++17

#[[
  这是括号注释，
  可以跨越多行，
  适合大段说明或临时屏蔽代码块。
]]
add_executable(app main.cpp)

常见误区

• 误区一：在注释中使用中文括号或全角符号，导致某些编辑器或旧版本 CMake 解析异常。
• 误区二：将注释放在命令参数中间，例如 set(VAR # 注释\n "value")，这会导致语法错误。
• 误区三：过度注释“是什么”而忽略“为什么”，好的注释应解释设计意图和约束条件。

4.2 命令：CMake 的“动词”

核心原理

CMake 命令分为两类：脚本命令（如 set()、message()）和构建命令（如 add_executable()、target_link_libraries()）。命令的调用形式为 命令名(参数1 参数2 ...)，参数之间以空格分隔。命令名是大小写不敏感的，但强烈建议全部使用小写，以保持代码风格统一。

命令的参数可以是普通字符串、变量引用（${VAR}）或嵌套命令调用。CMake 在解析命令时，会先进行变量展开，再执行命令本身。这意味着参数中的 ${VAR} 会在命令执行前被替换为实际值。

set(PROJECT_NAME "MyApp")
message(STATUS "项目名称: ${PROJECT_NAME}")  # 输出: 项目名称: MyApp

操作流程：命令参数解析规则

4.3 变量：数据存储的核心

核心原理

CMake 变量本质上是字符串到字符串的映射。变量名区分大小写，且可以包含字母、数字、下划线和连字符。变量通过 set() 命令定义，通过 ${VAR} 引用。变量作用域分为目录作用域、函数作用域和缓存作用域，其中缓存变量（通过 set(VAR value CACHE BOOL "" FORCE) 定义）可以跨目录和跨构建共享。

set(CMAKE_BUILD_TYPE "Release")          # 普通变量
set(CMAKE_CXX_FLAGS "-Wall -O2")         # 缓存变量（CMake 内置）
set(MY_CUSTOM_VAR "hello" CACHE STRING "自定义缓存变量")  # 自定义缓存变量

判断方法：变量作用域优先级

当同名变量在不同作用域存在时，CMake 遵循“内层优先”的查找规则：函数作用域 > 目录作用域 > 缓存作用域。理解这一规则对排查“变量值不符合预期”的问题至关重要。

set(VAR "global")
function(test_scope)
    set(VAR "local")
    message("函数内: ${VAR}")  # 输出 local
endfunction()
test_scope()
message("函数外: ${VAR}")      # 输出 global

4.4 字符串与列表：变量的两种形态

核心原理

在 CMake 中，字符串是最基本的数据类型，而列表则是以分号（;）分隔的字符串序列。列表本质上仍是字符串，但 CMake 提供了 list() 命令来操作列表元素。理解字符串与列表的转换关系是避免许多隐蔽 Bug 的关键。

set(MY_LIST "a;b;c")          # 定义列表
list(APPEND MY_LIST "d")      # 追加元素，结果为 a;b;c;d
list(LENGTH MY_LIST len)      # len = 4
list(GET MY_LIST 1 item)      # item = b

# 字符串转列表
set(STR "x y z")
string(REPLACE " " ";" STR_LIST "${STR}")  # STR_LIST = x;y;z

案例拆解：源文件列表的构建

在实际项目中，我们经常需要收集多个目录下的源文件。以下是一个典型的场景：

# 收集 src 目录下所有 .cpp 文件
file(GLOB_RECURSE SOURCES "src/*.cpp")
# 此时 SOURCES 是一个列表，元素为 /path/to/src/a.cpp;/path/to/src/b.cpp;...

# 将列表转换为带引号的字符串（用于 message 输出）
string(JOIN ", " SOURCES_STR ${SOURCES})
message("源文件: ${SOURCES_STR}")

# 添加可执行文件
add_executable(app ${SOURCES})

4.5 条件与循环控制结构

核心原理

CMake 提供了 if()、elseif()、else()、endif() 条件判断，以及 foreach()、while() 循环结构。条件判断支持变量存在性检查、字符串比较、数值比较、逻辑运算等。循环结构支持遍历列表、范围迭代和嵌套循环。

# 条件判断
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    message("调试模式")
elseif(CMAKE_BUILD_TYPE STREQUAL "Release")
    message("发布模式")
else()
    message("未知模式")
endif()

# foreach 循环遍历列表
set(LANGUAGES "C" "C++" "Python")
foreach(lang ${LANGUAGES})
    message("支持语言: ${lang}")
endforeach()

# while 循环
set(counter 0)
while(counter LESS 3)
    message("计数: ${counter}")
    math(EXPR counter "${counter} + 1")
endwhile()

判断方法：条件表达式的真值规则

案例拆解：跨平台编译选项配置

以下是一个综合运用条件与循环的实战案例，展示了如何根据平台和编译器配置不同的编译选项：

# 目标：在 Windows 上使用 MSVC 时启用 /W4 警告级别，在 Linux 上使用 GCC/Clang 时启用 -Wall -Wextra
# 同时为 Debug 构建添加调试符号

if(MSVC)
    # MSVC 编译器
    add_compile_options(/W4)
    if(CMAKE_BUILD_TYPE STREQUAL "Debug")
        add_compile_options(/Zi /Od)
    endif()
elseif(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
    # GCC 或 Clang
    add_compile_options(-Wall -Wextra)
    if(CMAKE_BUILD_TYPE STREQUAL "Debug")
        add_compile_options(-g -O0)
    else()
        add_compile_options(-O2)
    endif()
endif()

# 遍历所有目标，为每个目标设置 C++ 标准
set(ALL_TARGETS app test_lib)
foreach(target ${ALL_TARGETS})
    target_compile_features(${target} PRIVATE cxx_std_17)
endforeach()

常见误区与最佳实践

• 误区一：在 if() 中直接使用 ${VAR} 而不是 VAR。例如 if(${CMAKE_BUILD_TYPE} STREQUAL "Debug") 在变量为空时会展开为 if( STREQUAL "Debug") 导致语法错误。正确写法是 if(CMAKE_BUILD_TYPE STREQUAL "Debug")。
• 误区二：混淆 set(VAR value) 与 set(VAR value CACHE BOOL "" FORCE)。前者是普通变量，后者是缓存变量，后者会覆盖前者的值。
• 误区三：在循环中修改列表时，应使用 list(REMOVE_ITEM) 或先收集再统一处理，避免在迭代过程中修改列表导致未定义行为。
• 最佳实践：所有变量引用尽量使用 ${VAR} 形式，但在 if() 条件中直接使用变量名；字符串比较使用 STREQUAL，数值比较使用 EQUAL、LESS 等；循环中优先使用 foreach(RANGE) 处理数值范围。