llvm-cov - カバレッジ情報の発行

概要

llvm-cov コマンド [引数...]

説明

llvm-cov ツールは、プロファイルデータを発行するようにインストルメントされたプログラムのコードカバレッジ情報を表示します。これは、gcov スタイルのカバレッジや、clang のインストルメンテーションベースのプロファイリングで利用できます。

プログラムが gcov のベース名で呼び出された場合、llvm-cov gcov コマンドが呼び出されたかのように動作します。それ以外の場合は、コマンドを指定する必要があります。

コマンド

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 変数からのプレフィックスが追加されます。これらの環境変数を使用すると、元のオブジェクトファイルディレクトリにアクセスできないマシンでインストルメントされたプログラムを実行できますが、その後、llvm-cov gcov がそれらを見つけるために使用するオブジェクトファイルディレクトリに .gcda ファイルをコピーして戻す必要があります。

カバレッジデータファイルを生成したら、カバレッジ結果を確認したいメインソースファイルごとに llvm-cov gcov を実行します。これは、以前にコンパイラを実行した同じディレクトリから実行する必要があります。指定されたソースファイルの結果は、.gcov サフィックスを付加した名前のファイルに書き込まれます。メインソースファイルに含まれている各ファイルに対しても、.gcov サフィックスが追加された個別の出力ファイルが作成されます。

.gcov 出力ファイルの基本的な内容は、ソースファイルのコピーであり、すべての行に実行回数と行番号が先頭に追加されます。行に実行可能コードが含まれていない場合、実行回数は - として表示されます。行にコードが含まれているが、そのコードが一度も実行されなかった場合、回数は ##### として表示されます。

オプション

-a, --all-blocks

すべての基本ブロックを表示します。単一のソースコード行に複数のブロックがある場合、このオプションを使用すると、llvm-cov は行全体の 1 つのカウントだけではなく、各ブロックのカウントを表示します。

-b, --branch-probabilities

条件分岐の確率と分岐情報の概要を表示します。

-c, --branch-counts

確率の代わりに分岐回数を表示します（-b が必要です）。

-m, --demangled-names

関数名をデマングルします。

-f, --function-summaries

ソースファイル全体のサマリーを1つ表示する代わりに、関数ごとのカバレッジのサマリーを表示します。

--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

.gcov ファイルを作成する代わりに、標準出力に出力します。

-u, --unconditional-branches

–branch-probabilitiesオプションの出力に無条件分岐を含めます。

-version

llvm-cov のバージョンを表示します。

-x, --hash-filenames

カバレッジ出力ファイルの名前を付ける際に、ファイル名のMD5ハッシュを使用します。ソースファイル名には、## に続けて、計算されたMD5ハッシュがサフィックスとして付加されます。

終了ステータス

llvm-cov gcov は、入力ファイルを読み取れない場合は 1 を返します。それ以外の場合は、ゼロで終了します。

show コマンド

概要

llvm-cov show [options] -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

各行の実行回数を表示します。別の -show オプションが使用されない限り、デフォルトは true です。

-show-expansions

プリプロセッサマクロやテキストインクルージョンなどのインクルージョンをソースファイルの表示にインラインで展開します。デフォルトは false です。

-show-instantiations

C++ のテンプレートのように、複数回インスタンス化されるソース領域の場合、結合された概要だけでなく、各インスタンス化を個別に表示します。デフォルトは true です。

-show-regions

領域が開始する文字を指すキャレットを表示して、各領域の実行回数を表示します。デフォルトは false です。

-show-line-counts-or-regions

行に領域が1つしかない場合は各行の実行回数を表示しますが、行に複数の領域がある場合は個々の領域を表示します。デフォルトは false です。

-show-directory-coverage

少なくとも1つのソースファイルを含む各ディレクトリに、集計を示す最上位のインデックスを持つインデックスファイルを生成します。デフォルトは 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>

レポートを準備する際に、タブを <TABSIZE> 個のスペースに置き換えます。現在、これは html 形式でのみサポートされています。

-output-dir=PATH

カバレッジレポートを書き込むディレクトリを指定します。ディレクトリが存在しない場合は作成されます。関数ビューモード（つまり、特定の関数を選択するために -name または -name-regex が使用される場合）で使用すると、レポートは PATH/functions.EXTENSION に書き込まれます。ファイルビューモードで使用すると、ファイルごとのレポートが PATH/REL_PATH_TO_FILE.EXTENSION に書き込まれます。

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

シンボルデマングラーを指定します。これは、レポートをより人間が読みやすいものにするために使用できます。このオプションは、デマングラーに引数を渡すために複数回指定できます（例：C++の場合は-Xdemangler c++filt -Xdemangler -n）。デマングラーは、標準入力から改行で区切られたシンボルリストを読み込み、同じ長さの改行で区切られたリストを標準出力に書き出す必要があります。

-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>で構成されます。マッピングは、指定された順序で適用されます。1つのパスに複数のマッピングを適用できる場合、最初に見つかったマッピングが使用されます。

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

HTML形式の出力で、カバレッジの高および低ウォーターマークを設定します。これにより、カバレッジの高および低ウォーターマークを必要に応じて設定できます。カバレッジが>=高の場合に緑、カバレッジが<低の場合に赤、それ以外の場合は黄色になります。高と低の両方は0〜100の間で、高>低である必要があります。

-debuginfod

debuginfodを使用して、プロファイルに存在するがコマンドラインで指定されたどのオブジェクトにもないバイナリIDのカバレッジマッピングを検索します。debuginfodがコンパイルされていて、DEBUGINFOD_URLS環境変数を介して構成されている場合は、デフォルトでtrueになります。

-debug-file-directory=<dir>

（debuginfodと同様に）プロファイル内のバイナリIDに対応するオブジェクトを検索するためのローカルディレクトリを提供します。デフォルトは、システムのビルドIDディレクトリです。

-check-binary-ids

プロファイルに存在するバイナリIDのオブジェクトファイルが、コマンドラインでもバイナリIDルックアップでも見つからない場合に失敗します。

REPORT コマンド

概要

llvm-cov report [options] -instr-profile PROFILE [BIN] [-object BIN]… [-sources] [SOURCE]…

説明

llvm-cov report コマンドは、プロファイルデータPROFILEを使用して、バイナリBIN…のカバレッジの概要を表示します。オプションで、SOURCE…にリストされたファイルのカバレッジのみを表示するようにフィルタリングできます。

BIN は、実行可能ファイル、オブジェクトファイル、動的ライブラリ、またはアーカイブ（シンまたはそれ以外）である可能性があります。

ソースファイルが指定されていない場合、カバレッジデータ内の各ファイルに対して概要行が出力されます。ファイルが指定されている場合、-show-functionsオプションが有効になっている場合は、リストされたファイル内の各関数の概要を表示できます。

カバレッジ用のプログラムのコンパイルとプロファイルデータの生成の詳細については、SHOW コマンドを参照してください。

オプション

-use-color[=VALUE]

カラー出力を有効または無効にします。デフォルトでは、これは自動検出されます。

-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を使用して、オブジェクトからカバレッジマッピングを検索しようとします。これは、debuginfodがコンパイルされていて、DEBUGINFOD_URLSを介して構成されている限り、プロファイルに存在するがコマンドラインで提供されないバイナリIDに対してデフォルトで試行されます。

-debug-file-directory=<dir>

プロファイル内のバイナリIDに対応するオブジェクトを検索するためのディレクトリを提供します。

-check-binary-ids

プロファイルに存在するバイナリIDのオブジェクトファイルが、コマンドラインでもバイナリIDルックアップでも見つからない場合に失敗します。

EXPORT コマンド

概要

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

説明

llvm-cov export コマンドは、プロファイルデータPROFILEを使用して、バイナリBIN…のカバレッジデータをJSONまたはlcovトレースファイル形式でエクスポートします。

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を使用して、オブジェクトからカバレッジマッピングを検索しようとします。これは、debuginfodがコンパイルされていて、DEBUGINFOD_URLSを介して構成されている限り、プロファイルに存在するがコマンドラインで提供されないバイナリIDに対してデフォルトで試行されます。

-debug-file-directory=<dir>

プロファイル内のバイナリIDに対応するオブジェクトを検索するためのディレクトリを提供します。

-check-binary-ids

プロファイルに存在するバイナリIDのオブジェクトファイルが、コマンドラインでもバイナリIDルックアップでも見つからない場合に失敗します。

テスト用変換コマンド

警告

このコマンドは、llvm-cov の開発に携わっている LLVM 開発者のみを対象としています。

概要

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

説明

llvm-cov convert-for-testing コマンドは、llvm-cov 自体をテストする目的で使用されます。バイナリ BIN からすべてのコードカバレッジデータをファイル OUT に抽出することで、テストファイルのサイズを削減できます。出力ファイルには通常、.covmapping という拡張子が付きます。

.covmapping ファイルは、通常のバイナリファイルと同様に llvm-cov で読み込むことができます。