SpotBugs Ant タスクの使い方

この章では,一般的な Java ビルドおよびデプロイメントツールである Ant のビルドスクリプトに SpotBugs を統合する方法について説明します。SpotBugs Ant タスクを使用するとビルドスクリプトは Java コードで SpotBugs を自動的に実行できます。

Ant タスクは,Mike Fagan 氏の多大なる貢献によるものです。

Ant タスクのインストール

Ant タスクをインストールするには,Ant インストールの lib サブディレクトリに $SPOTBUGS_HOME/lib/spotbugs-ant.jar をコピーします。

注釈

SpotBugs に含まれていたバージョンの Ant タスクを使用することを強くお勧めします。Ant タスクの Jar ファイルは SpotBugsに含まれていたバージョン以外のバージョンで動作することを保証しません。

build.xml の変更

SpotBugs を build.xml (Ant のビルドスクリプト) に組み込むには,まず最初にタスク定義を追加する必要があります。これは次のように記述します。

<taskdef
    resource="edu/umd/cs/findbugs/anttask/tasks.properties"
    classpath="path/to/spotbugs-ant.jar" />

タスク定義は, spotbugs 要素を build.xml に記述したとき,タスクの実行に使用されるクラスを指定します。

タスク定義を追加したら,spotbugs タスクを使用するターゲットを定義できます。次の例は,build.xml に追加した Apache BCEL ライブラリです。

<property name="spotbugs.home" value="/export/home/daveho/work/spotbugs" />

<target name="spotbugs" depends="jar">
  <spotbugs home="${spotbugs.home}"
            output="xml"
            outputFile="bcel-sb.xml" >
    <auxClasspath path="${basedir}/lib/Regex.jar" />
    <sourcePath path="${basedir}/src/java" />
    <class location="${basedir}/bin/bcel.jar" />
  </spotbugs>
</target>

spotbugs 要素のhome 属性には,SpotBugsがインストールされているディレクトリが設定されている必要があります。つまり,$SPOTBUGS_HOME です。インストール を参照してください。

このターゲットは,bcel.jar に対して SpotBugs を実行します。これは,BCEL のビルドスクリプトによって生成された Jar ファイルです。("jar" ターゲットに依存させることで,SpotBugs を実行する前にライブラリが完全にコンパイルされていることを保証します) SpotBugs の出力は,XML 形式で bcel-sb.xml というファイルに保存されます。補助 Jar ファイル Regex.jar を補助クラスパスに追加します。なぜなら,BCEL ライブラリによって参照されるからです。保存されるバグデータが BCEL ソースコードへの正確な参照を持つようにするためにソースパスが指定されています。

タスクの実行

上記で定義した spotbugs ターゲットを使用して,コマンドラインから Ant を起動する例を示します。

[daveho@noir]$ ant spotbugs
Buildfile: build.xml

init:

compile:

examples:

jar:

spotbugs:
 [spotbugs] Running SpotBugs...
 [spotbugs] Bugs were found
 [spotbugs] Output saved to bcel-sb.xml

BUILD SUCCESSFUL
Total time: 35 seconds

この場合バグ結果を XML ファイルに保存したので SpotBugs GUI を使用して結果を表示できます。SpotBugs の実行 を参照してください。

パラメータ

この節では,SpotBugs タスクの使用時に指定できるパラメータについて説明します。

class

オプションのネストされた要素です。解析するクラスを指定します。class 要素は,解析されるアーカイブファイル (jar,zip など),ディレクトリ,クラスファイルの名前を location 属性に指定する必要があります。複数のクラス要素は,単一の spotbugs 要素の子要素として指定します。

クラス要素の指定を追加する,または代わりに,SpotBugs タスクに解析するファイルを指定する 1 つまたは複数の fileset 要素を含めることができます。たとえば,fileset を使用して,ディレクトリ内のすべての jar ファイルを分析するように指定できます。

auxClasspath
オプションのネストされた要素です。解析するライブラリまたはアプリケーションで使用されるが,解析したくはないクラスを含むクラスパス (jar ファイルまたはディレクトリ) を指定します。Ant のJava タスクの classpath 要素と同じ方法で指定します。
sourcePath
オプションのネストされた要素です。解析される Java コードをコンパイルするために使用されるソースファイルを含むソースディレクトリのパスを指定します。ソースパスを指定することにより生成された XML バグ出力に完全なソース情報が含まれ,後で GUI で見ることができます。
home
必須属性です。SpotBugs がインストールされているディレクトリの名前を設定する必要があります。
quietErrors
オプションのブール値属性です。true のときは,SpotBugs の出力で深刻な解析エラーや見つからなかったクラスの報告が抑制されます。デフォルトは 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
オプション属性です。出力が html に設定されているときに html 出力を生成するために使用するスタイルシートを設定します。SpotBugs 配布物に含まれるスタイルシートには,default.xsl,fancy.xsl,fancy-hist.xsl,plain.xsl,summary.xsl があります。stylesheet 属性が指定されていないときのデフォルト値は default.xsl です。
sort
オプション属性です。output 属性が text に設定されているときは,sort 属性は報告されたバグをクラスごとにソートするかどうかを設定します。デフォルトは true です。
outputFile
オプション属性です。SpotBugs 出力を保存する出力ファイルの名前を指定します。デフォルトでは,出力は Ant によって直接表示されます。
debug
オプションのブール値属性です。true に設定すると,SpotBugs はどのクラスが解析されているか,どのバグパターンディテクタが実行されているかに関する診断情報を出力します。デフォルトは false です。
effort
解析力を設定します。指定する値は,mindefaultmax のいずれかでなければなりません。解析力の詳細については コマンドラインオプション を参照してください。
conserveSpace
effort="min" と同義です。
workHard
effort="max" と同義です。
visitors
オプション属性です。実行すべきバグディテクタのコンマ区切りリストを指定します。バグディテクタは,パッケージ名がないクラス名で指定します。デフォルトでは,デフォルトで無効にされていないすべてのディテクタが実行されます。
omitVisitors
オプション属性です。コンマ区切りのバグディテクタのリストを指定します。visitors 属性と似ていますが,実行しないディテクタを設定します。
chooseVisitors
オプション属性です。コンマ区切りのバグディテクタリストのバグディテクタの接頭辞に「+」または「 -」を設定して,選択的に有効/無効にします。
excludeFilter
オプション属性です。レポートから除外するバグを指定するフィルタのファイル名を指定します。フィルタファイル を参照してください。
excludePath
An optional nested element. It specifies a path containing filters specifying bugs to exclude from being reported. See フィルタファイル.
includeFilter
オプション属性です。報告するバグを指定するフィルタのファイル名を指定します。フィルタファイル を参照してください。
includePath
An optional nested element. It specifies a path containing filters specifying which bugs are reported. See フィルタファイル.
projectFile
オプション属性です。プロジェクトファイルの名前を指定します。プロジェクトファイルは,SpotBugs GUI によって作成され,クラス,補助クラスパスエントリ,ソースディレクトリを指定します。プロジェクトに名前を付けることによって,class 要素や``auxClasspath`` または sourcePath 属性を設定する必要がありません。プロジェクトの作成 を参照してください。
jvmargs
オプション属性です。SpotBugs を実行するために使用する Java 仮想マシンに渡す必要がある引数を指定します。この属性を使用して,巨大なプログラムを解析するときに JVM が使用するメモリ量を増やすためのフラグを指定する必要があります。
systemProperty
オプションのネストされた要素です。システムプロパティを定義します。name 属性はシステムプロパティの名前を指定し,value 属性はシステムプロパティの値を指定します。
timeout
オプション属性です。SpotBugs を実行している Java プロセスがハングアップして終了する前に実行される時間をミリ秒単位で指定します。デフォルトは 600,000 ミリ秒 (10 分) です。巨大なプログラムのときは,SpotBugs は解析を完了するのに 10 分以上かかることがあります。
failOnError
オプションのブール値属性です。SpotBugs を実行中にエラーが発生したときに,ビルドプロセスを中断するかどうか指定します。デフォルトは false です。
errorProperty
オプション属性です。SpotBugs の実行中にエラーが発生したときに,true に設定するプロパティの名前を指定します。
warningsProperty
オプション属性です。 SpotBugs によって解析されたプログラムの警告が報告されたときに, true に設定するプロパティの名前を指定します。
userPreferencesFile
オプション属性です。使用するユーザ設定ファイルを設定します。上記のオプションの一部が上書きされる可能性があります。最初の引数として userPreferencesFile を指定すると,後続のオプションで上書きすることを意味します。最後の引数として指定すると以前のオプションを上書きすることを意味します。このオプションの背後にある根拠は,コマンドライン実行で SpotBugs Eclipse プロジェクトの設定を再利用するためです。
nested
オプション属性です。解析されるファイルとディレクトリのリストにあるネストされた jar/zip ファイルのスキャンを有効また無効にします。デフォルトでは,ネストされた jar/zip ファイルのスキャンが有効になっています。
setExitCode
オプションのブール値属性です。終了コードがメインの ant ジョブに戻されるかどうか指定します。デフォルトは true です。