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 警告 (開發者)，繼續處理。

DEPRECATION

如果變數 CMAKE_ERROR_DEPRECATED 或 CMAKE_WARN_DEPRECATED 分別啟用，則為 CMake 棄用錯誤或警告，否則不顯示訊息。

(none) 或 NOTICE

列印到 stderr 的重要訊息，以吸引使用者注意。

STATUS

專案使用者可能感興趣的主要訊息。理想情況下，這些訊息應該簡潔，不超過一行，但仍然提供資訊。

VERBOSE

提供給專案使用者的詳細資訊訊息。這些訊息應提供額外的細節，在大多數情況下使用者不會感興趣，但對於那些希望深入了解正在發生的事情的專案建置者可能會很有用。

DEBUG

提供給正在開發專案本身的開發人員的詳細資訊訊息，而不是只想建置專案的使用者。這些訊息通常不會引起其他建置專案的使用者的興趣，並且通常與內部實作細節密切相關。

TRACE

具有非常低階實作細節的細微訊息。使用此日誌層級的訊息通常僅是暫時性的，並且預期會在發布專案、打包檔案等之前移除。

在 3.15 版本中新增: 新增了 NOTICE、VERBOSE、DEBUG 和 TRACE 層級。

CMake 命令列工具會將 STATUS 到 TRACE 訊息顯示在 stdout 上，訊息前面有兩個連字符和一個空格。所有其他訊息類型都會傳送到 stderr，且不帶連字符前綴。CMake GUI 會在其日誌區域中顯示所有訊息。curses 介面 會在狀態列上一次顯示一個 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 腳本模式下），則此命令不會執行任何操作。

另請參閱