cmake-instrumentation(7)

在版本 4.0 中新增。

簡介

注意

此功能僅在透過 CMAKE_EXPERIMENTAL_INSTRUMENTATION 閘道啟用 Instrumentation 的實驗性支援時可用。

CMake Instrumentation API 允許在 CMake 專案的配置、產生、建置、測試和安裝步驟期間收集計時資料、目標資訊和系統診斷資訊。

此功能僅適用於使用 Makefile 產生器 或 Ninja 產生器 的專案。

與 CMake Instrumentation API 的所有互動都必須指定 API 版本和 Data 版本。目前，每個版本只有一個版本：API v1 和 Data v1。

資料收集

每當執行命令並啟用 Instrumentation 時，都會在專案建置樹中建立 v1 片段檔案，其中包含特定於該命令的資料。這些檔案會保留到 索引 發生之後。

CMake 設定 RULE_LAUNCH_COMPILE、RULE_LAUNCH_LINK 和 RULE_LAUNCH_CUSTOM 全域屬性，以使用 ctest --instrument 啟動器，以便分別擷取每個編譯、連結和自訂命令的詳細資訊。如果專案已使用 CTestUseLaunchers 進行配置，則 ctest --instrument 也將包含通常由 ctest --launch 執行的行為。

索引

索引是整理產生的 Instrumentation 資料的過程。索引會在特定的間隔（稱為鉤點）發生，例如在每次建置之後。這些鉤點配置為 v1 查詢檔案 的一部分。每當觸發鉤點時，就會產生一個索引檔案，其中包含比先前索引新的片段檔案列表。

索引也可以透過手動調用 ctest --collect-instrumentation <建置> 來執行。

回呼

作為 v1 查詢檔案 的一部分，使用者可以提供回呼列表，旨在處理此功能收集的資料。

每當 索引 發生時，每個提供的回呼都會被執行，並將產生的索引檔案的路徑作為引數傳遞。

這些在使用者層級或專案層級定義的回呼應讀取 Instrumentation 資料並執行任何所需的處理。一旦所有回呼完成，CMake 會自動刪除索引檔案及其列出的片段。請注意，回呼絕不應手動移動或刪除這些資料檔案，因為其他回呼可能需要它們。

啟用 Instrumentation

可以為個別 CMake 專案啟用 Instrumentation，也可以為使用者配置和建置的所有 CMake 專案啟用 Instrumentation。對於這兩種情況，請參閱 v1 查詢檔案，以了解有關配置此功能的詳細資訊。

在專案層級啟用 Instrumentation

專案程式碼可以包含使用 cmake_instrumentation() 命令的 Instrumentation 查詢。

此外，查詢檔案可以手動放置在建置樹頂層的 <建置>/.cmake/instrumentation/<版本>/query/ 下。此版本的 CMake 僅支援一個版本架構，API v1。

在使用者層級啟用 Instrumentation

可以透過將查詢檔案放置在 CMAKE_CONFIG_DIR 下的 <設定目錄>/instrumentation/<版本>/query/ 中，在使用者層級配置 Instrumentation。

為 CDash 提交啟用 Instrumentation

您可以在 儀表板用戶端 模式中使用 CTest 時，透過將 CTEST_USE_INSTRUMENTATION 環境變數設定為 CMAKE_EXPERIMENTAL_INSTRUMENTATION 功能的目前 UUID，來啟用 Instrumentation。這樣做會自動啟用 dynamicSystemInformation 查詢。

下表顯示了每種 Instrumentation 命令類型如何對應到對應的 CTest XML 檔案類型。

片段角色	CTest XML 檔案
配置	Configure.xml
產生	Configure.xml
編譯	Build.xml
連結	Build.xml
自訂	Build.xml
建置	未使用！
cmakeBuild	Build.xml
cmakeInstall	Build.xml
安裝	Build.xml
ctest	Build.xml
測試	Test.xml

預設情況下，報告給 CDash 的命令列會在第一個空格處截斷。您可以選擇透過將 CTEST_USE_VERBOSE_INSTRUMENTATION 設定為 1，來改為報告完整命令列（包括引數）。

API v1

API 版本指定 Instrumentation 資料的子目錄佈局和查詢檔案的格式。

Instrumentation API v1 位於 instrumentation/v1/ 目錄下，該目錄位於 <建置>/.cmake/ 下，用於輸出資料和專案層級查詢，或位於 <設定目錄>/ 下，用於使用者層級查詢。v1 目錄的元件表示 API 版本。它具有以下子目錄

query/

保存使用者或用戶端寫入的查詢檔案。任何具有 .json 副檔名的檔案都將被識別為查詢檔案。這些檔案歸建立它們的用戶端或使用者所有。

query/generated/

保存由 CMake 專案使用 cmake_instrumentation() 命令產生的查詢檔案。這些檔案歸 CMake 所有，並且在 CMake 配置步驟期間自動刪除和重新產生。

data/

保存專案上收集的 Instrumentation 資料。CMake 擁有所有資料檔案，其他程序絕不應移除它們。此處收集的資料將保留到 索引 發生且所有 回呼 都執行完畢之後。

cdash/

保存內部用於產生要提交到 CDash 的 XML 內容的暫存檔案。

v1 查詢檔案

在 instrumentation/v1/query/ 目錄下，任何具有 .json 副檔名的檔案都被識別為 Instrumentation 資料的查詢。

這些檔案必須包含具有以下鍵的 JSON 物件。version 鍵是必需的，但所有其他欄位都是選用的。

version

要產生的片段檔案的 Data 版本，一個整數。目前唯一支援的版本是 1。

callbacks

用於處理收集的 Instrumentation 資料的 回呼 的命令列字串列表。每當執行這些回呼時，v1 索引檔案 的完整路徑都會附加到字串中包含的引數。

hooks

指定何時應自動發生 索引 的字串列表。這些是應整理 Instrumentation 資料並調用使用者 回呼 以處理資料的時間間隔。此列表中的元素應為以下其中之一

• postGenerate

• preBuild（在調用 ninja 或 make 時調用；在 Windows 上不可用）

• postBuild（在 ninja 或 make 完成時調用；在 Windows 上不可用）

• preCMakeBuild（在調用 cmake --build 時調用）

• postCMakeBuild（在 cmake --build 完成時調用）

• postInstall

• postTest

queries

指定在 Instrumentation 期間要收集的其他選用資料的字串列表。此列表中的元素應為以下其中之一

staticSystemInformation

啟用收集執行 CMake 的主機的靜態資訊。此資料在 索引 期間收集，並包含在產生的 v1 索引檔案 中。

dynamicSystemInformation

啟用收集執行 CMake 的主機的動態資訊。資料是針對 CMake 產生的每個 v1 片段檔案 收集的，並且包含在命令執行之前和之後立即取得的資訊。

列出的 callbacks 將至少在指定的鉤點期間被調用。當有多個查詢檔案時，它們之間的 callbacks、hooks 和 queries 將被合併。因此，如果任何查詢檔案包含任何 hooks，則所有查詢檔案中的每個 callback 都將在所有查詢檔案中的每個 hook 處執行。此外，如果任何查詢檔案包含任何選用的 queries，則選用的查詢資料將存在於所有資料檔案中。

範例

{
  "version": 1,
  "callbacks": [
    "/usr/bin/python callback.py",
    "/usr/bin/cmake -P callback.cmake arg",
  ],
  "hooks": [
    "postCMakeBuild",
    "postInstall"
  ],
  "queries": [
    "staticSystemInformation",
    "dynamicSystemInformation"
  ]
}

在此範例中，每次調用 cmake --build 或 cmake --install 後，都會在 <建置>/.cmake/instrumentation/v1/data 中產生一個索引檔案 index-<時間戳記>.json，其中包含自上次索引以來建立的資料片段檔案列表。命令 /usr/bin/python callback.py index-<時間戳記>.json 和 /usr/bin/cmake -P callback.cmake arg index-<時間戳記>.json 將按該順序執行。索引檔案將包含 staticSystemInformation 資料，並且索引中列出的每個片段檔案都將包含 dynamicSystemInformation 資料。一旦兩個回呼都完成，索引檔案及其列出的所有片段檔案將從專案建置樹中刪除。

Data v1

Data 版本指定 CMake Instrumentation API 作為 資料收集 和 索引 的一部分產生的輸出檔案的內容。產生兩種資料檔案類型：v1 片段檔案 和 v1 索引檔案。當使用 API v1 時，這些檔案位於專案建置樹下的 <建置>/.cmake/instrumentation/v1/data/ 中。

v1 片段檔案

片段檔案是針對 CMake 建置或安裝步驟中調用的每個編譯、連結和自訂命令產生的，並且包含有關已執行命令的 Instrumentation 資料。此外，還為以下項目建立片段檔案

• CMake 配置步驟

• CMake 產生步驟

• 整個建置步驟（使用 cmake --build 執行）

• 整個安裝步驟（使用 cmake --install 執行）

• 每次 ctest 調用

• 由 ctest 執行的每個個別測試。

這些檔案會保留在建置樹中，直到 索引 發生且任何使用者指定的 回呼 都執行完畢之後。

片段檔案的檔案名稱語法為 <角色>-<雜湊值>-<時間戳記>.json，並且包含以下資料

version

片段檔案的 Data 版本，一個整數。目前版本始終為 1。

command

執行的完整命令。當 role 為 build 時排除。

workingDir

執行 command 的工作目錄。

result

命令的結束值，一個整數。

role

執行的命令類型，將為以下值之一

• configure：CMake 配置步驟

• generate：CMake 產生步驟

• compile：在建置期間調用的個別編譯步驟

• link：在建置期間調用的個別連結步驟

• custom：在建置期間調用的個別自訂命令

• build：完整的 make 或 ninja 調用。僅在啟用 preBuild 或 postBuild 鉤點時產生。

• cmakeBuild：完整的 cmake --build 調用

• cmakeInstall：完整的 cmake --install 調用

• install：個別的 cmake -P cmake_install.cmake 調用

• ctest：完整的 ctest 調用

• test：由 CTest 執行的單個測試

target

與命令關聯的 CMake 目標。僅當 role 為 compile 或 link 時包含。

targetType

目標的 TYPE。僅當 role 為 link 時包含。

targetLabels

目標的 LABELS。僅當 role 為 link 時包含。

timeStart

命令開始的時間，表示為自系統紀元以來的毫秒數。

duration

命令運行的持續時間，以毫秒為單位表示。

outputs

命令的輸出檔案，一個陣列。僅當 role 是以下其中之一時包含：compile、link、custom。

outputSizes

outputs 的大小（以位元組為單位），一個陣列。對於不存在的檔案，大小為 0。在與 outputs 欄位相同的條件下包含。

source

正在編譯的原始程式碼檔案。僅當 role 為 compile 時包含。

language

正在編譯的原始程式碼檔案的語言。僅當 role 為 compile 時包含。

testName

正在執行的測試名稱。僅當 role 為 test 時包含。

config

建置類型，例如 Release 或 Debug。僅當 role 為 compile、link 或 test 時包含。

dynamicSystemInformation

指定收集的關於執行 CMake 的主機的動態資訊。資料是針對 CMake 產生的每個片段檔案收集的，其中包含命令執行之前和之後立即取得的資料。僅在由 v1 查詢檔案 啟用時包含。

beforeHostMemoryUsed

在 timeStart 時使用的主機記憶體（以 KiB 為單位）。

afterHostMemoryUsed

在 timeStop 時使用的主機記憶體（以 KiB 為單位）。

beforeCPULoadAverage

在 timeStart 時的平均 CPU 負載。

afterCPULoadAverage

在 timeStop 時的平均 CPU 負載。

範例

{
  "version": 1,
  "command" : "\"/usr/bin/c++\" \"-MD\" \"-MT\" \"CMakeFiles/main.dir/main.cxx.o\" \"-MF\" \"CMakeFiles/main.dir/main.cxx.o.d\" \"-o\" \"CMakeFiles/main.dir/main.cxx.o\" \"-c\" \"<src>/main.cxx\"",
  "role" : "compile",
  "return" : 1,
  "target": "main",
  "language" : "C++",
  "outputs" : [ "CMakeFiles/main.dir/main.cxx.o" ],
  "outputSizes" : [ 0 ],
  "source" : "<src>/main.cxx",
  "config" : "Debug",
  "dynamicSystemInformation" :
  {
    "afterCPULoadAverage" : 2.3500000000000001,
    "afterHostMemoryUsed" : 6635680.0
    "beforeCPULoadAverage" : 2.3500000000000001,
    "beforeHostMemoryUsed" : 6635832.0
  },
  "timeStart" : 1737053448177,
  "duration" : 31
}

v1 索引檔案

索引檔案包含 v1 片段檔案 的列表。它作為導航 Instrumentation 資料的入口點。它們在每次 索引 發生時產生，並在任何使用者指定的 回呼 執行後刪除。

version

索引檔案的 Data 版本，一個整數。目前版本始終為 1。

buildDir

CMake 專案的建置目錄。

dataDir

到 <建置>/.cmake/instrumentation/v1/data/ 目錄的完整路徑。

hook

負責產生索引檔案的鉤點名稱。除了可以由 v1 查詢檔案 之一指定的鉤點之外，如果索引是透過調用 ctest --collect-instrumentation <建置> 執行的，則此值可以設定為 manual。

snippets

包含 v1 片段檔案 的列表。這包括自上次建立索引檔案以來產生的所有片段檔案。檔案路徑相對於 dataDir。

staticSystemInformation

指定收集的關於執行 CMake 的主機的靜態資訊。僅在由 v1 查詢檔案 啟用時包含。

• OSName

• OSPlatform

• OSRelease

• OSVersion

• familyId

• hostname

• is64Bits

• modelId

• numberOfLogicalCPU

• numberOfPhysicalCPU

• processorAPICID

• processorCacheSize

• processorClockFrequency

• processorName

• totalPhysicalMemory

• totalVirtualMemory

• vendorID

• vendorString

範例

{
  "version": 1,
  "hook": "manual",
  "buildDir": "<build>",
  "dataDir": "<build>/.cmake/instrumentation/v1/data",
  "snippets": [
    "configure-<hash>-<timestamp>.json",
    "generate-<hash>-<timestamp>.json",
    "compile-<hash>-<timestamp>.json",
    "compile-<hash>-<timestamp>.json",
    "link-<hash>-<timestamp>.json",
    "install-<hash>-<timestamp>.json",
    "ctest-<hash>-<timestamp>.json",
    "test-<hash>-<timestamp>.json",
    "test-<hash>-<timestamp>.json",
  ]
}