CMake 015：日志级别全解析

在 CMake 工程化开发中，日志输出是调试、定位问题、感知构建状态的核心手段。CMake 提供了一套从严重错误到跟踪调试的完整日志级别体系，遵循「从高到低」的使用原则，不同级别对应不同行为、输出格式与信息流走向。熟练掌握这套规则，能让你的构建脚本更健壮、问题定位更高效。

本文将从最致命的FATAL开始，逐级拆解每类日志的行为、用法、输出特征，并附上可直接运行的代码示例，最后讲透标准输出 / 标准错误输出的重定向技巧。

一、日志级别总览（从高到低）

CMake 日志优先级从高到低依次为：
FATAL→ERROR→WARNING→NOTICE→STATUS→VERBOSE→DEBUG→TRACE

越高级别的日志，对构建流程影响越大；越低级别，信息量越细、默认越不显示。

二、最高危：FATAL 级别 —— 进程直接终止

FATAL是最高优先级错误，一旦触发，CMake 进程立即退出，后续所有代码完全不执行。

核心行为

• 打印错误信息

• 进程直接退出，后续逻辑彻底中断

• 属于标准错误输出（STDERR）

示例代码

# FATAL 错误：触发后直接退出 message(FATAL_ERROR "test fatal error") # 👇 这行永远不会被执行！ message("after fatal error")

执行结果

test fatal error

after fatal error完全不输出，CMake 直接终止。

关键结论：FATAL_ERROR用于不可恢复的致命错误，必须确保在安全场景才启用，测试时务必注释掉。

三、次严重：SEND_ERROR 级别 —— 构建停止，进程继续

SEND_ERROR不会杀死 CMake 进程，脚本会继续往下跑，但项目构建产物完全不生成。

核心行为

• 打印错误信息

• CMake 进程继续执行

• 停止生成可执行文件 / 库（add_executable/add_library失效）

• 带文件路径 + 行号，便于定位

• 属于标准错误输出（STDERR）

示例代码

# 触发 ERROR，不退出但不生成项目 message(SEND_ERROR "test send error") # 👇 会继续执行 message("after error") # 👇 项目文件不会生成！ add_executable(test_message test_message.cpp)

执行结果

• 控制台输出错误与行号

• after error正常打印

• build目录无任何可执行文件

关键结论：SEND_ERROR适合业务逻辑错误但不必终止脚本的场景，阻止非法构建，但不中断流程。

四、警告级别：WARNING—— 提示风险，不阻断构建

WARNING用于非阻断性警告，不影响生成、不退出，只提醒风险。

核心行为

• 打印警告信息

• 带文件路径 + 行号

• 进程正常执行、项目正常生成

• 属于标准错误输出（STDERR）

示例代码

message(WARNING "test warning")

执行结果

CMake Warning at xxx/CMakeLists.txt:xx (message): test warning

关键结论：WARNING用于潜在问题提示，不影响正常构建流程。

五、普通提示：NOTICE—— 无格式纯信息输出

NOTICE是默认普通提示，与不带任何参数的message("msg")完全等价。

核心行为

• 纯文本输出

• 不带路径 / 行号

• 简洁、通用，适合常规提示

• 属于标准错误输出（STDERR）

示例代码

message(NOTICE "test notice") message("等同于 notice") # 等价写法

关键结论：NOTICE是最常用的通用日志，无多余格式，适合流程说明。

六、用户状态：STATUS—— 带前缀的友好提示

STATUS用于输出用户关心的构建状态，比NOTICE级别更低，自带前缀标识。

核心行为

• 输出自带前缀：-- test status

• 简洁、清晰，适合库编译成功、配置完成等状态

• 属于标准输出（STDOUT）

示例代码

message(STATUS "test status")

执行结果

-- test status

关键结论：STATUS面向使用者，展示关键状态，不干扰错误信息。

七、详细信息：VERBOSE—— 默认隐藏的扩展日志

VERBOSE是用户级详细信息，默认不显示，需手动开启日志级别。

核心行为

• 默认隐藏

• 自带--前缀

• 属于标准输出（STDOUT）

• 适合输出详细配置、路径、依赖等信息

开启方式

cmake-S.-Bbuild --log-level=verbose

示例代码

message(VERBOSE "test verbose")

关键结论：VERBOSE用于需要时才展示的详细信息，避免控制台污染。

八、开发者调试：DEBUG & TRACE—— 底层跟踪专用

DEBUG与TRACE是开发者级日志，默认不显示，用于深度调试。

核心行为

• 均自带前缀

• DEBUG：调试信息

• TRACE：路径 / 流程跟踪

• 需指定级别才能显示

开启方式

# 显示 DEBUGcmake-S.-Bbuild --log-level=debug# 显示 TRACE（最详细）cmake-S.-Bbuild --log-level=trace

示例代码

message(DEBUG "test debug") message(TRACE "test trace")

九、核心机制：STDOUT 与 STDERR 分流

CMake 日志严格分为两类信息流：

1️⃣ 标准输出 STDOUT（可重定向到文件）

• STATUS

• VERBOSE

• DEBUG

• TRACE

2️⃣ 标准错误输出 STDERR（控制台默认展示）

• FATAL_ERROR

• SEND_ERROR

• WARNING

• NOTICE/ 无参数 message

十、终极技巧：全量日志重定向到文件

在 Windows/Linux 通用，把 ** 所有输出（STDOUT+STDERR）** 写入日志文件：

cmake-S.-Bbuild --log-level=trace>log.txt2>&1

• > log.txt：重定向 STDOUT

• 2>&1：把 STDERR 合并到 STDOUT，一起写入文件

打开log.txt，即可看到完整构建日志，便于复盘与排查。

十一、级别速查表（记忆版）

总结

CMake 日志体系层级清晰、行为明确、分流严谨：

• 高级别控制流程，低级别提供信息

• FATAL/ERROR保障构建安全

• STATUS/VERBOSE提升用户体验

• DEBUG/TRACE支撑深度调试

• 输出重定向让日志可沉淀、可分析

把这套规则用到项目里，你的 CMake 脚本会更规范、更易维护、更易排查问题。