日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
GCOV(1) GNU GCOV(1)
名称
gcov - カバレッジテストツール
書式
gcov [-v|--version] [-h|--help]
[-a|--all-blocks]
[-b|--branch-probabilities]
[-c|--branch-counts]
[-n|--no-output]
[-l|--long-file-names]
[-p|--preserve-paths]
[-f|--function-summaries]
[-o|--object-directory directory|file] sourcefile
[-u|--unconditional-branches]
解説
gcov はテストカバレッジプログラムです。利用者のプログラムを解析して、よ
り効率的でより速い実行コードを作成することを助けるために、利用者のプロ
グラムのテストされていない部分を発見するために、GCC と協調して使用しま
す。利用者の最適化の努力が利用者のコードに最もよく影響する場所を発見す
ることを助けるプロファイリングツールとして gcov を使用することができま
す。また、利用者のコード使用のどの部分で最も計算時間を使用しているかを
評価する他のプロファイリングツール、gprof とともに gcov を使用すること
もできます。
プロファイリングツールを使って、利用者のコードの性能を解析することがで
きます。gcov や gprof のようなプロファイラを使うと、性能にかかわる以下
のような基礎的な統計情報が得られます。
• コードの各行が何回実行されるか。
• コードのどの部分が実際に実行されたのか。
• コードの各部分の実行にどれだけの時間がかかっているか。
コンパイルされたコードがどのように動くのかがわかれば、最適化すべきモ
ジュールを見つけられます。gcov を使えば、最適化のためにどこに力をいれれ
ばよいかを決める事ができます。
ソフトウェア開発者は、カバレッジテストをテストスイートといっしょに使う
事で、ソフトウェアがリリース可能な品質を持つことを確認できます。テスト
スイートはプログラムが期待どおり動作する事を検証します。一方、カバレッ
ジテストによって、テストスイートがプログラムをどれだけテストしているか
を調べる事ができます。より良いテストとより良い最終製品を作るために、テ
ストスイートにどんな種類のテストケースを追加すればよいかを決める事がで
きます。
gcov を使う場合には最適化無しでコンパイルするべきです。なぜなら最適化に
よって数行のコードが 1 つにまとめられてしまうと、実行時間の多くを消費し
ている「ホットスポット」を探すのに必要な情報が十分集まらなくなってしま
うかもしれないからです。さらに、gcov は統計情報を行ごと (最小分析単位)
に集めるので、各行に文を 1 つずつ書くプログラミングスタイルにすると、
もっとも役に立つ結果が得られます。ループや他の制御構文に展開される複雑
なマクロを使うと、マクロ呼び出しの 1 行にしか情報が出ませんから、統計情
報はあまり役に立たなくなってしまいます。もしそのマクロが関数のように振
る舞うものなら、それをインライン関数に置き換えるとこの問題を解決できま
す。
gcov は sourcefile.gcov というログファイルを作ります。これには
sourcefile.c というソースファイルのどの行が何回実行されたかが記録されて
います。このログファイルを gprof といっしょに使えば、利用者のプログラム
の性能をファインチューニングする助けになります。gprof からは、gcov の出
力といっしょに使える、タイミング情報が得られます。
gcov は、GCC でコンパイルされたコードのみで動作します。他のプロファイル
やテストカバレッジの仕組みとの互換はありません。
オプション
-h
--help
gcov の使いかたを標準出力に表示して、プログラムを終了します。それ以
外の処理はしません。
-v
--version
gcov のバージョン番号を標準出力に表示して、プログラムを終了します。
それ以外の処理はしません。
-a
--all-blocks
あらゆる基本ブロック (basic block (文節)) のための個々の実行カウン
トを書き込みます。通常、gcov は行のメインブロックのためだけに実行カ
ウントを出力します。このオプションで、利用者は、単一の行中のブロッ
クが実行されていないかどうかを確認することができます。
-b
--branch-probabilities
出力ファイルに分岐 (branch) の頻度を書き込み、標準出力に分岐の概要
情報を書き込みます。このオプションによって、利用者はプログラムの各
分岐がどのくらい頻繁であるかを理解することができます。無条件分岐
は、-u オプションが与えられないなら、表示されません。
-c
--branch-counts
分岐が成立した割合 (パーセント) の代わりに、分岐の成立した回数を出
力します。
-n
--no-output
gcov 出力ファイルを作りません。
-l
--long-file-names
インクルードされたソースファイルのために長いファイル名を作成しま
す。例えば、ヘッダファイル x.h がコードを含んでいて、ファイル a.c
にインクルードされていたなら、ファイル a.c で gcov を実行すると、
x.h.gcov の代わりに a.c##x.h.gcov と呼ばれる出力ファイルを作成しま
す。これは、x.h が複数のソースファイルにインクルードされているな
ら、役に立ちます。利用者が -p オプションを使用するなら、インクルー
ドしているファイルとインクルードされているファイル名は、完全パス名
になります。
-p
--preserve-paths
生成された .gcov ファイルの名前の完全なパス情報を保存します。このオ
プションがなければ、単にファイル名の構成要素が使用されます。このオ
プションがあるなら、すべてのディレクトリの / 文字を # 文字に変換
し、. ディレクトリの構成要素は削除し、.. 構成要素は ^ に名前を変更
して使用されます。これは、ソースファイルがいくつかの異なったディレ
クトリにあるなら、役に立ちます。また、それは -l オプションに影響し
ます。
-f
--function-summaries
ファイルレベルのサマリの他に、各関数についてのサマリも出力します。
-o directory|file
--object-directory directory
--object-file file
gcov データファイルを含むディレクトリまたはオブジェクトパス名のどち
らかを指定します。.gcno と .gcda データファイルは、このオプションを
使用して検索されます。ディレクトリが指定されるなら、データファイル
は、そのディレクトリにあり、ソースファイル名にちなんで拡張なしで名
前がつけられます。ファイルがここで指定されるなら、データファイルは
拡張なしでそのファイルにちなんで名前がつけられます。このオプション
が供給されないなら、カレントディレクトリをデフォルトとします。
-u
--unconditional-branches
分岐確率が与えられるとき、無条件分岐のものを含めます。無条件分岐は
通常つまらないものです。
gcov は、利用者がコンパイラを呼び出したときと同じカレントディレクトリで
実行されるべきです。そうでなければ、ソースファイルの場所を見つけること
ができません。gcov は、カレントディレクトリに mangledname.gcov と呼ばれ
るファイルを作成します。これらは対応するソースファイルのカバレッジ情報
を含んでいます。1 つの .gcov ファイルは、データファイルを作成するために
コンパイルされたコードを含む各ソースファイルのために作成されます。出力
ファイル名の mangledname (残骸名) 部分は、通常単にソースファイル名です
が、-l または -p オプションが与えられるなら、何かより複雑なものになるか
もしれません。詳細はそれらのオプションを参照してください。
フィールドを含んでいます。形式は次の通りです。
<execution_count>:<line_number>:<source line text>
追加ブロック情報は、コマンドラインオプションで要求されるとき、各行に続
きます。execution_count は、コードを含まない行のためには - で、決して実
行されなかった行のためには ##### です。最初のいくつかの情報の行には、0
の line_number があります。
前置きの行は次の形式です。
-:0:<tag>:<value>
これらの前置きの行の順序と数は、gcov 開発が進歩するのに従って増加します
--- それらが変更がないままであることを当てにしないでください。特定の前
置き行を位置付けるために tag を使用します。
追加ブロック情報は、次の形式です。
<tag> <information>
information は、人間に解読可能ですが、マシン構文解析にも十分簡単になる
ように設計されています。
パーセンテージ (割合) を印刷 (表示) するとき、値がそれぞれ正確に 0% と
100% であるときのみ、0% と 100% を印刷 (表示) します。通常 0% または
100% に丸められる他の値は、代わりに最も近い非境界値で印刷 (表示) されま
す。
gcov を使うには、最初にまず GCC の 2 つの特別なオプション、
-fprofile-arcs, -ftest-coverage を指定して、プログラムをコンパイルしな
ければなりません。これによってコンパイラは、gcov が必要とする追加情報
(基本的にはプログラムのフローグラフ) を生成し、また gcov が必要とするプ
ロファイル情報を生成するコードをオブジェクトファイルに含めます。これら
の追加のファイルは、オブジェクトファイルのあるディレクトリに作られま
す。
プログラムを実行すると、プロファイル結果が生成されます。-fprofile-arcs
を指定してコンパイルしたソースファイル毎に、対応する .gcda ファイルがオ
ブジェクトファイルディレクトリに作られます。
プログラムのソースファイル名を引数にして gcov を実行すると、コードの各
行に実行回数を示したソースリストを生成します。プログラム名を tmp.c とす
ると、gcov の基本機能は以下のようにして使います。
$ gcc -fprofile-arcs -ftest-coverage tmp.c
$ a.out
$ gcov tmp.c
90.00% of 10 source lines executed in file tmp.c
Creating tmp.c.gcov.
gcov の出力は tmp.c.gcov に格納されています。以下はそのサンプルです。
-: 0:Source:tmp.c
-: 0:Graph:tmp.gcno
-: 0:Data:tmp.gcda
-: 0:Runs:1
-: 0:Programs:1
-: 1:#include <stdio.h>
-: 2:
-: 3:int main (void)
1: 4:{
1: 5: int i, total;
-: 6:
1: 7: total = 0;
-: 8:
11: 9: for (i = 0; i < 10; i++)
10: 10: total += i;
-: 11:
1: 12: if (total != 45)
#####: 13: printf ("Failure\n");
-: 14: else
1: 15: printf ("Success\n");
1: 16: return 0;
-: 17:}
-a オプションを使用するとき、利用者は、個々のブロックカウントを取得し、
出力は次のようになります:
-: 0:Source:tmp.c
-: 0:Graph:tmp.gcno
-: 0:Data:tmp.gcda
-: 0:Runs:1
-: 0:Programs:1
-: 1:#include <stdio.h>
-: 2:
-: 3:int main (void)
1: 4:{
1: 4-block 0
1: 5: int i, total;
-: 6:
1: 7: total = 0;
-: 8:
11: 9: for (i = 0; i < 10; i++)
11: 9-block 0
10: 10: total += i;
10: 10-block 0
-: 11:
1: 12: if (total != 45)
1: 12-block 0
#####: 13: printf ("Failure\n");
$$$$$: 13-block 0
-: 14: else
1: 15: printf ("Success\n");
1: 15-block 0
1: 16: return 0;
1: 16-block 0
-: 17:}
このモードでは、各基本ブロック (basic block) は 1 つの行 -- ブロックの
最後の行、のみ表示されます。複数行のブロックは、その最後の行の実行カウ
ントだけ寄与し、他の行は、前のブロックがそれらの行で終わっていないな
ら、コードを含むように表示されません。行の合計実行カウントが表示され、
それに続く行は、その行で終っている個々のブロックのための実行カウントを
表示します。-b オプションが与えられるなら、各ブロックの後に、ブロックの
分岐と呼び出しカウントが表示されます。
GCC 計測計器 (instrument) 呼び出しの方法のために、個々のブロックなしで
行の後に、呼び出しカウントを表示することができます。お分かりのように、
行 13 は実行されなかった基本ブロックを含んでいます。
-b オプションを使うと、出力は次のようになります。
$ gcov -b tmp.c
90.00% of 10 source lines executed in file tmp.c
80.00% of 5 branches executed in file tmp.c
80.00% of 5 branches taken at least once in file tmp.c
50.00% of 2 calls executed in file tmp.c
Creating tmp.c.gcov.
以下は、結果の tmp.c.gcov ファイルのサンプルです。
-: 0:Source:tmp.c
-: 0:Graph:tmp.gcno
-: 0:Data:tmp.gcda
-: 0:Runs:1
-: 0:Programs:1
-: 1:#include <stdio.h>
-: 2:
-: 3:int main (void)
function main called 1 returned 1 blocks executed 75%
1: 4:{
1: 5: int i, total;
-: 6:
1: 7: total = 0;
-: 8:
11: 9: for (i = 0; i < 10; i++)
branch 0 taken 91% (fallthrough)
branch 1 taken 9%
10: 10: total += i;
-: 11:
1: 12: if (total != 45)
branch 0 taken 0% (fallthrough)
branch 1 taken 100%
#####: 13: printf ("Failure\n");
call 0 never executed
-: 14: else
1: 15: printf ("Success\n");
call 0 called 1 returned 100%
1: 16: return 0;
-: 17:}
各関数において、関数が何回呼び出されたか、何回返ったか、そして、関数の
ブロックの何パーセントが実行されたかを 1 つの行に示して印刷されます。
基本ブロック (basic block) について、基本ブロックの最終行の次に、基本ブ
ロックを終わらせた分岐か関数呼び出しについての行を表示します。ある行で
終わる基本ブロックが複数ある場合、そのソース行に対して複数の分岐や関数
呼び出しが示される事があります。この場合、それらの分岐や関数呼び出しに
は番号がふられます。その番号とソース上の要素とのマッピングは単純ではあ
りませんが、もっとも小さい番号を持つ分岐や関数呼び出しが、ソース上で
もっとも左にあるのが普通です。
分岐 (branch) について、一度でも実行された分岐は、分岐の成立した回数を
分岐の実行数で割った比率をパーセントで示します。一度も実行されなかった
分岐は "never executed" と表示します。
関数呼び出し (call) について、一度でも実行された関数呼び出しは、呼び出
しから戻った回数を呼び出した回数で割った比率をパーセントで示します。こ
れは普通は 100% になりますが、"exit" や "longjmp" を呼び出すために戻っ
てこない事のある関数ではそれより少なくなるかもしれません。
実行回数は積算されます。もし .gcda ファイルを消さずにプログラムを再実行
すると、ソースの各行の実行回数は、以前の実行の結果に加えられます。これ
にはいくつか役に立つ使い道を考えられます。たとえばテストスイートの一部
として行われる、プログラムの複数回の実行結果をまとめたり、長期間のより
正確な情報を得るためにプログラムを非常に大きな回数実行して結果をまとめ
たりする事ができます。
.gcda ファイルのデータは、プログラムの終了直前に保存されます。
-fprofile-arcs を指定してコンパイルされた各ファイルに組み込まれているプ
ロファイリングコードは、まず始めに既存の .gcda ファイルを読み込みます。
もしその内容が実行プログラムと一致しなければ (基本ブロックの数が合わな
ければ)、ファイルの内容は無視します。一致する場合には、新しい実行回数を
足し込んでから、データをファイルに書き出します。
gcov と GCC の最適化の関係
利用者のコードを gcov を使って最適化しようとするならば、最初にまず GCC
の 2 つの特別なオプション -fprofile-arcs, -ftest-coverage を指定して、
プログラムをコンパイルしなければなりません。それに加えて GCC の他のどん
なオプションも指定する事ができます。一方、プログラム中の全ての行が実行
される事を確認したい時には、最適化を指定してはいけません。一部のマシン
では最適化によって複数の行が 1 つにまとめられてしまい、行の区別が無く
なってしまう可能性があります。たとえば以下のようなコードがあるとします:
if (a != b)
c = 1;
else
c = 0;
ある種のマシンではこのコードは 1 命令にコンパイルする事ができます。その
場合、各行に対応する命令コードが存在しないため、gcov は行ごとの実行回数
を数える事ができません。したがってプログラムを最適化した時の gcov の出
力は以下のようになります。
100: 12:if (a != b)
100: 13: c = 1;
100: 14:else
100: 15: c = 0;
この出力は、最適化によって結合されたこのコードブロックが 100 回実行され
た事を示しています。4 行からなるブロックが 1 命令にまとめられたのですか
ら、これはある意味では正しいものです。しかしながら、結果が 0 になった回
数や 1 になった回数を、この出力から読み込むことはできません。
インライン可能な関数は、予期されないラインカウントを作成することができ
ます。ラインカウントは、インライン可能な関数のソースコードのために表示
されますが、何が表示されかは、関数のどの部分がインラインか、または全く
インラインでないかどうかによって決まります。
関数がインラインでないなら、コンパイラは、それを必要とする任意のオブ
ジェクトファイルに、関数のインラインでない (out of line) コピーを出力し
なければなりません。fileA.o と fileB.o fileA.o の両方が、特定のインライ
ン可能な関数のインラインでない本体を含んでいるなら、それらはともにその
関数のためのカバレッジカウントも含みます。fileA.o と fileB.o がともリン
クされるとき、多くのシステムで、リンカは、その関数への全ての呼び出しの
ためにそれらのインラインでない本体の 1 つを選択し、他は削除するかまたは
無視します。残念ながら、未使用の関数本体のためのカバレッジカウンタは削
除されません。したがって、計測計器が取り付けられるとき、その関数の使用
の 1 を除いたすべては、0 のカウントを表示します。
関数がいくつかの場所でインラインにされているなら、各位置のブロック構造
は同じでないかもしれません。例えば、現在条件は場合によってはコンパイル
時に計算することができるかもしれません。インライン関数のすべての使用の
カバレッジが同じソース行を示しているので、行カウント自体は矛盾している
ように見えるかもしれません。
関連項目
gpl(7), gfdl(7), fsf-funding(7), gcc(1) と gcc の Info エントリ。
COPYRIGHT
Copyright (c) 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free
Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the
Back-Cover Texts being (b) (see below). A copy of the license is
included in the gfdl(7) man page.
(a) The FSF's Front-Cover Text is:
A GNU Manual
(b) The FSF's Back-Cover Text is:
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development.
gcc-4.2.1 2007-07-19 GCOV(1)