第6章 FindBugsAnt タスクの使用方法

目次

1. Ant タスクのインストール
2. build.xml の書き方
3. タスクの実行
4. パラメーター

この章では、 FindBugsAnt のビルドスクリプトに組み入れる方法について説明します。 Ant は、ビルドや配備を行うことができる Java でよく使用されるツールです。FindBugs Ant タスクを使用すると、 ビルドスクリプトを作成して機械的に FindBugs による Java コードの分析を実行することができます。

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

1. Ant タスクのインストール

Ant タスクのインストールは、 $FINDBUGS_HOME/lib/findbugs-ant.jarAnt インストールディレクトリーのlib サブディレクトリーにコピーするだけです。

[注記]注記

使用する Ant タスクと FindBugs 本体は、同梱されていた同じバージョンのものを使用することを強く推奨します。別のバージョンの FindBugs に含まれていた Ant タスク Jar ファイルでの動作は保証しません。

2. build.xml の書き方

FindBugsbuild.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 ソースコードへの正確な参照が記述されます。

3. タスクの実行

コマンドラインから 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™ の実行 を参照してください。

4. パラメーター

このセクションでは、 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

分析の活動レベルを設定します。mindefault または max のいずれかの値を設定してください。分析レベルの設定に関する詳細情報は、 「コマンドラインオプション」 を参照してください。

conserveSpace

effort="min" と同義です。

workHard

effort="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 の分析は有効です。