このセクションの内容
ソース コードのインストゥルメントとビルド
このフェーズでは、次の 3 つのステップが実行されます。
- ソース コードがインストゥルメントされます。
- インストゥルメントされたコードがオブジェクト ファイルにコンパイルされます。
- インストゥルメントされたオブジェクトとインストゥルメントされていないオブジェクトがすべてカバレッジ ツールのライブラリおよびその他の最終的なバイナリ成果物を作成するのに必要なライブラリにリンクされます。
通常、これらのステップはビルド プロセスで実行され、カバレッジ ツールがユーザーのビルド システムと統合されている必要があります。cpptestcc
ツールはソース コードをインストゥルメントし、オブジェクト ファイルにコンパイルします。cpptestcc
はコンパイル時のコマンド ラインでコンパイラの接頭辞として使用します。
元のコンパイル コマンド ライン
cc -I app/includes -D defines -c source.cpp
カバレッジ モードでのコンパイル コマンド ライン
cpptestcc -compiler gcc_9-64 -line-coverage -workspace /home/test/proj/cov -- cc -I app/includes -D defines -c source.cpp
コンパイル コマンド ラインをカバレッジ モードで実行すると、cpptestcc
は次の処理を行います。
- コンパイル コマンドラインを解析してソース ファイルの情報を抽出します。
- 検出されたすべてのソース ファイルをパースしてカバレッジ メトリクス取得用にインストゥルメントします。
- インストゥルメント済みのファイルを
-workspace
スイッチで指定された場所に再構築します。レポート生成時に使用されるコードの構造に関する付加情報も保存されます。 - コンパイル コマンド ラインを変更して元のソース ファイルをインストゥルメントされたバージョンに置き換えます。
- コンパイル コマンド ラインを実行し、元のコマンド ラインの場合と同じ場所にオブジェクト ファイルを作成します。
PATH 変数に [INSTALL_DIR]/bin
ディレクトリを追加し、cpptestcc
コマンドを指定するときにフルパスを使用しないで済むようにできます。このドキュメントのすべてのサンプルは、PATH 変数に [INSTALL_DIR]/bin ディレクトリが追加されていることを前提としています。
次のパターンは、カバレッジのインストゥルメントの構文を表しています。
cpptestcc -compiler <compiler configuration> <coverage metric specification> -workspace <workspace directory> -- <compilation command line>
<compiler configuration>
はサポート対象のコンパイラ コンフィギュレーション (例:gcc_9-64)を表します。サポート対象コンパイラの一覧は「サポート対象コンパイラ」を参照してください。<coverage metric specification>
はサポート対象カバレッジ メトリクス (例:行カバレッジ)を表します。サポート対象カバレッジの一覧は「cpptestcc コマンド ライン リファレンス」を参照してください。cpptestcc
コマンド ラインは区切り文字--
によってコンパイラ コマンド ラインと分けられます。
インストゥルメントされたコードのリンク
オリジナルのリンカー コマンドを変更し、コード カバレッジのインストゥルメントに必要な追加のライブラリをインクルードする必要があります。次のサンプルは、一般的なコマンド ラインの変更方法を表しています。
元のコンパイル コマンド ライン
lxx -L app/lib app/source.o -lsomelib -o app.exe
カバレッジ モードでのコンパイル コマンド ライン
lxx -L app/lib app/source.o somelib.lib <coverage tool>/runtime/lib/cpptest.lib -o app.exe
インストゥルメントされたコードの実行
実行環境の詳細はアプリケーションの仕様によって異なりますが、カバレッジ ツールを使用することにより、実行時に以下のような依存関係の制限が加わります。
- カバレッジ ツールのライブラリが共有 (動的ロード) ライブラリとしてリンクされた場合、インストゥルメントされたアプリケーションの開始時にカバレッジ ツールのライブラリを確実にロードできるようにする必要があります。それには、Windows では通常 PATH 環境変数に
[INSTALL_DIR]/bin
ディレクトリを追加する必要があります。Linux では LD_LIBRARY_PATH 変数に[INSTALL_DIR]/runtime/lib
を追加します。 - カバレッジの結果転送チャネルを変更する場合、変更によって生じるすべての要件を満たす必要があります。たとえば、結果を TCP/IP ソケットまたは rs232 によって送信する場合、インストゥルメントされたアプリケーションを実行する前に適切なリスニング エージェントが開始する必要があります。
インストゥルメントされたアプリケーションの実行が終了すると、収集された結果はファイルに保存され、そのファイルがレポートの生成に使用されます。
レポートの生成
次の 2 つの種類の情報から最終的なカバレッジ レポートが生成されます。
- ビルド プロセス中に
cpptestcc
によって生成されたコードの構造情報 (ワークスペースに保存) - インストゥルメントされたコードの実行により取得されたカバレッジ結果
カバレッジ レポートは HTML フォーマットで生成するか、DTP Server に送信することができます。次の例はレポートを生成するためのコマンドを表しています。
cpptestcli -config builtin://Coverage -input cpptest_results.clog -workspace /home/test/proj/cov
DTP Server で適切にカバレッジ データをマージするには、コマンド ラインまたは .properties 設定ファイルで 1 つ以上のカバレッジ イメージ タグを指定する必要があります。カバレッジ イメージは接続された DTP に自動的に送信され、DTP でフィルターとカバレッジ イメージを関連付けることができます。
report.coverage.images
プロパティを使用すると、DTP Server でカバレッジ イメージを作成するのに使用できるタグを 3 つまで指定できます。
report.coverage.images=[tag1; tag2; tag3]
DTP の Report Center 管理ページ ([管理] > [プロジェクト] > [フィルター] > フィルターをクリック ) でカバレッジ イメージを関連付けます。
また、report.coverage.limit
プロパティを使用すると、カバレッジの下限を指定することもできます。
report.coverage.limit=[value]
この値よりも低いカバレッジは、レポートで強調表示されます。デフォルト値は 40
です。
使用例
このサンプルでは、main.c
という名前の C++ ソース ファイルのコードを例とします。
#include <iostream> int main(int argc, char ** argv) { if (argc > 1) { std::cout << "Thank you for arguments" << std::endl; } else { std::cout << "Provide some arguments please !" << std::endl; } return 0; }
通常のコンパイル コマンドは gcc
です。
g++ -c main.c -o main.o
このファイルをインストゥルメントし、インストゥルメントされたコードをオブジェクト ファイルにコンパイルするには、コンパイル コマンド ラインに cpptestcc
接頭辞を含めます。
cpptestcc -compiler gcc_9-64 -line-coverage -workspace /home/test/proj/cov -- g++ -c main.c -o main.o
cpptestcc コマンドを呼び出すと、次の 2 つの成果物が作成されます。
- インストゥルメントされたコードのオブジェクト
-workspace
オプションで指定されたディレクトリに保存されたコード構造情報
ソース ファイルをインストゥルメントし、オブジェクト ファイルにコンパイルしたら、最終的な実行モジュールの形にリンクできます。この簡単な例では、通常は次のコマンドを使用してリンクします。
g++ main.o -o app.exe
カバレッジのインストゥルメントには、追加のライブラリが必要なため、リンク コマンド ラインは次のようになります。
g++ main.o <coverage tool install dir>/runtime/lib/cpptest.a -o app.exe
このサンプルでは、カバレッジ ライブラリの静的なバージョンが使用されます。動的/共有バージョンのほか、ソース コードも提供されているため、カスタマイズされたバージョンをビルドできます。追加情報については、「コード カバレッジ ランタイム ライブラリ」を参照してください。
アプリケーションをリンクしたら、アプリケーションを実行してコード カバレッジ情報を収集できます。次のコマンドを実行します。
./app.exe
アプリケーションはカバレッジ ログ ファイルを出力します。デフォルトでは、ログ ファイルは cpptest_results.clog
という名前で現在の作業ディレクトリに出力されます。
最後に、次のコマンドを実行してレポートを生成します。
cpptestcli -config builtin://Coverage -workspace /home/test/proj/cov -input cpptest_results.clog -report report_dir
レポートのディレクトリが作成され、そこにコード カバレッジ情報を記載した HTML レポートが生成されます。