lcov.1 - lcov翻訳 Wiki - lcov翻訳

Up: man page

Prev: man page

Next: genhtml

名前

lcov - グラフィカルなGCOVのフロントエンド

書式

    lcov -c|--capture
        [-d|--directory directory] [-k|--kernel-directory directory]
        [-o|--output-file tracefile] [-t|--test-name testname]
        [-b|--base-directory directory] [-i|--initial] [--gcov-tool tool]
        [--checksum] [--no-checksum] [--no-recursion] [-f|--follow]
        [--compat-libtool] [--no-compat-libtool] [--ignore-errors errors]
        [--to-package package] [--from-package package] [-q|--quiet]
        [--no-markers]

    lcov -z|--zerocounters
        [-d|--directory directory] [--no-recursion] [-f|--follow]
        [-q|--quiet]

    lcov -l|--list tracefile
        [-q|--quiet] [--list-full-path] [--no-list-full-path]

    lcov -a|--add-tracefile tracefile
        [-o|--output-file tracefile] [--checksum] [--no-checksum]
        [-q|--quiet]

    lcov -e|--extract tracefile pattern
        [-o|--output-file tracefile] [--checksum] [--no-checksum]
        [-q|--quiet]

    lcov -r|--remove tracefile pattern
        [-o|--output-file tracefile] [--checksum] [--no-checksum]
        [-q|--quiet]

    lcov --diff tracefile diff
        [-o|--output-file tracefile] [--checksum] [--no-checksum]
        [--convert-filenames] [--strip depth] [--path path] [-q|--quiet]

    lcov [-h|--help] [-v|--version]

説明

lcovは、GCCのカバレッジテストツールgcovのためのグラフィカルフロントエンドです。 複数のソースファイルの行、関数と分岐のカバレッジデータを収集し、 カバレッジ情報を持つ注釈付きソースコードを含むHTMLページを作成します。 また、ファイル構造内を簡単にナビゲートする概要ページが追加されます。

カバレッジデータを収集するためにlcovを、HTMLページを作成するためにgenhtmlを使用してください。 カバレッジデータは、現在実行中のLinuxカーネルまたはユーザースペースのアプリケーションから 収集することができます。これを行うには、次の準備手順を完了する必要があります。

Linuxカーネルのカバレッジに対しては:

gcov-kernelのインフラストラクチャに対してセットアップの指示に従ってください:
http://ltp.sourceforge.net/coverage/gcov.php

ユーザ空間のアプリケーションをカバーに対しては:

"-fpro-file-arcs"と"-ftest-coverage"オプションを使用してGCCでアプリケーションをコンパイルしてください。

このマニュアルページは".da"ファイルと呼ばれるGCOVの出力と".info"ファイル又は"tracefile" としてlcovの出力フォーマットを参照していることに注意してください。

オプション

-a tracefile
--add-tracefile tracefile

tracefileの内容を追加します。

テストとファイル名の組み合わせを一致させるために実行カウントを加算することによって、 これらのファイルに含まれているカバレッジデータを結合するために、-aスイッチを使用して、 複数のトレースファイルを指定します。

加算演算の結果は標準出力（stdout）または-oで指定したトレースファイルに書き込まれます。

-z, -c, -a, -e, -r, -l と --diff の1つだけ同時に指定することができます。

-b directory
--base-directory directory

相対パスの基準ディレクトリとしてdirectoryを使用します。

lcovが次のようなエラーメッセージを出力するとき、ビルド環境の基準ディレクトリを指定するには、このオプションを使用します。
ERROR: could not read source file /home/user/project/subdir1/subdir2/subdir1/subdir2/file.c

この例では、基準ディレクトリとして/home/user/projectが使用されています。

このオプションは、基準ディレクトリ（すなわち、コンパイラの呼び出しが ソースコードがあるディレクトリと異なる場合の現在の作業ディレクトリ環境） で作業するlibtoolまたは同様のビルド環境でビルドしたプロジェクト上でlcovを 使用するときに必要です。

このオプションは、複数のベースディレクトリが使用されている環境では 動作しないことに注意してください。その場合、最初のソースコードファイルを 見つけることができなかったときの終了からlcovを防止するために --ignore-errorsオプションを使用している間、それぞれの基準ディレクトリ に対してlcovを繰り返してください。その後、この方法で、-aオプションを使用して 組み合わせることができるそれぞれの基準ディレクトリの部分的なカバレッジ情報を 取得することができます。

-c
--capture

カバレッジデータをキャプチャします。

デフォルトでは、現在のカーネルの実行回数をキャプチャし、 標準出力にカバリッジデータの結果を出力します。ユーザスペースのプログラムに対して 実行回数をキャプチャするためには--directoryオプションを使用してください。

キャプチャ動作の結果が標準出力（stdout）または-oで指定したトレースファイルに書き込まれます。

-z, -c, -a, -e, -r, -l と --diff の1つだけ同時に指定することができます。

--checksum
--no-checksum

トレースファイルを書き込むときにチェックサムデータを生成するかどうかを指定します。

チェックサムの生成を有効にするときは--checksumを、無効にするときは--no-checksumを使用してください。チェックサムの生成は、デフォルトでは無効になっています。

チェックサムの生成が有効になっている場合、チェックサムは、 それぞれのソースコードの行に対して生成され、カバレッジデータと共に保存されます。 このチェックサムは、異なるソースコードのバージョンからカバレッジデータを結合する試みを 防止するために使用されます。

別のソースコードのバージョンで動作しない場合で、カバレッジデータの処理を高速化するためと トレースファイルのサイズを減らすためにはこのオプションを無効にしてください。

--compat-libtool
--no-compat-libtool

libtoolの互換モードを有効にするかどうかを指定します。

libtoolの互換モードを有効にするときは--compat-libtoolを、無効にするときは --no-compat-libtoolを使用してください。libtoolの互換モードはデフォルトでは 有効になっています。

libtoolの互換モードを有効にすると、lcovは".libs"というディレクトリにある".da" ファイルに関連するソースコードが親ディレクトリで見つけることができると想定します。

あなたのビルド環境で".libs"という名前のディレクトリがあるが、libtoolを使用しない場合は、 カバレッジデータをキャプチャする際の問題を回避するには、このオプションを無効にします。

--convert-filenames

diffを適用するときにファイル名を変換します。

差分が提供するデータに応じて設定する処理されたデータのファイル名を変更するために --diffと一緒にこのオプションを使用してください。

--diff tracefile difffile

ソースコード差分ファイルのdifffileを使用して tracefile内のカバレッジデータを変換します。

例えば、もし古いバージョンから取得したデータを持っており、 より多くの現在のバージョンからのデータとそれを結合したい場合、 あなたがプログラムの別のソースコードレベルからカバレッジデータをマージする場合は、 このオプションを使用します。lcovは、これらのバージョン間でソースコードの行をマッピングし、 それぞれのカバレッジデータを調整しようとします。 difffileは統一された形式にする必要があります。すなわち、それは差分ツールの"-u"オプションを 使用して作成する必要があります。

古いバージョンで存在しない行は、計測対象としてカウントされないことに注意してください。 この操作に起因するため、トレースファイルが新しいバージョンから取得した 他のトレースファイルと個別が一緒に解釈されるべきではありません。また、それ自体が、 精度の損失をもたらす処理として変換したカバレッジデータは、 概要のみの目的で使用されるべきであることに留意してください。

差分演算の結果は標準出力（stdout）または-oで指定したトレースファイルに書き込まれます。

-z, -c, -a, -e, -r, -l と --diff の1つだけ同時に指定することができます。

-d directory
--directory directory

カーネルの代わりにdirectory内の.daファイルを使用します。

あなたがユーザ空間のプログラムに対してのカバレッジデータを操作したい場合は、 プログラムがコンパイルされた場所（.daで終わるカウンタファイルが保存される場所です） を指定するために、このオプションを使用します。

複数回このオプションを指定する可能性があることに注意してください。

-e tracefile pattern
--extract tracefile pattern

tracefileからデータを抽出します。

あなたがトレースファイルからファイルの唯一の特定のセットに対して カバレッジデータを抽出する場合は、このスイッチを使用してください。 追加のコマンドラインパラメータはシェルのワイルドカードパターンとして解釈されます （それらは最初にそれらの拡大からシェルを防ぐために、 それに応じてエスケープする必要がある可能性があることに注意してください。）。 これらのパターンの少なくとも1つに一致するtracefile内のすべての ファイルエントリが抽出されます。

抽出操作の結果は標準出力（stdout）または-oで指定したトレースファイルに書き込まれます。

-z, -c, -a, -e, -r, -l と --diff の1つだけ同時に指定することができます。

-f
--follow

.daファイルの検索時にリンクをたどります。

--from-package package

カーネルかディレクトリの代わりにpackage内の.daファイルを使用します。

あなたがビルドとテストに対しての別個のマシンを持ち、ビルドマシン上で.infoファイル の作成を行いたい場合にこのオプションを使用してください。詳細については --to-packageを参照してください。

--gcov-tool tool

gcovのツールの位置を指定します。

-h
--help

短いヘルプテキストを表示して終了します。

--ignore-errors errors

処理を継続する後にエラーのリストを指定します。

lcovがアボートする代わりに処理を続行するまでのエラーの1つ以上のクラスのリストを 指定するために、このオプションを使用します。

errorsは、次のキーワードをコンマで区切って指定できます:

gcov: gcovツールは、ゼロ以外のリターンコードを返しました。

source: データセットに対してのソースコードファイルが見つかりませんでした。

-i
--initial

初期ゼロカバレッジデータをキャプチャします。

任意のテストケースを実行する前に.bb, ,bbg もしくは .gcnoファイルを含むディレクトリ上で -cとこのオプションを使用してlcovを実行してください。結果はすべての計測対象の行に対しての ゼロカバレッジが含まれている"baseline"カバレッジデータファイルです。 テスト中にロードされたソースコードファイルの一部がない場合でも、対象となる合計の行の割合が 正しいことを確認するためテスト実行後にキャプチャされたカバレッジデータファイルを使用して （lcov -a を使用して）このデータファイルを結合します。

テストケースのデータをキャプチャする際の手順を推奨します:

1.ベースラインのカバレージデータファイルを作成します。
# lcov -c -i -d appdir -o app_base.info

2.テストを実行します。
# appdir/test

3.テストカバレージデータファイルを作成します。
# lcov -c -d appdir -o app_test.info

4.ベースラインとテストカバレッジデータを結合します。
# lcov -a app_base.info -a app_test.info -o app_total.info

-k subdirectory
--kernel-directory subdirectory

subdirectoryからのみカーネルカバレッジデータをキャプチャします。

カーネルのすべてのカバレッジデータを取得したくはないが、特定のサブディレクトリのみ欲しい場合、 このオプションを使用してください。このオプションは複数回指定することができます。

カーネルのgcovのサポートのバージョンに応じてカーネルのサブディレクトリへのフルパスを指定する 必要がある可能性があることに注意してください。

-l tracefile
--list tracefile

tracefileの内容を一覧表示します。

-z, -c, -a, -e, -r, -l と --diff の1つだけ同時に指定することができます。

--list-full-path
--no-list-full-path

リストの操作中にフルパスを表示するかどうかを指定します。

リストの操作中にフルパスを表示する場合は--list-full-pathを使用してください。 短縮パスを表示する場合は--no-list-full-pathを使用してください。 パスはデフォルトで短縮形式です。

--no-markers

あなたがソースコードファイルの除外のマーカーに関係なく、カバレッジデータを取得したい場合、 このオプションを使用してください。除外マーカーの詳細については、geninfo（1）を参照してください。

--no-recursion

あなたが処理サブディレクトリを除いて指定したディレクトリに対してのみカバレッジデータを 取得したい場合、このオプションを使用してください。

-o tracefile
--output-file tracefile

標準出力（stdout）の代わりにtracefileにデータを出力します。

標準出力を使用するためにはファイル名として"-"を指定してください。

慣例により、lcovで生成されたカバレッジデータファイルは、"tracefiles"と呼ばれ、 ファイルの拡張子".info"を持つ必要があります。

--path path

diffを適用するときにファイル名からパスをはがします。

トレースファイルと差分ファイル名の間のマッチング時に、指定された初期パスコンポーネントを無視するためにlcovを呼ぶためには、--diffと一緒にこのオプションを使用してください。

-q
--quiet

進行状況メッセージを出力しません。

このオプションは、進捗メッセージが、標準出力にも出力されるカバレッジデータと混ざらないようにするために 指定されるファイルがないとき、暗黙で設定されます。

-r tracefile pattern
--remove tracefile pattern

tracefileからデータを削除します。

あなたがトレースファイルからファイルの特定のセットに対してカバレッジデータを削除する場合は、 このスイッチを使用してください。追加のコマンドラインパラメータはシェルのワイルドカードパターンとして 解釈されます（それらは最初にそれらの拡大からシェルを防ぐために、 それに応じてエスケープする必要がある可能性があることに注意してください。）。 これらのパターンの少なくとも1つに一致するtracefile内のすべてのファイルエントリが削除されます。

削除操作の結果は標準出力（stdout）または- oで指定したトレースファイルに書き込まれます。

-z, -c, -a, -e, -r, -l と --diff の1つだけ同時に指定することができます。

--strip depth

diffを適用するときにパスのコンポーネントをはがします。

トレースファイルと差分ファイルのマッチング時に初期ディレクトリの指定数を無視するために lcovを呼ぶためには、--diffと一緒にこのオプションを使用してください。

-t testname
--test-name testname

トレースファイルに格納されるテストの名前を指定します。

この名前は、複数のデータセットを組み合わせたトレースファイルにマージされたときに設定される カバレッジデータを識別します（-a オプションを参照してください）。

有効なテスト名は、英字、小数点以下の数字とアンダースコア文字("_")で構成することができます。

--to-package package

後で処理するために.daファイルを記憶させます。

あなたがビルドとテストに対しての別個のマシンを持ち、ビルドマシン上で.infoファイルの生成を 行いたい場合、このオプションを使用してください。 これを行うには、次の手順を実行します:

テストマシン上で:

- テストを実行する
- lcov -c [-d directory] --to-package file を実行する
- ビルドマシンにfileをコピーする

ビルドマシン上で:

- lcov -c --from-package file [-o and other options] を実行する

これは、カーネルとユーザ空間のカバレッジデータの両方で動作します。 --to-package 又は --from-packageのいずれかと一緒に-bを使用してビルドディレクトリへのパスを 指定する必要がある可能性があることに注意してください。 パッケージデータは、プログラムを再コンパイルする前に.infoファイルに変換する必要があります。 さもないと、それが無効になります。

-v
--version

バージョン番号を表示し、終了します。

-z
--zerocounters

ゼロにすべての実行カウントをリセットします。

デフォルトではカーネルの実行回数をリセットしようとします。 ユーザ空間のプログラムのすべてのカウンタをリセットするためには-directoryオプションを使用してください。

-z, -c, -a, -e, -r, -l と --diff の1つだけ同時に指定することができます。

ファイル

/etc/lcovrc

システム全体の設定ファイル。

~/.lcovrc

ユーザごとの設定ファイル。

著者

Peter Oberparleiter <[e-mail]>

関連項目

lcovrc(5), genhtml(1), geninfo(1), genpng(1), gendesc(1), gcov(1)

このドキュメントはlcov(英)のサイトを元に作成しました

Up: man page

Prev: man page

Next: genhtml