cmake-configure-log(7)

於版本 3.26 新增。

簡介

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

為了方便人類使用，此版本的 CMake 會將組態日誌寫入到檔案

${CMAKE_BINARY_DIR}/CMakeFiles/CMakeConfigureLog.yaml

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

日誌結構

組態日誌設計為同時可供機器和人類讀取。

日誌檔案是一個 YAML 文件流，包含零或多個以文件分隔符號分隔的 YAML 文件。每個文件都以 --- 文件分隔符號行開始，包含一個 YAML 映射，記錄來自一個 CMake 「組態」步驟的事件，並且，如果組態步驟正常完成，則以 ... 文件分隔符號行結束

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

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

每個文件根映射的鍵是

events

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

日誌版本控制

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

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

  • 未來版本的 CMake 可能會引入新的事件種類或版本。

  • 如果使用不同版本的 CMake 重新組態現有的建置樹，則日誌可能包含相同事件種類的不同版本。

  • 如果 cmake-file-api(7) 查詢請求一個或多個 configureLog 物件版本，則日誌可能包含同一事件的多個條目，每個條目都具有不同版本的事件種類。

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

文字區塊編碼

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

  • \\ 編碼一個反斜線。

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

事件種類

每個事件種類都由以下形式的 YAML 映射表示

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

所有事件通用的鍵是

kind

一個字串，用於識別事件種類和主要版本。

backtrace

一個 YAML 區塊序列，報告事件發生的 CMake 原始碼位置的呼叫堆疊，從最近到最遠。每個節點都是一個字串，指定一個位置，格式為 <file>:<line> (<function>)。

checks

一個可選的鍵，當事件發生時，至少有一個待處理的 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 映射的鍵是

message

一個 YAML literal block scalar，包含訊息文字，使用我們的 文字區塊編碼 表示。

事件種類 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 映射的鍵是

description

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

directories

一個描述與編譯嘗試相關聯的目錄的映射。它具有以下鍵

source

字串，指定 try_compile() 專案的原始碼目錄。

binary

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

cmakeVariables

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

buildResult

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

variable

一個字串，指定儲存嘗試建置測試專案結果的 CMake 變數的名稱。

cached

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

stdout

一個 YAML literal block scalar，包含來自建置測試專案的輸出，使用我們的 文字區塊編碼 表示。這包含來自 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

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

variable

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

cached

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

stdout

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

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

stderr

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

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

exitCode

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