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 错误,停止处理和生成。

cmake(1) 可执行文件将返回非零的退出代码

SEND_ERROR

CMake 错误,继续处理,但跳过生成。

WARNING

CMake 警告,继续处理。

AUTHOR_WARNING

CMake 警告 (dev),继续处理。

DEPRECATION

如果变量 CMAKE_ERROR_DEPRECATEDCMAKE_WARN_DEPRECATED 分别启用,则为 CMake 弃用错误或警告,否则不显示消息。

(无) 或 NOTICE

打印到 stderr 的重要消息,以吸引用户注意。

STATUS

项目用户可能感兴趣的主要消息。理想情况下,这些消息应该简洁,不超过一行,但仍具信息量。

VERBOSE

供项目用户使用的详细信息消息。这些消息应提供在大多数情况下不感兴趣的额外详细信息,但对于那些希望深入了解正在发生的事情的项目构建者来说可能有用。

DEBUG

供开发项目本身的开发人员使用的详细信息消息,而不是只想构建它的用户。这些消息通常不会引起构建项目的其他用户的兴趣,并且通常与内部实现细节密切相关。

TRACE

包含非常低级实现细节的细粒度消息。使用此日志级别的消息通常只应是临时的,并期望在发布项目、打包文件等之前删除。

版本 3.15 新增: 添加了 NOTICEVERBOSEDEBUGTRACE 级别。

CMake 命令行工具将 STATUSTRACE 消息显示在标准输出上,消息前缀为两个连字符和一个空格。所有其他消息类型都发送到标准错误,并且没有连字符前缀。CMake GUI 在其日志区域显示所有消息。curses interface 在状态行上一次显示一个 STATUSTRACE 消息,并在交互式弹出框中显示其他消息。这些工具的 --log-level 命令行选项可用于控制将显示哪些消息。

版本 3.17 新增: 为了使日志级别在 CMake 运行之间持久化,可以设置 CMAKE_MESSAGE_LOG_LEVEL 变量。请注意,命令行选项优先于缓存变量。

版本 3.16 新增: 日志级别为 NOTICE 及以下的消息的每一行都将以 CMAKE_MESSAGE_INDENT 变量的内容(通过连接其列表项转换为单个字符串)作为前缀。对于 STATUSTRACE 消息,此缩进内容将插入到连字符之后。

版本 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_PASSCHECK_FAIL 关键字之后提供的消息文本。检查消息始终以 STATUS 日志级别报告。

检查可以嵌套,每个 CHECK_START 应该正好有一个匹配的 CHECK_PASSCHECK_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 脚本模式下,此命令不执行任何操作。

另请参阅