インテル® C++ コンパイラー 19.0 デベロッパー・ガイドおよびリファレンス
コードカバレッジ・ツールは、ソフトウェア開発者に、特定のワークロードをアプリケーションに適用した場合にどのくらいのアプリケーション・コードが実行されるかについて情報を提供します。使用するコードを決定するために、コードカバレッジ・ツールは、プロファイルに基づく最適化 (PGO) オプションと最適化手法を使用します。コードカバレッジ・ツールの主な特徴は次のとおりです。
カスタマイズ可能なコードカバレッジ配色で、アプリケーションのコードカバレッジ情報をビジュアルに表示します。
アプリケーションの各基本ブロックの動的実行カウントを表示します。
2 つの異なるアプリケーション実行のプロファイル・データの差分カバレッジまたは比較を提供します。
コードカバレッジ・ツールの使用方法については、次の個別のセクションをそれぞれ参照してください。
ツールは、コンパイラーによって生成される静的プロファイル情報と、ワークロードでインストルメント済みアプリケーションのバイナリーを実行して生成される動的プロファイル情報を解析します。ツールは、HTML 形式でレポートを生成し、カバレッジデータをテキストおよび XML 形式のファイルにエクスポートできます。レポートは、色分け、アノテーション付きのソースコード一覧で、使用されたコードと未使用のコードを識別して表示するようにカスタマイズできます。
コードカバレッジ・ツールは、サポートされるすべてのインテル® アーキテクチャー (Linux* および Windows*、macOS*) で利用できます。
さまざまな方法でツールを使用して、開発効率を改善し、問題を減らして、アプリケーションのパフォーマンスを向上させます。
プロジェクトのテストフェーズ中に、ツールは、どのくらいのコードが実際にテストされたかを示すことで、テストの全体的な性能を測定します。
パフォーマンス・ワークロードのプロファイルが適用されると、コードカバレッジ・ツールはワークロードがアプリケーションの重要なコードをどの程度カバーするかを示します。インテル® コンパイラーが提供するプロファイルに基づく最適化の利点を完全に受けるためには、パフォーマンス・クリティカルなモジュールの高いカバレッジが必要です。
ツールは、アプリケーションの各基本ブロックの動的実行カウントを表示できるオプションを提供します。これは、カバレッジとパフォーマンス・チューニングの両方で役立ちます。
コードカバレッジ・ツールは、2 つの異なるアプリケーション実行のプロファイルを比較できます。この機能は、テスト中はカバーされないが、アプリケーションがテストスペース外で使用された場合 (例えば、カスタマーによって使用された場合) に実行される、アプリケーションのコードの部分を見つけるのに使用できます。
コードカバレッジ・ツールをアプリケーションで実行するには、次のファイルが必要です。
アプリケーションのソース。
-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 [-codecov_option] |
-codecov_option は、ツールに渡すツールオプションを指定する 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 ファイルを生成するプロファイル・オプションとともに、プロファイル・フィードバックに必要なより高いレベルのインストルメンテーションが有効になります。コマンドラインで指定された順序は関係ありません。
インストルメント済みアプリケーションを実行します。
このステップは、動的プロファイル情報 (.dyn) ファイルを生成します。インストルメント済みアプリケーションを実行するたびに、コンパイラーは、現在のディレクトリー、-prof-dir (Linux* および macOS*) または /Qprof-dir (Windows*) オプション、または PROF_DIR 環境変数で指定されたディレクトリーに一意の .dyn ファイルを生成します。Windows* では、/Qcov-dir または COV_DIR 環境変数を使用することもできます。これらは、/Qprof-dir および PROF_DIR と同じ効果があります。
profmerge ツールを使用して、すべての .dyn ファイルを 1 つの .dpi (pgopti.dpi) ファイルにマージします。
このステップは、アプリケーションのすべての実行から結果を結合して合計のプロファイル情報を表示し、最適化されたバイナリーを生成して、コードカバレッジ・ツールで必要な .dpi ファイルを作成します。
profmerge ツールを使用すると、アプリケーションをコンパイルしないで、.dyn ファイルを .dpi ファイルにマージできます。profmerge ツールは、profmerge -a オプションを使用して複数の .dpi ファイルを 1 つの .dpi ファイルにマージし、profmerge -prof_dpi オプションを使用して、出力 .dpi ファイルの名前を選択します。
profmerge ツールは指定されたディレクトリーに存在するすべての .dyn ファイルをマージします。無関係な .dyn ファイルが存在していないことを確認してください。無関係な .dyn ファイルが存在していると、プロファイル情報に無効なプロファイル・データが含まれてしまいます。この結果、不適切なカバレッジ情報が生成され、最適化されたコードのパフォーマンスに悪影響を与えることがあります。
コードカバレッジ・ツールを実行します。有効な構文とツールオプションは次のとおりです。
このステップは、指定されたようにレポートまたはエクスポートされたデータを作成します。他のオプションが指定されていない場合、コードカバレッジ・ツールは、現在のディレクトリーに 1 つの HTML ファイル (CODE_COVERAGE.HTML) とサブディレクトリー (CodeCoverage) を生成します。このファイルを Web ブラウザーで開いてレポートを確認します。
Windows* のみ: フォワードスラッシュ ("/") から始まるコンパイラー・オプションとは異なり、ツールオプションはハイフン ("-") から始まります。
コードカバレッジ・ツールは、プロジェクトを指定して、特定の必要なファイルへのパスを指定できます。次に、プロジェクトを指定して、使用する .dpi および .spi ファイルを設定する例を示します。
.dpi および .spi ファイルを指定する例 |
---|
codecov -prj myProject -spi pgopti.spi -dpi pgopti.dpi |
ツールには、宛先を追加して、各 HTML ページの最後にその宛先に電子メールを送信するリンクを生成するオプションもあります。このオプションにより、指定された宛先に電子メールを送信できます。次に、宛先を指定して、電子メールを送信するリンクを追加する例を示します。
宛先情報を追加する例 |
---|
codecov -prj myProject -mname JoeSmith -maddr js@company.com |
次に、プロジェクト名、動的プロファイル情報ファイル、そして出力形式とファイル名を指定する方法を示します。
データをテキストへエクスポートする例 |
---|
codecov -prj test1 -dpi test1.dpi -txtbcvrg test1_bcvrg.txt |
コードカバレッジ・ツールのオプション
オプション |
デフォルト |
説明 |
---|---|---|
-bcolorcolor |
#FFFF99 |
カバーされなかったブロックの HTML カラー名またはコードを指定します。 |
-beginblkdsblstring |
カバレッジツールによって無視されるコード・フラグメントの始まりを示すコメントを指定します。 |
|
-ccolorcolor |
#FFFFFF |
カバーされたコードの HTML カラー名またはコードを指定します。 |
-compfile |
表示 (または非表示) されるファイルのリストを含むファイル名を指定します。 |
|
-counts |
動的実行カウントを生成します。 |
|
-demang |
関数名とその引数の両方を復号します。 |
|
-dpifile |
pgopti.dpi |
動的プロファイル情報ファイル (.dpi) のファイル名を設定します。 |
-endblkdsblstring |
カバレッジツールによって無視されるコード・フラグメントの終わりを示すコメントを指定します。 |
|
-fcolorcolor |
#FFCCCC |
カバーされなかった関数の HTML カラー名またはコードを指定します。 |
-help、-h |
ツールオプションの説明を出力します。 |
|
-icolorcolor |
#FFFFFF |
基本ブロックマーカーや動的カウントなど HTML カラー名や情報行のコードを指定します。 |
-include-nonexec |
-xmlbcvrg[full] または -txtbcvrg[full] オプションと一緒に使用すると、実行されなかった関数のブロックの詳細もリストされます。 |
|
-maddrstring |
Nobody |
Web ページの所有者のメールアドレスを設定します。 |
-mnamestring |
Nobody |
Web ページの所有者の名前を設定します。 |
-nopartial |
一部カバーされたコードを完全にカバーされたコードとして扱います。 |
|
-nopmeter |
プログレスメーターをオフにします。メーターはデフォルトで有効になっています。 |
|
-nounwind |
基本ブロックカバレッジを計算または表示するときに、コンパイラーにより生成される例外処理クリーンアップ用の巻き戻しハンドラーを無視します。 |
|
-onelinedsblstring |
カバレッジツールによって無視されるコードの行または関数全体を示すコメントを指定します。 |
|
-pcolorcolor |
#FAFAD2 |
一部カバーされたコードの HTML カラー名またはコードを指定します。 |
-prjstring |
プロジェクト名を設定します。 |
|
-ref |
ref_dpi_file に関する差分カバレッジを検索します。 |
|
-showdirnames |
HTML レポートで、基本ファイル名の代わりに、ソースファイルのフルパス名を表示します。 |
|
-spifile |
pgopti.spi |
静的プロファイル情報 (.spi) ファイルのファイル名を指定します。 |
-srcrootdir |
絶対パスの代わりにソースファイルへの相対パスに使用するため、コンパイラーのインストルメンテーション実行中に使用されたディレクトリーとは異なるトップレベルのプロジェクト・ディレクトリーを指定します。 注新しいプロジェクト・ディレクトリーを使用するには、次のいずれかのコンパイラー・オプションを使用してソースをコンパイルする必要があります: [Q]prof-src-root または [Q]prof-src-root-cwd。このオプションは、プロジェクトのルート・ディレクトリーとして扱われるベース・ディレクトリーを指定します。 使用例: 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 これで、ソースファイルの検索時に "C:\workspaces\new_project_dir" が "c:\workspaces\orig_project_dir" の代わりに使用されます。 [Q]prof-src-root オプションと [Q]prof-src-root-cwd オプションの使用法については、prof-src-root/Qprof-src-root と prof-src-root-cwd/Qprof-src-root-cwd を参照してください。 |
|
-txtbcvrgfile |
カバーされた関数のブロックカバレッジをテキスト形式でエクスポートします。ファイル引数は有効なファイル名の形式でなければなりません。 |
|
-txtbcvrgfullfile |
アプリケーション全体のブロックカバレッジをテキスト形式および HTML 形式でエクスポートします。ファイル引数は有効なファイル名の形式でなければなりません。 |
|
-txtdcgfile |
テキスト形式の動的コールグラフ情報を生成します。ファイル引数は有効なファイル名の形式でなければなりません。 |
|
-txtfcvrgfile |
カバーされた関数の関数カバレッジをテキスト形式でエクスポートします。ファイル引数は有効なファイル名の形式でなければなりません。 |
|
-ucolorcolor |
#FFFFFF |
不明なコードの HTML カラー名またはコードを指定します。 |
-xcolorcolor |
#90EE90 |
無視されたコードの HTML カラー名またはコードを指定します。 |
-xmlbcvrgfile |
カバーされた関数のブロックカバレッジを XML 形式でエクスポートします。ファイル引数は有効なファイル名の形式でなければなりません。 |
|
-xmlbcvrgfullfile |
アプリケーション全体の関数カバレッジを HTML 出力および XML 形式でエクスポートします。ファイル引数は有効なファイル名の形式でなければなりません。 |
|
-xmlfcvrgfile |
カバーされた関数の関数カバレッジを XML 形式でエクスポートします。ファイル引数は有効なファイル名の形式でなければなりません。 |
アプリケーションをテストするときにインストルメント済みバイナリーを実行して集められたプロファイル情報を基に、インテル® コンパイラーはコードカバレッジ・ツールを使用して HTML 形式のレポートを作成します。これらのレポートは、テストによって実行された (実行されなかった) ソースコードの部分を示します。パフォーマンス・ワークロードのプロファイルが適用されると、コードカバレッジ情報は実行されたワークロードがアプリケーションの重要なコードをどの程度カバーするかを示します。プロファイルに基づく最適化の利点を完全に受けるためには、パフォーマンス・クリティカルなモジュールの高いカバレッジが必要です。
コードカバレッジ・ツールは、2 つのレベルのカバレッジを作成できます。
トップレベル (選択されたモジュールのグループ)
個々のモジュール・ソース・ビュー
トップレベルのカバレッジ
トップレベルのカバレッジは選択されたモジュールのコードカバレッジ全体をレポートします。次のオプションがあります。
処理するモジュールを選択します。
選択されたモジュールについて、ツールはモジュールとそのカバレッジ情報のリストを生成します。情報には、モジュールにある関数とブロックの総数、カバーされた部分が含まれます。
レポートされた表でカラムのタイトルをクリックすると、リストが次の項目に基づいて昇順または降順でソートされます。
基本ブロックカバレッジ
関数カバレッジ
関数名
デフォルトでは、コードカバレッジ・ツールは、現在のディレクトリーに 1 つの HTML ファイル (CODE_COVERAGE.HTML) およびサブディレクトリー (CodeCoverage) を生成します。HTML ファイルは、他に生成されたすべてのレポートを表示するためのフレームセットを定義します。HTML ファイルは Web ブラウザーで開きます。ツールは、他に生成されたすべてのレポートファイルを CodeCoverage サブディレクトリーに保存します。
HTML 形式のレポートを生成した場合、ブラウザーからその特定モジュールのソースを直接表示できます。次の図は、トップレベルのカバレッジレポートを示したものです。
コードカバレッジ・ツールは、カバーされなかったコードが容易に識別できるように、フレームセットを作成します。上のフレームにはカバーされなかった関数のリストが、下のフレームにはカバーされた関数のリストがそれぞれ表示されます。カバーされなかった関数については、各関数の基本ブロックの総数も表示されます。カバーされた関数については、ブロックの総数とカバーされたブロックの数、その比率 (つまり、カバレッジ率) が表示されます。
例えば、66.67(4/6) は、対応する関数の 6 つのブロックのうち 4 つのブロックがカバーされたことを示します。関数のブロックカバレッジ率は 66.67% になります。これらのリストは、カバレッジ率、ブロック数、関数名でソートできます。関数名はソースビューで関数が開始する位置とリンクされています。ワンクリックで、リストで最もカバーされなかった関数を確認できます。再度クリックすると、関数本体が表示されます。ソースビューでスクロールして関数のソースを参照できます。
個々のモジュール・ソース・ビュー
個々のモジュール・ソース・ビューで、ツールはカバーされなかった関数のリストとカバーされた関数のリストを表示します。リストは、ソースコードを容易に参照できるように、2 つの別々のフレームに表示されます。リストは、次の項目でソートできます。
カバーされなかった関数内のブロックの数
カバーされた関数のブロックカバレッジ
関数名
コードカバレッジ用の配色の設定
ツールは、カバレッジカテゴリーを、カバーされたコード、カバーされなかった基本ブロック、カバーされなかった関数、一部カバーされたコード、および不明なコードに色分けします。カバレッジ情報を示すためにツールが使用するデフォルト色を、次の表に示します。
カテゴリー |
デフォルト |
説明 |
---|---|---|
カバーされたコード |
#FFFFFF |
コードがテストによって実行されたことを示します。デフォルト色は -ccolor ツールオプションで無効にできます。 |
カバーされなかった基本ブロック |
#FFFF99 |
テストによって実行されなかった基本ブロックを示します。しかし、これらのブロックはテスト中に実行された関数内にあります。デフォルト色は -bcolor ツールオプションで無効にできます。 |
カバーされなかった関数 |
#FFCCCC |
テスト中に呼び出されなかった関数を示します。デフォルト色は -fcolor ツールオプションで無効にできます。 |
一部カバーされたコード |
#FAFAD2 |
この位置でコード用に複数の基本ブロックが生成されたことを示します。カバーされたブロックとカバーされなかったブロックがあります。デフォルト色は -pcolor ツールオプションで無効にできます。 |
無視されたコード |
#90EE90 |
テストで無視されるように特別に明示されたコードを示します。デフォルト色は -xcolor ツールオプションで無効にできます。 |
情報行 |
#FFFFFF |
基本ブロックマーカーや動的カウントを示します。デフォルト色は -icolor ツールオプションで無効にできます。 |
不明 |
#FFFFFF |
このソース行に対してソースが生成されなかったことを示します。ほとんどの場合、この位置のソースはコメント、ヘッダーファイルのインクルード、または変数宣言です。デフォルト色は -ucolor ツールオプションで無効にできます。 |
デフォルト色は、上記の表の各カバレッジカテゴリーで説明されているオプションを使用して、任意の HTML カラーまたは 16 進数の値にカスタマイズできます。
コードカバレッジ・プレゼンテーションでは、コードカバレッジ・ツールは次のヒューリスティックを使用します。ソース文字は、プロファイル情報によって基本ブロックの先頭として示されたソースの位置に達するまでスキャンされます。その基本ブロックのプロファイル情報でカバレッジのカテゴリーが変わったことが示されると、ツールはコードのその部分のカバレッジ条件に対応して色を変更し、カバレッジツールは HTML 形式のレポートファイルに適切なタグを挿入します。
コードのコンテキスト中の色を解釈する必要があります。例えば、実行されなかった基本ブロックに続くコメント行はカバーされなかったブロックと同じ色になります。C/C++ アプリケーションの閉じ括弧も同様です。
動的カウンター
コードカバレッジ・ツールは、動的実行カウントに関する情報を生成するように設定できます。この機能は、アプリケーションの各基本ブロックの動的実行カウントを表示し、カバレッジおよびパフォーマンスの調整に役立ちます。
カスタム設定を行うには、-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 オプションを使用して、リファレンス・データの動的プロファイル情報を作成します。この情報は、後でレポートする差分カバレッジで使用できます。次に、リファレンス・データを生成する一般的なコマンドを示します。
リファレンス・データを生成する例 |
---|
codecov -prj Project_Name -dpi customer.dpi -ref appTests.dpi |
差分カバレッジのカバレッジ統計は、新規実行で実行され、リファレンス実行で実行されなかったコードの比率をパーセントで表示します。この場合、ツールはカバーされなかったコードを含むモジュールのみを表示します。ソースビューで配色を表示する場合は、この点に注意してください。
コードが両方の実行で同じカバレッジ・プロパティー (カバーされたまたはカバーされなかった) の場合、コードはカバーされたコードとして扱われます。コードが新規実行でカバーされ、リファレンス実行でカバーされなかった場合、コードはカバーされなかったコードとして扱われます。また、コードがリファレンス実行でカバーされ、新規実行でカバーされなかった場合、差分カバレッジのソースビューはコードをカバーされたコードとして表示します。
差分カバレッジ用の実行
コードカバレッジ・ツールを差分カバレッジ用に実行するには、アプリケーション・ソース、.spi ファイル、および .dpi ファイルが必要です (上記のコードカバレッジ・ツールの要件セクションを参照)。
必要なファイルが準備できたら、次のようなコマンドを入力して、差分カバレッジ解析を開始します。
例 |
---|
codecov -prj Project_Name -spi pgopti.spi -dpi pgopti.dpi |
-spi および -dpi オプションを使用して .dpi ファイルと .spi ファイルを指定します。
コードカバレッジ・ツールは、カバレッジ解析からコードの一部を除外できます。この機能は、例えば、コードの特定の部分にデバッグでのみ使用される関数が含まれている場合に役立ちます。テストケースには、最終的なアプリケーションで利用できない機能のテストを含めるべきではありません。
除外できるコードの別の例として、アプリケーションで発生しそうもない内部エラーに対処するコードがあります。この場合、テストケースが不足していることが前提となります。カバレッジ解析で実行されない (デッド) コードは無視してもかまいません。コードカバレッジ・ツールは、コードが実行されない (デッドな) 部分をマークして、ファイルレベル、関数レベル、およびユーザー固有のコメントによって示された任意のコード境界でコードを無視するいくつかのオプションを提供します。次のセクションでは、さまざまなレベルでコードを除外する方法を説明します。
ファイルレベルでのカバレッジの追加と除外
コードカバレッジ・ツールは、解析するファイルを選択的に追加または除外できます。コンポーネント・ファイルを作成して、追加または除外するコードのファイル名およびディレクトリー名を示す適切な文字列値を追加します。-comp オプションの引数としてファイル名を渡します。次に、一般的なコマンドの例を示します。
コンポーネント・ファイルを指定する例 |
---|
codecov -comp file |
file は、テキストファイル名です。このファイルで指定された文字列が名前に含まれる場合、そのファイル/ディレクトリーはファイルレベルの解析で追加/除外されます。例えば、次のように仮定します。
ファイル名またはディレクトリー名に文字列 "source" を含むすべてのファイルを追加します。
名前に文字列 "source" を含むファイル/ディレクトリーを追加するように指定した、myComp.txt という名前のコンポーネント・テキスト・ファイルを作成します。
コンポーネント・ファイルを作成したら、次のようなコマンドを入力します。
例 |
---|
codecov -comp myComp.txt |
この例では、名前に文字列 "source" を含むファイル (例えば、source1.c や source2.c) と名前に文字列 "source" を含むディレクトリーにあるすべてのファイル (例えば、source/file1.c や source2\file2.c ) が解析されます。
ファイル/ディレクトリーを解析から除外するには、文字列の先頭にチルダ (~) を追加します。同じファイルで追加と除外を指定できます。例えば、名前に文字列 "source" を含むすべてのファイルおよびディレクトリー解析し、文字列 "skip" を含むすべてのファイルおよびディレクトリーを解析から除外する場合、コンポーネント・ファイル (myComp.txt) に次のような文字列を追加して、-comp オプションに渡します。
myComp.txt ファイルの追加/除外文字列の例 |
---|
source ~skip |
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 コメント付きのすべての関数を除外するには、次のようなコマンドを入力します。
例 |
---|
codecov -onelinedsbl NO_COVER -onelinedsbl "INF IA-32 architecture" |
複数の除外文字列を同時に指定できます。また、マーカーに対して任意の文字列値を指定できます。しかし、このオプションを使用するときは、次のガイドラインに沿っていることを確認してください。
インラインコメントは、文の最後になければなりません。
文字列は、インラインコメントの一部でなければなりません。
同じ方法を使用して関数全体をカバレッジ解析から除外できます。例えば、上記のコマンドを発行すると、カバレッジ解析から次の関数が除外されます。
サンプルコード |
---|
void dumpInfo (int n) { // NO_COVER ... } |
さらに、-onelinedsbl および -xcolor オプションを組み合わせることで、任意の HTML カラーコードで実行されないコードに色を付けることができます。 次に、オプションを組み合わせた例を示します。
ツールオプションの組み合わせ例 |
---|
codecov -onelinedsbl INF -xcolor lightgreen codecov -onelinedsbl INF -xcolor #CCFFCC |
任意の境界の定義によるコードの除外
コードカバレッジ・ツールには、カバレッジ解析から任意のコードを除外する機能があります。この機能は、関数の内部または複数の関数の範囲にわたって発生するコードの除外に役立ちます。
-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 オプションを使用して、上記のサンプルから除外するコードの始まりと終わりをマークするコマンドの例を示します。
任意のコード・マーカー・コマンドの例 |
---|
codecov -xcolor #ccFFCC -beginblkdsbl BINF -endblkdsbl EINF codecov -xcolor #ccFFCC -beginblkdsbl "BEGIN_INF" -endblkdsbl "END_INF" |
これらのオプションは -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 形式でカバーされた関数のレポートを生成するには、次のようなコマンドを入力します。
関数データのクイック・エクスポートの例 |
---|
codecov -prj test1 -dpi test1.dpi -xmlfcvrg test1_fcvrg.xml |
生成されるレポートは、カバーされたブロックの数および各関数のブロックカバレッジと一緒に、各関数が実行された回数および各関数のブロックの総数を示します。次に、一般的な 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 ... |
テキスト形式のレポートの各行は、次の方法で情報を示します。
列 1 |
列 2 |
列 3 |
列 4 |
列 5 |
---|---|---|---|---|
関数名 |
実行回数 |
関数定義の開始の行番号 |
関数定義の開始の列番号 |
関数の基本ブロックカバレッジの割合 |
ツールは、-xmlbcvrg オプションを使用したブロックレベルのカバレッジデータのエクスポートもサポートしています。例えば、XML 形式でカバーされたブロックのレポートを生成するには、次のようなコマンドを入力します。
ブロックデータの XML へのクイック・エクスポートの例 |
---|
codecov -prj test1 -dpi test1.dpi -xmlbcvrg test1_bcvrg.xml |
上記のコマンドは、次のような 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 オプションを使用すると、ツールによりアプリケーションの動的コールグラフについての情報を参照できます。動的コールグラフ・レポートの出力ファイルを指定します。出力されたコールグラフ・レポートには、アプリケーション・レベル、モジュールレベル、関数レベルでの静的呼び出しおよび動的呼び出し (直接、間接、仮想) についての情報が含まれます。