この章では、 FindBugs を Ant のビルドスクリプトに組み入れる方法について説明します。 Ant は、ビルドや配備を行うことができる Java でよく使用されるツールです。FindBugs Ant タスクを使用すると、 ビルドスクリプトを作成して機械的に FindBugs による Java コードの分析を実行することができます。
この Ant タスクは、 Mike Fagan 氏の多大な貢献によるものです。
Ant タスクのインストールは、 $FINDBUGS_HOME/lib/findbugs-ant.jarlib サブディレクトリーにコピーするだけです。
![[注記]](note.png) | 注記 |
|---|---|
使用する Ant タスクと FindBugs 本体は、同梱されていた同じバージョンのものを使用することを強く推奨します。別のバージョンの FindBugs に含まれていた Ant タスク Jar ファイルでの動作は保証しません。 |
FindBugs を build.xml (Ant ビルドスクリプト) に組み入れるためにはまず、タスク定義を記述する必要があります。タスク定義は次のように記述します。:
<taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/>
タスク定義は、 findbugs 要素を build.xml 上に記述したとき、そのタスクの実行に使用されるクラスを指定します。
タスク定義の記述をすれば、findbugs タスクを使ってターゲットを定義できます。次に示すのは、 Apache BCEL ライブラリーを分析する場合を想定した build.xml の記述例です。
<property name="findbugs.home" value="/export/home/daveho/work/findbugs" />
<target name="findbugs" depends="jar">
<findbugs home="${findbugs.home}"
output="xml"
outputFile="bcel-fb.xml" >
<auxClasspath path="${basedir}/lib/Regex.jar" />
<sourcePath path="${basedir}/src/java" />
<class location="${basedir}/bin/bcel.jar" />
</findbugs>
</target>
findbugs 要素には、 home 属性が必須です。 FindBugs のインストールディレクトリーすなわち $FINDBUGS_HOME の値を設定します。2章FindBugs™ のインストール を参照してください。
このターゲットは bcel.jar に対して FindBugs を実行します。この Jar ファイルは、 BCEL ビルドスクリプトによって作成されるものです。(上記のターゲットが「jar」ターゲットに依存している (depends) と設定することにより、 FindBugs が実行される前に当該ライブラリーが完全にコンパイルされていることを保証しています。) FindBugs の出力は、 XML 形式で bcel-fb.xml ファイルに保存されます。補助 Jar ファイル Regex.jar を aux classpath に記述しています。なぜなら、当該 Jar ファイルが BCEL メイン･ライブラリーから参照されるからです。source path を指定することで、保存されるバグデータに BCEL ソースコードへの正確な参照が記述されます。
コマンドラインから Ant を起動する例を次に示します。前述の findbugs ターゲットを使用しています。
[daveho@noir]$ ant findbugs
Buildfile: build.xml
init:
compile:
examples:
jar:
findbugs:
[findbugs] Running FindBugs...
[findbugs] Bugs were found
[findbugs] Output saved to bcel-fb.xml
BUILD SUCCESSFUL
Total time: 35 seconds
この事例においては、XML ファイルでバグ検索結果を保存しているので、 FindBugs GUI を使って結果を参照することができます。 4章FindBugs™ の実行 を参照してください。
このセクションでは、 FindBugs タスクを使用する際に、指定することができるパラメーターについて説明します。
class任意指定のネストされる要素です。分析の対象となるクラス群を指定します。
class要素にはlocation属性の指定が必須です。 分析対象となるアーカイブファイル (jar, zip, 他)、ディレクトリーまたはクラスファイルの名前を記述します。 1 つのfindbugs要素に対して、複数のclass子要素を指定することができます。class要素の指定を置き換えるまたは追加する形で、 FindBugs タスクに1個以上のfileset要素を記述することで 分析するファイル群を指定することができます。 例えば、 fileset において特定のディレクトリにある全ての jar ファイルを分析対象に指定することができます。auxClasspath任意指定のネストされる要素です。分析対象のライブラリーまたはアプリケーションによって使用されているが分析の対象にはしたくないクラスを含んでいるクラスパス (Jar ファイルまたはディレクトリー) を指定します。 Ant の Java タスクにある
classpath要素 と同じ方法で指定することができます。sourcePath任意指定のネストされる要素です。分析対象 Java コードのコンパイル時に使用したソースファイルを含んでいるソースディレクトリーへのパスを指定します。ソースパスを指定することにより、生成される XML のバグ出力結果に完全なソース情報をもたせることができ、後になって GUI で参照することができます。
home必須属性です。FindBugs がインストールされているディレクトリー名を設定します。
quietErrors任意指定のブール値属性です。true を設定すると、深刻な分析エラー発生やクラスがみつからないといった情報が FindBugs 出力に記録されません。デフォルトは、 false です。
reportLevel任意指定の属性です。報告される問題の信頼度・優先度のしきい値を指定します。 「low」に設定すると、バグ報告が信頼度により除外されることはありません。 「medium」 (デフォルト) に設定すると、信頼度(低)の問題が除外されます。 「high」に設定すると、信頼度(高) のバグのみが報告されます。
output任意指定の属性です。出力形式を指定します。「xml」 (デフォルト) に設定すると、出力は XML 形式になります。「xml:withMessages」 に設定すると、出力は人間が読めるメッセージ が追加された XML 形式になります。(XSL スタイルシートを使ってレポートを作成することを計画している場合はこの形式を使用してください。) 「html」に設定すると、出力は HTML 形式(デフォルトのスタイルシートは default.xsl) になります。 「text」に設定すると、出力は特別なテキスト形式になります。「emacs」に設定すると、出力は Emacs エラーメッセージ形式になります。「xdocs」に設定すると、出力は Apache Maven で使用できる xdoc XML になります。
stylesheet任意指定の属性です。output 属性 に html を指定した場合に、 HTML 出力作成に使用されるスタイルシートを指定します。FindBugs 配布物に含まれているスタイルシートは、 default.xsl、 fancy.xsl 、 fancy-hist.xsl 、 plain.xsl および summary.xsl です。デフォルト値は default.xsl です。
sort任意指定の属性です。
output属性に「text」を指定した場合に、バグの報告をクラス順にソートするかどうかをsort属性で指定します。デフォルトは、 true です。outputFile任意指定の属性です。指定した場合、FindBugs の出力はその名前のファイルへと保存されます。省略時、出力は Ant によって直接表示されます。
debug任意指定のブール値属性です。true に設定すると、 FindBugs は 診断情報を出力します。どのクラスを分析しているか、どのパグパターンディテクタが実行されているか、という情報が表示されます。デフォルトは、 false です。
effort分析の活動レベルを設定します。
min、defaultまたはmaxのいずれかの値を設定してください。分析レベルの設定に関する詳細情報は、 「コマンドラインオプション」 を参照してください。conserveSpaceeffort="min" と同義です。
workHardeffort="max" と同義です。
visitors任意指定の属性です。どのバグディテクタを実行するかをコンマ区切りのリストで指定します。バグディテクタはパッケージ指定なしのクラス名で指定します。省略時、デフォルトで無効化されているものを除くすべてのディテクタが実行されます。
omitVisitors任意指定の属性です。 バグディテクタをコンマ区切りのリストで指定します。
visitors属性と似ていますが、こちらは 実行されない ディテクタを指定します。chooseVisitors任意指定の属性です。 頭に「+」または「-」を付け加えたバグディテクタをコンマ区切りのリストで指定します。 「+」を付け加えたバグディテクタは有効に、「-」を付け加えたバグディテクタは無効になります。
excludeFilter任意指定の属性です。フィルターファイル名を指定します。報告から除外されるバグを指定します。8章フィルターファイル を参照してください。
includeFilter任意指定の属性です。フィルターファイル名を指定します。報告されるバグを指定します。8章フィルターファイル を参照してください。
projectFile任意指定の属性です。プロジェクトファイル名を指定します。プロジェクトファイルは、 FindBugs GUI で作成します。分析されるクラス、および、補助クラスパス、ソースディレクトリーが記入されてます。プロジェクトファイルを指定した場合は、
class要素・auxClasspath属性およびsourcePath属性を設定する必要はありません。プロジェクトの作成方法は、 4章FindBugs™ の実行 を参照してください。jvmargs任意指定の属性です。FindBugs を実行している Java 仮想マシンに対して受け渡される引数を指定します。巨大なプログラムを分析する場合に、 JVM が使用するメモリ容量を増やす指定をするためにこの引数を利用する必要があるかもしれません。
systemProperty任意指定のネストされる要素です。指定した場合、Java システムプロパティーを定義します。
name属性にはシステムプロパティーの名前を指定します。そして、value属性にはシステムプロパティの値を指定します。timeout任意指定の属性です。FindBugs を実行している Java プロセス の実行許容時間をミリ秒単位で指定します。時間を超過するとハングアップしていると判断してプロセスが終了されます。デフォルトは、 600,000 ミリ秒 (10 分) です。巨大なプログラムの場合は、 FindBugs が分析を完了するまでに 10 分 以上掛かる可能性があることに注意してください。
failOnError任意指定のブール値属性です。FindBugs の実行中にエラーがあった場合に、ビルドプロセス自体を打ち切って異常終了させるかどうかを指定します。デフォルトは、「false」です。
errorProperty任意指定の属性です。FindBugs の実行中にエラーが発生した場合に、「true」が設定されるプロパティーの名前を指定します。
warningsProperty任意指定の属性です。FindBugs が分析したプログラムにバグ報告が 1 件でもある場合に、「true」が設定されるプロパティーの名前を指定します。
userPreferencesFile任意指定の属性です。 ユーザー設定ファイルのパスを設定します。ユーザー設定ファイルの内容で、他のオプションの一部を上書きすることができます。
userPreferencesFileを一番目の引数に指定した場合は、後続のオプションの方がユーザー設定ファイルの内容に優先します。userPreferencesFileを最後の引数に指定した場合は、ユーザー設定ファイルの内容の方が前に指定したオプションに優先します。 このオプションを設けた背景・理由は、 Eclipse プロジェクトの FindBugs の設定をコマンドライン実行で再利用するためです。nested任意指定の属性です。分析対象のファイル・ディレクトリーリストにあるファイル内にネストされた jar および zip ファイルに対する分析を有効化・無効化します。 デフォルトでは、ネストされた jar/zip の分析は有効です。