CMake 015：日志级别全解析

CMake 015：日志级别全解析

• 一、日志级别总览（从高到低）
• [二、最高危：FATAL 级别 ------ 进程直接终止](#二、最高危：FATAL 级别 —— 进程直接终止)
• • 核心行为
  • 示例代码
  • 执行结果
• [三、次严重：SEND_ERROR 级别 ------ 构建停止，进程继续](#三、次严重：SEND_ERROR 级别 —— 构建停止，进程继续)
• • 核心行为
  • 示例代码
  • 执行结果
• [四、警告级别：WARNING------ 提示风险，不阻断构建](#四、警告级别：WARNING—— 提示风险，不阻断构建)
• • 核心行为
  • 示例代码
  • 执行结果
• [五、普通提示：NOTICE------ 无格式纯信息输出](#五、普通提示：NOTICE—— 无格式纯信息输出)
• • 核心行为
  • 示例代码
• [六、用户状态：STATUS------ 带前缀的友好提示](#六、用户状态：STATUS—— 带前缀的友好提示)
• • 核心行为
  • 示例代码
  • 执行结果
• [七、详细信息：VERBOSE------ 默认隐藏的扩展日志](#七、详细信息：VERBOSE—— 默认隐藏的扩展日志)
• • 核心行为
  • 开启方式
  • 示例代码
• [八、开发者调试：DEBUG & TRACE------ 底层跟踪专用](#八、开发者调试：DEBUG & TRACE—— 底层跟踪专用)
• • 核心行为
  • 开启方式
  • 示例代码
• [九、核心机制：STDOUT 与 STDERR 分流](#九、核心机制：STDOUT 与 STDERR 分流)
• • [1️⃣ 标准输出 STDOUT（可重定向到文件）](#1️⃣ 标准输出 STDOUT（可重定向到文件）)
  • [2️⃣ 标准错误输出 STDERR（控制台默认展示）](#2️⃣ 标准错误输出 STDERR（控制台默认展示）)
• 十、终极技巧：全量日志重定向到文件
• 十一、级别速查表（记忆版）
• 总结

在 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 . -B build --log-level=verbose

示例代码

message(VERBOSE "test verbose")

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

---

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

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

核心行为

• 均自带前缀

• DEBUG：调试信息

• TRACE：路径 / 流程跟踪

• 需指定级别才能显示

开启方式

# 显示 DEBUG
cmake -S . -B build --log-level=debug

# 显示 TRACE（最详细）
cmake -S . -B build --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 . -B build --log-level=trace > log.txt 2>&1

• > log.txt：重定向 STDOUT

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

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

---

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

级别	行为	输出	信息流	适用场景
FATAL	进程退出	错误	STDERR	致命错误
ERROR	不生成项目	错误 + 行号	STDERR	阻断构建
WARNING	正常构建	警告 + 行号	STDERR	风险提示
NOTICE	正常输出	纯文本	STDERR	通用提示
STATUS	状态输出	-- 前缀	STDOUT	用户状态
VERBOSE	默认隐藏	-- 前缀	STDOUT	详细信息
DEBUG	默认隐藏	前缀	STDOUT	调试
TRACE	默认隐藏	前缀	STDOUT	跟踪

---

总结

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

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

• FATAL/ERROR 保障构建安全

• STATUS/VERBOSE 提升用户体验

• DEBUG/TRACE 支撑深度调试

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

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