llvm-cov - 發出覆蓋率資訊

語法

llvm-cov 指令 [參數…]

說明

llvm-cov 工具顯示已插入程式碼以發出效能分析資料的程式的程式碼覆蓋率資訊。它可以用於處理 gcov 風格的覆蓋率或 clang 的基於插裝的效能分析。

如果程式是以 gcov 的基本名稱呼叫的，則它的行為就像呼叫了 llvm-cov gcov 命令一樣。否則，應該提供一個命令。

指令

• gcov

• show

• report

• export

GCOV 指令

語法

llvm-cov gcov [選項] 原始碼檔案

說明

llvm-cov gcov 工具讀取程式碼覆蓋率資料檔案，並顯示指定原始碼檔案的覆蓋率資訊。它與 GCC 4.2 版的 gcov 工具相容，也可能與某些更高版本的 gcov 相容。

要使用 llvm-cov gcov，您必須先建立應用程式的已插入程式碼版本，以便在執行時收集覆蓋率資料。使用 -fprofile-arcs 和 -ftest-coverage 選項進行編譯以新增插裝。（或者，您可以使用 --coverage 選項，其中包含這兩個選項。）

編譯已插入程式碼時，會為每個物件檔案產生一個 .gcno 資料檔案。這些 .gcno 檔案包含一半的覆蓋率資料。另一半資料來自執行已插入程式碼時產生的 .gcda 檔案，每個物件檔案都有一個單獨的 .gcda 檔案。每次執行程式時，執行次數都會加總到任何現有的 .gcda 檔案中，因此如果您不希望包含舊檔案的內容，請務必刪除它們。

默認情況下，.gcda 文件會被寫入目標文件所在的目錄，但您可以通過設置 GCOV_PREFIX 和 GCOV_PREFIX_STRIP 環境變數來覆蓋此行為。 GCOV_PREFIX_STRIP 變數指定要從目標文件目錄的絕對路徑開頭移除的目錄組件數量。在移除這些目錄後，會添加 GCOV_PREFIX 變數中的前綴。這些環境變數允許您在無法訪問原始目標文件目錄的機器上運行已插樁的程序，但您需要將 .gcda 文件複製回 llvm-cov gcov 預期找到它們的目標文件目錄。

生成覆蓋率數據文件後，請為要檢查覆蓋率結果的每個主要源文件運行 llvm-cov gcov。這應該在您之前運行編譯器的目錄中執行。指定源文件的結果會寫入一個文件，該文件的名稱是在其後附加 .gcov 後綴。同時也會為主要源文件包含的每個文件創建一個單獨的輸出文件，同樣也會在名稱後附加 .gcov 後綴。

.gcov 輸出文件的基礎內容是源文件的副本，并在每一行前面加上執行次數和行號。如果一行不包含任何可執行代碼，則執行次數顯示為 -。如果一行包含代碼但該代碼從未被執行，則計數顯示為 #####。

選項

-a, --all-blocks

顯示所有基本塊。如果單行源代碼有多個塊，則此選項會導致 llvm-cov 顯示每個塊的計數，而不僅僅是整行的計數。

-b, --branch-probabilities

顯示條件分支概率和分支信息摘要。

-c, --branch-counts

顯示分支計數而不是概率（需要 -b）。

-m, --demangled-names

解構函數名稱。

-f, --function-summaries

顯示每個函式的覆蓋率摘要，而不是僅顯示整個原始程式碼檔的一個摘要。

--help

顯示可用的選項（使用 --help-hidden 顯示更多）。

-l, --long-file-names

對於從主要原始程式碼檔包含的檔案的覆蓋率輸出，請在輸出檔名的前面加上主要檔名，後面跟著 ##。這可以與 --preserve-paths 選項組合使用，以便同時使用主要檔案和包含檔案的完整路徑。

-n, --no-output

不要輸出任何 .gcov 檔案。仍然會顯示摘要資訊。

-o <DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE>

在 DIR 中尋找物件，或根據 FILE 的路徑尋找物件。如果您指定特定的物件檔案，則預期覆蓋率數據檔案具有相同的基底名稱，並帶有 .gcno 和 .gcda 副檔名。如果您指定目錄，則預期檔案位於該目錄中，並且具有與原始程式碼檔相同的基底名稱。

-p, --preserve-paths

命名覆蓋率輸出檔案時保留路徑組件。除了原始程式碼檔名之外，還要包含該檔案路徑中的目錄。目錄以 # 字元分隔，其中 . 目錄被移除，而 .. 目錄則替換為 ^ 字元。與 --long-file-names 選項一起使用時，這將同時套用於主要檔名和包含檔名。

-r

僅傾印具有相對路徑或具有 -s 指定之字首的絕對路徑的檔案。

-s <string>

要省略的來源前綴。

-t, --stdout

輸出到 stdout，而不是產生 .gcov 檔案。

-u, --unconditional-branches

在 –branch-probabilities 選項的輸出中包含無條件分支。

-version

顯示 llvm-cov 的版本。

-x, --hash-filenames

在命名覆蓋率輸出檔案時使用檔案名稱的 md5 雜湊值。來源檔案名稱將加上 ## 後綴，後跟為其計算的 MD5 雜湊值。

結束狀態

如果 llvm-cov gcov 無法讀取輸入檔案，則返回 1。否則，它以零退出。

顯示命令

概要

llvm-cov show [選項] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…

描述

llvm-cov show 命令使用設定檔資料 PROFILE 顯示二進制檔案 BIN… 的逐行覆蓋率。它可以選擇性地過濾以僅顯示 SOURCE… 中列出的檔案的覆蓋率。

BIN 可以是可執行檔、物件檔案、動態程式庫或封存檔（精簡或其他）。

要使用 llvm-cov show，您需要一個使用檢測編譯的程式來發出設定檔和覆蓋率資料。要使用 clang 建立這樣的程式，請使用 -fprofile-instr-generate 和 -fcoverage-mapping 旗標。如果與 clang 驅動程式連結，請將 -fprofile-instr-generate 傳遞到連結階段，以確保連結必要的執行時程式庫。

覆蓋率資訊儲存在已建置的可執行檔或程式庫本身中，這就是您應該傳遞給 llvm-cov show 作為 BIN 參數的內容。設定檔資料是透過正常執行這個已檢測的程式來產生的。當程式退出時，它會寫入一個原始設定檔檔案，通常稱為 default.profraw，可以使用 llvm-profdata merge 工具將其轉換為適合 PROFILE 參數的格式。

選項

-show-branches=<VIEW>

以計數或百分比的形式顯示分支條件的覆蓋率。支援的檢視為：「count」、「percent」。

-show-mcdc

顯示每個適用的布林運算式的修改條件/決策覆蓋率 (MC/DC)。

-show-line-counts

顯示每行的執行次數。預設為 true，除非使用其他 -show 選項。

-show-expansions

在顯示原始程式碼時，將包含內容（例如前置處理器巨集或文字包含內容）直接展開。預設為 false。

-show-instantiations

對於多次實例化的原始程式碼區域（例如 C++ 中的模板），分別顯示每個實例化以及組合的摘要。預設為 true。

-show-regions

顯示每個區域的執行次數，方法是顯示一個插入號，指向該區域開始的字元。預設為 false。

-show-line-counts-or-regions

如果一行中只有一個區域，則顯示每行的執行次數，但如果一行中有多個區域，則顯示個別的區域。預設為 false。

-show-directory-coverage

在每個至少包含一個原始程式碼檔案的目錄中產生一個索引檔案，其中包含一個頂級索引，顯示彙總資訊。預設為 false。

-use-color

啟用或停用彩色輸出。預設情況下會自動偵測。

-arch=[*NAMES*]

指定架構清單，使得清單中的第 N 個項目對應於指定的第 N 個二進制檔案。如果涵蓋的物件是通用二進制檔案，則指定要使用的架構。指定通用二進制檔案中未包含的架構或使用與非通用二進制檔案不符的架構是錯誤的。

-name=<NAME>

僅顯示具有指定名稱的函式的程式碼覆蓋率。

-name-allowlist=<FILE>

僅顯示指定檔案中列出的函式的程式碼覆蓋率。檔案中的每一行都應以 allowlist_fun: 開頭，後面緊跟著要接受的函式名稱。此名稱可以是萬用字元運算式。

-name-regex=<PATTERN>

僅顯示與指定正規表示式相符的函式的程式碼覆蓋率。

-ignore-filename-regex=<PATTERN>

跳過檔案路徑符合指定正規表達式的原始程式碼檔案。

-format=<FORMAT>

使用指定的輸出格式。支援的格式有：「text」、「html」。

-tab-size=<TABSIZE>

在準備報告時，將定位鍵 (tab) 替換為 <TABSIZE> 個空格。目前僅支援 html 格式。

-output-dir=PATH

指定要將覆蓋率報告寫入的目錄。如果目錄不存在，則會建立目錄。當在函式檢視模式中使用（即使用 -name 或 -name-regex 選擇特定函式時），報告會寫入到 PATH/functions.EXTENSION。當在檔案檢視模式中使用時，每個檔案的報告會寫入到 PATH/REL_PATH_TO_FILE.EXTENSION。

-Xdemangler=<TOOL>|<TOOL-OPTION>

指定符號還原工具。這可以用於使報告更易於理解。可以多次指定此選項以將參數提供給還原工具（例如 -Xdemangler c++filt -Xdemangler -n 用於 C++）。預期還原工具會從標準輸入讀取以換行符號分隔的符號列表，並將相同長度的以換行符號分隔的列表寫入標準輸出。

-num-threads=N, -j=N

使用 N 個執行緒來寫入檔案報告（僅在指定 -output-dir 時適用）。當 N=0 時，llvm-cov 會自動偵測要使用的適當執行緒數量。這是預設值。

-compilation-dir=<dir>

用作相對覆蓋率映射路徑基準的目錄。僅在使用 -fcoverage-prefix-map、-fcoverage-compilation-dir 或 -ffile-compilation-dir 編譯二進制文件時適用。

-line-coverage-gt=<N>

僅顯示行覆蓋率大於指定閾值的函式的程式碼覆蓋率。

-line-coverage-lt=<N>

僅顯示行覆蓋率小於指定閾值的函式的程式碼覆蓋率。

-region-coverage-gt=<N>

僅顯示區域覆蓋率大於指定閾值的函式的程式碼覆蓋率。

-region-coverage-lt=<N>

僅顯示區域覆蓋率低於指定閾值的函數的程式碼覆蓋率。

-path-equivalence=<from>,<to>

將覆蓋率數據中的路徑映射到本地原始程式碼檔案路徑。這允許您在一台機器上生成覆蓋率數據，然後在另一台具有相同檔案但路徑不同的機器上使用 llvm-cov。可以傳遞多個 -path-equivalence 參數來指定不同的映射。每個參數都包含一個原始路徑 <from> 及其對應的本地路徑 <to>。映射按指定的順序應用。如果可以將多個映射應用於單一路徑，則使用遇到的第一個映射。

-coverage-watermark=<high>,<low>

設定 html 格式輸出中覆蓋率的高低水位線。這允許您根據需要設定覆蓋率的高低水位線，當覆蓋率 >= 高時為綠色，當覆蓋率 < 低時為紅色，否則為黃色。高和低都應該在 0-100 之間，並且高 > 低。

-debuginfod

使用 debuginfod 查找出現在設定檔中但未出現在命令列上任何物件中的二進制 ID 的覆蓋率映射。如果 debuginfod 已編譯並通過 DEBUGINFOD_URLS 環境變數配置，則預設為 true。

-debug-file-directory=<dir>

提供本地目錄以搜索與設定檔中二進制 ID 對應的物件（與 debuginfod 相同）。預設為系統建置 ID 目錄。

-check-binary-ids

如果在命令列或通過二進制 ID 查找都找不到設定檔中存在的二進制 ID 的物件檔案，則失敗。

REPORT 命令

概要

llvm-cov report [選項] -instr-profile 設定檔 [二進制檔案] [-object 二進制檔案]… [-sources] [原始碼]…

描述

llvm-cov report 命令使用設定檔數據 設定檔 顯示二進制檔案 二進制檔案… 的覆蓋率摘要。可以選擇將其過濾為僅顯示 原始碼… 中列出的檔案的覆蓋率。

BIN 可以是可執行檔、物件檔案、動態程式庫或封存檔（精簡或其他）。

如果沒有提供原始程式碼檔案，則會為覆蓋率數據中的每個檔案打印一個摘要行。如果提供了任何檔案，則如果啟用了 -show-functions 選項，則可以顯示列出檔案中每個函數的摘要。

有關編譯用於覆蓋率的程式和生成設定檔數據的資訊，請參閱 SHOW 命令。

選項

-use-color[=值]

啟用或停用彩色輸出。預設情況下會自動偵測。

-arch=<name>

如果已涵蓋的二進制文件是通用二進制文件，請選擇要使用的架構。 指定通用二進制文件中未包含的架構，或使用與非通用二進制文件不符的架構，都是錯誤的。

-show-region-summary

顯示所有區域的統計信息。 默認為 true。

-show-branch-summary

顯示所有分支條件的統計信息。 默認為 true。

-show-mcdc-summary

顯示 MC/DC 統計信息。 默認為 false。

-show-functions

顯示每個函數的覆蓋率摘要。 默認為 false。

-show-instantiation-summary

顯示所有函數實例化的統計信息。 默認為 false。

-ignore-filename-regex=<PATTERN>

跳過檔案路徑符合指定正規表達式的原始程式碼檔案。

-compilation-dir=<dir>

用作相對覆蓋率映射路徑基準的目錄。僅在使用 -fcoverage-prefix-map、-fcoverage-compilation-dir 或 -ffile-compilation-dir 編譯二進制文件時適用。

-debuginfod

嘗試使用 debuginfod 查找對象的覆蓋率映射。 默認情況下，會嘗試為配置文件中存在但未在命令行上提供的二進制 ID 執行此操作，前提是已編譯 debuginfod 並通過 DEBUGINFOD_URLS 進行配置。

-debug-file-directory=<dir>

提供一個目錄來搜索與配置文件中二進制 ID 相對應的對象。

-check-binary-ids

如果在命令列或通過二進制 ID 查找都找不到設定檔中存在的二進制 ID 的物件檔案，則失敗。

匯出指令

概要

llvm-cov export [選項] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…

描述

llvm-cov export 指令使用配置文件數據 PROFILE 以 JSON 或 lcov 追蹤文件格式匯出二進制文件 BIN… 的覆蓋率數據。

匯出 JSON 時，將匯出覆蓋率數據的區域、函數、分支、擴展和摘要。 匯出 lcov 追蹤文件時，將匯出基於行的覆蓋率、分支覆蓋率和摘要。

可以選擇性地篩選匯出的數據，以便僅匯出 SOURCE… 中列出的文件的覆蓋率。

有關編譯用於覆蓋率的程式和生成設定檔數據的資訊，請參閱 SHOW 命令。

選項

-arch=<name>

如果已涵蓋的二進制文件是通用二進制文件，請選擇要使用的架構。 指定通用二進制文件中未包含的架構，或使用與非通用二進制文件不符的架構，都是錯誤的。

-format=<FORMAT>

使用指定的輸出格式。支援的格式有："text"（JSON）、"lcov"。

-summary-only

僅匯出覆蓋率資料中每個檔案的摘要資訊。此模式不會匯出較小單元的覆蓋率資訊，例如個別函式或區域。結果將包含與 llvm-cov report 命令產生的資訊相同，但以 JSON 或 lcov 格式呈現，而不是文字。

-ignore-filename-regex=<PATTERN>

跳過檔案路徑符合指定正規表達式的原始程式碼檔案。

-skip-expansions

略過匯出巨集展開覆蓋率資料。

-skip-functions

略過匯出每個函式的覆蓋率資料。

-num-threads=N, -j=N

使用 N 個執行緒來匯出覆蓋率資料。當 N=0 時，llvm-cov 會自動偵測要使用的適當執行緒數量。這是預設值。

-compilation-dir=<dir>

用作相對覆蓋率映射路徑基準的目錄。僅在使用 -fcoverage-prefix-map、-fcoverage-compilation-dir 或 -ffile-compilation-dir 編譯二進制文件時適用。

-debuginfod

嘗試使用 debuginfod 查找對象的覆蓋率映射。 默認情況下，會嘗試為配置文件中存在但未在命令行上提供的二進制 ID 執行此操作，前提是已編譯 debuginfod 並通過 DEBUGINFOD_URLS 進行配置。

-debug-file-directory=<dir>

提供一個目錄來搜索與配置文件中二進制 ID 相對應的對象。

-check-binary-ids

如果在命令列或通過二進制 ID 查找都找不到設定檔中存在的二進制 ID 的物件檔案，則失敗。

CONVERT-FOR-TESTING 命令

警告

此命令僅供正在開發 llvm-cov 的 LLVM 開發人員使用。

語法

llvm-cov convert-for-testing BIN -o OUT

說明

llvm-cov convert-for-testing 命令用於測試 llvm-cov 本身。它可以從二進位檔案 BIN 中提取所有程式碼覆蓋率資料到檔案 OUT 中，從而減少測試檔案的大小。輸出檔案通常帶有 .covmapping 副檔名。

llvm-cov 可以像讀取普通二進位檔案一樣讀取 .covmapping 檔案。