message¶
记录消息。
概要¶
General messages message([<mode>] "message text" ...) Reporting checks message(<checkState> "message text" ...) Configure Log message(CONFIGURE_LOG <text>...)
通用消息¶
message([<mode>] "message text" ...)
在日志中记录指定的消息文本。如果给出多个消息字符串,它们将被连接成一个单独的消息,字符串之间没有分隔符。
可选的 <mode>
关键字决定了消息的类型,这会影响消息的处理方式
FATAL_ERROR
CMake 错误,停止处理和生成。
SEND_ERROR
CMake 错误,继续处理,但跳过生成。
WARNING
CMake 警告,继续处理。
AUTHOR_WARNING
CMake 警告 (开发),继续处理。
DEPRECATION
如果变量
CMAKE_ERROR_DEPRECATED
或CMAKE_WARN_DEPRECATED
分别启用,则为 CMake 弃用错误或警告,否则不显示消息。- (none) 或
NOTICE
打印到 stderr 的重要消息,以引起用户注意。
STATUS
项目用户可能感兴趣的主要有趣消息。理想情况下,这些消息应该简洁明了,不超过一行,但仍然信息丰富。
VERBOSE
面向项目用户的详细信息性消息。这些消息应提供在大多数情况下不相关的其他详细信息,但对于那些希望深入了解正在发生的事情的项目构建者可能很有用。
DEBUG
面向正在开发项目本身的开发人员而不是只想构建它的用户的详细信息性消息。这些消息通常不会引起构建项目的其他用户的兴趣,并且通常与内部实现细节密切相关。
TRACE
具有非常低级别实现细节的细粒度消息。使用此日志级别的消息通常只是临时的,并且希望在发布项目、打包文件等之前删除。
3.15 版本新增: 添加了 NOTICE
、VERBOSE
、DEBUG
和 TRACE
级别。
CMake 命令行工具在 stdout 上显示 STATUS
到 TRACE
消息,消息前缀为两个连字符和一个空格。所有其他消息类型都发送到 stderr,并且没有连字符前缀。CMake GUI
在其日志区域中显示所有消息。curses interface
在状态行上一次显示一条 STATUS
到 TRACE
消息,并在交互式弹出框中显示其他消息。--log-level
这些工具的命令行选项可用于控制将显示哪些消息。
3.17 版本新增: 为了使日志级别在 CMake 运行之间持久存在,可以改为设置 CMAKE_MESSAGE_LOG_LEVEL
变量。请注意,命令行选项优先于缓存变量。
3.16 版本新增: 日志级别为 NOTICE
及以下的消息,其每行前面都会有 CMAKE_MESSAGE_INDENT
变量的内容(通过连接其列表项转换为单个字符串)。对于 STATUS
到 TRACE
消息,此缩进内容将插入到连字符之后。
3.17 版本新增: 日志级别为 NOTICE
及以下的消息,其每行前面也可以带有 [some.context.example]
形式的上下文。方括号之间的内容是通过将 CMAKE_MESSAGE_CONTEXT
列表变量转换为点分隔的字符串获得的。消息上下文将始终出现在任何缩进内容之前,但在任何自动添加的前导连字符之后。默认情况下,消息上下文不显示,必须通过给出 cmake --log-context
命令行选项或将 CMAKE_MESSAGE_CONTEXT_SHOW
变量设置为 true 来显式启用。有关用法示例,请参见 CMAKE_MESSAGE_CONTEXT
文档。
CMake 警告和错误消息文本显示使用简单的标记语言。非缩进文本以换行符分隔的行包裹段落格式化。缩进文本被认为是预格式化的。
报告检查¶
3.17 版本新增。
CMake 输出中常见的模式是指示某种检查开始的消息,然后是另一条报告该检查结果的消息。例如
message(STATUS "Looking for someheader.h")
#... do the checks, set checkSuccess with the result
if(checkSuccess)
message(STATUS "Looking for someheader.h - found")
else()
message(STATUS "Looking for someheader.h - not found")
endif()
可以使用 message()
命令的 CHECK_...
关键字形式更健壮和方便地表达这一点
message(<checkState> "message" ...)
其中 <checkState>
必须是以下之一
CHECK_START
记录有关即将执行的检查的简洁消息。
CHECK_PASS
记录检查的成功结果。
CHECK_FAIL
记录检查的失败结果。
记录检查结果时,该命令会重复最近启动的检查的消息,该检查尚未报告任何结果,然后是一些分隔符字符,然后是 CHECK_PASS
或 CHECK_FAIL
关键字后提供的消息文本。检查消息始终以 STATUS
日志级别报告。
检查可以是嵌套的,每个 CHECK_START
都应恰好有一个匹配的 CHECK_PASS
或 CHECK_FAIL
。CMAKE_MESSAGE_INDENT
变量也可用于向嵌套检查添加缩进(如果需要)。例如
message(CHECK_START "Finding my things")
list(APPEND CMAKE_MESSAGE_INDENT " ")
unset(missingComponents)
message(CHECK_START "Finding partA")
# ... do check, assume we find A
message(CHECK_PASS "found")
message(CHECK_START "Finding partB")
# ... do check, assume we don't find B
list(APPEND missingComponents B)
message(CHECK_FAIL "not found")
list(POP_BACK CMAKE_MESSAGE_INDENT)
if(missingComponents)
message(CHECK_FAIL "missing components: ${missingComponents}")
else()
message(CHECK_PASS "all components found")
endif()
以上输出将如下所示
-- Finding my things
-- Finding partA
-- Finding partA - found
-- Finding partB
-- Finding partB - not found
-- Finding my things - missing components: B
配置日志¶
3.26 版本新增。
message(CONFIGURE_LOG <text>...)
使用指定的 <text>
记录 配置日志消息事件。按照惯例,如果文本包含多行,则第一行应为事件的摘要。
此模式旨在记录系统检查或其他由缓存条目保护的一次性操作的详细信息,但未使用 try_compile()
或 try_run()
执行,它们会自动记录其详细信息。项目应避免在每次 CMake 运行时都调用它。例如
if (NOT DEFINED MY_CHECK_RESULT)
# Print check summary in configure output.
message(CHECK_START "My Check")
# ... perform system inspection, e.g., with execute_process ...
# Cache the result so we do not run the check again.
set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check")
# Record the check details in the cmake-configure-log.
message(CONFIGURE_LOG
"My Check Result: ${MY_CHECK_RESULT}\n"
"${details}"
)
# Print check result in configure output.
if(MY_CHECK_RESULT)
message(CHECK_PASS "passed")
else()
message(CHECK_FAIL "failed")
endif()
endif()
如果没有正在配置的项目,例如在 cmake -P 脚本模式下,此命令不执行任何操作。