49. 附录A：CMake常用变量速查表

2天前发布

引言：施工队长的“仪表盘”与“工地导航牌”

走到附录这一章，我们的CMake“施工队长”已经完成了从新手到专家的历练。在漫长的施工过程中，队长手里始终握着几张关键的“图纸”和“导航牌”——它们就是CMake的内置变量。这些变量就像是工地的仪表盘，时刻告诉队长：我们现在在哪（路径）、面对的是什么样的地形（平台）、手里有什么样的机械（编译器）、以及今天的施工模式是什么（构建配置）。

本附录不是枯燥的词典，而是一份带场景说明的速查手册。当你在实际项目中需要判断路径、区分平台或调试编译器问题时，翻开这一页，就能快速找到答案。

一、目录与路径变量：工地的“坐标系统”

在一个多目录、多子模块的CMake项目中，搞清楚“我当前在哪”是最基本也最容易混淆的问题。CMake提供了一套清晰的“坐标系统”。

CMAKE_SOURCE_DIR：指向最顶层的CMakeLists.txt所在的目录。无论CMake当前正在处理哪个子目录，这个变量永远指向项目“大本营”。
CMAKE_BINARY_DIR：指向最顶层的构建目录（即你运行cmake -B build时的那个build目录）。

类比：无论你是在大楼的地下车库还是天台施工，CMAKE_SOURCE_DIR永远是大楼的设计院地址，CMAKE_BINARY_DIR永远是大楼的施工总指挥部地址。

message(STATUS "项目源码根目录: ${CMAKE_SOURCE_DIR}")
message(STATUS "构建输出根目录: ${CMAKE_BINARY_DIR}")

1.2 当前处理目录

CMAKE_CURRENT_SOURCE_DIR：CMake当前正在处理的CMakeLists.txt所在的目录。当通过add_subdirectory进入子目录时，这个变量会随之改变。
CMAKE_CURRENT_BINARY_DIR：与当前源码目录对应的构建输出目录。

# 假设我们在 src/core/CMakeLists.txt 中
message(STATUS "当前源码目录: ${CMAKE_CURRENT_SOURCE_DIR}")
message(STATUS "当前构建目录: ${CMAKE_CURRENT_BINARY_DIR}")
# 输出示例：
# /home/project/src/core
# /home/project/build/src/core

1.3 模块与脚本定位

CMAKE_CURRENT_LIST_DIR：当前正在处理的脚本文件（.cmake模块或CMakeLists.txt）所在的目录。这个变量在include()一个模块文件时特别有用，因为它永远指向被包含文件的位置，而不是调用者。

场景：你写了一个自定义模块cmake/modules/MyHelpers.cmake，模块内部需要引用同目录下的另一个文件，就应该用${CMAKE_CURRENT_LIST_DIR}/another.cmake，而不是${CMAKE_SOURCE_DIR}。

# 在 cmake/modules/MyHelpers.cmake 中
include(${CMAKE_CURRENT_LIST_DIR}/CommonUtils.cmake)

1.4 模块搜索路径

CMAKE_MODULE_PATH：一个列表（List），包含CMake查找FindXXX.cmake模块时的额外搜索路径。默认只搜索CMake安装目录下的Modules文件夹。

使用时机：当你把自定义的FindMyLib.cmake放在项目下的cmake/modules目录时，必须在顶层CMakeLists.txt中把这个路径加进去：

list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/modules")

二、系统与平台变量：识别“施工地形”

跨平台开发就像在不同地质条件的地区施工——在沙地上打桩和在岩石上打桩，方法完全不同。CMake提供了一组变量，让你在配置阶段就能“勘察地形”。

2.1 目标系统与主机系统

CMAKE_SYSTEM_NAME：目标系统的名称。在本地编译时，它通常等于主机系统名（如Linux、Windows、Darwin）；在交叉编译时，它由工具链文件设定，代表你要编译出的程序将运行在哪个系统上。
CMAKE_HOST_SYSTEM_NAME：运行CMake的主机系统名称。
CMAKE_SYSTEM_PROCESSOR：目标处理器架构（如x86_64、arm64、riscv64）。
CMAKE_HOST_SYSTEM_PROCESSOR：主机处理器架构。

message(STATUS "目标系统: ${CMAKE_SYSTEM_NAME}")
message(STATUS "目标架构: ${CMAKE_SYSTEM_PROCESSOR}")
message(STATUS "主机系统: ${CMAKE_HOST_SYSTEM_NAME}")

2.2 便捷的平台判断变量

CMake为最常见的平台判断提供了“快捷开关”，在if()语句中直接使用即可：

WIN32：在所有Windows平台上（包括64位）为TRUE。
UNIX：在所有类Unix系统（Linux、macOS、*BSD）上为TRUE。
APPLE：在所有Apple系统（macOS、iOS、watchOS等）上为TRUE。
MSVC：当使用Microsoft Visual C++编译器时为TRUE。
MINGW：当使用MinGW工具链时为TRUE。
CYGWIN：当使用Cygwin时为TRUE。

if(WIN32)
    target_compile_definitions(myapp PRIVATE PLATFORM_WINDOWS=1)
elseif(APPLE)
    target_compile_definitions(myapp PRIVATE PLATFORM_APPLE=1)
elseif(UNIX)
    target_compile_definitions(myapp PRIVATE PLATFORM_UNIX=1)
endif()

现代CMake建议：对于编译器判断，更推荐用CMAKE_CXX_COMPILER_ID（见下一节），而不是依赖CMAKE_COMPILER_IS_GNUCXX这类旧变量。

三、编译器变量：识别“施工机械”

不同的编译器就像不同品牌的工程机械——它们的基本功能类似，但操作面板、马力参数和独门绝技各不相同。CMake会在第一次配置时自动检测编译器，并把结果存入这些变量。

3.1 编译器路径与标识

CMAKE_C_COMPILER：C编译器的完整路径（如/usr/bin/gcc）。
CMAKE_CXX_COMPILER：C++编译器的完整路径（如/usr/bin/g++）。
CMAKE_CXX_COMPILER_ID：编译器的“身份证”字符串。常见取值：
- GNU（GCC）
- Clang（Clang/LLVM）
- AppleClang（Apple定制的Clang）
- MSVC（Microsoft Visual C++）
- Intel（Intel C++ Compiler）
CMAKE_CXX_COMPILER_VERSION：编译器的版本号（如11.4.0、19.36）。

message(STATUS "C++编译器: ${CMAKE_CXX_COMPILER}")
message(STATUS "编译器ID: ${CMAKE_CXX_COMPILER_ID}")
message(STATUS "编译器版本: ${CMAKE_CXX_COMPILER_VERSION}")

# 根据编译器做特殊处理
if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
    if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "9.0")
        message(FATAL_ERROR "需要GCC 9.0或更高版本")
    endif()
endif()

3.2 语言标准变量

虽然现代CMake推荐用target_compile_features或cxx_std_17这类目标属性来设置标准，但以下全局变量在快速原型或遗留项目中依然常见：

CMAKE_C_STANDARD / CMAKE_CXX_STANDARD：指定C/C++语言标准版本（如11、17、20、23）。
CMAKE_C_STANDARD_REQUIRED / CMAKE_CXX_STANDARD_REQUIRED：设为ON时，如果编译器不支持指定标准，CMake将报错而不是回退。
CMAKE_CXX_EXTENSIONS：设为ON（默认）允许使用编译器扩展（如GNU++17）；设为OFF强制使用严格标准（如-std=c++17而不是-std=gnu++17）。

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

注意：这些变量会影响之后创建的所有目标。在Modern CMake中，更推荐为每个目标单独设置属性，保持最小作用域原则：

set_target_properties(mytarget PROPERTIES
    CXX_STANDARD 17
    CXX_STANDARD_REQUIRED ON
    CXX_EXTENSIONS OFF
)

四、构建配置变量：切换“施工模式”

同一套图纸，白天施工和夜间施工的安全规范不同；同一套代码，调试版和发布版的编译选项也不同。CMake通过构建配置来管理这些差异。

4.1 单配置与多配置生成器

这是CMake中一个容易混淆的概念，必须先理清：

单配置生成器（如Unix Makefiles、Ninja）：一次配置只生成一种构建类型。你用CMAKE_BUILD_TYPE指定它是Debug还是Release。
多配置生成器（如Visual Studio、Xcode）：一次配置可以同时生成多种构建类型。你用CMAKE_CONFIGURATION_TYPES指定支持哪些配置，之后在IDE里选择当前要编译哪一种。

4.2 CMAKE_BUILD_TYPE

用于单配置生成器。常见取值：

Debug：关闭优化，包含完整调试信息。
Release：开启高级优化，去除调试信息。
RelWithDebInfo：开启优化，但保留调试信息（适合性能分析）。
MinSizeRel：针对代码体积进行优化。

# 命令行配置时指定
cmake -B build -DCMAKE_BUILD_TYPE=Release

在CMakeLists.txt中读取它：

if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    message(STATUS "默认设置为Debug模式")
    set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "构建类型" FORCE)
endif()

4.3 CMAKE_CONFIGURATION_TYPES

用于多配置生成器。默认通常是Debug;Release;MinSizeRel;RelWithDebInfo。你可以自定义这个列表，限制IDE中可见的配置：

set(CMAKE_CONFIGURATION_TYPES "Debug;Release" CACHE STRING "" FORCE)

4.4 配置相关的编译/链接标志

CMake为每种配置预设了一组标志变量。虽然Modern CMake更推荐用target_compile_options配合生成器表达式（见3.3节），但在快速调试或遗留项目中，这些变量依然很有用：

CMAKE_C_FLAGS / CMAKE_CXX_FLAGS：所有配置通用的基础编译标志。
CMAKE_C_FLAGS_DEBUG / CMAKE_CXX_FLAGS_DEBUG：Debug配置下追加的标志（默认通常包含-g）。
CMAKE_C_FLAGS_RELEASE / CMAKE_CXX_FLAGS_RELEASE：Release配置下追加的标志（默认通常包含-O3 -DNDEBUG）。
CMAKE_EXE_LINKER_FLAGS / CMAKE_SHARED_LINKER_FLAGS：链接器标志。

# 为Debug模式追加一个宏定义
set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -DMY_DEBUG_MACRO=1")

# 查看当前所有标志（调试用）
message(STATUS "CXX_FLAGS: ${CMAKE_CXX_FLAGS}")
message(STATUS "CXX_FLAGS_DEBUG: ${CMAKE_CXX_FLAGS_DEBUG}")

温馨提示：直接修改这些全局标志变量是“老派CMake”的做法。在Modern CMake中，应尽量使用target_compile_options配合$<CONFIG:Debug>等生成器表达式，让设置绑定到具体目标上，避免污染全局环境。

五、如何组合使用：一份实用查询模板

变量单独看很简单，但在实际工程中，往往需要组合使用。下面给出一份CMake项目中最常见的“信息诊断”代码片段，建议保存到你的项目模板中：

# 在顶层 CMakeLists.txt 中，配置阶段打印关键信息
message(STATUS "==========  CMake 项目诊断信息  ==========")
message(STATUS "CMake版本: ${CMAKE_VERSION}")
message(STATUS "源码根目录: ${CMAKE_SOURCE_DIR}")
message(STATUS "构建根目录: ${CMAKE_BINARY_DIR}")
message(STATUS "主机系统: ${CMAKE_HOST_SYSTEM_NAME} ${CMAKE_HOST_SYSTEM_PROCESSOR}")
message(STATUS "目标系统: ${CMAKE_SYSTEM_NAME} ${CMAKE_SYSTEM_PROCESSOR}")
message(STATUS "C编译器: ${CMAKE_C_COMPILER_ID} ${CMAKE_C_COMPILER_VERSION}")
message(STATUS "C++编译器: ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION}")
if(CMAKE_BUILD_TYPE)
    message(STATUS "构建类型: ${CMAKE_BUILD_TYPE}")
else()
    message(STATUS "多配置生成器，可用配置: ${CMAKE_CONFIGURATION_TYPES}")
endif()
message(STATUS "========================================")

这段代码就像施工队长的每日晨会简报——在项目配置时一目了然地展示所有关键环境信息，能帮你快速定位“为什么我的编译器没被识别”“为什么交叉编译时系统名不对”这类问题。

结语：从速查到精通

本附录列出的只是CMake庞大变量体系中最常用、最核心的一部分。它们就像是施工队长口袋里那张磨旧的速查卡——不需要背诵每一个字母，但需要知道在什么时候该查哪一行。

随着你项目经验的积累，你会逐渐发现：Modern CMake的哲学是“能不用全局变量就不用全局变量”。这些变量在诊断环境、编写工具链文件或处理遗留代码时是不可或缺的利器；但在日常定义构建规则时，还是要回归到target_***命令和目标属性的思路上来。两手准备，方能游刃有余。

测试标签

评分

欢迎为Ta评分