cmake-configure-log(7)¶

在 3.26 版本中新增。

簡介 ¶

CMake 會寫入一個執行日誌，稱為「組態日誌」，記錄在組態步驟期間發生的特定事件。組態日誌「並未」包含組態專案時列印的所有輸出、錯誤或訊息的日誌。它是關於特定事件詳細資訊的日誌，例如 try_compile() 的工具鏈檢查，目的是為了除錯建置樹的組態。

對於人類使用，這個版本的 CMake 會將組態日誌寫入檔案

${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml

然而，日誌檔案的「位置和名稱可能會在未來的 CMake 版本中變更」。讀取組態日誌的工具應使用 configureLog 查詢到 cmake-file-api(7) 來取得其位置。請參閱下方的日誌版本控制章節以取得詳細資訊。

日誌結構 ¶

組態日誌的設計同時要讓機器和人類都能讀取。

日誌檔案是一個 YAML 文件串流，其中包含零或多個以文件標記分隔的 YAML 文件。每個文件都以 --- 文件標記行開頭，包含一個 YAML 對應，記錄來自一個 CMake「組態」步驟的事件，並且如果組態步驟正常完成，則以 ... 文件標記行結尾

---
events:
  -
    kind: "try_compile-v1"
    # (other fields omitted)
  -
    kind: "try_compile-v1"
    # (other fields omitted)
...

每次 CMake 組態建置樹並記錄新事件時，都會將新的文件附加到日誌中。

每個文件根對應的鍵是

事件: 一個 YAML 區塊序列，其中包含對應於在一個 CMake「組態」步驟期間記錄的事件的節點。每個事件都是一個 YAML 節點，其中包含下面記錄的事件種類之一。

日誌版本控制 ¶

每個事件種類都是獨立版本控制的。事件的日誌條目提供的鍵集是特定於其主要版本的。當記錄事件時，總是將執行中的 CMake 版本已知的其事件種類的最新版本寫入日誌。

讀取組態日誌的工具必須忽略它們不理解的事件種類和版本

未來版本的 CMake 可能會引入新的事件種類或版本。
如果使用不同版本的 CMake 重新組態現有的建置樹，則日誌可能包含相同事件種類的不同版本。
如果 cmake-file-api(7) 查詢請求一個或多個 configureLog 物件版本，則日誌可能包含相同事件的多個條目，每個條目都具有其事件種類的不同版本。

IDE 應在執行 CMake 之前，先寫入一個 cmake-file-api(7) 查詢，請求特定的 configureLog 物件版本，然後僅按照 file-api 回覆的描述讀取組態日誌。

文字區塊編碼 ¶

為了使日誌易於人類閱讀，文字區塊始終使用 YAML 文字區塊純量 (|) 表示。由於文字區塊純量不支援逸出，因此反斜線和不可列印的字元會在應用程式層級進行編碼

\\ 編碼一個反斜線。
\xXX 使用兩個十六進位數字 XX 編碼一個位元組。

事件種類 ¶

每個事件種類都以 YAML 對應表示，其形式為

kind: "<kind>-v<major>"
backtrace:
  - "<file>:<line> (<function>)"
checks:
  - "Checking for something"
#...event-specific keys...

所有事件通用的鍵是

種類: 一個字串，用於識別事件種類和主要版本。
回溯: 一個 YAML 區塊序列，報告事件發生的 CMake 原始程式碼位置的呼叫堆疊，從最近到最遠。每個節點都是一個字串，指定一個位置，其格式為 <file>:<line> (<function>)。
檢查: 一個可選的鍵，當事件發生時，至少有一個待處理的 message(CHECK_START) 時存在。它的值是一個 YAML 區塊序列，報告待處理檢查的堆疊，從最近到最遠。每個節點都是一個字串，其中包含待處理的檢查訊息。

其他對應鍵是特定於每個（版本化的）事件種類的，如下所述。

事件種類 `message`¶

message(CONFIGURE_LOG) 命令會記錄 message 事件。

只有一個 message 事件的主要版本，即版本 1。

`message-v1` 事件 ¶

message-v1 事件是一個 YAML 對應

kind: "message-v1"
backtrace:
  - "CMakeLists.txt:123 (message)"
checks:
  - "Checking for something"
message: |
  # ...

特定於 message-v1 對應的鍵是

訊息: 一個 YAML 文字區塊純量，其中包含訊息文字，使用我們的文字區塊編碼表示。

事件種類 `try_compile`¶

try_compile() 命令會記錄 try_compile 事件。

只有一個 try_compile 事件的主要版本，即版本 1。

`try_compile-v1` 事件 ¶

try_compile-v1 事件是一個 YAML 對應

kind: "try_compile-v1"
backtrace:
  - "CMakeLists.txt:123 (try_compile)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-01234"
  binary: "/path/to/.../TryCompile-01234"
cmakeVariables:
  SOME_VARIABLE: "Some Value"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0

特定於 try_compile-v1 對應的鍵是

描述

一個可選的鍵，當使用 LOG_DESCRIPTION <text> 選項時存在。其值是一個字串，其中包含描述 <text>。

目錄

一個對應，描述與編譯嘗試相關的目錄。它具有以下鍵

原始碼: 一個字串，指定 try_compile() 專案的原始碼目錄。
二進位: 一個字串，指定 try_compile() 專案的二進位目錄。對於非專案呼叫，這通常與原始碼目錄相同。

cmake 變數

一個可選的鍵，當 CMake 將變數傳播到測試專案中時存在，無論是自動還是由於 CMAKE_TRY_COMPILE_PLATFORM_VARIABLES 變數所致。它的值是從變數名稱到其值的對應。

建置結果

一個對應，描述編譯測試程式碼的結果。它具有以下鍵

變數: 一個字串，指定儲存嘗試建置測試專案結果的 CMake 變數的名稱。
已快取: 一個布林值，指示上述結果 variable 是否儲存在 CMake 快取中。
stdout: 一個 YAML 字面區塊純量，包含建置測試專案的輸出，並使用我們的文字區塊編碼表示。其中包含來自 stdout 和 stderr 的建置輸出。
exitCode: 一個整數，指定嘗試建置測試專案時，建置工具的結束代碼。

事件種類 `try_run`¶

try_run() 命令會記錄 try_run 事件。

只有一個 try_run 事件主要版本，版本 1。

`try_run-v1` 事件 ¶

一個 try_run-v1 事件是一個 YAML 對應。

kind: "try_run-v1"
backtrace:
  - "CMakeLists.txt:456 (try_run)"
checks:
  - "Checking for something"
description: "Explicit LOG_DESCRIPTION"
directories:
  source: "/path/to/.../TryCompile-56789"
  binary: "/path/to/.../TryCompile-56789"
buildResult:
  variable: "COMPILE_RESULT"
  cached: true
  stdout: |
    # ...
  exitCode: 0
runResult:
  variable: "RUN_RESULT"
  cached: true
  stdout: |
    # ...
  stderr: |
    # ...
  exitCode: 0

try_run-v1 對應特有的鍵，包含 try_compile-v1 事件所記錄的鍵，加上

runResult

一個描述執行測試程式碼結果的對應。它具有以下鍵

變數

一個字串，指定儲存嘗試執行測試可執行檔結果的 CMake 變數名稱。

已快取

一個布林值，指示上述結果 variable 是否儲存在 CMake 快取中。

stdout

一個可選的鍵，當測試專案建置成功時存在。它的值是一個 YAML 字面區塊純量，包含執行測試可執行檔的輸出，並使用我們的文字區塊編碼表示。

如果使用了 RUN_OUTPUT_VARIABLE，stdout 和 stderr 會一起捕獲，因此它會包含兩者。否則，它只會包含 stdout 輸出。

stderr

一個可選的鍵，當測試專案建置成功且未使用 RUN_OUTPUT_VARIABLE 選項時存在。它的值是一個 YAML 字面區塊純量，包含執行測試可執行檔的輸出，並使用我們的文字區塊編碼表示。

如果使用了 RUN_OUTPUT_VARIABLE，stdout 和 stderr 會一起捕獲在 stdout 鍵中，且這個鍵不會存在。否則，它將包含 stderr 輸出。

exitCode

一個可選的鍵，當測試專案建置成功時存在。它的值是一個整數，指定結束代碼，或是一個包含錯誤訊息的字串，來自嘗試執行測試可執行檔。