コードカバレッジ・ツール

コードカバレッジ・ツールの要件

コードカバレッジ・ツールをアプリケーションで実行するには、次のファイルが必要です。

• アプリケーションのソース。

• -prof-gen=srcpos (Linux* および macOS*) または /Qprof-gen:srcpos (Windows*) オプションを使用してインストルメント済みバイナリー用にアプリケーションをコンパイルしたときに、インテル® コンパイラーによって生成される .spi ファイル。

  注

  収集されたデータをコードカバレッジ・ツールとプロファイル・フィードバックに使用する場合、[Q]prof-gen:srcpos オプションを使用します。インストルメンテーションをコードカバレッジ・ツールにのみ使用する場合は、/Qcov-gen オプションを使用します。/Qcov-gen オプションは時間を節約し、パフォーマンスを向上します。このオプションは、すべてのアーキテクチャーの Windows* でのみ利用可能です。

• profmerge ツールによって最も簡単に生成される、動的プロファイル情報 (.dyn) ファイルをマージした結果を含む pgopti.dpi ファイル。このファイルは、.dyn および .dpi ファイルと一緒に [Q]prof-use オプションを使用してアプリケーションをコンパイルする場合にも、インテル® コンパイラーによって暗黙的に生成されます。

ツールの使用

ツールの構文は、次のとおりです。

-codecov_option は、ツールに渡すツールオプションを指定する 1 つ以上のオプションの引数です。利用可能なツールオプションは、コードカバレッジ・ツールのオプションにリストされています。追加のツールオプションを使用しない場合、ツールはアプリケーション全体についてトップレベルのコードカバレッジを出力します。

一般に、コードカバレッジ・ツールを使用するには次のステップを実行する必要があります。

1. -prof-gen=srcpos (Linux* および macOS*) または /Qprof-gen:srcpos オプション (Windows*)、/Qcov-gen オプション (Windows*) を使用してアプリケーションをコンパイルします。

   このステップは、-[Q]prof-gen=srcpos オプションが使用されると、インストルメント済み実行ファイルおよび対応する静的プロファイル情報 (pgopti.spi) ファイルを生成します。/Qcov-gen オプションが使用されると、コードカバレッジ・ツール用のみの最小限のインストルメンテーションと .spi ファイル生成が有効になります。

   注

   コマンドラインで /Qprof-gen=srcpos と /Qcov-gen の両オプションを指定できます。.spi ファイルを生成するプロファイル・オプションとともに、プロファイル・フィードバックに必要なより高いレベルのインストルメンテーションが有効になります。コマンドラインで指定された順序は関係ありません。

2. インストルメント済みアプリケーションを実行します。

   このステップは、動的プロファイル情報 (.dyn) ファイルを生成します。インストルメント済みアプリケーションを実行するたびに、コンパイラーは、現在のディレクトリー、-prof-dir (Linux* および macOS*) または /Qprof-dir (Windows*) オプション、または PROF_DIR 環境変数で指定されたディレクトリーに一意の .dyn ファイルを生成します。Windows* では、/Qcov-dir または COV_DIR 環境変数を使用することもできます。これらは、/Qprof-dir および PROF_DIR と同じ効果があります。

3. profmerge ツールを使用して、すべての .dyn ファイルを 1 つの .dpi (pgopti.dpi) ファイルにマージします。

   このステップは、アプリケーションのすべての実行から結果を結合して合計のプロファイル情報を表示し、最適化されたバイナリーを生成して、コードカバレッジ・ツールで必要な .dpi ファイルを作成します。

   profmerge ツールを使用すると、アプリケーションをコンパイルしないで、.dyn ファイルを .dpi ファイルにマージできます。profmerge ツールは、profmerge -a オプションを使用して複数の .dpi ファイルを 1 つの .dpi ファイルにマージし、profmerge -prof_dpi オプションを使用して、出力 .dpi ファイルの名前を選択します。

   注意

   profmerge ツールは指定されたディレクトリーに存在するすべての .dyn ファイルをマージします。無関係な .dyn ファイルが存在していないことを確認してください。無関係な .dyn ファイルが存在していると、プロファイル情報に無効なプロファイル・データが含まれてしまいます。この結果、不適切なカバレッジ情報が生成され、最適化されたコードのパフォーマンスに悪影響を与えることがあります。

4. コードカバレッジ・ツールを実行します。有効な構文とツールオプションは次のとおりです。

   このステップは、指定されたようにレポートまたはエクスポートされたデータを作成します。他のオプションが指定されていない場合、コードカバレッジ・ツールは、現在のディレクトリーに 1 つの HTML ファイル (CODE_COVERAGE.HTML) とサブディレクトリー (CodeCoverage) を生成します。このファイルを Web ブラウザーで開いてレポートを確認します。

コードカバレッジ・ツールは、プロジェクトを指定して、特定の必要なファイルへのパスを指定できます。次に、プロジェクトを指定して、使用する .dpi および .spi ファイルを設定する例を示します。

ツールには、宛先を追加して、各 HTML ページの最後にその宛先に電子メールを送信するリンクを生成するオプションもあります。このオプションにより、指定された宛先に電子メールを送信できます。次に、宛先を指定して、電子メールを送信するリンクを追加する例を示します。

次に、プロジェクト名、動的プロファイル情報ファイル、そして出力形式とファイル名を指定する方法を示します。

コードカバレッジ・ツールのオプション

C:> ifort -Qprof-gen:srcpos -Qprof-src-root c:\workspaces\orig_project_dir test1.f90 test2.f90
C:> test1.exe
C:> profmerge
C:> cd \workspaces\
C:> mv orig_project_dir new_project_dir
C:> cd new_project_dir\src
C:> codecov -srcroot C:\workspaces\new_project_dir

アプリケーションのコードカバレッジのビジュアルな表示

アプリケーションをテストするときにインストルメント済みバイナリーを実行して集められたプロファイル情報を基に、インテル® コンパイラーはコードカバレッジ・ツールを使用して HTML 形式のレポートを作成します。これらのレポートは、テストによって実行された (実行されなかった) ソースコードの部分を示します。パフォーマンス・ワークロードのプロファイルが適用されると、コードカバレッジ情報は実行されたワークロードがアプリケーションの重要なコードをどの程度カバーするかを示します。プロファイルに基づく最適化の利点を完全に受けるためには、パフォーマンス・クリティカルなモジュールの高いカバレッジが必要です。

コードカバレッジ・ツールは、2 つのレベルのカバレッジを作成できます。

• トップレベル (選択されたモジュールのグループ)

• 個々のモジュール・ソース・ビュー

トップレベルのカバレッジ

トップレベルのカバレッジは選択されたモジュールのコードカバレッジ全体をレポートします。次のオプションがあります。

• 処理するモジュールを選択します。

• 選択されたモジュールについて、ツールはモジュールとそのカバレッジ情報のリストを生成します。情報には、モジュールにある関数とブロックの総数、カバーされた部分が含まれます。

• レポートされた表でカラムのタイトルをクリックすると、リストが次の項目に基づいて昇順または降順でソートされます。

  • 基本ブロックカバレッジ

  • 関数カバレッジ

  • 関数名

デフォルトでは、コードカバレッジ・ツールは、現在のディレクトリーに 1 つの HTML ファイル (CODE_COVERAGE.HTML) およびサブディレクトリー (CodeCoverage) を生成します。HTML ファイルは、他に生成されたすべてのレポートを表示するためのフレームセットを定義します。HTML ファイルは Web ブラウザーで開きます。ツールは、他に生成されたすべてのレポートファイルを CodeCoverage サブディレクトリーに保存します。

HTML 形式のレポートを生成した場合、ブラウザーからその特定モジュールのソースを直接表示できます。次の図は、トップレベルのカバレッジレポートを示したものです。

コードカバレッジ・ツールは、カバーされなかったコードが容易に識別できるように、フレームセットを作成します。上のフレームにはカバーされなかった関数のリストが、下のフレームにはカバーされた関数のリストがそれぞれ表示されます。カバーされなかった関数については、各関数の基本ブロックの総数も表示されます。カバーされた関数については、ブロックの総数とカバーされたブロックの数、その比率 (つまり、カバレッジ率) が表示されます。

例えば、66.67(4/6) は、対応する関数の 6 つのブロックのうち 4 つのブロックがカバーされたことを示します。関数のブロックカバレッジ率は 66.67% になります。これらのリストは、カバレッジ率、ブロック数、関数名でソートできます。関数名はソースビューで関数が開始する位置とリンクされています。ワンクリックで、リストで最もカバーされなかった関数を確認できます。再度クリックすると、関数本体が表示されます。ソースビューでスクロールして関数のソースを参照できます。

個々のモジュール・ソース・ビュー

個々のモジュール・ソース・ビューで、ツールはカバーされなかった関数のリストとカバーされた関数のリストを表示します。リストは、ソースコードを容易に参照できるように、2 つの別々のフレームに表示されます。リストは、次の項目でソートできます。

• カバーされなかった関数内のブロックの数

• カバーされた関数のブロックカバレッジ

• 関数名

コードカバレッジ用の配色の設定

ツールは、カバレッジカテゴリーを、カバーされたコード、カバーされなかった基本ブロック、カバーされなかった関数、一部カバーされたコード、および不明なコードに色分けします。カバレッジ情報を示すためにツールが使用するデフォルト色を、次の表に示します。

デフォルト色は、上記の表の各カバレッジカテゴリーで説明されているオプションを使用して、任意の HTML カラーまたは 16 進数の値にカスタマイズできます。

コードカバレッジ・プレゼンテーションでは、コードカバレッジ・ツールは次のヒューリスティックを使用します。ソース文字は、プロファイル情報によって基本ブロックの先頭として示されたソースの位置に達するまでスキャンされます。その基本ブロックのプロファイル情報でカバレッジのカテゴリーが変わったことが示されると、ツールはコードのその部分のカバレッジ条件に対応して色を変更し、カバレッジツールは HTML 形式のレポートファイルに適切なタグを挿入します。

動的カウンター

コードカバレッジ・ツールは、動的実行カウントに関する情報を生成するように設定できます。この機能は、アプリケーションの各基本ブロックの動的実行カウントを表示し、カバレッジおよびパフォーマンスの調整に役立ちます。

カスタム設定を行うには、-counts オプションを使用します。カウント情報は、対応する基本ブロックが開始するソースの位置で、"^" 記号の後のコードで正確に表示されます。

そのソースの位置でコードに複数の基本ブロックが生成される場合 (例えば、マクロ)、そのようなブロックの総数と実行されたブロックの総数が実行カウントの前に表示されます。例えば、コードの行 11 は if 文です。

11  if ((N == 1).OR. (N == 0))
     ^ 10 (1/2) 
12      printf("%d\n", N)
        ^

行 11 と 12 のカバレッジ行には次の情報が含まれています。

• 行 11 の IF 文は 10 回実行された。

• 行 11 の IF 文に対して 2 つの基本ブロックが生成された。

• これら 2 ブロックのうち 1 つだけが実行されているため、部分的なカバレッジの色で表示される。

• 10 回のうち 7 回のみ、変数 n が 0 または 1 の値となった。

特定の状況では、1 つのソースの位置用に生成されたすべてのブロックを 1 つのエンティティーとして考慮する必要があります。この場合、少なくとも 1 つのブロックがカバーされたのであれば、1 つのソースの位置用に生成されたすべてのブロックがカバーされたと仮定する必要があります。仮定するには、-nopartial オプションを使用します。このオプションが指定されれば、カバレッジの決定は無効になり、関連する統計がそれに従って調節されます。コードの 11 行目および 12 行目は、12 行目の PRINT 文がカバーされたことを示しています。しかし、11 行目の条件の 1 つのみが常に真であったとします。-nopartial オプションを使用すると、ツールは (11 行目のコードのように) 一部がカバーされたコードを完全にカバーされたコードとして扱います。

差分カバレッジ

コードカバレッジ・ツールを使用すると、アプリケーションの 2 つの実行 (リファレンス実行と新規実行) を比較して、新規実行ではカバーされるがリファレンス実行ではカバーされないコードを識別できます。この機能は、アプリケーションのテストではカバーされないが、カスタマーによって起動された際に実行されるアプリケーションのコードの部分を見つけるために使用できます。また、アプリケーションのテストスペースに新しく追加されたテストのインクリメンタル・カバレッジの影響を探すためにも使用できます。

リファレンス・データの生成

-ref オプションを使用して、リファレンス・データの動的プロファイル情報を作成します。この情報は、後でレポートする差分カバレッジで使用できます。次に、リファレンス・データを生成する一般的なコマンドを示します。

差分カバレッジのカバレッジ統計は、新規実行で実行され、リファレンス実行で実行されなかったコードの比率をパーセントで表示します。この場合、ツールはカバーされなかったコードを含むモジュールのみを表示します。ソースビューで配色を表示する場合は、この点に注意してください。

コードが両方の実行で同じカバレッジ・プロパティー (カバーされたまたはカバーされなかった) の場合、コードはカバーされたコードとして扱われます。コードが新規実行でカバーされ、リファレンス実行でカバーされなかった場合、コードはカバーされなかったコードとして扱われます。また、コードがリファレンス実行でカバーされ、新規実行でカバーされなかった場合、差分カバレッジのソースビューはコードをカバーされたコードとして表示します。

差分カバレッジ用の実行

コードカバレッジ・ツールを差分カバレッジ用に実行するには、アプリケーション・ソース、.spi ファイル、および .dpi ファイルが必要です (上記のコードカバレッジ・ツールの要件セクションを参照)。

必要なファイルが準備できたら、次のようなコマンドを入力して、差分カバレッジ解析を開始します。

-spi および -dpi オプションを使用して .dpi ファイルと .spi ファイルを指定します。

カバレッジ解析からのコードの除外

コードカバレッジ・ツールは、カバレッジ解析からコードの一部を除外できます。この機能は、例えば、コードの特定の部分にデバッグでのみ使用される関数が含まれている場合に役立ちます。テストケースには、最終的なアプリケーションで利用できない機能のテストを含めるべきではありません。

除外できるコードの別の例として、アプリケーションで発生しそうもない内部エラーに対処するコードがあります。この場合、テストケースが不足していることが前提となります。カバレッジ解析で実行されない (デッド) コードは無視してもかまいません。コードカバレッジ・ツールは、コードが実行されない (デッドな) 部分をマークして、ファイルレベル、関数レベル、およびユーザー固有のコメントによって示された任意のコード境界でコードを無視するいくつかのオプションを提供します。次のセクションでは、さまざまなレベルでコードを除外する方法を説明します。

ファイルレベルでのカバレッジの追加と除外

コードカバレッジ・ツールは、解析するファイルを選択的に追加または除外できます。コンポーネント・ファイルを作成して、追加または除外するコードのファイル名およびディレクトリー名を示す適切な文字列値を追加します。-comp オプションの引数としてファイル名を渡します。次に、一般的なコマンドの例を示します。

file は、テキストファイル名です。このファイルで指定された文字列が名前に含まれる場合、そのファイル/ディレクトリーはファイルレベルの解析で追加/除外されます。例えば、次のように仮定します。

• ファイル名またはディレクトリー名に文字列 "source" を含むすべてのファイルを追加します。

• 名前に文字列 "source" を含むファイル/ディレクトリーを追加するように指定した、myComp.txt という名前のコンポーネント・テキスト・ファイルを作成します。

コンポーネント・ファイルを作成したら、次のようなコマンドを入力します。

この例では、名前に文字列 "source" を含むファイル (例えば、source1.c や source2.c) と名前に文字列 "source" を含むディレクトリーにあるすべてのファイル (例えば、source/file1.c や source2\file2.c ) が解析されます。

ファイル/ディレクトリーを解析から除外するには、文字列の先頭にチルダ (~) を追加します。同じファイルで追加と除外を指定できます。例えば、名前に文字列 "source" を含むすべてのファイルおよびディレクトリー解析し、文字列 "skip" を含むすべてのファイルおよびディレクトリーを解析から除外する場合、コンポーネント・ファイル (myComp.txt) に次のような文字列を追加して、-comp オプションに渡します。

codecov -comp myComp.txt コマンドを実行すると、myComp.txt は codecov ツールに次のことを指示します。

• 名前に文字列 "source" を含むファイル (例えば、source1.c や source2.c) を解析に追加します。

• 名前に文字列 "source" を含むディレクトリーにあるすべてのファイル (例えば、source/file1.c や source2\file2.c) を解析に追加します。

• 名前に文字列 "skip" を含むファイル (例えば、skipthis1.c や skipthis2.c) を解析から除外します。

• 名前に文字列 "skip" を含むディレクトリーにあるすべてのファイル (例えば、skipthese1\debug1.c や skipthese2\debug2.c) を解析から除外します。

行レベルおよび関数レベルでのカバレッジの除外

-onelinedsbl オプションに文字列値を渡すことで、除外する個々の行をマークできます。例えば、次のようなコードがあると仮定します。

printf ("internal error 123 - please report!\n");  // NO_COVER 
printf ("internal error 456 - please report!\n");  /* INF IA-32 アーキテクチャー */

NO_COVER コメントや INF IA-32 architecture コメント付きのすべての関数を除外するには、次のようなコマンドを入力します。

複数の除外文字列を同時に指定できます。また、マーカーに対して任意の文字列値を指定できます。しかし、このオプションを使用するときは、次のガイドラインに沿っていることを確認してください。

• インラインコメントは、文の最後になければなりません。

• 文字列は、インラインコメントの一部でなければなりません。

同じ方法を使用して関数全体をカバレッジ解析から除外できます。例えば、上記のコマンドを発行すると、カバレッジ解析から次の関数が除外されます。

void dumpInfo (int n) 
{      // NO_COVER 
... 
}

さらに、-onelinedsbl および -xcolor オプションを組み合わせることで、任意の HTML カラーコードで実行されないコードに色を付けることができます。 次に、オプションを組み合わせた例を示します。

任意の境界の定義によるコードの除外

コードカバレッジ・ツールには、カバレッジ解析から任意のコードを除外する機能があります。この機能は、関数の内部または複数の関数の範囲にわたって発生するコードの除外に役立ちます。

-beginblkdsbl および -endblkdsbl オプションを使用して、解析から除外するように定義する任意の境界の始まりと終わりをそれぞれマークします。これらのオプションを使用するときは、次のガイドラインに沿っていることを確認してください。

• インラインコメントは、文の最後になければなりません。

• 文字列は、インラインコメントの一部でなければなりません。

例えば、次のコードがあると仮定します。

void div (int m, int n) { 
if (n == 0) 
/* BEGIN_INF */ 
{ printf (internal error 314 please report\n); 
recover (); } 
/* END_INF */ 
else { ... } 
} 
... 
// BINF 
Void recover () { ... } 
// EINF

次に、-beginblkdsbl オプションおよび -endblkdsbl オプションを使用して、上記のサンプルから除外するコードの始まりと終わりをマークするコマンドの例を示します。

これらのオプションは -xcolor オプションと組み合わせて使用できる点に注意してください。

カバレッジデータのエクスポート

コードカバレッジ・ツールは、さまざまなワークロードでインストルメント済みアプリケーションを実行して生成される動的プロファイル情報 (.dpi) ファイルからカバレッジデータを抽出する特定のオプションを提供します。ツールは、後処理およびデータベースへのロード用に各種 (デフォルト HTML、テキスト、XML) の形式でカバレッジデータをエクスポートできます。エクスポートは、関数および基本ブロックレベルでデータを選択できます。

データのエクスポートには、クイック・エクスポートと結合エクスポートの 2 つの基本的な方法があります。各方法は、ツールでサポートされているオプションと関連付けられています。

• クイック・エクスポート: 1 つ目の方法は、デフォルトの HTML レポートを生成しないで、カバレッジデータをテキストまたは XML 形式のファイルにエクスポートします。この方法では、アプリケーションのソースは必要ありません。コードカバレッジ・ツールは、レポートを作成して、実行されたアプリケーションの一部についてのみ統計を提供します。解析およびレポート生成が素早く行われるため、個々のテストのプロファイルまたはすべてのテストをマージしたプロファイルにツールを適用する代わりに、指定されたテストスペースで、すべてのテストケースの動的プロファイル情報 (.dpi ファイル) にカバレッジツールを実際に適用できます。-xmlfcvrg、-txtfcvrg、-xmlbcvrg および -txtbcvrg オプションは、1 つ目の方法をサポートします。

• 結合エクスポート: 2 つ目の方法は、デフォルトの HTML レポートを生成して、同時にカバレッジデータをテキストまたは XML 形式のファイルにエクスポートします。この方法は、アプリケーションのソースを解析してレポートを生成するため、1 つ目の方法よりも遅くなります。-xmlbcvrgfull および -txtbcvrgfull オプションは、2 つ目の方法をサポートします。

これらのエクスポート方法は、コードカバレッジ・ツールから一貫した形式のレポートを出力することで、コードカバレッジのレポート機能を素早く拡張する手段を提供します。

クイック・エクスポート

アプリケーションのカバーされた関数のプロファイルは、-xmlfcvrg、-txtfcvrg、-xmlbcvrg、および -txtbcvrg オプションを使用して素早くエクスポートできます。これらのオプションを使用する場合、カバレッジレポートの出力ファイルを指定します。例えば、XML 形式でカバーされた関数のレポートを生成するには、次のようなコマンドを入力します。

生成されるレポートは、カバーされたブロックの数および各関数のブロックカバレッジと一緒に、各関数が実行された回数および各関数のブロックの総数を示します。次に、一般的な XML レポートの内容のいくつかを示します。

<PROJECT name = "test1">
   <MODULE name = "D:\SAMPLE.C">
      <FUNCTION name="f0" freq="2">
         <BLOCKS total="6" covered="5" coverage="83.33%"></BLOCKS>
      </FUNCTION>
      ...
   </MODULE>
   <MODULE name = "D:\SAMPLE2.C">
      ...
   </MODULE> 
</PROJECT>

上記の例では、ファイル sample.c で定義されている関数 f0 が 2 回実行されていることが分かります。全部で 6 つの基本ブロックがあり、そのうち 5 つのブロックが実行されています。これは基本ブロックカバレッジの 83.33% にあたります。

-txtfcvrg オプションを使用してテキスト形式でデータをエクスポートすることもできます。上記の例に対してこのオプションを使用すると、次のようなテキスト形式のレポートが生成されます。

Covered Functions in File: "D:\SAMPLE.C" 
"f0"    2       6       5        83.33 
"f1"    1       6       4        66.67 
"f2"    1       6       3        50.00 
...

テキスト形式のレポートの各行は、次の方法で情報を示します。

ツールは、-xmlbcvrg オプションを使用したブロックレベルのカバレッジデータのエクスポートもサポートしています。例えば、XML 形式でカバーされたブロックのレポートを生成するには、次のようなコマンドを入力します。

上記のコマンドは、次のような XML 形式のレポートを生成します。

<PROJECT name = "test1">
  <MODULE name = "D:\SAMPLE.cpp">
    <FUNCTION name="f0" freq="2">
    ...
      <BLOCK line="11" col="2">
        <INSTANCE id="1" freq="1"> </INSTANCE>
      </BLOCK>
      <BLOCK line="12" col="3">
        <INSTANCE id="1" freq="2"> </INSTANCE>
        <INSTANCE id="2" freq="1"> </INSTANCE>
      </BLOCK>

サンプルレポートでは、ファイル sample.cpp の行 11、列 2 の関数 f0 のコードに 1 つの基本ブロックが生成されたことが分かります。このブロックは、1 回だけ実行されています。また、ファイルの行 12、列 3 から開始するコードに 2 つの基本ブロックが生成されたことも分かります。これらのブロックのうち、id = 1 のブロックは、別のブロックが 1 回実行される間に 2 回実行されています。-txtbcvrg オプションを使用すると、テキスト形式で同様のレポートが生成されます。

結合エクスポート

コードカバレッジ・ツールは、デフォルトの HTML レポートを生成すると同時に、カバレッジデータをテキストまたは XML 形式のファイルにエクスポートすることもできます。

1 回の実行でサポートされているすべての形式のレポートを生成するには、-xmlbcvrgfull および -txtbcvrgfull オプションを使用します。これらのオプションは、HTML レポートを生成すると同時に、基本ブロックレベルのカバレッジデータをエクスポートします。これらのオプションは、全く実行されなかった関数の解析を含む、より完全なレポートを生成します。しかし、これらのレポートを使用してカバレッジデータをエクスポートするには、アプリケーションのソースファイルへアクセスする必要があります。また、実行も非常に長くなります。

動的コールグラフ

-txtdcg オプションを使用すると、ツールによりアプリケーションの動的コールグラフについての情報を参照できます。動的コールグラフ・レポートの出力ファイルを指定します。出力されたコールグラフ・レポートには、アプリケーション・レベル、モジュールレベル、関数レベルでの静的呼び出しおよび動的呼び出し (直接、間接、仮想) についての情報が含まれます。