| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "../../etc/docbook/docbookx.dtd" [ |
| <!ENTITY FindBugs "<application>FindBugs</application>"> |
| <!ENTITY Ant "<application>Ant</application>"> |
| <!ENTITY Saxon "<application>Saxon</application>"> |
| <!ENTITY FBHome "<replaceable>$FINDBUGS_HOME</replaceable>"> |
| <!ENTITY FBHomeWin "<replaceable>%FINDBUGS_HOME%</replaceable>"> |
| <!ENTITY nbsp " "> |
| ]> |
| <book lang="ja" id="findbugs-manual"> |
| |
| <bookinfo> |
| <title>&FindBugs;™ マニュアル</title> |
| |
| <authorgroup lang="en"> |
| <author> |
| <firstname>David</firstname> |
| <othername>H.</othername> |
| <surname>Hovemeyer</surname> |
| </author> |
| <author> |
| <firstname>William</firstname> |
| <othername>W.</othername> |
| <surname>Pugh</surname> |
| </author> |
| </authorgroup> |
| |
| <copyright lang="en"> |
| <year>2003 - 2012</year> |
| <holder>University of Maryland</holder> |
| </copyright> |
| |
| <legalnotice> |
| <para>このマニュアルは、クリエイティブ・コモンズ表示-非営利-継承に基づく使用許諾がなされています。使用許諾書をご覧になる場合は、 <ulink url="http://creativecommons.org/licenses/by-nc-sa/1.0/deed.ja">http://creativecommons.org/licenses/by-nc-sa/1.0/</ulink> にアクセスするか、クリエイティブ・コモンズ(559 Nathan Abbott Way, Stanford, California 94305, USA)に書簡を送付してください。</para> |
| <para>名称「FindBugs」および FindBugs のロゴは、メリーランド大学の登録商標です。</para> |
| </legalnotice> |
| |
| <edition>3.0.1</edition> |
| |
| <pubdate>12:37:51 EST, 06 March, 2015 (翻訳 2014年7月)</pubdate> |
| |
| </bookinfo> |
| |
| <!-- |
| ************************************************************************** |
| Introduction |
| ************************************************************************** |
| --> |
| |
| <chapter id="introduction"> |
| <title>はじめに</title> |
| |
| <para>&FindBugs;™ は、Java プログラムの中のバグを見つけるプログラムです。このプログラムは、「バグ パターン」の実例を探します。「バグ パターン」とは、エラーとなる可能性の高いコードの事例です。</para> |
| |
| <para>この文書は、&FindBugs; バージョン 3.0.1 について説明してます。私たちは、 &FindBugs; に対するフィードバックを心待ちにしています。どうぞ、 <ulink url="http://findbugs.sourceforge.net">&FindBugs; Web ページ</ulink> にアクセスしてください。&FindBugs; についての最新情報、連絡先および &FindBugs; メーリングリストなどのサポート情報を入手することができます。</para> |
| |
| <sect1> |
| <title>必要条件</title> |
| <para>&FindBugs; を使用するには、 <ulink url="http://java.sun.com/j2se">Java 2 Standard Edition</ulink>, バージョン 1.5 以降のバージョンと互換性のあるランタイム環境が必要です。&FindBugs; は、プラットフォーム非依存であり、 GNU/Linux 、 Windows 、 MacOS X プラットフォーム上で動作することが知られています。</para> |
| |
| <para>&FindBugs; を使用するためには、少なくとも 512 MB のメモリが必要です。巨大なプロジェクトを解析するためには、それより多くのメモリが必要とされることがあります。</para> |
| </sect1> |
| |
| </chapter> |
| |
| <!-- |
| ************************************************************************** |
| Installing FindBugs |
| ************************************************************************** |
| --> |
| |
| <chapter id="installing"> |
| <title>&FindBugs;™ のインストール</title> |
| |
| <para>この章では、 &FindBugs; のインストール方法を説明します。</para> |
| |
| <sect1> |
| <title>配布物の展開</title> |
| |
| <para>&FindBugs; をインストールする最も簡単な方法は、バイナリ配布物をダウンロードすることです。 バイナリ配布物は、 <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-3.0.1.tar.gz?download">gzipped tar 形式</ulink> および <ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-3.0.1.zip?download">zip 形式</ulink> がそれぞれ入手可能です。バイナリ配布物をダウンロードしてきたら、それを任意のディレクトリーに展開します。</para> |
| |
| <para>gzipped tar 形式配布物の展開方法例:<screen> |
| <prompt>$ </prompt><command>gunzip -c findbugs-3.0.1.tar.gz | tar xvf -</command> |
| </screen> |
| </para> |
| |
| <para>zip 形式配布物の展開方法例:<screen> |
| <prompt>C:\Software></prompt><command>unzip findbugs-3.0.1.zip</command> |
| </screen> |
| </para> |
| |
| <para>バイナリ配布物の展開すると、通常は <filename class="directory">findbugs-3.0.1</filename> ディレクトリーが作成されます。例えば、ディレクトリー <filename class="directory">C:\Software</filename> でバイナリ配布物を展開すると、ディレクトリー <filename class="directory">C:\Software\findbugs-3.0.1</filename> に &FindBugs; は展開されます。このディレクトリーが &FindBugs; のホームディレクトリーになります。このマニュアルでは、このホームディレクトリーを &FBHome; (Windowsでは &FBHomeWin;) を用いて参照します。</para> |
| </sect1> |
| |
| </chapter> |
| |
| <!-- |
| ************************************************************************** |
| Compiling FindBugs from Source |
| ************************************************************************** |
| --> |
| |
| <chapter id="building"> |
| <title>&FindBugs;™ のソールからのビルド</title> |
| |
| <para>この章では、 &FindBugs; をソースコードからビルドする方法を説明します。&FindBugs; を修正することに興味がないのであれば、 <link linkend="running">次の章</link> に進んでください。</para> |
| |
| <sect1> |
| <title>前提条件</title> |
| |
| <para>ソースから &FindBugs; をコンパイルするためには、以下のものが必要です。<itemizedlist> |
| <listitem> |
| <para><ulink url="http://prdownloads.sourceforge.net/findbugs/findbugs-3.0.1-source.zip?download">&FindBugs; のソース配布物</ulink> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <ulink url="http://java.sun.com/j2se/">JDK 1.5.0 またはそれ以降</ulink> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <ulink url="http://ant.apache.org/">Apache &Ant;</ulink>, バージョン 1.6.3 またはそれ以降</para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| |
| <warning> |
| <para>Redhat Linux システムの <filename>/usr/bin/ant</filename> に同梱されている &Ant; のバージョンでは、 &FindBugs; のコンパイルは<emphasis>うまくできません</emphasis>。<ulink url="http://ant.apache.org/">&Ant; web サイト</ulink>からバイナリ配布物をダウンロードしてインストールすることを推奨します。&Ant; を実行する場合は、 環境変数 <replaceable>JAVA_HOME</replaceable> が JDK 1.5 (またはそれ以降)をインストールしたディレクトリーを指していることを確認してください。</para> |
| </warning> |
| |
| <para>体裁の整った &FindBugs; のドキュメントを生成したい場合は、以下のソフトウェアも必要となります:<itemizedlist> |
| <listitem> |
| <para><ulink url="http://docbook.sourceforge.net/projects/xsl/index.html">DocBook XSL スタイルシート</ulink>。&FindBugs; のマニュアルを HTML に変換するのに必要です。</para> |
| </listitem> |
| <listitem> |
| <para><ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT プロセッサー</ulink>。(同様に、 &FindBugs; のマニュアルを HTML に変換するのに必要です。)</para> |
| </listitem> |
| <!-- |
| <listitem> |
| <para> |
| </para> |
| </listitem> |
| --> |
| </itemizedlist> |
| </para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>ソース配布物の展開</title> |
| <para>ソース配布物をダウンロードした後に、それを作業用ディレクトリーに展開する必要があります。通常は、次のようなコマンドで展開を行います:<screen> |
| <prompt>$ </prompt><command>unzip findbugs-3.0.1-source.zip</command> |
| </screen> |
| |
| </para> |
| </sect1> |
| |
| <sect1> |
| <title><filename>local.properties</filename> の修正</title> |
| <para>FindBugs のドキュメントをビルドするためには、 <filename>local.properties</filename> ファイルを修正する必要があります。このファイルは、 &FindBugs; をビルドする際に <ulink url="http://ant.apache.org/">&Ant;</ulink> <filename>build.xml</filename> ファイルが参照します。FindBugs のドキュメントをビルドしない場合は、このファイルは無視してもかまいません。</para> |
| |
| <para><filename>local.properties</filename> での定義は、 <filename>build.properties</filename> ファイルでの定義に優先します。<filename>build.properties</filename> は次のような内容です:<programlisting> |
| <![CDATA[ |
| # User Configuration: |
| # This section must be modified to reflect your system. |
| |
| local.software.home =/export/home/daveho/linux |
| |
| # Set this to the directory containing the DocBook Modular XSL Stylesheets |
| # from http://docbook.sourceforge.net/projects/xsl/ |
| |
| xsl.stylesheet.home =${local.software.home}/docbook/docbook-xsl-1.71.1 |
| |
| # Set this to the directory where Saxon (http://saxon.sourceforge.net/) |
| # is installed. |
| |
| saxon.home =${local.software.home}/java/saxon-6.5.5 |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para><varname>xsl.stylesheet.home</varname> プロパティーには、<ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook Modular XSL スタイルシート</ulink>がインストールしてあるディレクトリーの絶対パスを指定します。&FindBugs; ドキュメントを生成しようと考えている場合にのみ、このプロパティーを指定する必要があります。</para> |
| |
| <para><varname>saxon.home</varname> プロパティーには、<ulink url="http://saxon.sourceforge.net/">&Saxon; XSLT プロセッサー</ulink>がインストールしてあるディレクトリーの絶対パスを指定します。&FindBugs; ドキュメントを生成しようと考えている場合にのみ、このプロパティーを指定する必要があります。</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>&Ant; の実行</title> |
| |
| <para>ソース配布物の展開、 &Ant; のインストール、<filename>build.properties</filename>(<filename>local.properties</filename>) の修正 (これは任意) およびツール (&Saxon; など)の環境構築ができれば、 &FindBugs; をビルドするための準備は完了です。&Ant; の起動する方法は、単にコマンドを実行するだけです。<screen> |
| <prompt>$ </prompt><command>ant <replaceable>target</replaceable></command> |
| </screen><replaceable>target</replaceable> には以下のいずれかを指定します: <variablelist> <varlistentry> <term><command>build</command></term> |
| <listitem> |
| <para>このターゲットは、 &FindBugs; のコードをコンパイルします。これは、デフォルトのターゲットです。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>docs</command></term> |
| <listitem> |
| <para>このターゲットは、ドキュメントの整形を行います(また、副作用としていくつかのソースのコンパイルも行います。)</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>runjunit</command></term> |
| <listitem> |
| <para>このターゲットは、コンパイルを行い &FindBugs; が持っている JUnit テストを実行します。ユニットテストが失敗した場合は、エラーメッセージが表示されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>bindist</command></term> |
| <listitem> |
| <para>&FindBugs; のバイナリ配布物を構築します。このターゲットは、 <filename>.zip</filename> および <filename>.tar.gz</filename> のアーカイブをそれぞれ作成します。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| |
| <para>&Ant; コマンドの実行後、次のような出力が表示されるはずです。 (この前に &Ant; が実行したタスクに関するメッセージもいくらか出力されます。):<screen> |
| <computeroutput> |
| BUILD SUCCESSFUL |
| Total time: 17 seconds |
| </computeroutput> |
| </screen> |
| </para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>ソースディレクトリーからの &FindBugs;™ の実行</title> |
| <para><command>build</command> ターゲットの実行が終了すると、バイナリ配布物と同様の状態が作業ディレクトリーに構築されるように &FindBugs; の&Ant; ビルドスクリプトは記述されています。したがって、<xref linkend="running"/> の &FindBugs; の実行に関する情報はソース配布物の場合にも応用できます。</para> |
| </sect1> |
| |
| </chapter> |
| |
| |
| <!-- |
| ************************************************************************** |
| Running FindBugs |
| ************************************************************************** |
| --> |
| |
| <chapter id="running"> |
| <title>&FindBugs;™ の実行</title> |
| |
| <para>&FindBugs; には2つのユーザーインタフェースがあります。すなわち、グラフィカルユーザーインタフェース (GUI) および コマンドラインインタフェースです。この章では、それぞれのインタフェースの実行方法について説明します。</para> |
| |
| <warning> |
| <para>この章は、現在書き直し中です。書き直しはまだ完了していません。</para> |
| </warning> |
| |
| <!-- |
| <sect1> |
| <title>Executing the &FindBugs;™ GUI</title> |
| </sect1> |
| --> |
| |
| <sect1> |
| <title>クイック・スタート</title> |
| <para>Windows システムで &FindBugs; を起動する場合は、 <filename>&FBHomeWin;\lib\findbugs.jar</filename> ファイルをダブルクリックしてください。 &FindBugs; GUI が起動します。</para> |
| |
| <para>Unix 、 Linux または Mac OS X システムの場合は、<filename>&FBHome;/bin/findbugs</filename> スクリプトを実行するか、以下のコマンドを実行します。<screen> |
| <command>java -jar &FBHome;/lib/findbugs.jar</command></screen>これで、 &FindBugs; GUI が起動します。</para> |
| |
| <para>GUI の使用方法については、 <xref linkend="gui"/> を参照してください。</para> |
| </sect1> |
| |
| <sect1> |
| |
| <title>&FindBugs; の起動</title> |
| |
| <para>このセクションでは、 &FindBugs; の起動方法を説明します。&FindBugs; を起動するには2つの方法があります。すなわち、直接起動する方法、および、ラップしているスクリプトを使用する方法です。</para> |
| |
| |
| <sect2 id="directInvocation"> |
| <title>&FindBugs; の直接起動</title> |
| |
| <para>最初に述べる &FindBugs; の起動方法は、 <filename>&FBHome;/lib/findbugs.jar</filename> を直接実行する方法です。JVM (<command>java</command>) 実行プログラムの <command>-jar</command> コマンドラインスイッチを使用します。(&FindBugs;のバージョンが 1.3.5 より前の場合は、ラップしているスクリプトを使用する必要があります。)</para> |
| |
| <para>&FindBugs; を直接起動するための、一般的な構文は以下のようになります。<screen> |
| <command>java <replaceable>[JVM 引数]</replaceable> -jar &FBHome;/lib/findbugs.jar <replaceable>オプション…</replaceable></command> |
| </screen> |
| </para> |
| |
| <!-- |
| <para> |
| By default, executing <filename>findbugs.jar</filename> runs the |
| &FindBugs; graphical user interface (GUI). On windows systems, |
| you can double-click on <filename>findbugs.jar</filename> to launch |
| the GUI. From a command line, the command |
| <screen> |
| java -jar <replaceable>&FBHome;</replaceable>/lib/findbugs.jar</screen> |
| will launch the GUI. |
| </para> |
| --> |
| |
| <sect3 id="chooseUI"> |
| <title> ユーザーインタフェースの選択</title> |
| |
| <para>1 番目のコマンドラインオプションは、起動する &FindBugs; ユーザーインタフェースを選択するためのものです。指定可能な値は次の通りです:</para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <command>-gui</command>: グラフィカルユーザーインタフェース (GUI) を起動します。</para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <command>-textui</command>: コマンドラインインタフェースを起動します。</para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <command>-version</command>: &FindBugs; のバージョン番号を表示します。</para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <command>-help</command>: &FindBugs; コマンドラインインタフェースのヘルプ情報を表示します。</para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| <command>-gui1</command>: 最初に作成された &FindBugs; グラフィカルユーザーインタフェース(すでに廃止されサポートされていない)を起動します。</para> |
| </listitem> |
| </itemizedlist> |
| |
| </sect3> |
| |
| <sect3 id="jvmArgs"> |
| <title>Java 仮想マシン (JVM) 引数</title> |
| |
| <para>&FindBugs; を起動する際に有用な Java 仮想マシン 引数をいくつか紹介します。</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><command>-Xmx<replaceable>NN</replaceable>m</command></term> |
| <listitem> |
| <para>Java ヒープサイズの最大値を <replaceable>NN</replaceable> メガバイトに設定します。&FindBugs; は一般的に大容量のメモリサイズを必要とします。大きなプロジェクトでは、 1500 メガバイトを使用することも珍しくありません。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-D<replaceable>name</replaceable>=<replaceable>value</replaceable></command></term> |
| <listitem> |
| <para>Java システムプロパティーを設定します。例えば、引数 <command>-Duser.language=ja</command> を使用すると GUI 文言が日本語で表示されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <!-- |
| <varlistentry> |
| <term></term> |
| <listitem> |
| <para> |
| </para> |
| </listitem> |
| </varlistentry> |
| --> |
| </variablelist> |
| </sect3> |
| |
| </sect2> |
| |
| <sect2 id="wrapperScript"> |
| <title>ラップしているスクリプトを使用した &FindBugs; の起動</title> |
| |
| <para>&FindBugs; を起動するもうひとつの方法は、ラップしているスクリプトを使用する方法です。</para> |
| |
| <para>Unix 系のシステムにおいては、次のようなコマンドでラップしているスクリプトを起動します :<screen> |
| <prompt>$ </prompt><command>&FBHome;/bin/findbugs <replaceable>オプション…</replaceable></command> |
| </screen> |
| </para> |
| |
| <para>Windows システムにおいては、ラップしているスクリプトを起動するコマンドは次のようになります。<screen> |
| <prompt>C:\My Directory></prompt><command>&FBHomeWin;\bin\findbugs.bat <replaceable>オプション…</replaceable></command> |
| </screen> |
| </para> |
| |
| <para>Unix 系システム および Windows システムのどちらにおいても、ディレクトリー <filename><replaceable>$FINDBUGS_HOME</replaceable>/bin</filename> を環境変数 <filename>PATH</filename> に追加するだけで、 <command>findbugs</command> コマンドを使用して FindBugs を起動することができます。</para> |
| |
| <sect3 id="wrapperOptions"> |
| <title>ラップしているスクリプトのコマンドラインオプション</title> |
| <para>&FindBugs; のラップしているスクリプトは、次のようなコマンドラインオプションをサポートしています。これらのコマンドラインオプションは &FindBugs; プログラム 自体が操作するのでは<emphasis>なく</emphasis>、どちらかといえば、ラップしているスクリプトの方が処理を行います。</para> |
| <variablelist> |
| <varlistentry> |
| <term><command>-jvmArgs <replaceable>引数</replaceable></command></term> |
| <listitem> |
| <para>JVM に受け渡される引数を指定します。例えば、次のような JVM プロパティが設定できます:<screen> |
| <prompt>$ </prompt><command>findbugs -textui -jvmArgs "-Duser.language=ja" <replaceable>myApp.jar</replaceable></command> |
| </screen> |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-javahome <replaceable>ディレクトリー</replaceable></command></term> |
| <listitem> |
| <para>&FindBugs; の実行に使用する JRE (Java ランタイム環境) がインストールされているディレクトリーを指定します。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-maxHeap <replaceable>サイズ</replaceable></command></term> |
| <listitem> |
| <para>Java ヒープサイズの最大値をメガバイト単位で指定します。デフォルトは、 256 です。巨大なプログラムやライブラリを分析するには、もっと大きなメモリー容量が必要になる可能性があります。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-debug</command></term> |
| <listitem> |
| <para>ディテクタ実行およびクラス分析のトレース情報が標準出力に出力されます。分析が予期せず失敗した際の、トラブルシューティングに有用です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-property</command> <replaceable>name=value</replaceable></term> |
| <listitem> |
| <para>このオプションを使用してシステムプロパティーを設定することができます。 &FindBugs; はシステムプロパティーを使用して分析特性の設定を行います。<xref linkend="analysisprops"/> を参照してください。このオプションを複数指定して、複数のシステムプロパティを設定することが可能です。注: Windows の多くのバージョンでは、 <replaceable>name=value</replaceable> 文字列を引用符で囲む必要があります。</para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| |
| </sect3> |
| |
| </sect2> |
| |
| </sect1> |
| |
| <sect1 id="commandLineOptions"> |
| <title>コマンドラインオプション</title> |
| |
| <!-- |
| <para> |
| |
| There are two ways to invoke &FindBugs;. The first invokes the the Graphical User Interface (GUI): |
| |
| <screen> |
| <prompt>$ </prompt><command>findbugs <replaceable>[standard options]</replaceable> <replaceable>[GUI options]</replaceable></command> |
| </screen> |
| |
| The second invokes the Command Line Interface (Text UI): |
| |
| <screen> |
| <prompt>$ </prompt><command>findbugs -textui <replaceable>[standard options]</replaceable> <replaceable>[Text UI options]</replaceable></command> |
| </screen> |
| </para> |
| --> |
| |
| <para>このセクションでは、 &FindBugs; がサポートするコマンドラインオプションについて説明します。ここで示すコマンドラインオプションは、 &FindBugs; 直接起動、または、ラップしているスクリプトによる起動で使用できます。</para> |
| |
| <sect2> |
| <title>共通のコマンドラインオプション</title> |
| |
| <para>ここで示すオプションは、 GUI および コマンドラインインタフェースの両方で使用できます。</para> |
| |
| <variablelist> |
| |
| <varlistentry> |
| <term><command>-effort:min</command></term> |
| <listitem> |
| <para>このオプションを指定すると、精度を上げるために大量のメモリーを消費する分析が無効になります。&FindBugs; の実行時にメモリー不足になったり、分析を完了するまでに異常に長い時間がかかる場合に試してみてください。</para> |
| </listitem> |
| </varlistentry> |
| |
| |
| <varlistentry> |
| <term><command>-effort:max</command></term> |
| <listitem> |
| <para>精度が高く、より多くのバグを検出する分析を有効にします。ただし、多くのメモリー容量を必要とし、また、完了までの時間が多くかかる可能性があります。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-project</command> <replaceable>project</replaceable></term> |
| <listitem> |
| <para>分析するプロジェクトを指定します。指定するプロジェクトファイルには、 GUI を使って作成したものを使用してください。ファイルの拡張子は、一般的には <filename>.fb</filename> または <filename>.fbp</filename> です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <!-- |
| <varlistentry> |
| <term><command></command></term> |
| <listitem> |
| <para> |
| |
| </para> |
| </listitem> |
| </varlistentry> |
| --> |
| |
| </variablelist> |
| |
| </sect2> |
| |
| <sect2> |
| <title>GUI オプション</title> |
| |
| <para>ここで示すオプションは、グラフィカルユーザーインタフェースでのみ使用できます。<variablelist> <varlistentry> <term><command>-look:</command><replaceable>plastic|gtk|native</replaceable></term> |
| <listitem> |
| <para>Swing のルック・アンド・フィールを設定します。</para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>テキストユーザーインタフェースオプション</title> |
| |
| <para>ここで示すオプションは、テキストユーザーインタフェースでのみ使用できます。</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><command>-sortByClass</command></term> |
| <listitem> |
| <para>報告されるバグ検索結果をクラス名でソートします。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-include</command> <replaceable>filterFile.xml</replaceable></term> |
| <listitem> |
| <para><replaceable>filterFile.xml</replaceable> で指定したフィルターに一致したバグ検索結果のみ報告されます。<xref linkend="filter"/> を参照してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-exclude</command> <replaceable>filterFile.xml</replaceable></term> |
| <listitem> |
| <para><replaceable>filterFile.xml</replaceable> で指定したフィルターに一致したバグ検索結果は報告されません。<xref linkend="filter"/> を参照してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-onlyAnalyze</command> <replaceable>com.foobar.MyClass,com.foobar.mypkg.*</replaceable></term> |
| <listitem> |
| <para>コンマ区切りで指定したクラスおよびパッケージのみに限定して、バグ検出の分析を行うようにします。フィルターと違って、このオプションを使うと一致しないクラスおよびパッケージに対する分析の実行を回避することができます。大きなプロジェクトにおいて、このオプションを活用すると分析にかかる時間を大きく削減することができる可能性があります。(しかしながら、アプリケーションの全体で実行していないために不正確な結果を出してしまうディテクタがある可能性もあります。) クラスはパッケージも含んだ完全な名前を指定する必要があります。また、パッケージは、 Java の <literal>import</literal> 文でパッケージ下のすべてのクラスをインポートするときと同じ方法で指定します。 (すなわち、パッケージの完全な名前に <literal>.*</literal> を付け加えた形です。)<literal>.*</literal> の代わりに <literal>.-</literal> を指定すると、サブパッケージも含めてすべてが分析されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-low</command></term> |
| <listitem> |
| <para>すべてのバグが報告されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-medium</command></term> |
| <listitem> |
| <para>優先度 (中) および優先度 (高) のバグが報告されます。これは、デフォルトの設定値です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-high</command></term> |
| <listitem> |
| <para>優先度 (高) のバグのみが報告されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-relaxed</command></term> |
| <listitem> |
| <para>手抜き報告モードです。このオプションを指定すると、多くのディテクタにおいて 誤検出を回避するためのヒューリスティック機能が抑止されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-xml</command></term> |
| <listitem> |
| <para>バグ報告が XML で作成されます。作成された XML データは 、後で GUI で見ることができます。このオプションは <command>-xml:withMessages</command> と指定することもできます。こうすると 出力 XML には 各バグに関して人間に読むことができるメッセージが含まれるようになります。このオプションで作成された XML ファイルは 報告書に変換するのが簡単です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-html</command></term> |
| <listitem> |
| <para>HTML 出力が生成されます。デフォルトでは &FindBugs; は <filename>default.xsl</filename> <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink> スタイルシートを使用して HTML 出力を生成します: このファイルは、 <filename>findbugs.jar</filename> の中、または、 &FindBugs; のソース配布物もしくはバイナリ配布物の中にあります。このオプションには、次のようなバリエーションも存在します。すなわち、 <command>-html:plain.xsl</command> 、 <command>-html:fancy.xsl</command> および <command>-html:fancy-hist.xsl</command> です。<filename>plain.xsl</filename> スタイルシートは Javascript や DOM を利用しません。したがって、古いWeb ブラウザ使用時や印刷時にも比較的うまく表示されるでしょう。<filename>fancy.xsl</filename> スタイルシートは DOM と Javascript を利用してナビゲーションを行います。また、ビジュアル表示に CSS を使用します。<command>fancy-hist.xsl</command> は <command>fancy.xsl</command> スタイルシートを更に進化させたものです。DOM や Javascript をふんだんに駆使して、バグの一覧を動的にフィルタリングします。</para> |
| |
| <para>ユーザー自身の XSLT スタイルシートを用いて HTML への変換を行いたい場合は、 <command>-html:<replaceable>myStylesheet.xsl</replaceable></command> のように指定してください。ここで、 <replaceable>myStylesheet.xsl</replaceable> はユーザーが使用したいスタイルシートのファイル名です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-emacs</command></term> |
| <listitem> |
| <para>バグ報告が Emacs 形式で作成されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-xdocs</command></term> |
| <listitem> |
| <para>バグ報告が xdoc XML 形式で作成されます。Apache Mavenで使用できます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-output</command> <replaceable>ファイル名</replaceable></term> |
| <listitem> |
| <para>指定したファイルに出力結果が作成されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-outputFile</command> <replaceable>ファイル名</replaceable></term> |
| <listitem> |
| <para>この引数は、使用すべきではありません。代わりに、 <command>-output</command> を使用してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-nested</command><replaceable>[:true|false]</replaceable></term> |
| <listitem> |
| <para>このオプションは、ファイルやディレクトリーの中で入れ子になった jar および zip ファイルを分析するかどうかを指定します。デフォルトでは、入れ子になった jar および zip ファイルも分析します。入れ子になった jar および zip ファイルの分析するを無効にする場合は、 <command>-nested:false</command> をコマンドライン引数に追加してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-auxclasspath</command> <replaceable>クラスパス</replaceable></term> |
| <listitem> |
| <para>分析時に使用する補助クラスパスを設定します。分析するプログラムで使用するjarファイルやクラスディレクトリーをすべて指定してください。補助クラスパスに指定したクラスは分析の対象にはなりません。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-auxclasspathFromInput</command> </term> |
| <listitem> |
| <para>分析時に使用する補助クラスパスを標準入力から読み込みます。標準入力の各行が分析時に使用する補助クラスパスに追加されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-auxclasspathFromFile</command> <replaceable>ファイルパス</replaceable></term> |
| <listitem> |
| <para>分析時に使用する補助クラスパスをファイルから読み込みます。ファイルの各行が分析時に使用する補助クラスパスに追加されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-analyzeFromFile</command> <replaceable>ファイルパス</replaceable></term> |
| <listitem> |
| <para>分析対象ファイルをファイルから読み込みます。ファイルの各行が分析対象クラスパスに追加されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>-userPrefs</command> <replaceable>edu.umd.cs.findbugs.core.prefs</replaceable></term> |
| <listitem> |
| <para>ユーザー設定ファイルのパスを設定します。ユーザー設定ファイルの内容で、他のオプションの一部を上書きすることができます。 |
| <literal>userPrefs</literal> を一番目の引数に指定した場合は、後続のオプションの方がユーザー設定ファイルの内容に優先します。 |
| <literal>userPrefs</literal> を最後の引数に指定した場合は、ユーザー設定ファイルの内容の方が前に指定したオプションに優先します。 |
| このオプションを設けた背景・理由は、 Eclipse プロジェクトの FindBugs の設定をコマンドライン実行で再利用するためです。</para> |
| </listitem> |
| </varlistentry> |
| |
| <!-- |
| <varlistentry> |
| <term><command></command> <replaceable></replaceable></term> |
| <listitem> |
| <para> |
| </para> |
| </listitem> |
| </varlistentry> |
| --> |
| |
| </variablelist> |
| |
| </sect2> |
| </sect1> |
| |
| |
| </chapter> |
| |
| <chapter id="gui"> |
| <title>&FindBugs; GUI の使用方法</title> |
| |
| <para>この章では、&FindBugs; グラフィカルユーザーインタフェース (GUI) の使用方法を説明します。</para> |
| |
| <sect1> |
| <title>プロジェクトの作成</title> |
| <para><command>findbugs</command> コマンドで &FindBugs; を起動してから、メニューで <menuchoice><guimenu>File</guimenu><guimenuitem>New Project</guimenuitem></menuchoice> を選択してください。そうすると、次のようなダイアログが表示されます:<mediaobject> |
| <imageobject> |
| <imagedata fileref="project-dialog.png"/> |
| </imageobject> |
| </mediaobject> |
| </para> |
| |
| <para>「Classpath to analyze」の横にある 「Add」ボタンを押すと、バグを分析する java クラスを含んでいる Java アーカイブファイル (zip, jar, ear, or war file) を選択して指定できます。複数の アーカイブ/ディレクトリーを追加することが可能です。</para> |
| |
| <para>また、分析を行う Java アーカイブのソースコードを含んだソースディレクトリーを指定することもできます。そうすると、バグの可能性があるソースコードの場所が、&FindBugs; 上でハイライトして表示されます。ソースディレクトリーは、Java パッケージ階層のルートディレクトリーを指定する必要があります。例えば、ユーザのアプリケーションが <varname>org.foobar.myapp</varname> パッケージの中にある場合は、 <filename class="directory">org</filename> ディレクトリーの親ディレクトリーをソースディレクトリーリストに指定する必要があります。</para> |
| |
| <para>もうひとつ、任意指定の手順があります。それは、補助用の Jar ファイルおよびディレクトリーを 「Auxiliary classpath locations」のエントリーに追加することです。分析するアーカイブ/ディレクトリーにも標準の実行時クラスパスにも含まれていないクラスを、分析するアーカイブ/ディレクトリーが参照している場合は、この項目を設定した方がいいでしょう。クラス階層に関する情報を使用するバグディテクタが、 &FindBugs; にはいくつかあります。したがって、&FindBugs; が分析を行うクラスの完全なクラス階層を参照できれば、より正確な分析結果を取得することができます。</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>分析の実行</title> |
| <para>アーカイブ、ディレクトリーおよびソースディレクトリーの指定ができれば、「Analyze」ボタンを押して Jar ファイルに含まれるクラスに対する分析を実行します。巨大なプロジェクトを古いコンピュータ上で実行すると、かなりの時間(数十分)がかかることに注意してください。大容量メモリである最近のコンピュータなら、大きなプログラムであっても数分程度で分析できます。</para> |
| </sect1> |
| |
| <sect1> |
| <title>結果の閲覧</title> |
| |
| <para>分析が完了すると、次のような画面が表示されます :<mediaobject> |
| <imageobject> |
| <imagedata fileref="example-details.png"/> |
| </imageobject> |
| </mediaobject> |
| </para> |
| |
| <para>左上のペインにはバグ階層ツリーが表示されます。これは、分析でみつかったバグの検索結果が階層的に表示されたものです。</para> |
| |
| <para>上部のペインでバグ検索結果を選択すると、下部の「Details」ペインにバグの詳細説明が表示されます。更に、ソースがみつかれば、右上のソースコードペインにバグの出現箇所に該当するソースコードが表示されます。上図の例で表示されているバグは、ストリームオブジェクトがクローズされていないというものです。ソースコード・ウィンドウにおいて当該ストリームオブジェクトを生成している行がハイライトされています。</para> |
| |
| <para>バグの検索結果に対してテキストで注釈を入れることができます。階層ツリー図のすぐ下にあるテキストボックスに注釈を入力してください。記録しておきたい情報を何でも自由に入力することができます。バグ結果ファイルの保存および読み込みを行ったときに、注釈も保存されます。</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>保存と読み込み</title> |
| |
| <para>メニュー項目から <menuchoice><guimenu>File</guimenu><guimenuitem>Save as...</guimenuitem></menuchoice> を選択すると、ユーザーの作業結果を保存することができます。「Save as...」ダイアログにあるドロップダウン・リストの中から「FindBugs analysis results (.xml)」を選択ことで、ユーザーが指定した jar ファイルリストやバグ検索結果などの作業結果を保存することができます。また、jar ファイルリストのみを保存する選択肢 (「FindBugs project file (.fbp)」) やバグ検索結果のみを保存する選択肢 (「FindBugs analysis file (.fba)」) もあります。保存したファイルは、メニュー項目から <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> を選択することで、読み込むことができます。</para> |
| |
| </sect1> |
| |
| <!-- |
| <sect1 id="textui"> |
| <title>Using the &FindBugs;™ Command Line Interface</title> |
| |
| <para> |
| The &FindBugs; Command Line Interface (or Text UI) can be used to |
| analyze an application for bugs non-interactively. Each bug instance will be |
| reported on a single line. All output is written to the standard output file descriptor. |
| <xref linkend="filter" /> explains how bug reports may be filtered in order |
| to get only the output you're interested in. |
| </para> |
| |
| <para> |
| See <xref linkend="commandLineOptions" /> for a description of how to invoke the |
| Command Line Interface. |
| </para> |
| </sect1> |
| --> |
| |
| </chapter> |
| |
| <!-- |
| ************************************************************************** |
| Using the FindBugs Ant task |
| ************************************************************************** |
| --> |
| |
| <chapter id="anttask"> |
| <title>&FindBugs;™ &Ant; タスクの使用方法</title> |
| |
| <para>この章では、 &FindBugs; を <ulink url="http://ant.apache.org/">&Ant;</ulink> のビルドスクリプトに組み入れる方法について説明します。 <ulink url="http://ant.apache.org/">&Ant;</ulink> は、ビルドや配備を行うことができる Java でよく使用されるツールです。&FindBugs; &Ant; タスクを使用すると、 ビルドスクリプトを作成して機械的に &FindBugs; による Java コードの分析を実行することができます。</para> |
| |
| <para>この &Ant; タスクは、 Mike Fagan 氏の多大な貢献によるものです。</para> |
| |
| <sect1> |
| <title>&Ant; タスクのインストール</title> |
| |
| <para>&Ant; タスクのインストールは、 <filename>&FBHome;/lib/findbugs-ant.jar</filename> を &Ant; インストールディレクトリーの<filename>lib</filename> サブディレクトリーにコピーするだけです。<note> |
| <para>使用する &Ant; タスクと &FindBugs; 本体は、同梱されていた同じバージョンのものを使用することを強く推奨します。別のバージョンの &FindBugs; に含まれていた &Ant; タスク Jar ファイルでの動作は保証しません。</para> |
| </note> |
| </para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>build.xml の書き方</title> |
| |
| <para>&FindBugs; を <filename>build.xml</filename> (&Ant; ビルドスクリプト) に組み入れるためにはまず、タスク定義を記述する必要があります。タスク定義は次のように記述します。:<screen> |
| <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"/> |
| </screen>タスク定義は、 <literal>findbugs</literal> 要素を <filename>build.xml</filename> 上に記述したとき、そのタスクの実行に使用されるクラスを指定します。</para> |
| |
| <para>タスク定義の記述をすれば、<literal>findbugs</literal> タスクを使ってターゲットを定義できます。次に示すのは、 Apache <ulink url="http://jakarta.apache.org/bcel/">BCEL</ulink> ライブラリーを分析する場合を想定した <filename>build.xml</filename> の記述例です。<screen> |
| <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> |
| </screen><literal>findbugs</literal> 要素には、 <literal>home</literal> 属性が必須です。 &FindBugs; のインストールディレクトリーすなわち &FBHome; の値を設定します。<xref linkend="installing"/> を参照してください。</para> |
| |
| <para>このターゲットは <filename>bcel.jar</filename> に対して &FindBugs; を実行します。この Jar ファイルは、 BCEL ビルドスクリプトによって作成されるものです。(上記のターゲットが「jar」ターゲットに依存している (depends) と設定することにより、 &FindBugs; が実行される前に当該ライブラリーが完全にコンパイルされていることを保証しています。) &FindBugs; の出力は、 XML 形式で <filename>bcel-fb.xml</filename> ファイルに保存されます。補助 Jar ファイル <filename>Regex.jar</filename> を aux classpath に記述しています。なぜなら、当該 Jar ファイルが BCEL メイン･ライブラリーから参照されるからです。source path を指定することで、保存されるバグデータに BCEL ソースコードへの正確な参照が記述されます。</para> |
| </sect1> |
| |
| <sect1> |
| <title>タスクの実行</title> |
| |
| <para>コマンドラインから &Ant; を起動する例を次に示します。前述の <literal>findbugs</literal> ターゲットを使用しています。<screen> |
| <prompt>[daveho@noir]$</prompt> <command>ant findbugs</command> |
| 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 |
| </screen>この事例においては、XML ファイルでバグ検索結果を保存しているので、 &FindBugs; GUI を使って結果を参照することができます。 <xref linkend="running"/> を参照してください。</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>パラメーター</title> |
| |
| <para>このセクションでは、 &FindBugs; タスクを使用する際に、指定することができるパラメーターについて説明します。 |
| |
| <variablelist> |
| |
| <varlistentry> |
| <term><literal>class</literal></term> |
| <listitem> |
| <para>任意指定のネストされる要素です。分析の対象となるクラス群を指定します。 |
| <literal>class</literal> 要素には <literal>location</literal> 属性の指定が必須です。 |
| 分析対象となるアーカイブファイル (jar, zip, 他)、ディレクトリーまたはクラスファイルの名前を記述します。 |
| 1 つの <literal>findbugs</literal> 要素に対して、複数の <literal>class</literal> 子要素を指定することができます。 |
| </para> |
| <para><literal>class</literal> 要素の指定を置き換えるまたは追加する形で、 &FindBugs; タスクに1個以上の <literal>fileset</literal> 要素を記述することで |
| 分析するファイル群を指定することができます。 |
| 例えば、 fileset において特定のディレクトリにある全ての jar ファイルを分析対象に指定することができます。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>auxClasspath</literal></term> |
| <listitem> |
| <para>任意指定のネストされる要素です。分析対象のライブラリーまたはアプリケーションによって使用されているが分析の対象にはしたくないクラスを含んでいるクラスパス (Jar ファイルまたはディレクトリー) を指定します。 &Ant; の Java タスクにある <literal>classpath</literal> 要素 と同じ方法で指定することができます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>sourcePath</literal></term> |
| <listitem> |
| <para>任意指定のネストされる要素です。分析対象 Java コードのコンパイル時に使用したソースファイルを含んでいるソースディレクトリーへのパスを指定します。ソースパスを指定することにより、生成される XML のバグ出力結果に完全なソース情報をもたせることができ、後になって GUI で参照することができます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>home</literal></term> |
| <listitem> |
| <para>必須属性です。&FindBugs; がインストールされているディレクトリー名を設定します。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>quietErrors</literal></term> |
| <listitem> |
| <para>任意指定のブール値属性です。true を設定すると、深刻な分析エラー発生やクラスがみつからないといった情報が &FindBugs; 出力に記録されません。デフォルトは、 false です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>reportLevel</literal></term> |
| <listitem> |
| <para> |
| 任意指定の属性です。報告される問題の信頼度・優先度のしきい値を指定します。 |
| 「low」に設定すると、バグ報告が信頼度により除外されることはありません。 |
| 「medium」 (デフォルト) に設定すると、信頼度(低)の問題が除外されます。 |
| 「high」に設定すると、信頼度(高) のバグのみが報告されます。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>output</literal></term> |
| <listitem> |
| <para>任意指定の属性です。出力形式を指定します。「xml」 (デフォルト) に設定すると、出力は XML 形式になります。「xml:withMessages」 に設定すると、出力は人間が読めるメッセージ が追加された XML 形式になります。(XSL スタイルシートを使ってレポートを作成することを計画している場合はこの形式を使用してください。) 「html」に設定すると、出力は HTML 形式(デフォルトのスタイルシートは default.xsl) になります。 「text」に設定すると、出力は特別なテキスト形式になります。「emacs」に設定すると、出力は <ulink url="http://www.gnu.org/software/emacs/">Emacs</ulink> エラーメッセージ形式になります。「xdocs」に設定すると、出力は Apache Maven で使用できる xdoc XML になります。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><literal>stylesheet</literal></term> |
| <listitem> |
| <para>任意指定の属性です。output 属性 に html を指定した場合に、 HTML 出力作成に使用されるスタイルシートを指定します。FindBugs 配布物に含まれているスタイルシートは、 default.xsl、 fancy.xsl 、 fancy-hist.xsl 、 plain.xsl および summary.xsl です。デフォルト値は default.xsl です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>sort</literal></term> |
| <listitem> |
| <para>任意指定の属性です。<literal>output</literal> 属性に「text」を指定した場合に、バグの報告をクラス順にソートするかどうかを <literal>sort</literal> 属性で指定します。デフォルトは、 true です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>outputFile</literal></term> |
| <listitem> |
| <para>任意指定の属性です。指定した場合、&FindBugs; の出力はその名前のファイルへと保存されます。省略時、出力は &Ant; によって直接表示されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>debug</literal></term> |
| <listitem> |
| <para>任意指定のブール値属性です。true に設定すると、 &FindBugs; は 診断情報を出力します。どのクラスを分析しているか、どのパグパターンディテクタが実行されているか、という情報が表示されます。デフォルトは、 false です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>effort</literal></term> |
| <listitem> |
| <para>分析の活動レベルを設定します。<literal>min</literal> 、<literal>default</literal> または <literal>max</literal> のいずれかの値を設定してください。分析レベルの設定に関する詳細情報は、 <xref linkend="commandLineOptions"/> を参照してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>conserveSpace</literal></term> |
| <listitem> |
| <para>effort="min" と同義です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>workHard</literal></term> |
| <listitem> |
| <para>effort="max" と同義です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>visitors</literal></term> |
| <listitem> |
| <para>任意指定の属性です。どのバグディテクタを実行するかをコンマ区切りのリストで指定します。バグディテクタはパッケージ指定なしのクラス名で指定します。省略時、デフォルトで無効化されているものを除くすべてのディテクタが実行されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>omitVisitors</literal></term> |
| <listitem> |
| <para> |
| 任意指定の属性です。 |
| バグディテクタをコンマ区切りのリストで指定します。 |
| <literal>visitors</literal> 属性と似ていますが、こちらは <emphasis>実行されない</emphasis> ディテクタを指定します。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>chooseVisitors</literal></term> |
| <listitem> |
| <para> |
| 任意指定の属性です。 |
| 頭に「+」または「-」を付け加えたバグディテクタをコンマ区切りのリストで指定します。 |
| 「+」を付け加えたバグディテクタは有効に、「-」を付け加えたバグディテクタは無効になります。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>excludeFilter</literal></term> |
| <listitem> |
| <para>任意指定の属性です。フィルターファイル名を指定します。報告から除外されるバグを指定します。<xref linkend="filter"/> を参照してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>includeFilter</literal></term> |
| <listitem> |
| <para>任意指定の属性です。フィルターファイル名を指定します。報告されるバグを指定します。<xref linkend="filter"/> を参照してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>projectFile</literal></term> |
| <listitem> |
| <para>任意指定の属性です。プロジェクトファイル名を指定します。プロジェクトファイルは、 &FindBugs; GUI で作成します。分析されるクラス、および、補助クラスパス、ソースディレクトリーが記入されてます。プロジェクトファイルを指定した場合は、 <literal>class</literal> 要素・ <literal>auxClasspath</literal> 属性および <literal>sourcePath</literal> 属性を設定する必要はありません。プロジェクトの作成方法は、 <xref linkend="running"/> を参照してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>jvmargs</literal></term> |
| <listitem> |
| <para>任意指定の属性です。&FindBugs; を実行している Java 仮想マシンに対して受け渡される引数を指定します。巨大なプログラムを分析する場合に、 JVM が使用するメモリ容量を増やす指定をするためにこの引数を利用する必要があるかもしれません。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>systemProperty</literal></term> |
| <listitem> |
| <para>任意指定のネストされる要素です。指定した場合、Java システムプロパティーを定義します。<literal>name</literal> 属性にはシステムプロパティーの名前を指定します。そして、 <literal>value</literal> 属性にはシステムプロパティの値を指定します。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>timeout</literal></term> |
| <listitem> |
| <para>任意指定の属性です。&FindBugs; を実行している Java プロセス の実行許容時間をミリ秒単位で指定します。時間を超過するとハングアップしていると判断してプロセスが終了されます。デフォルトは、 600,000 ミリ秒 (10 分) です。巨大なプログラムの場合は、 &FindBugs; が分析を完了するまでに 10 分 以上掛かる可能性があることに注意してください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>failOnError</literal></term> |
| <listitem> |
| <para>任意指定のブール値属性です。&FindBugs; の実行中にエラーがあった場合に、ビルドプロセス自体を打ち切って異常終了させるかどうかを指定します。デフォルトは、「false」です。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>errorProperty</literal></term> |
| <listitem> |
| <para>任意指定の属性です。&FindBugs; の実行中にエラーが発生した場合に、「true」が設定されるプロパティーの名前を指定します。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>warningsProperty</literal></term> |
| <listitem> |
| <para>任意指定の属性です。&FindBugs; が分析したプログラムにバグ報告が 1 件でもある場合に、「true」が設定されるプロパティーの名前を指定します。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>userPreferencesFile</literal></term> |
| <listitem> |
| <para> |
| 任意指定の属性です。 |
| ユーザー設定ファイルのパスを設定します。ユーザー設定ファイルの内容で、他のオプションの一部を上書きすることができます。 |
| <literal>userPreferencesFile</literal> を一番目の引数に指定した場合は、後続のオプションの方がユーザー設定ファイルの内容に優先します。 |
| <literal>userPreferencesFile</literal> を最後の引数に指定した場合は、ユーザー設定ファイルの内容の方が前に指定したオプションに優先します。 |
| このオプションを設けた背景・理由は、 Eclipse プロジェクトの FindBugs の設定をコマンドライン実行で再利用するためです。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal>nested</literal></term> |
| <listitem> |
| <para> |
| 任意指定の属性です。分析対象のファイル・ディレクトリーリストにあるファイル内にネストされた jar および zip ファイルに対する分析を有効化・無効化します。 |
| デフォルトでは、ネストされた jar/zip の分析は有効です。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| |
| |
| </para> |
| |
| <!-- |
| |
| --> |
| |
| </sect1> |
| |
| </chapter> |
| |
| <!-- |
| ************************************************************************** |
| Using the FindBugs Eclipse plugin |
| ************************************************************************** |
| --> |
| |
| <chapter id="eclipse"> |
| <title>&FindBugs;™ Eclipse プラグインの使用方法</title> |
| |
| <para> |
| FindBugs Eclipse プラグインを使用することによって、 &FindBugs; を <ulink url="http://www.eclipse.org/">Eclipse</ulink> IDE で使用することができるようになります。 |
| このFindBugs Eclipse プラグインは、 Peter Friese 氏の多大な貢献によるものです。 |
| Phil Crosby 氏 と Andrey Loskutov 氏は、プラグインの重要な改良に貢献しました。 |
| </para> |
| |
| <sect1> |
| <title>必要条件</title> |
| |
| <para>&FindBugs; Eclipse Plugin を使用するためには、 Eclipse 3.3 あるいはそれ以降のバージョン、また、 JRE/JDK 1.5 あるいはそれ以降のバージョンが必要です。</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>インストール</title> |
| |
| <para>更新サイトが提供されています。更新サイトを利用して、機械的に FindBugs を Eclipse にインストールできます。また自動的に、最新版のアップデートを照会してインストールすることもできます。内容の異なる 3 つの更新サイトが存在します。</para> |
| |
| <variablelist><title>FindBugs Eclipse 更新サイト一覧</title> |
| <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse/">http://findbugs.cs.umd.edu/eclipse/</ulink></term> |
| |
| <listitem> |
| <para>FindBugs の公式リリース物を提供します。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-candidate/">http://findbugs.cs.umd.edu/eclipse-candidate/</ulink></term> |
| |
| <listitem> |
| <para>FindBugsの公式リリース物に加えて、公式リリース候補版を提供します。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry><term><ulink url="http://findbugs.cs.umd.edu/eclipse-daily/">http://findbugs.cs.umd.edu/eclipse-daily/</ulink></term> |
| |
| <listitem> |
| <para>FindBugsの日次ビルド物を提供します。コンパイルができること以上のテストは行われていません。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>また、次に示すリンクから手動でプラグインをダウンロードすることもできます : <ulink url="http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_3.0.1.20150306.zip?download">http://prdownloads.sourceforge.net/findbugs/edu.umd.cs.findbugs.plugin.eclipse_3.0.1.20150306.zip?download</ulink>. 展開して Eclipse の「plugins」サブディレクトリーに入れてください。(そうすると、 <eclipse インストールディレクトリー >/plugins/edu.umd.cs.findbugs.plugin.eclipse_3.0.1.20150306/findbugs.png が &FindBugs; のロゴファイルへのパスになるはずです。)</para> |
| |
| <para>プラグインの展開ができたら、 Eclipse を起動して <menuchoice> <guimenu>Help</guimenu> <guimenuitem>About Eclipse Platform</guimenuitem> <guimenuitem>Plug-in Details</guimenuitem> </menuchoice> を選択してください。「FindBugs Project」から提供された「FindBugs Plug-in」というプラグインがあることを確認してください。</para> |
| </sect1> |
| |
| <sect1> |
| <title>プラグインの使用方法</title> |
| |
| <para>実行するには、 Java プロジェクト上で右クリックして「Find Bugs」を選択します。&FindBugs; が実行されて、バグパターンの実例の可能性があると識別されたコード箇所に問題マーカーがつきます。 (ソース画面および Eclipse 問題ビューに表示されます。)</para> |
| |
| <para>Java プロジェクトのプロパティーダイアログを開いて「Findbugs」プロパティーページを選択することで、 &FindBugs; の動作をカスタマイズすることができます。選択できる項目には次のようなものがあります :</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>「Run FindBugs Automatically」チェックボックスの設定。チェックすると、プロジェクト内の Java クラスが修正されるたびに FindBugs が実行されます。</para> |
| </listitem> |
| |
| <listitem> |
| <para>優先度とバグカテゴリーの選択。これらのオプションは、どの警告を表示するかを選択します。例えば、優先度で 「Medium」 を選択すると、優先度 (中) および優先度 (高) の警告のみが表示されます。同様に、「Style」チェックボックスのチェックマークを外すと、Style カテゴリーに属する警告は表示されません。</para> |
| </listitem> |
| |
| <listitem> |
| <para>ディテクタの選択。表からプロジェクトで有効にしたいディテクタを選択することができます。</para> |
| </listitem> |
| </itemizedlist> |
| |
| </sect1> |
| |
| <sect1> |
| <title>Eclipse プラグインの拡張方法 (2.0.0 以降)</title> |
| <para> |
| Eclipse プラグインでは、 独自の &FindBugs; ディテクタを追加することができます。 |
| (詳しく知りたい方は、 |
| <ulink url="http://code.google.com/p/findbugs/source/browse/findbugs/src/doc/AddingDetectors.txt">AddingDetectors.txt</ulink> |
| もご覧ください)。 |
| 独自のプラグインを Eclipse に追加するには以下の2通りの方法があります。 |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| 既存の標準 &FindBugs; ディテクタパッケージは以下で設定できます。 |
| <menuchoice> |
| <guimenu>Window</guimenu> |
| <guimenuitem>Preferences</guimenuitem> |
| <guimenuitem>Java</guimenuitem> |
| <guimenuitem>FindBugs</guimenuitem> |
| <guimenuitem>Misc. Settings</guimenuitem> |
| <guimenuitem>Custom Detectors</guimenuitem> |
| </menuchoice>。 |
| ここで追加するプラグインライブラリの場所を指定するだけです。 |
| </para> |
| |
| <para> |
| この方法の利点は、既存のディテクタパッケージは「そのまま」で、サードパーティーディテクタの品質をすばやく検証できることです。 |
| 欠点としては、この設定は Eclipse ワークスペース毎に適用する必要があり、この設定をチームメンバー間で共有することができないことです。 |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Eclipse 標準の拡張機構を使って独自のディテクタを追加することができます。 |
| </para> |
| |
| <para> |
| <ulink url="http://code.google.com/p/findbugs/source/browse/eclipsePlugin/schema/detectorPlugins.exsd"> |
| findBugsEclipsePlugin/schema/detectorPlugins.exsd</ulink> の documentation で plugin.xml の更新方法を確認してください。 |
| 既存の &FindBugs; ディテクタプラグイン を簡単に「拡張」して強力な &FindBugs; Eclipse ディテクタプラグイン にすることができます。 |
| 通常必要なのは、 META-INF/MANIFEST.MF および plugin.xml を jar に追加してかつ、 MANIFEST.MF がビルド時に上書きされないようにビルドスクリプトを更新するだけです。 |
| </para> |
| |
| <para> |
| この方法の利点は、 Eclipse インストールを共有しさえすれば、チームメンバー同士で正確に同じディテクタ設定を使用できることです。 |
| 前提条件は現在使用しているディテクタパッケージを Eclipse プラグインに変換しておくことです。 |
| これはサードパーティのディテクタパッケージも同様です。 |
| もうひとつの主な差別化要因は、 FindBugs のデフォルト実行時クラスパス に当該サードパーティライブラリーを追加することが必要なことです(くわしくは |
| <ulink url="http://code.google.com/p/findbugs/source/browse/findbugs/src/doc/AddingDetectors.txt">AddingDetectors.txt</ulink> |
| をご覧ください)。 |
| </para> |
| </listitem> |
| |
| </itemizedlist> |
| |
| </sect1> |
| |
| <sect1> |
| <title>トラブルシューティング</title> |
| |
| <para> |
| このセクションでは、プラグインに関する一般的な問題と (判明していれば) それらの問題の解決方法を記述します。 |
| </para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| Eclipse において &FindBugs; の分析開始後に OutOfMemory エラーダイアログが 出た場合は、 |
| JVM の使用メモリを増やしてください。すなわち、 eclipse.ini の末尾に以下の記述を追加してください。 |
| <programlisting> |
| -vmargs |
| -Xmx1000m |
| </programlisting> |
| 重要：「-vmargs」で始まる設定引数は eclipse.ini ファイルの末尾に記述する必要があります。 |
| また、各行には引数を一つだけしか書くことができません！ |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| &FindBugs; 問題マーカーが (ソース画面および問題ビューに) 表示されない場合は、問題ビューのフィルター設定を変更してください。 |
| 詳細情報は <ulink url="http://findbugs.sourceforge.net/FAQ.html#q7">http://findbugs.sourceforge.net/FAQ.html#q7</ulink> を参照してください。 |
| </para> |
| </listitem> |
| |
| </itemizedlist> |
| |
| </sect1> |
| |
| |
| </chapter> |
| |
| |
| <!-- |
| ************************************************************************** |
| Filter files |
| ************************************************************************** |
| --> |
| |
| <chapter id="filter"> |
| <title>フィルターファイル</title> |
| |
| <para>フィルターファイルを使用することで、特定のクラスやメソッドをバグ報告に含めたりバグ報告から除外したりすることができます。この章では、フィルターファイルの使用方法を説明します。<note> |
| <title>計画されている機能</title> |
| <para>フィルターは現在、コマンドラインインタフェースでのみサポートされています。最終的には、フィルターのサポートは GUI にも追加される予定です。</para> |
| </note> |
| </para> |
| |
| |
| <sect1> |
| <title>フィルターファイルの概要</title> |
| |
| <para>概念的に言えば、フィルターはバグ検索結果をある基準と照合します。フィルターを定義することで、 特別な取り扱いをするバグ検索結果を選択することができます。例えば、あるバグ検索結果をバグ報告に含めたり、バグ報告から除外したりすることができます。</para> |
| |
| <para>フィルターファイルは、 <ulink url="http://www.w3.org/XML/">XML</ulink> 文書です。最上位要素が <literal>FindBugsFilter</literal> 要素 であり、その子要素として <literal>Match</literal> 要素を複数個定義します。それぞれの <literal>Match</literal> 要素は、生成されたバグ検索結果に適用される述部にあたります。通常、フィルターはバグ検索結果を除外するために使用します。次に、例を示します:<screen> |
| <prompt>$ </prompt><command>findbugs -textui -exclude <replaceable>myExcludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command> |
| </screen>また一方で、的をしぼった報告を得るためにバグ報告結果を選択するためにフィルターを使用することも考えられます :<screen> |
| <prompt>$ </prompt><command>findbugs -textui -include <replaceable>myIncludeFilter.xml</replaceable> <replaceable>myApp.jar</replaceable></command> |
| </screen> |
| </para> |
| |
| <para> |
| <literal>Match</literal> 要素は子要素を持ちます。それらの子要素は論理積で述部になります。つまり、述部が真であるためには、すべての子要素が真である必要があります。</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>マッチング条件の種類</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><literal><Bug></literal></term> |
| <listitem><para>この要素は、バグパターンを指定して照合します。<literal>pattern</literal> 属性には、コンマ区切りでバグパターン類型のリストを指定します。どの警告がどのバグパターン類型にあたるかは、 <command>-xml</command> オプションをつかって出力されたもの (<literal>BugInstance</literal> 要素の <literal>type</literal> 属性) を見るか、または、 <ulink url="../../bugDescriptions.html">バグ解説ドキュメント</ulink>を参照してください。</para><para>もっと粒度の粗い照合を行いたいときは、 <literal>code</literal> 属性を使用してください。バグ略称のコンマ区切りのリストで指定できます。さらに粒度の粗い照合を行いたいときは、 <literal>category</literal> 属性を使用してください。次に示す、バグカテゴリー名のコンマ区切りのリストで指定できます : <literal>CORRECTNESS</literal>, <literal>MT_CORRECTNESS</literal>, <literal>BAD_PRACTICICE</literal>, <literal>PERFORMANCE</literal>, <literal>STYLE</literal>.</para><para>同じ <literal><Bug></literal> 要素に上記の属性を複数指定した場合は、バグパターン名、バグ略称、バグカテゴリーのいずれか1つでも該当すれば、バグパターンは合致すると判定されます。</para><para>下位互換性を持たせたい場合は、 <literal><Bug></literal> 要素の代わりに <literal><BugPattern></literal> 要素および <literal><BugCode></literal> 要素を使用してください。これらの要素はそれぞれ、 <literal>name</literal> 属性で値のリストを指定します。これらの要素は、将来サポートされなくなる可能性があります。</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Confidence></literal></term> |
| <listitem> |
| <para> |
| この要素は、特定のバグ信頼度をもつ警告を照合します。 |
| <literal>value</literal> 属性には、整数値を指定します。すなわち 1 は信頼度(高) 、また、 2 は信頼度(中) 、 3 は信頼度(低) を示します。 |
| <Confidence> は 2.0.0 リリースから <Priority> の後継として取って代わりました。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Priority></literal></term> |
| <listitem> |
| <para> |
| <literal><Confidence></literal> と同一です。下位互換性を保つため残されています。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Rank></literal></term> |
| <listitem> |
| <para> |
| この要素は、特定のバグランクをもつ警告を照合します。 |
| <literal>value</literal> 属性には、 1 から 20 の整数値を指定します。 |
| 1 から 4 は最も恐ろしいバグ、 5 から 9 は恐ろしいバグ、 10 から 14 は厄介なバグ, |
| そして 15 から 20 は不安なバグを示します。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Package></literal></term> |
| <listitem> |
| <para>この要素は、 <literal>name</literal> 属性で指定した特定のパッケージ内にあるクラスに関連した警告を照合します。入れ子のパッケージは含まれません (Java import 文に従っています) 。しかしながら、正規表現を使うと複数パッケージにマッチさせることは簡単にできます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Class></literal></term> |
| <listitem> |
| <para>この要素は、特定のクラスに関連した警告を照合します。<literal>name</literal> 属性を使用して、照合するクラス名をクラス名そのものか、または、正規表現で指定します。</para> |
| |
| <para>下位互換性を持たせたい場合は、この要素の代わりに <literal>Match</literal> 要素を使用してください。クラス名そのものの指定は <literal>class</literal> 属性を、クラス名を正規表現で指定する場合は <literal>classregex</literal> 属性をそれぞれ使用してください</para> |
| |
| <para>もし <literal>Match</literal> 要素に <literal>Class</literal> 要素が無かったり、 <literal>class</literal> / <literal>classregex</literal> 属性が無かったりした場合は、すべてのクラスに適用されます。その場合、想定外に多くのバグ検索結果が一致してしまうことがあり得ます。その場合は、適当なメソッドやフィールドで絞り込んでください。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Source></literal></term> |
| <listitem> |
| <para> |
| この要素は、特定のソースファイルに関連した警告を照合します。 |
| <literal>name</literal> 属性を使用して、照合するソースファイル名をソースファイル名そのものか、または、正規表現で指定します。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Method></literal></term> |
| |
| <listitem><para>この要素は、メソッドを指定します。<literal>name</literal> 属性を使用して、照合するメソッド名をメソッド名そのものか、または、正規表現で指定します。<literal>params</literal> 属性には、コンマ区切りでメソッド引数の型のリストを指定します。<literal>returns</literal> 属性にはメソッドの戻り値の型を指定します。<literal>params</literal> および <literal>returns</literal> においては、クラス名は完全修飾名である必要があります。(例えば、単に "String" ではなく "java.lang.String" としてください。) <literal>params</literal> <literal>returns</literal> のどちらか一方を指定した場合は、もう一方の属性の指定も必須です。なぜならば、メソッドシグニチャーを構築のために必要だからです。<literal>name</literal> 属性、<literal>params</literal> 属性 および <literal>returns</literal> 属性または 3 つの 属性すべて、のどれかを条件とすることできることを意味しています。このように、名前とシグニチャーに基づく様々な種類の条件を規定できます。</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Field></literal></term> |
| |
| <listitem><para>この要素は、フィールドを指定します。<literal>name</literal> 属性を使用して、照合するフィールド名をフィールド名そのものか、または、正規表現で指定します。また、フィールドのシグニチャーに照らしたフィルタリングをすることができます。 <literal>type</literal> 属性を使用して、フィールドの型を完全修飾名で指定してください。名前とシグニチャーに基づく条件を規定するために、その2つの属性を両方とも指定することができます。</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Local></literal></term> |
| |
| <listitem><para>この要素は、ローカル変数を指定します。<literal>name</literal> 属性を使用して、照合するローカル変数名をローカル変数名そのものか、または、正規表現で指定します。ローカル変数とは、メソッド内で定義した変数です。</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><literal><Or></literal></term> |
| <listitem><para>この要素は、論理和として <literal>Match</literal> 条項を結合します。すなわち、2つの <literal>Method</literal> 要素を <literal>Or</literal> 条項に入れることで、どちらか一方のメソッドでマッチさせることができます。</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><literal><And></literal></term> |
| <listitem><para> |
| この要素は、論理積として <literal>Match</literal> 条項を結合します。 |
| すなわち、 <literal>Bug</literal> および <literal>Confidence</literal> 要素を <literal>And</literal> 条項内に指定することで |
| 特定の信頼度の特定のバグのみ照合することができます。 |
| </para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><literal><Not></literal></term> |
| <listitem><para> |
| この要素は、内包する子 <literal>Match</literal> を反転します。 |
| すなわち、 <literal>Bug</literal> 要素を <literal>Not</literal> 条項内に指定することで指定したバグ以外のすべてのバグと照合します。 |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| |
| </sect1> |
| |
| <sect1> |
| <title>Java 要素名マッチング</title> |
| |
| <para> |
| <literal>Class</literal> 、 <literal>Source</literal> 、 <literal>Method</literal> または <literal>Field</literal> の <literal>name</literal> 属性が文字 ~ で始まっている場合は、 |
| 属性値の残りの部分を Java の正規表現として解釈します。 |
| そうして、当該 Java 要素の名前に対しての照合が行われます。 |
| </para> |
| |
| <para>パターンの照合は要素の名前全体に対して行われることに注意してください。そのため、部分一致照合を行いたい場合はパターン文字列の前後に .* を付加して使用する必要があります。</para> |
| |
| <para>パターンの構文規則に関しては、 <ulink url="http://java.sun.com/j2se/1.5.0/ja/docs/ja/api/java/util/regex/Pattern.html"><literal>java.util.regex.Pattern</literal></ulink> のドキュメントを参照してください。</para> |
| </sect1> |
| |
| <sect1> |
| <title>留意事項</title> |
| |
| <para> |
| <literal>Match</literal> 条項は、バグ検索結果に実際に含まれている情報にのみ一致します。すべてのバグ検索結果はクラスを持っています。したがって、一般的に言って、バグを除外するためにはクラスを用いて行うとうまくいくことが多いです。</para> |
| |
| <para>バグ検索結果の中には、2個以上のクラスを保持しているものもあります。例えば、 DE (dropped exception : 例外の無視) バグは、 例外の無視が発生したメソッドを持っているクラスと、 無視された例外の型を表すクラスの両方を含んだ形で報告されます。<literal>Match</literal> 条項とは、 <emphasis>1番目</emphasis> (主) のクラスのみが照合されます。したがって、例えば、クラス "com.foobar.A" 、 "com.foobar.B" 間での IC (initialization circularity : 初期化時の処理循環) バグ報告を抑止したい場合、以下に示すように 2つの <literal>Match</literal> 条項を使用します :<programlisting> |
| <Match> |
| <Class name="com.foobar.A" /> |
| <Bug code="IC" /> |
| </Match> |
| |
| <Match> |
| <Class name="com.foobar.B" /> |
| <Bug code="IC" /> |
| </Match> |
| </programlisting>明示的に両方のクラスで照合することによって、循環しているどちらのクラスがバグ検索結果の 1 番目になっているかに関係なく一致させることができます。(もちろんこの方法は、処理循環が "com.foobar.A" 、 "com.foobar.B" に加えて3番目のクラスも含んでいる場合は図らずも失敗してしまう恐れがあります。)</para> |
| |
| <para>多くの種類のバグ報告は、自身が出現したメソッドを報告します。それらのバグ検索結果に対しては、 <literal>Method</literal> 条項を <literal>Match</literal> 要素に加えると期待通りの動作をするでしょう。</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>例</title> |
| |
| <para>1. 特定のクラスに対するすべてのバグ報告に一致させます。<programlisting> |
| <![CDATA[ |
| <Match> |
| <Class name="com.foobar.MyClass" /> |
| </Match> |
| ]]> |
| </programlisting> |
| |
| </para> |
| |
| <para>2. バグ略称を指定して、特定のクラスに対する特定の検査項目に一致させます。<programlisting> |
| <![CDATA[ |
| <Match> |
| <Class name="com.foobar.MyClass"/ > |
| <Bug code="DE,UrF,SIC" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>3. バグ略称を指定して、すべてのクラスに対する特定の検査項目に一致させます。<programlisting> |
| <![CDATA[ |
| <Match> |
| <Bug code="DE,UrF,SIC" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>4. バグカテゴリーを指定して、すべてのクラスに対する特定の検査項目に一致させます。<programlisting> |
| <![CDATA[ |
| <Match> |
| <Bug category="PERFORMANCE" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>5. バグ略称を指定して、特定のクラスの指定されたメソッドに対する特定のバグ種別に一致させます。<programlisting> |
| <![CDATA[ |
| <Match> |
| <Class name="com.foobar.MyClass" /> |
| <Or> |
| <Method name="frob" params="int,java.lang.String" returns="void" /> |
| <Method name="blat" params="" returns="boolean" /> |
| </Or> |
| <Bug code="DC" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>6. 特定のメソッドに対する特定のバグパターンに一致させます。<programlisting> |
| <![CDATA[ |
| <!-- open stream に関する誤検出があるメソッド。--> |
| <Match> |
| <Class name="com.foobar.MyClass" /> |
| <Method name="writeDataToFile" /> |
| <Bug pattern="OS_OPEN_STREAM" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>7. 特定のメソッドに対する特定の優先度を付与された特定のバグパターンに一致させます。<programlisting> |
| <![CDATA[ |
| <!-- dead local store (優先度 (中)) に関する誤検出があるメソッド。--> |
| <Match> |
| <Class name="com.foobar.MyClass" /> |
| <Method name="someMethod" /> |
| <Bug pattern="DLS_DEAD_LOCAL_STORE" /> |
| <Priority value="2" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>8. AspectJ コンパイラーによって引き起こされるマイナーバグに一致させます (AspectJ の開発者でもない限り、それらのバグに関心を持つことはないと考えます)。<programlisting> |
| <![CDATA[ |
| <Match> |
| <Class name="~.*\$AjcClosure\d+" /> |
| <Bug pattern="DLS_DEAD_LOCAL_STORE" /> |
| <Method name="run" /> |
| </Match> |
| <Match> |
| <Bug pattern="UUF_UNUSED_FIELD" /> |
| <Field name="~ajc\$.*" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>9. 基盤コードの特定の部分に対するバグに一致させます<programlisting> |
| <![CDATA[ |
| <!-- すべてのパッケージにある Messages クラスに対する unused fields 警告に一致。 --> |
| <Match> |
| <Class name="~.*\.Messages" /> |
| <Bug code="UUF" /> |
| </Match> |
| <!-- すべての internal パッケージ内の mutable statics 警告に一致。 --> |
| <Match> |
| <Package name="~.*\.internal" /> |
| <Bug code="MS" /> |
| </Match> |
| <!-- ui パッケージ階層内の anonymoous inner classes 警告に一致。 --> |
| <Match> |
| <Package name="~com\.foobar\.fooproject\.ui.*" /> |
| <Bug pattern="SIC_INNER_SHOULD_BE_STATIC_ANON" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para>10. 特定のシグニチャーを持つフィールドまたはメソッドのバグに一致させます。<programlisting> |
| <![CDATA[ |
| <!-- すべてのクラスの main(String[]) メソッドに対する System.exit(...) usage 警告に一致。 --> |
| <Match> |
| <Method returns="void" name="main" params="java.lang.String[]" /> |
| <Method pattern="DM_EXIT" /> |
| </Match> |
| <!-- すべてのクラスの com.foobar.DebugInfo 型のフィールドに対する UuF 警告に一致。 --> |
| <Match> |
| <Field type="com.foobar.DebugInfo" /> |
| <Bug code="UuF" /> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| |
| <para> |
| 11. Not フィルター演算子を使用してバグに一致させます。 |
| <programlisting> |
| <![CDATA[ |
| <!-- テストクラスのバグは無視する。ただし、 JUnit テスト特有のバグは例外とする。 --> |
| <!-- i.e. filter bug if ( classIsJUnitTest && ! bugIsRelatedToJUnit ) --> |
| <Match> |
| <!-- Match フィルタは論理和と同等 --> |
| |
| <Class name="~.*\.*Test" /> |
| <!-- テストクラスは末尾に「Test」 --> |
| |
| <Not> |
| <Bug code="IJU" /> <!-- 「IJU」は JUnit テストコード関連のバグコード --> |
| </Not> |
| </Match> |
| ]]> |
| </programlisting> |
| </para> |
| |
| <para> |
| 12. 完全な除外フィルター。 Groovy ソースファイルから生成された全クラスを除外します。 |
| |
| <programlisting> |
| <![CDATA[ |
| <?xml version="1.0" encoding="UTF-8"?> |
| <FindBugsFilter> |
| <Match> |
| <Source name="~.*\.groovy" /> |
| </Match> |
| </FindBugsFilter> |
| ]]> |
| </programlisting> |
| </para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>完全な例</title> |
| |
| <programlisting> |
| <![CDATA[ |
| <FindBugsFilter> |
| <Match> |
| <Class name="com.foobar.ClassNotToBeAnalyzed" /> |
| </Match> |
| |
| <Match> |
| <Class name="com.foobar.ClassWithSomeBugsMatched" /> |
| <Bug code="DE,UrF,SIC" /> |
| </Match> |
| |
| <!-- XYZ 違反に一致。--> |
| <Match> |
| <Bug code="XYZ" /> |
| </Match> |
| |
| <!-- "AnotherClass" の特定のメソッドの doublecheck 違反に一致。--> |
| <Match> |
| <Class name="com.foobar.AnotherClass" /> |
| <Or> |
| <Method name="nonOverloadedMethod" /> |
| <Method name="frob" params="int,java.lang.String" returns="void" /> |
| <Method name="blat" params="" returns="boolean" /> |
| </Or> |
| <Bug code="DC" /> |
| </Match> |
| |
| <!-- dead local store (優先度 (中)) に関する誤検出があるメソッド。--> |
| <Match> |
| <Class name="com.foobar.MyClass" /> |
| <Method name="someMethod" /> |
| <Bug pattern="DLS_DEAD_LOCAL_STORE" /> |
| <Priority value="2" /> |
| </Match> |
| |
| <!-- テストクラスのバグすべて。 JUnit 特有のバグは除く。 --> |
| <Match> |
| <Class name="~.*\.*Test" /> |
| <Not> |
| <Bug code="IJU" /> |
| </Not> |
| </Match> |
| |
| </FindBugsFilter> |
| ]]> |
| </programlisting> |
| |
| </sect1> |
| |
| |
| </chapter> |
| |
| |
| <!-- |
| ************************************************************************** |
| Analysis properties |
| ************************************************************************** |
| --> |
| |
| <chapter id="analysisprops"> |
| <title>分析プロパティー</title> |
| |
| <para>&FindBugs; は分析する場合にいくつかの観点を持っています。そして、観点をカスタマイズして実行することができます。システムプロパティーを使って、それらのオプションを設定します。この章では、分析オプションの設定方法を説明します。</para> |
| |
| <para>分析オプションの主な目的は、 2 つあります。1 番目は、 &FindBugs; に対して分析されるアプリケーションのメソッドの意味を伝えることです。そうすることで &FindBugs; がより正確な結果を出すことができ、誤検出を減らすことができます。2 番目に、分析を行うに当たりその精度を設定できるようにすることです。分析の精度を落とすことで、メモリ使用量と分析時間を減らすことができます。ただし、本当のバグを見逃したり、誤検出の数が増えるという代償があります。</para> |
| |
| <para>コマンドラインオプション <command>-property</command> を使って、分析オプションを設定することができます。次に、例を示します:<screen> |
| <prompt>$ </prompt><command>findbugs -textui -property "cfg.noprune=true" <replaceable>myApp.jar</replaceable></command> |
| </screen> |
| </para> |
| |
| <para>設定することができる分析オプションの一覧を <xref linkend="analysisproptable"/> に示します。</para> |
| |
| <table id="analysisproptable"> |
| <title>設定可能な分析プロパティー</title> |
| <tgroup cols="3" align="left"> |
| <thead> |
| <row> |
| <entry>プロパティー名</entry> |
| <entry>設定値</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <!-- |
| <row> |
| <entry>cfg.noprune</entry> |
| <entry>true or false</entry> |
| <entry>If true, infeasible exception edges are not pruned from |
| the control flow graphs of analyzed methods. This option |
| increases the speed of the analysis (by about 20%-30%), |
| but causes some detectors to produce more false warnings.</entry> |
| </row> |
| --> |
| <row> |
| <entry>findbugs.assertionmethods</entry> |
| <entry>コンマ区切りの完全修飾メソッド名リスト : 例、 "com.foo.MyClass.checkAssertion"</entry> |
| <entry>このプロパティーには、プログラムが正しいことをチェックするために使われるメソッドを指定します。これらのメソッドを指定することで、 チェックメソッドで確認した値に対する null 参照アクセスディテクタの誤検出を回避できます。</entry> |
| </row> |
| <row> |
| <entry>findbugs.de.comment</entry> |
| <entry>true または false</entry> |
| <entry>true に設定すると、 DroppedException (無視された例外) ディテクタは空の catch ブロック にコメントが無いか探します。そして、コメントがみつかった場合には警告が報告されません。</entry> |
| </row> |
| <row> |
| <entry>findbugs.maskedfields.locals</entry> |
| <entry>true または false</entry> |
| <entry>true に設定すると、フィールドを隠蔽しているローカル変数に対して優先度(低)の警告が発行されます。デフォルトは、 false です。</entry> |
| </row> |
| <row> |
| <entry>findbugs.nullderef.assumensp</entry> |
| <entry>true または false</entry> |
| <entry>使用されません。 (意図 : true に設定すると、null 参照アクセスディテクタはメソッドからの戻り値、または、メソッドに受け渡される引数を null であると仮定します。デフォルトは、 false です。このプロパティーを有効にすると、大量の誤検出が生成されるであろうことに注意してください。)</entry> |
| </row> |
| <row> |
| <entry>findbugs.refcomp.reportAll</entry> |
| <entry>true または false</entry> |
| <entry>true に設定すると、 == および != 演算子を使っている疑わしい参照比較がすべて報告されます。 false に設定すると、同様の警告は 1 メソッドにつき 1 つしか発行されません。デフォルトは、 false です。</entry> |
| </row> |
| <row> |
| <entry>findbugs.sf.comment</entry> |
| <entry>true または false</entry> |
| <entry>true に設定すると、 SwitchFallthrough ディテクタはソースコードに「fall」または「nobreak」という単語を含んだコメントを記載していない caseラベル に限り警告を報告します。(この機能が正しく動作するためには、正確なソースパスが必要です。) これにより、意図的ではない switch 文の fallthrough を発見し易くなります。</entry> |
| </row> |
| <!-- see others at src/doc/manual/sysprops.html |
| <row> |
| <entry></entry> |
| <entry></entry> |
| <entry></entry> |
| </row> |
| --> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| </chapter> |
| |
| <!-- |
| ************************************************************************** |
| Annotations |
| *************************************************************************** |
| --> |
| |
| <chapter id="annotations"> |
| <title>アノテーション</title> |
| |
| <para>&FindBugs; はいくつかのアノテーションをサポートしています。開発者の意図を明確にすることで、 FindBugs はより的確に警告を発行することができます。アノテーションを使用するためには Java 5 が必要であり、 annotations.jar および jsr305.jar ファイルをコンパイル時のクラスパスに含める必要があります。</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.CheckForNull</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Field, Method, Parameter |
| </para> |
| </listitem> |
| <listitem> |
| <para>アノテーションをつけた要素は、 null である可能性があります。したがって、当該要素を使用する際は null チェックをするべきです。このアノテーションをメソッドに適用すると、メソッドの戻り値に適用されます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.CheckReturnValue</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Method, Constructor |
| </para> |
| </listitem> |
| <listitem> |
| <variablelist> |
| <varlistentry> |
| <term><command>[Parameter]</command></term> |
| <listitem> |
| <para> |
| <command>priority:</command> 警告の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para> |
| </listitem> |
| <listitem> |
| <para> |
| <command>explanation:</command>戻り値をチェックしなけばならない理由をテキストで説明します。デフォルト値 :""。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| <listitem> |
| <para>このアノテーションを使用して、呼出し後に戻り値をチェックすべきメソッドを表すことができます。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotation</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Type, Package |
| </para> |
| </listitem> |
| <listitem> |
| <variablelist> |
| <varlistentry> |
| <term><command>[Parameter]</command></term> |
| <listitem> |
| <para> |
| <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para> |
| </listitem> |
| <listitem> |
| <para> |
| <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| <listitem> |
| <para> |
| クラスまたはパッケージのすべてのメンバーが指定されたアノテーションクラスのデフォルト値でアノテートされることを指定することができます。 |
| この指定は @NonNull 、 @CheckForNull 、または @CheckReturnValueなどに使用する想定です。 |
| 具体的には、 クラスまたはパッケージに @DefaultAnnotation(NonNull.class) を指定した上で、 |
| null を許容したいパラメーター、メソッドまたはフィールドにのみ @Nullable を指定するという使用方法があります。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForFields</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Type, Package |
| </para> |
| </listitem> |
| <listitem> |
| <variablelist> |
| <varlistentry> |
| <term><command>[Parameter]</command></term> |
| <listitem> |
| <para> |
| <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para> |
| </listitem> |
| <listitem> |
| <para> |
| <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| <listitem> |
| <para> |
| フィールドのみに適用されること以外は DefaultAnnotation と同様です。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForMethods</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Type, Package |
| </para> |
| </listitem> |
| <listitem> |
| <variablelist> |
| <varlistentry> |
| <term><command>[Parameter]</command></term> |
| <listitem> |
| <para> |
| <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para> |
| </listitem> |
| <listitem> |
| <para> |
| <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| <listitem> |
| <para> |
| メソッドのみに適用されること以外は DefaultAnnotation と同様です。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.DefaultAnnotationForParameters</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Type, Package |
| </para> |
| </listitem> |
| <listitem> |
| <variablelist> |
| <varlistentry> |
| <term><command>[Parameter]</command></term> |
| <listitem> |
| <para> |
| <command>value:</command>アノテーションクラスのclassオブジェクト。複数のクラスを指定することができます。</para> |
| </listitem> |
| <listitem> |
| <para> |
| <command>priority:</command>省略時の優先度を指定します (HIGH, MEDIUM, LOW, IGNORE) 。デフォルト値 :MEDIUM。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| <listitem> |
| <para> |
| パラメーターのみに適用されること以外は DefaultAnnotation と同様です。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.NonNull</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Field, Method, Parameter |
| </para> |
| </listitem> |
| <listitem> |
| <para>アノテーションをつけた要素は、 null であってはいけません。アノテーションをつけたフィールドは、構築完了後 null であってはいけません。アノテーションをつけたメソッドは、 null ではない値を戻り値としなければなりません。</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.Nullable</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Field, Method, Parameter |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| アノテーションをつけた要素は、 条件により null である可能性があります。 |
| 一般に、開発者はドキュメントを読んで null 値を許容するかどうかまたは null 値をチェックするかどうかを決定する必要があります。 |
| FindBugs はこのアノテーションをつけた要素を、アノテーションがついていないものと同様に扱います。 |
| </para> |
| <para> |
| 実際には、このアノテーションは NonNull をつけた要素をオーバーライドする場合に有用です。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.OverrideMustInvoke</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Method |
| </para> |
| </listitem> |
| <listitem> |
| <variablelist> |
| <varlistentry> |
| <term><command>[Parameter]</command></term> |
| <listitem> |
| <para> |
| <command>value:</command>super の呼び出し箇所を指定します (FIRST, ANYTIME, LAST)。 デフォルト値 :ANYTIME。 |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| <listitem> |
| <para> |
| オーバーライドされた場合にオーバーライドメソッド内で super を呼び出すべきメソッドにアノテートします。 |
| 例えば、 finalize() や clone() がそのようなメソッドに該当します。 |
| 引数は、 super の呼び出し箇所を指定します。すなわち、随時、メソッドの最初またはメソッドの最後です。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.PossiblyNull</command></term> |
| <listitem> |
| <para> |
| 非推奨です。 CheckForNull を使用してください。 |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.SuppressWarnings</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Type, Field, Method, Parameter, Constructor, Package |
| </para> |
| </listitem> |
| <listitem> |
| <variablelist> |
| <varlistentry> |
| <term><command>[Parameter]</command></term> |
| <listitem> |
| <para> |
| <command>value:</command>警告の名称。複数の名称を指定することができます。 |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <command>justification:</command>警告を無視する理由。 デフォルト値 :""。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </listitem> |
| <listitem> |
| <para> |
| The set of warnings that are to be suppressed by the compiler in the annotated element. |
| Duplicate names are permitted. The second and successive occurrences of a name are ignored. |
| The presence of unrecognized warning names is <emphasis>not</emphasis> an error: Compilers |
| must ignore any warning names they do not recognize. They are, however, free to emit a |
| warning if an annotation contains an unrecognized warning name. Compiler vendors should |
| document the warning names they support in conjunction with this annotation type. They |
| are encouraged to cooperate to ensure that the same names work across multiple compilers. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Field, Method, Parameter |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><command>edu.umd.cs.findbugs.annotations.UnknownNullness</command></term> |
| <listitem> |
| <para> |
| <command>[Target]</command> Field, Method, Parameter |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Used to indicate that the nullness of the target is unknown, or my vary in unknown ways in subclasses. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>また、 &FindBugs; 次に示すアノテーションもサポートしています。 :<itemizedlist> |
| <listitem><para>net.jcip.annotations.GuardedBy</para></listitem> |
| <listitem><para>net.jcip.annotations.Immutable</para></listitem> |
| <listitem><para>net.jcip.annotations.NotThreadSafe</para></listitem> |
| <listitem><para>net.jcip.annotations.ThreadSafe</para></listitem> |
| </itemizedlist> |
| </para> |
| <para><ulink url="http://jcip.net/">Java Concurrency in Practice</ulink> の <ulink url="http://jcip.net/annotations/doc/index.html"> API ドキュメント</ulink> を参照してください。</para> |
| </chapter> |
| |
| <!-- |
| ************************************************************************** |
| Using rejarForAnalysis |
| ************************************************************************** |
| --> |
| |
| <chapter id="rejarForAnalysis"> |
| <title>rejarForAnalysis の使用方法</title> |
| |
| <para>プロジェクトに多くの jar ファイル があったり、 jar ファイルが多くのディレクトリに点在したりする場合は、 <command>rejarForAnalysis </command> スクリプトを使用すると FindBugs の実行が比較的簡単になります。このスクリプトは、数多い jar ファイルを集めて 1 つの大きな jar ファイルに結合します。そうすると、分析時にFindBugs に jar ファイルを設定することが比較的簡単になります。このスクリプトは、 unix システムの 'find' コマンドと組み合わせるととりわけ有用になります ; 次に例を示します。 <command>find . -name '*.jar' | xargs rejarForAnalysis </command>.</para> |
| |
| <para>また、 <command>rejarForAnalysis</command> スクリプトは巨大なプロジェクトを複数の jar ファイルに分割することに使用できます。プロジェクトのクラスファイルは、複数の jar ファイルに均等に配分されます。これは、プロジェクト全体に対して FindBugs を実行すると時間とメモリ消費が著しい場合に有用です。プロジェクト全体に対して FindBugs を実行する代わりに、 <command> rejarForAnalysis</command> ですべてのクラスを含む大きな jar ファイルを構築します。続いて、 <command>rejarForAnalysis</command> を再び実行して複数の jar ファイルに分割します。そして、各々の jar ファイルに対して順に FindBugs を実行します。その際、 <command>-auxclasspath</command> に最初に 1 つにまとめた jar ファイルを指定してください。</para> |
| |
| <para><command>rejarForAnalysis</command> スクリプトに指定することができるオプションを以下に示します :</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><command>-maxAge</command> <replaceable>日数</replaceable></term> |
| <listitem> |
| <para>最後に更新された日からの経過時間を日単位で指定します (指定した日数より古い jar ファイルは無視されます)。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command>-inputFileList</command> <replaceable>ファイル名</replaceable></term> |
| <listitem> |
| <para>jar ファイル名を記載したテキストファイルを指定します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command>-maxClasses</command> <replaceable>クラス数</replaceable></term> |
| <listitem> |
| <para>analysis*.jar ファイル 1 ファイルに対するクラスの最大数を指定します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command>-prefix</command> <replaceable>プレフィックス</replaceable></term> |
| <listitem> |
| <para>分析するクラス名のプレフィックスを指定します (例、 edu.umd.cs.) 。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </chapter> |
| |
| <!-- |
| ************************************************************************** |
| Data mining |
| ************************************************************************** |
| --> |
| |
| <chapter id="datamining"> |
| <title>&FindBugs;™ によるデータ・マイニング</title> |
| |
| <para>バグデータベースへの高機能の問い合わせ機能、および、調査対象のコードの複数のバージョンにわたる警告の追跡記録機能を、 FindBugs は内蔵しています。これらを使って次のようなことができます。すなわち、いつバグが最初持ち込まれたかを捜し出すこと、最終リリース以後持ち込まれた警告の分析を行うこと、または、無限再起ループの数を時間軸でグラフにすることです。</para> |
| |
| <para>これらの技術は、 FindBugs が警告の保存に使う XML 書式を使用します。これらの XML ファイルは、通常、特定の 1 分析に対する警告が入れられています。しかしそれらには、一連のソフトウェアのビルドやバージョンに対する分析結果を格納することもできます。</para> |
| |
| <para>すべての FindBugs XML バグデータベースには、バージョン名とタイム・スタンプ が入れられています。FindBugs は分析が行われるファイルの更新時刻からタイム・スタンプを計算します (例えば、タイム・スタンプはクラスファイルの生成時刻になるようになっています。分析が行われた時刻ではありません) 。各々のバグデータベースには、バージョン名も入れられています。バージョン名とタイム・スタンプは、 <command>setBugDatabaseInfo</command> (<xref linkend="setBugDatabaseInfo"/>) コマンドを使用して手動で設定することもできます。</para> |
| |
| <para>複数バージョンを格納するバグデータベースにおいては、分析されるコードの各バージョンごとにシーケンス番号が割り当てられます。これらのシーケンス番号は単に 0 から始まる連続する整数値です (例えば、 4 つのコードバージョンを格納するバグデータベースには、バージョン 0~3 が入れられます) 。バグデータベースにはまた、各バージョンの名前とタイム・スタンプがそれぞれ記録されます。<command>filterBugs</command> コマンドを使用すると、シーケンス番号、バージョン名またはタイム・スタンプからバージョンを参照することができます。</para> |
| |
| <para>1 バージョンを格納するバグデータベースの集合から、 1 個の複数バージョンバグデータベースを作成することができます。また、複数バージョンバグデータベースに対して、それ以後に作成された 1 バージョンのバグデータベースを結合することができます。</para> |
| |
| <para>これらのコマンドのいくつかは、 ant タスクとして実行することができます。コマンドの実行方法および属性・引数の詳細は、以下を参照してください。以下のすべての例においては、 <literal>findbugs.lib</literal> <literal>refid</literal> が正しく設定されていることを前提としています。設定方法の一例を次に示します :</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <!-- findbugs タスク定義 --> |
| <property name="findbugs.home" value="/your/path/to/findbugs" /> |
| <path id="findbugs.lib"> |
| <fileset dir="${findbugs.home}/lib"> |
| <include name="findbugs-ant.jar"/> |
| </fileset> |
| </path> |
| ]]> |
| </programlisting> |
| |
| <sect1 id="commands"> |
| <title>コマンド</title> |
| |
| <para>FindBugs データ・マイニング ツールはすべてコマンドラインから実行することができます。また、いくつかのより有用なコマンドは、 ant ビルドファイルから実行することができます。</para> |
| |
| <para>コマンドラインツールについて簡単に説明します :</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><command><link linkend="unionBugs">unionBugs</link></command></term> |
| <listitem> |
| <para>別のクラスに対する別個の分析結果を結合します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command><link linkend="computeBugHistory">computeBugHistory</link></command></term> |
| <listitem> |
| <para>複数バージョンから得られた複数のバグ警告を、マージして 1 個の複数バージョンバグデータベースにします。これを使って、既存の複数バージョンバグデータベースに更にバージョンを追加したり、 1 バージョンを格納するバグデータベースの集合から 1 個の複数バージョンバグデータベースを作成したり、できます。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command><link linkend="setBugDatabaseInfo">setBugDatabaseInfo</link></command></term> |
| <listitem> |
| <para>リビジョン名やタイム・スタンプなどの情報を XML データベースに設定します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command><link linkend="listBugDatabaseInfo">listBugDatabaseInfo</link></command></term> |
| <listitem> |
| <para>XML データベースにあるリビジョン名やタイム・スタンプなどの情報を一覧表示します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command><link linkend="filterBugs">filterBugs</link></command></term> |
| <listitem> |
| <para>バグデータベースの部分集合を選択します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command><link linkend="mineBugHistory">mineBugHistory</link></command></term> |
| <listitem> |
| <para>複数バージョンバグデータベースの各バージョン毎の警告数を一覧にした表を作成します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command><link linkend="defectDensity">defectDensity</link></command></term> |
| <listitem> |
| <para>プロジェクト全体およびクラス毎・パッケージ毎の不良密度 (1000 NCSS 毎の警告数) に関する情報を一覧表示します。</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><command><link linkend="convertXmlToText">convertXmlToText</link></command></term> |
| <listitem> |
| <para>XML 形式のバグ警告を、 1 行 1 バグのテキスト形式、または、HTML形式に変換します。</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| |
| <sect2 id="unionBugs"> |
| <title>unionBugs</title> |
| |
| <para>分析するのにアプリケーションの jar ファイルを分割している場合、このコマンドを使用することで、別個に生成された XML バグ警告ファイルをすべての警告を含んでいる 1 つの ファイルにすることができます。</para> |
| |
| <para>同じファイルの異なるバージョンを分析した結果を結合する場合は、このコマンドを<emphasis>使用しないでください</emphasis>。代わりに <command>computeBugHistory</command> を使用してください。</para> |
| |
| <para>XML ファイルは、コマンドラインで指定してください。結果は、標準出力に送られます。</para> |
| </sect2> |
| |
| <sect2 id="computeBugHistory"> |
| <title>computeBugHistory</title> |
| |
| <para>このコマンドを使用することで、分析するソフトウェアの異なるビルドまたはバージョンの情報を含むバグデータベースを生成することができます入力として提供したファイルの 1 番目のファイルから履歴が取得されます。後に続くファイルは 1 バージョンのバグデータベースであるようにしてください (もし、履歴を持っていたとしても無視されます) 。</para> |
| <para>デフォルトでは、結果は標準出力に送られます。</para> |
| |
| <para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>computeBugHistory</command> を taskdef で定義します :</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| ]]> |
| </programlisting> |
| |
| <para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal><datafile></literal> 要素を入れ子にして入れてください。次に、例を示します:</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <computeBugHistory home="${findbugs.home}" ...> |
| <datafile name="analyze1.xml"/> |
| <datafile name="analyze2.xml"/> |
| </computeBugHistory> |
| ]]> |
| </programlisting> |
| |
| <table id="computeBugHistoryTable"> |
| <title>computeBugHistory コマンドのオプション一覧</title> |
| <tgroup cols="3" align="left"> |
| <thead> |
| <row> |
| <entry>コマンドラインオプション</entry> |
| <entry>Ant 属性</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry>-output <file></entry> <entry>output="<file>"</entry> <entry>出力結果を保存するファイル名を指定します。 (同時に入力ファイルにもなりえます)</entry></row> |
| <row><entry>-overrideRevisionNames[:truth]</entry> <entry>overrideRevisionNames="[true|false]"</entry><entry>ファイル名から算出されるそれぞれのバージョン名を指定変更します。</entry></row> |
| <row><entry>-noPackageMoves[:truth]</entry> <entry>noPackageMoves="[true|false]"</entry><entry>パッケージを移動したクラスがある場合、当該クラスの警告は別の存在として扱われます。</entry></row> |
| <row><entry>-preciseMatch[:truth]</entry> <entry>preciseMatch="[true|false]"</entry><entry>バグパターンが正確に一致することを要求します。</entry></row> |
| <row><entry>-precisePriorityMatch[:truth]</entry> <entry>precisePriorityMatch="[true|false]"</entry><entry>優先度が正確に一致した場合のみ警告が同一であると判断されます。</entry></row> |
| <row><entry>-quiet[:truth]</entry> <entry>quiet="[true|false]"</entry><entry>エラーが発生しない限り、標準出力には何も表示されません。</entry></row> |
| <row><entry>-withMessages[:truth]</entry> <entry>withMessages="[true|false]"</entry><entry>出力 XML に人間が読むことができるバグメッセージが含まれます。</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| </sect2> |
| <sect2 id="filterBugs"> |
| <title>filterBugs</title> |
| <para>このコマンドを使用することで、 FindBugs XML 警告ファイルから一部分を選び出して新規 FindBugs 警告ファイルに選択された部分を書き込むことができます。</para> |
| <para>このコマンドには、オプション群に続いて 0 個から 2 個の findbugs xml バグファイルを指定することができます。</para> |
| <para>ファイル名をひとつも指定しない場合は、標準入力から読んで標準出力に出力されます。ファイル名を 1 個 指定した場合は、指定したファイルから読んで標準出力に出力されます。ファイル名を 2 個 指定した場合は、 1 番目に指定したファイルから読んで 2 番目に指定したファイルに出力されます。</para> |
| |
| <para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>filterBugs</command> を taskdef で定義します :</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <taskdef name="filterBugs" classname="edu.umd.cs.findbugs.anttask.FilterBugsTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| ]]> |
| </programlisting> |
| |
| <para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>input</literal> 属性を使用するか、 <literal><datafile></literal> 要素を入れ子にして入れてください。次に、例を示します:</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <filterBugs home="${findbugs.home}" ...> |
| <datafile name="analyze.xml"/> |
| </filterBugs> |
| ]]> |
| </programlisting> |
| |
| <table id="filterOptionsTable"> |
| <title>filterBugs コマンドのオプション一覧</title> |
| <tgroup cols="3" align="left"> |
| <thead> |
| <row> |
| <entry>コマンドラインオプション</entry> |
| <entry>Ant 属性</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry/> <entry>input="<file>"</entry> <entry>入力ファイルを指定します。</entry></row> |
| <row><entry/> <entry>output="<file>"</entry> <entry>出力ファイルを指定します。</entry></row> |
| <row><entry>-not</entry> <entry>not="[true|false]"</entry> <entry>フィルターのスイッチを反転します。</entry></row> |
| <row><entry>-withSource[:truth]</entry> <entry>withSource="[true|false]"</entry> <entry>ソースが入手可能な警告のみ出力されます。</entry></row> |
| <row><entry>-exclude <filter file></entry><entry>exclude="<filter file>"</entry> <entry>フィルターに一致するバグが除外されます。</entry></row> |
| <row><entry>-include <filter file></entry><entry>include="<filter file>"</entry> <entry>フィルターに一致するバグのみを含まれます。</entry></row> |
| <row><entry>-annotation <text></entry> <entry>annotation="<text>"</entry> <entry>手で入力した注釈に指定した文言を含む警告のみ出力されます。</entry></row> |
| <row><entry>-after <when></entry> <entry>after="<when>"</entry> <entry>指定したバージョンより後に初めて出現した警告のみ出力されます。</entry></row> |
| <row><entry>-before <when></entry> <entry>before="<when>"</entry> <entry>指定したバージョンより前に初めて出現した警告のみ出力されます。</entry></row> |
| <row><entry>-first <when></entry> <entry>first="<when>"</entry> <entry>指定したバージョンに初めて出現した警告のみ出力されます。</entry></row> |
| <row><entry>-last <when></entry> <entry>last="<when>"</entry> <entry>指定したバージョンが出現した最後である警告のみ出力されます。</entry></row> |
| <row><entry>-fixed <when></entry> <entry>fixed="<when>"</entry> <entry>指定したバージョンの前回のバージョンが出現した最後である警告のみ出力されます。 (<option>-last</option> に優先します)。</entry></row> |
| <row><entry>-present <when></entry> <entry>present="<when>"</entry> <entry>指定したバージョンに存在する警告のみ出力されます。</entry></row> |
| <row><entry>-absent <when></entry> <entry>absent="<when>"</entry> <entry>指定したバージョンに存在しない警告のみ出力されます。</entry></row> |
| <row><entry>-active[:truth]</entry> <entry>active="[true|false]"</entry> <entry>最終通番に存在する警告のみ出力されます。</entry></row> |
| <row><entry>-introducedByChange[:truth]</entry> <entry>introducedByChange="[true|false]"</entry><entry>存在するクラスの変更によってもたらされた警告のみ出力されます。</entry></row> |
| <row><entry>-removedByChange[:truth]</entry> <entry>removedByChange="[true|false]"</entry> <entry>存在するクラスの変更によって除去された警告のみ出力されます。</entry></row> |
| <row><entry>-newCode[:truth]</entry> <entry>newCode="[true|false]"</entry> <entry>新クラスの追加によってもたらされた警告のみ出力されます。</entry></row> |
| <row><entry>-removedCode[:truth]</entry> <entry>removedCode="[true|false]"</entry> <entry>クラスの削除によって除去された警告のみ出力されます。</entry></row> |
| <row><entry>-priority <level></entry> <entry>priority="<level>"</entry> <entry>指定した優先度以上の優先度をもつ警告のみ出力されます。</entry></row> |
| <row><entry>-maxRank <rank></entry> <entry>rank="[1..20]"</entry> <entry>allow only warnings with this rank or lower</entry></row> |
| <row><entry>-class <pattern></entry> <entry>class="<class>"</entry> <entry>指定したパターンに一致する主クラスをもつ警告のみ出力されます。</entry></row> |
| <row><entry>-bugPattern <pattern></entry> <entry>bugPattern="<pattern>"</entry> <entry>指定したパターンに一致するバグ種別をもつ警告のみ出力されます。</entry></row> |
| <row><entry>-category <category></entry> <entry>category="<category>"</entry> <entry>指定した文字列で始まるカテゴリーの警告のみ出力されます。</entry></row> |
| <row><entry>-designation <designation></entry> <entry>designation="<designation>"</entry> <entry>指定したバグ分類指定をもつ警告のみ出力されます。 (例、 -designation SHOULD_FIX)</entry></row> |
| <row><entry>-withMessages[:truth] </entry> <entry>withMessages="[true|false]"</entry> <entry>テキストメッセージを含んだ XML が生成されます。</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| </sect2> |
| |
| <sect2 id="mineBugHistory"> |
| <title>mineBugHistory</title> |
| <para>このコマンドを使用することで、複数バージョンバグデータベースの各バージョン毎の警告数を一覧にした表を作成することができます。</para> |
| |
| |
| <para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>mineBugHistory</command> を taskdef で定義します :</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| ]]> |
| </programlisting> |
| |
| <para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>input</literal> 属性を使用するか、 <literal><datafile></literal> 要素を入れ子にして入れてください。次に、例を示します:</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <mineBugHistory home="${findbugs.home}" ...> |
| <datafile name="analyze.xml"/> |
| </mineBugHistory> |
| ]]> |
| </programlisting> |
| |
| <table id="mineBugHistoryOptionsTable"> |
| <title>mineBugHistory コマンドのオプション一覧</title> |
| <tgroup cols="3" align="left"> |
| <thead> |
| <row> |
| <entry>コマンドラインオプション</entry> |
| <entry>Ant 属性</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry/> <entry>input="<file>"</entry> <entry>入力ファイルを指定します。</entry></row> |
| <row><entry/> <entry>output="<file>"</entry> <entry>出力ファイルを指定します。</entry></row> |
| <row><entry>-formatDates</entry> <entry>formatDates="[true|false]"</entry> <entry>データがテキスト形式で描画されます。</entry></row> |
| <row><entry>-noTabs</entry> <entry>noTabs="[true|false]"</entry> <entry>タブの代わりに複数スペースでカラムが区切られます (下記参照)。</entry></row> |
| <row><entry>-summary</entry> <entry>summary="[true|false]"</entry> <entry>最新 10 件の変更の要約が出力されます。</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para><option>-noTabs</option> 出力を使うことで、固定幅フォントのシェルで読み易くなります。数値カラムは右寄せされるので、スペースがカラム値の前に挿入されます。また、このオプションを使用した場合、 <option>-formatDates</option> を指定したときに要約の日付を描画するのに空白が埋め込まれなくなります。</para> |
| |
| <para>出力される表は、 (<option>-noTabs</option> が無ければ) タブ区切りで次に示すカラムから成ります :</para> |
| |
| <table id="mineBugHistoryColumns"> |
| <title>mineBugHistory 出力のカラム一覧</title> |
| <tgroup cols="2" align="left"> |
| <thead> |
| <row> |
| <entry>表題</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry>seq</entry><entry>シーケンス番号 (0 始まりの連続した整数値)</entry></row> |
| <row><entry>version</entry><entry>バージョン名</entry></row> |
| <row><entry>time</entry><entry>リリースされた日時</entry></row> |
| <row><entry>classes</entry><entry>分析されたクラス数</entry></row> |
| <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements)</entry></row> |
| <row><entry>added</entry><entry>前回のバージョンに存在したクラスにおける新規警告数</entry></row> |
| <row><entry>newCode</entry><entry>前回のバージョンに存在しなかったクラスにおける新規警告数</entry></row> |
| <row><entry>fixed</entry><entry>現在のバージョンに存在するクラスにおける除去された警告数</entry></row> |
| <row><entry>removed</entry><entry>現在のバージョンに存在しないクラスの前回のバージョンにおける警告数</entry></row> |
| <row><entry>retained</entry><entry>現在のバージョンと前回のバージョンの両方に存在する警告の数</entry></row> |
| <row><entry>dead</entry><entry>以前のバージョンに存在したが現在のバージョンにも直前のバージョンにも存在しない警告の数</entry></row> |
| <row><entry>active</entry><entry>現在のバージョンに存在する警告総数</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| </sect2> |
| |
| <sect2 id="defectDensity"> |
| <title>defectDensity</title> |
| <para>このコマンドを使用することで、プロジェクト全体およびクラス毎・パッケージ毎の不良密度 (1000 NCSS 毎の警告数) に関する情報を一覧表示できます。標準入力から読み込む場合はファイル指定なしで、そうでなければ、コマンドラインでファイルを指定して、このコマンドを実行します。</para> |
| <para>出力される表は、次に示すカラムから成ります。また、プロジェクト全体情報の行、および、4 個以上の警告を含んでいる各パッケージ情報または各クラス情報の行も出力されます。</para> |
| <table id="defectDensityColumns"> |
| <title>defectDensity 出力のカラム一覧</title> |
| <tgroup cols="2" align="left"> |
| <thead> |
| <row> |
| <entry>表題</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry>kind</entry><entry>プロジェクト (project)、パッケージ (package) またはクラス (class)</entry></row> |
| <row><entry>name</entry><entry>プロジェクト、パッケージまたはクラスの名前</entry></row> |
| <row><entry>density</entry><entry> 1000 NCSS 毎の警告数</entry></row> |
| <row><entry>bugs</entry><entry>警告数</entry></row> |
| <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements) </entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| </sect2> |
| |
| <sect2 id="convertXmlToText"> |
| <title>convertXmlToText</title> |
| |
| <para>このコマンドを使用することで、XML 形式のバグ警告を、 1 行 1 バグのテキスト形式、または、HTML形式に変換することができます。</para> |
| |
| <para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>convertXmlToText</command> を taskdef で定義します :</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <taskdef name="convertXmlToText" classname="edu.umd.cs.findbugs.anttask.ConvertXmlToTextTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| ]]> |
| </programlisting> |
| |
| <para>この ant タスクに指定できる属性を、下表に一覧で示します。</para> |
| |
| <table id="convertXmlToTextTable"> |
| <title>convertXmlToText コマンドのオプション一覧</title> |
| <tgroup cols="3" align="left"> |
| <thead> |
| <row> |
| <entry>コマンドラインオプション</entry> |
| <entry>Ant 属性</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry/> <entry>input="<filename>"</entry> <entry>入力ファイルを指定します。</entry></row> |
| <row><entry/> <entry>output="<filename>"</entry> <entry>出力ファイルを指定します。</entry></row> |
| <row><entry>-longBugCodes</entry> <entry>longBugCodes="[true|false]"</entry> <entry>2 文字のバグ略称の代わりに、省略なしのバグパターンコードを使用します。</entry></row> |
| <row><entry/> <entry>format="text"</entry> <entry>プレーンテキストの出力が作成されます。1 行につき 1 つのバグが出力されます。コマンドライン時のデフォルトです。</entry></row> |
| <row><entry>-html[:stylesheet]</entry> <entry>format="html:<stylesheet>"</entry> <entry>指定されたスタイルシートを使用して出力が作成されます (下記参照) 。省略した場合は、 default.xsl が使用されます。</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <para>-html/format オプションには、plain.xsl 、 default.xsl 、 fancy.xsl 、 fancy-hist.xsl または ユーザ自身が作成した XSL スタイルシートのいずれかを指定することができます。オプション名をよそに、 html 以外の形式を出力するスタイルシートを指定することもできます。FindBugs に含まれているスタイルシート(上述)以外のスタイルシートを使用する場合は、オプション -html/format で当該スタイルシートへのパスまたは URL を指定してください。</para> |
| </sect2> |
| |
| <sect2 id="setBugDatabaseInfo"> |
| <title>setBugDatabaseInfo</title> |
| |
| <para>このコマンドを使用することで、指定したバグ警告にメタ情報を設定することができます。このコマンドには次に示すオプションがあります:</para> |
| |
| <para>この機能は、 ant からも使用することができます。まず次に示すように、ビルドファイルに <command>setBugDatabaseInfo</command> を taskdef で定義します :</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| ]]> |
| </programlisting> |
| |
| <para>この ant タスクに指定できる属性を、下表に一覧で示します。入力ファイルを指定するには、 <literal>input</literal> 属性を使用するか、 <literal><datafile></literal> 要素を入れ子にして入れてください。次に、例を示します:</para> |
| |
| <programlisting> |
| <![CDATA[ |
| <setBugDatabaseInfo home="${findbugs.home}" ...> |
| <datafile name="analyze.xml"/> |
| </setBugDatabaseInfo> |
| ]]> |
| </programlisting> |
| |
| <table id="setBugDatabaseInfoOptions"> |
| <title>setBugDatabaseInfo オプション一覧</title> |
| <tgroup cols="3" align="left"> |
| <thead> |
| <row> |
| <entry>コマンドラインオプション</entry> |
| <entry>Ant 属性</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry/> <entry>input="<file>"</entry> <entry>入力ファイルを指定します。</entry></row> |
| <row><entry/> <entry>output="<file>"</entry> <entry>出力ファイルを指定します。</entry></row> |
| <row><entry>-name <name></entry> <entry>name="<name>"</entry> <entry>最新リビジョンの名前を設定します。</entry></row> |
| <row><entry>-timestamp <when></entry> <entry>timestamp="<when>"</entry> <entry>最新リビジョンのタイム・スタンプを設定します。</entry></row> |
| <row><entry>-source <directory></entry> <entry>source="<directory>"</entry> <entry>ソースを検索するディレクトリーを追加指定します。</entry></row> |
| <row><entry>-findSource <directory></entry> <entry>findSource="<directory>"</entry> <entry>指定したディレクトリー内を検索して関連するソースの場所を追加します。</entry></row> |
| <row><entry>-suppress <filter file></entry> <entry>suppress="<filter file>"</entry> <entry>指定したファイルに一致する警告を抑止します (以前に指定した抑止設定は置き換えられます)。</entry></row> |
| <row><entry>-withMessages</entry> <entry>withMessages="[true|false]"</entry> <entry>XMLにテキストメッセージを追加します。</entry></row> |
| <row><entry>-resetSource</entry> <entry>resetSource="[true|false]"</entry> <entry>ソース検索パスをすべて削除します。</entry></row> |
| </tbody> |
| </tgroup> |
| </table> |
| </sect2> |
| |
| <sect2 id="listBugDatabaseInfo"> |
| <title>listBugDatabaseInfo</title> |
| |
| <para>このコマンドの実行においては、コマンドラインで 0 個以上の xml バグデータベースファイル名を指定します。ファイル名を1つも指定しなければ、標準出力から読み込みを行いテーブルのヘッダーは生成されません。</para> |
| |
| <para>このコマンドには 1 つだけオプションがあります : <option>-formatDates</option> を指定するとテキスト形式でデータが描画されます。</para> |
| |
| <para>出力される表は、各バグデータベースごとに行を持ち、次に示すカラムから成ります :</para> |
| <table id="listBugDatabaseInfoColumns"> |
| <title>listBugDatabaseInfo カラム一覧</title> |
| <tgroup cols="2" align="left"> |
| <thead> |
| <row> |
| <entry>カラム</entry> |
| <entry>目的</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row><entry>version</entry><entry>バージョン名</entry></row> |
| <row><entry>time</entry><entry>リリースされた日時</entry></row> |
| <row><entry>classes</entry><entry>分析されたクラス数</entry></row> |
| <row><entry>NCSS</entry><entry>コメント文を除いた命令数 (Non Commenting Source Statements)</entry></row> |
| <row><entry>total</entry><entry>全警告数</entry></row> |
| <row><entry>high</entry><entry>優先度(高)の警告の総数</entry></row> |
| <row><entry>medium</entry><entry>優先度(中)の警告の総数</entry></row> |
| <row><entry>low</entry><entry>優先度(低)の警告の総数</entry></row> |
| <row><entry>filename</entry><entry>データベースのファイル名</entry></row> |
| <!-- |
| <row><entry></entry><entry></entry></row> |
| <row><entry></entry><entry></entry></row> |
| <row><entry></entry><entry></entry></row> |
| <row><entry></entry><entry></entry></row> |
| <row><entry></entry><entry></entry></row> |
| <row><entry></entry><entry></entry></row> |
| --> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| </sect2> |
| |
| </sect1> |
| |
| <sect1 id="examples"> |
| <title>例</title> |
| <sect2 id="unixscriptsexamples"> |
| <title>提供されたシェル・スクリプトを使用しての履歴マイニング</title> |
| <para>以下はすべて、 jdk1.6.0-b12, jdk1.6.0-b13, ..., jdk1.6.0-b60 のディレクトリに対してコマンドを実行しています。</para> |
| |
| <para>以下のコマンドを実行してみます :</para> |
| <screen> |
| computeBugHistory jdk1.6.0-b* | filterBugs -bugPattern IL_ | mineBugHistory -formatDates |
| </screen> |
| <para>すると、次のような出力が行われます :</para> |
| |
| <screen> |
| seq version time classes NCSS added newCode fixed removed retained dead active |
| 0 jdk1.6.0-b12 "Thu Nov 11 09:07:20 EST 2004" 13128 811569 0 4 0 0 0 0 4 |
| 1 jdk1.6.0-b13 "Thu Nov 18 06:02:06 EST 2004" 13128 811570 0 0 0 0 4 0 4 |
| 2 jdk1.6.0-b14 "Thu Dec 02 06:12:26 EST 2004" 13145 811786 0 0 2 0 2 0 2 |
| 3 jdk1.6.0-b15 "Thu Dec 09 06:07:04 EST 2004" 13174 811693 0 0 1 0 1 2 1 |
| 4 jdk1.6.0-b16 "Thu Dec 16 06:21:28 EST 2004" 13175 811715 0 0 0 0 1 3 1 |
| 5 jdk1.6.0-b17 "Thu Dec 23 06:27:22 EST 2004" 13176 811974 0 0 0 0 1 3 1 |
| 6 jdk1.6.0-b19 "Thu Jan 13 06:41:16 EST 2005" 13176 812011 0 0 0 0 1 3 1 |
| 7 jdk1.6.0-b21 "Thu Jan 27 05:57:52 EST 2005" 13177 812173 0 0 0 0 1 3 1 |
| 8 jdk1.6.0-b23 "Thu Feb 10 05:44:36 EST 2005" 13179 812188 0 0 0 0 1 3 1 |
| 9 jdk1.6.0-b26 "Thu Mar 03 06:04:02 EST 2005" 13199 811770 0 0 0 0 1 3 1 |
| 10 jdk1.6.0-b27 "Thu Mar 10 04:48:38 EST 2005" 13189 812440 0 0 0 0 1 3 1 |
| 11 jdk1.6.0-b28 "Thu Mar 17 02:54:22 EST 2005" 13185 812056 0 0 0 0 1 3 1 |
| 12 jdk1.6.0-b29 "Thu Mar 24 03:09:20 EST 2005" 13117 809468 0 0 0 0 1 3 1 |
| 13 jdk1.6.0-b30 "Thu Mar 31 02:53:32 EST 2005" 13118 809501 0 0 0 0 1 3 1 |
| 14 jdk1.6.0-b31 "Thu Apr 07 03:00:14 EDT 2005" 13117 809572 0 0 0 0 1 3 1 |
| 15 jdk1.6.0-b32 "Thu Apr 14 02:56:56 EDT 2005" 13169 811096 0 0 0 0 1 3 1 |
| 16 jdk1.6.0-b33 "Thu Apr 21 02:46:22 EDT 2005" 13187 811942 0 0 0 0 1 3 1 |
| 17 jdk1.6.0-b34 "Thu Apr 28 02:49:00 EDT 2005" 13195 813488 0 1 0 0 1 3 2 |
| 18 jdk1.6.0-b35 "Thu May 05 02:49:04 EDT 2005" 13457 829837 0 0 0 0 2 3 2 |
| 19 jdk1.6.0-b36 "Thu May 12 02:59:46 EDT 2005" 13462 831278 0 0 0 0 2 3 2 |
| 20 jdk1.6.0-b37 "Thu May 19 02:55:08 EDT 2005" 13464 831971 0 0 0 0 2 3 2 |
| 21 jdk1.6.0-b38 "Thu May 26 03:08:16 EDT 2005" 13564 836565 0 0 0 0 2 3 2 |
| 22 jdk1.6.0-b39 "Fri Jun 03 03:10:48 EDT 2005" 13856 849992 0 1 0 0 2 3 3 |
| 23 jdk1.6.0-b40 "Thu Jun 09 03:30:28 EDT 2005" 15972 959619 0 2 0 0 3 3 5 |
| 24 jdk1.6.0-b41 "Thu Jun 16 03:19:22 EDT 2005" 15972 959619 0 0 0 0 5 3 5 |
| 25 jdk1.6.0-b42 "Fri Jun 24 03:38:54 EDT 2005" 15966 958581 0 0 0 0 5 3 5 |
| 26 jdk1.6.0-b43 "Thu Jul 14 03:09:34 EDT 2005" 16041 960544 0 0 0 0 5 3 5 |
| 27 jdk1.6.0-b44 "Thu Jul 21 03:05:54 EDT 2005" 16041 960547 0 0 0 0 5 3 5 |
| 28 jdk1.6.0-b45 "Thu Jul 28 03:26:10 EDT 2005" 16037 960606 0 0 1 0 4 3 4 |
| 29 jdk1.6.0-b46 "Thu Aug 04 03:02:48 EDT 2005" 15936 951355 0 0 0 0 4 4 4 |
| 30 jdk1.6.0-b47 "Thu Aug 11 03:18:56 EDT 2005" 15964 952387 0 0 1 0 3 4 3 |
| 31 jdk1.6.0-b48 "Thu Aug 18 08:10:40 EDT 2005" 15970 953421 0 0 0 0 3 5 3 |
| 32 jdk1.6.0-b49 "Thu Aug 25 03:24:38 EDT 2005" 16048 958940 0 0 0 0 3 5 3 |
| 33 jdk1.6.0-b50 "Thu Sep 01 01:52:40 EDT 2005" 16287 974937 1 0 0 0 3 5 4 |
| 34 jdk1.6.0-b51 "Thu Sep 08 01:55:36 EDT 2005" 16362 979377 0 0 0 0 4 5 4 |
| 35 jdk1.6.0-b52 "Thu Sep 15 02:04:08 EDT 2005" 16477 979399 0 0 0 0 4 5 4 |
| 36 jdk1.6.0-b53 "Thu Sep 22 02:00:28 EDT 2005" 16019 957900 0 0 1 0 3 5 3 |
| 37 jdk1.6.0-b54 "Thu Sep 29 01:54:34 EDT 2005" 16019 957900 0 0 0 0 3 6 3 |
| 38 jdk1.6.0-b55 "Thu Oct 06 01:54:14 EDT 2005" 16051 959014 0 0 0 0 3 6 3 |
| 39 jdk1.6.0-b56 "Thu Oct 13 01:54:12 EDT 2005" 16211 970835 0 0 0 0 3 6 3 |
| 40 jdk1.6.0-b57 "Thu Oct 20 01:55:26 EDT 2005" 16279 971627 0 0 0 0 3 6 3 |
| 41 jdk1.6.0-b58 "Thu Oct 27 01:56:30 EDT 2005" 16283 971945 0 0 0 0 3 6 3 |
| 42 jdk1.6.0-b59 "Thu Nov 03 01:56:58 EST 2005" 16232 972193 0 0 0 0 3 6 3 |
| 43 jdk1.6.0-b60 "Thu Nov 10 01:54:18 EST 2005" 16235 972346 0 0 0 0 3 6 3 |
| </screen> |
| |
| <para>次に示すコマンドを実行すると、db.xml 中間ファイルを生成することなく直接同じ情報を作成できます。</para> |
| |
| <screen> |
| computeBugHistory jdk1.6.0-b*/jre/lib/rt.xml | filterBugs -bugPattern IL_ db.xml | mineBugHistory -formatDates |
| </screen> |
| |
| <para>この情報を使って、 Sun JDK1.6.0 の各ビルドにおいて FindBugs によって発見された無限再起ループの数を表すグラフを表示します。青色の領域は、当該ビルドにおける無限再起ループの数を表しています。その上に描かれている赤色の領域は、以前のバージョンには存在したが当該バージョンでは除去された無限再起ループの数を表しています。 (したがって、赤色の領域と青色の領域を足し合わせた高さは決して減少しないことが保証されています。そして、新たに無限再起ループのバグが持ち込まれた時点で増加します) 。赤色の領域の高さは、当該バージョンにおいて修正または削除されたバグ数の合計で算出されます。バージョン 13 および 14 において見られる減少は、 FindBugs を使用して見つかった JDK のバグの報告を Sun が受け取ったことによるものです。</para> |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="infiniteRecursiveLoops.png"/> |
| </imageobject> |
| </mediaobject> |
| |
| <para>db.xml ファイルは、 jdk1.6.0 のすべてのビルドに対する検索結果を保持しています。したがって、次に示すコマンドを実行することで、優先度(高)または優先度(低)の正確性に関する警告の履歴が表示されます :</para> |
| |
| <screen> |
| filterBugs -priority M -category C db.xml | mineBugHistory -formatDates |
| </screen> |
| |
| <para>作成される表の例 :</para> |
| |
| <screen> |
| seq version time classes NCSS added newCode fixed removed retained dead active |
| 0 jdk1.6.0-b12 "Thu Nov 11 09:07:20 EST 2004" 13128 811569 0 1075 0 0 0 0 1075 |
| 1 jdk1.6.0-b13 "Thu Nov 18 06:02:06 EST 2004" 13128 811570 0 0 0 0 1075 0 1075 |
| 2 jdk1.6.0-b14 "Thu Dec 02 06:12:26 EST 2004" 13145 811786 3 0 6 0 1069 0 1072 |
| 3 jdk1.6.0-b15 "Thu Dec 09 06:07:04 EST 2004" 13174 811693 2 1 3 0 1069 6 1072 |
| 4 jdk1.6.0-b16 "Thu Dec 16 06:21:28 EST 2004" 13175 811715 0 0 1 0 1071 9 1071 |
| 5 jdk1.6.0-b17 "Thu Dec 23 06:27:22 EST 2004" 13176 811974 0 0 1 0 1070 10 1070 |
| 6 jdk1.6.0-b19 "Thu Jan 13 06:41:16 EST 2005" 13176 812011 0 0 0 0 1070 11 1070 |
| 7 jdk1.6.0-b21 "Thu Jan 27 05:57:52 EST 2005" 13177 812173 0 0 1 0 1069 11 1069 |
| 8 jdk1.6.0-b23 "Thu Feb 10 05:44:36 EST 2005" 13179 812188 0 0 0 0 1069 12 1069 |
| 9 jdk1.6.0-b26 "Thu Mar 03 06:04:02 EST 2005" 13199 811770 0 0 2 1 1066 12 1066 |
| 10 jdk1.6.0-b27 "Thu Mar 10 04:48:38 EST 2005" 13189 812440 1 0 1 1 1064 15 1065 |
| 11 jdk1.6.0-b28 "Thu Mar 17 02:54:22 EST 2005" 13185 812056 0 0 0 0 1065 17 1065 |
| 12 jdk1.6.0-b29 "Thu Mar 24 03:09:20 EST 2005" 13117 809468 3 0 8 26 1031 17 1034 |
| 13 jdk1.6.0-b30 "Thu Mar 31 02:53:32 EST 2005" 13118 809501 0 0 0 0 1034 51 1034 |
| 14 jdk1.6.0-b31 "Thu Apr 07 03:00:14 EDT 2005" 13117 809572 0 0 0 0 1034 51 1034 |
| 15 jdk1.6.0-b32 "Thu Apr 14 02:56:56 EDT 2005" 13169 811096 1 1 0 1 1033 51 1035 |
| 16 jdk1.6.0-b33 "Thu Apr 21 02:46:22 EDT 2005" 13187 811942 3 0 2 1 1032 52 1035 |
| 17 jdk1.6.0-b34 "Thu Apr 28 02:49:00 EDT 2005" 13195 813488 0 1 0 0 1035 55 1036 |
| 18 jdk1.6.0-b35 "Thu May 05 02:49:04 EDT 2005" 13457 829837 0 36 2 0 1034 55 1070 |
| 19 jdk1.6.0-b36 "Thu May 12 02:59:46 EDT 2005" 13462 831278 0 0 0 0 1070 57 1070 |
| 20 jdk1.6.0-b37 "Thu May 19 02:55:08 EDT 2005" 13464 831971 0 1 1 0 1069 57 1070 |
| 21 jdk1.6.0-b38 "Thu May 26 03:08:16 EDT 2005" 13564 836565 1 7 2 6 1062 58 1070 |
| 22 jdk1.6.0-b39 "Fri Jun 03 03:10:48 EDT 2005" 13856 849992 6 39 5 0 1065 66 1110 |
| 23 jdk1.6.0-b40 "Thu Jun 09 03:30:28 EDT 2005" 15972 959619 7 147 11 0 1099 71 1253 |
| 24 jdk1.6.0-b41 "Thu Jun 16 03:19:22 EDT 2005" 15972 959619 0 0 0 0 1253 82 1253 |
| 25 jdk1.6.0-b42 "Fri Jun 24 03:38:54 EDT 2005" 15966 958581 3 0 1 2 1250 82 1253 |
| 26 jdk1.6.0-b43 "Thu Jul 14 03:09:34 EDT 2005" 16041 960544 5 11 15 8 1230 85 1246 |
| 27 jdk1.6.0-b44 "Thu Jul 21 03:05:54 EDT 2005" 16041 960547 0 0 0 0 1246 108 1246 |
| 28 jdk1.6.0-b45 "Thu Jul 28 03:26:10 EDT 2005" 16037 960606 19 0 2 0 1244 108 1263 |
| 29 jdk1.6.0-b46 "Thu Aug 04 03:02:48 EDT 2005" 15936 951355 13 1 1 32 1230 110 1244 |
| 30 jdk1.6.0-b47 "Thu Aug 11 03:18:56 EDT 2005" 15964 952387 163 8 7 20 1217 143 1388 |
| 31 jdk1.6.0-b48 "Thu Aug 18 08:10:40 EDT 2005" 15970 953421 0 0 0 0 1388 170 1388 |
| 32 jdk1.6.0-b49 "Thu Aug 25 03:24:38 EDT 2005" 16048 958940 1 11 1 0 1387 170 1399 |
| 33 jdk1.6.0-b50 "Thu Sep 01 01:52:40 EDT 2005" 16287 974937 19 27 16 7 1376 171 1422 |
| 34 jdk1.6.0-b51 "Thu Sep 08 01:55:36 EDT 2005" 16362 979377 1 15 3 0 1419 194 1435 |
| 35 jdk1.6.0-b52 "Thu Sep 15 02:04:08 EDT 2005" 16477 979399 0 0 1 1 1433 197 1433 |
| 36 jdk1.6.0-b53 "Thu Sep 22 02:00:28 EDT 2005" 16019 957900 13 12 16 20 1397 199 1422 |
| 37 jdk1.6.0-b54 "Thu Sep 29 01:54:34 EDT 2005" 16019 957900 0 0 0 0 1422 235 1422 |
| 38 jdk1.6.0-b55 "Thu Oct 06 01:54:14 EDT 2005" 16051 959014 1 4 7 0 1415 235 1420 |
| 39 jdk1.6.0-b56 "Thu Oct 13 01:54:12 EDT 2005" 16211 970835 6 8 37 0 1383 242 1397 |
| 40 jdk1.6.0-b57 "Thu Oct 20 01:55:26 EDT 2005" 16279 971627 0 0 0 0 1397 279 1397 |
| 41 jdk1.6.0-b58 "Thu Oct 27 01:56:30 EDT 2005" 16283 971945 0 1 1 0 1396 279 1397 |
| 42 jdk1.6.0-b59 "Thu Nov 03 01:56:58 EST 2005" 16232 972193 6 0 5 0 1392 280 1398 |
| 43 jdk1.6.0-b60 "Thu Nov 10 01:54:18 EST 2005" 16235 972346 0 0 0 0 1398 285 1398 |
| 44 jdk1.6.0-b61 "Thu Nov 17 01:58:42 EST 2005" 16202 971134 2 0 4 0 1394 285 1396 |
| </screen> |
| </sect2> |
| |
| <sect2 id="incrementalhistory"> |
| <title>増分履歴メンテナンス</title> |
| |
| <para>仮に、 db.xml がビルド b12 - b60 に対する findbugs 実行結果を保持している場合、次に示すコマンドを実行することで、 db.xml に b61 に対する実行結果を追加することができます :</para> |
| <screen> |
| computeBugHistory -output db.xml db.xml jdk1.6.0-b61/jre/lib/rt.xml |
| </screen> |
| </sect2> |
| |
| </sect1> |
| |
| <sect1 id="antexample"> |
| <title>Ant の例</title> |
| <para>findbugs の実行とその後のデータ・マイニングツールの活用の両方を実行している ant スクリプトの完全な例を以下に示します :</para> |
| <screen> |
| <![CDATA[ |
| <project name="analyze_asm_util" default="findbugs"> |
| <!-- findbugs タスク定義 --> |
| <property name="findbugs.home" value="/Users/ben/Documents/workspace/findbugs/findbugs" /> |
| <property name="jvmargs" value="-server -Xss1m -Xmx800m -Duser.language=en -Duser.region=EN -Dfindbugs.home=${findbugs.home}" /> |
| |
| <path id="findbugs.lib"> |
| <fileset dir="${findbugs.home}/lib"> |
| <include name="findbugs-ant.jar"/> |
| </fileset> |
| </path> |
| |
| <taskdef name="findbugs" classname="edu.umd.cs.findbugs.anttask.FindBugsTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| |
| <taskdef name="computeBugHistory" classname="edu.umd.cs.findbugs.anttask.ComputeBugHistoryTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| |
| <taskdef name="setBugDatabaseInfo" classname="edu.umd.cs.findbugs.anttask.SetBugDatabaseInfoTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| |
| <taskdef name="mineBugHistory" classname="edu.umd.cs.findbugs.anttask.MineBugHistoryTask"> |
| <classpath refid="findbugs.lib" /> |
| </taskdef> |
| |
| <!-- findbugs タスク定義 --> |
| <target name="findbugs"> |
| <antcall target="analyze" /> |
| <antcall target="mine" /> |
| </target> |
| |
| <!-- 分析を行うタスク--> |
| <target name="analyze"> |
| <!-- asm-util に対して findbugs を実行する --> |
| <findbugs home="${findbugs.home}" |
| output="xml:withMessages" |
| timeout="90000000" |
| reportLevel="experimental" |
| workHard="true" |
| effort="max" |
| adjustExperimental="true" |
| jvmargs="${jvmargs}" |
| failOnError="true" |
| outputFile="out.xml" |
| projectName="Findbugs" |
| debug="false"> |
| <class location="asm-util-3.0.jar" /> |
| </findbugs> |
| </target> |
| |
| <target name="mine"> |
| |
| <!-- 最新の分析結果に情報を設定する --> |
| <setBugDatabaseInfo home="${findbugs.home}" |
| withMessages="true" |
| name="asm-util-3.0.jar" |
| input="out.xml" |
| output="out-rel.xml"/> |
| |
| <!-- 履歴ファイル (out-hist.xml) が既に存在するかどうかを確認する --> |
| <condition property="mining.historyfile.available"> |
| <available file="out-hist.xml"/> |
| </condition> |
| <condition property="mining.historyfile.notavailable"> |
| <not> |
| <available file="out-hist.xml"/> |
| </not> |
| </condition> |
| |
| <!-- このターゲットは、履歴ファイルが存在しないとき (初回) だけ実行されます --> |
| <antcall target="history-init"> |
| <param name="data.file" value="out-rel.xml" /> |
| <param name="hist.file" value="out-hist.xml" /> |
| </antcall> |
| <!-- 上記以外の場合に実行されます --> |
| <antcall target="history"> |
| <param name="data.file" value="out-rel.xml" /> |
| <param name="hist.file" value="out-hist.xml" /> |
| <param name="hist.summary.file" value="out-hist.txt" /> |
| </antcall> |
| </target> |
| |
| <!-- 履歴ファイルを初期化します --> |
| <target name="history-init" if="mining.historyfile.notavailable"> |
| <copy file="${data.file}" tofile="${hist.file}" /> |
| </target> |
| |
| <!-- バグ履歴を算出します --> |
| <target name="history" if="mining.historyfile.available"> |
| <!-- ${data.file} を ${hist.file} にマージします --> |
| <computeBugHistory home="${findbugs.home}" |
| withMessages="true" |
| output="${hist.file}"> |
| <dataFile name="${hist.file}"/> |
| <dataFile name="${data.file}"/> |
| </computeBugHistory> |
| |
| <!-- 履歴を算出して ${hist.summary.file} に出力します --> |
| <mineBugHistory home="${findbugs.home}" |
| formatDates="true" |
| noTabs="true" |
| input="${hist.file}" |
| output="${hist.summary.file}"/> |
| </target> |
| |
| </project> |
| ]]> |
| </screen> |
| </sect1> |
| </chapter> |
| |
| |
| <!-- |
| ************************************************************************** |
| License |
| ************************************************************************** |
| --> |
| |
| <chapter id="license"> |
| <title>ライセンス</title> |
| |
| <para>名称「FindBugs」および FindBugs のロゴは、メリーランド大学の登録商標です。FindBugs はフリーソフトウェアであり、 <ulink url="http://www.gnu.org/licenses/lgpl.html">Lesser GNU Public License</ulink> の条件で配布されています。使用承諾書を入手したい場合は、 &FindBugs; 配布物に含まれる <filename>LICENSE.txt</filename> ファイルを参照してください。</para> |
| |
| <para>最新バージョンの FindBugs および そのソースコードは <ulink url="http://findbugs.sourceforge.net">FindBugs web ページ</ulink> で入手できます。</para> |
| |
| </chapter> |
| |
| |
| <!-- |
| ************************************************************************** |
| Acknowledgments |
| ************************************************************************** |
| --> |
| <chapter id="acknowledgments"> |
| <title>謝辞</title> |
| |
| <sect1> |
| <title>貢献者</title> |
| |
| <para>&FindBugs; was originally written by Bill Pugh (<email>pugh@cs.umd.edu</email>). |
| David Hovemeyer (<email>daveho@cs.umd.edu</email>) implemented some of the |
| detectors, added the Swing GUI, and is a co-maintainer.</para> |
| |
| <para>Mike Fagan (<email>mfagan@tde.com</email>) contributed the &Ant; build script, |
| the &Ant; task, and several enhancements and bug fixes to the GUI.</para> |
| |
| <para>Germano Leichsenring contributed Japanese translations of the bug |
| summaries.</para> |
| |
| <para>David Li contributed the Emacs bug report format.</para> |
| |
| <para>Peter D. Stout contributed recursive detection of Class-Path |
| attributes in analyzed Jar files, German translations of |
| text used in the Swing GUI, and other fixes.</para> |
| |
| <para>Peter Friese wrote the &FindBugs; Eclipse plugin.</para> |
| |
| <para>Rohan Lloyd contributed several Mac OS X enhancements, |
| bug detector improvements, |
| and maintains the Fink package for &FindBugs;.</para> |
| |
| <para>Hiroshi Okugawa translated the &FindBugs; manual and |
| more of the bug summaries into Japanese.</para> |
| |
| <para>Phil Crosby enhanced the Eclipse plugin to add a view |
| to display the bug details.</para> |
| |
| <para>Dave Brosius fixed a number of bugs, added user preferences |
| to the Swing GUI, improved several bug detectors, and |
| contributed the string concatenation detector.</para> |
| |
| <para>Thomas Klaeger contributed a number of bug fixes and |
| bug detector improvements.</para> |
| |
| <para>Andrey Loskutov made a number of bug fixes and |
| bug detector improvements. He is maintainer of the Eclipse plugin.</para> |
| |
| <para>Brian Goetz contributed a major refactoring of the |
| visitor classes to improve readability and understandability.</para> |
| |
| <para> Pete Angstadt fixed several problems in the Swing GUI.</para> |
| |
| <para>Francis Lalonde provided a task resource file for the |
| FindBugs Ant task.</para> |
| |
| <para>Garvin LeClaire contributed support for output in |
| Xdocs format, for use by Maven.</para> |
| |
| <para>Holger Stenzhorn contributed improved German translations of items |
| in the Swing GUI.</para> |
| |
| <para>Juha Knuutila contributed Finnish translations of items |
| in the Swing GUI.</para> |
| |
| <para>Tanel Lebedev contributed Estonian translations of items |
| in the Swing GUI.</para> |
| |
| <para>Hanai Shisei (ruimo) contributed full Japanese translations of |
| bug messages, and text used in the Swing GUI.</para> |
| |
| <para>David Cotton contributed Fresh translations for bug |
| messages and for the Swing GUI.</para> |
| |
| <para>Michael Tamm contributed support for the "errorProperty" attribute |
| in the Ant task.</para> |
| |
| <para>Thomas Kuehne improved the German translation of the Swing GUI.</para> |
| |
| <para>Len Trigg improved source file support for the Emacs output mode.</para> |
| |
| <para>Greg Bentz provided a fix for the hashcode/equals detector.</para> |
| |
| <para>K. Hashimoto contributed internationalization fixes and several other |
| bug fixes.</para> |
| |
| <para> |
| Glenn Boysko contributed support for ignoring specified local |
| variables in the dead local store detector. |
| </para> |
| |
| <para> |
| Jay Dunning contributed a detector to find equality comparisons |
| of floating-point values, and overhauled the analysis summary |
| report and its representation in the saved XML format. |
| </para> |
| |
| <para> |
| Olivier Parent contributed updated French translations for bug descriptions and |
| Swing GUI. |
| </para> |
| |
| <para> |
| Chris Nappin contributed the <filename>plain.xsl</filename> |
| stylesheet. |
| </para> |
| |
| <para> |
| Etienne Giraudy contributed the <filename>fancy.xsl</filename> and <filename>fancy-hist.xsl</filename> |
| stylesheets, and made improvements to the <command>-xml:withMessages</command> |
| option. |
| </para> |
| |
| <para> |
| Takashi Okamoto fixed bugs in the project preferences dialog |
| in the Eclipse plugin, and contributed to its internationalization and localization. |
| </para> |
| |
| <para>Thomas Einwaller fixed bugs in the project preferences dialog in the Eclipse plugin.</para> |
| |
| <para>Jeff Knox contributed support for the warningsProperty attribute |
| in the Ant task.</para> |
| |
| <para>Peter Hendriks extended the Eclipse plugin preferences, |
| and fixed a bug related to renaming the Eclipse plugin ID.</para> |
| |
| <para>Mark McKay contributed an Ant task to launch the findbugs frame.</para> |
| |
| <para>Dieter von Holten (dvholten) contributed |
| some German improvements to findbugs_de.properties.</para> |
| |
| |
| <para>If you have contributed to &FindBugs;, but aren't mentioned above, |
| please send email to <email>findbugs@cs.umd.edu</email> (and also accept |
| our humble apologies).</para> |
| |
| </sect1> |
| |
| <sect1> |
| <title>使用しているソフトウェア</title> |
| |
| <para>&FindBugs; は、いくつかのオープンソースソフトウェアパッケージを使用しています。これらがなければ、 &FindBugs; の開発は、より一層困難なものになったことでしょう。</para> |
| |
| <sect2> |
| <title>BCEL</title> |
| <para>&FindBugs; includes software developed by the Apache Software Foundation |
| (<ulink url="http://www.apache.org/">http://www.apache.org/</ulink>). |
| Specifically, it uses the <ulink url="http://jakarta.apache.org/bcel/">Byte Code |
| Engineering Library</ulink>.</para> |
| </sect2> |
| |
| <sect2> |
| <title>ASM</title> |
| <para>&FindBugs; uses the <ulink url="http://asm.objectweb.org/">ASM</ulink> |
| bytecode framework, which is distributed under the following license:</para> |
| |
| <blockquote> |
| <para> |
| Copyright (c) 2000-2005 INRIA, France Telecom |
| All rights reserved. |
| </para> |
| |
| <para> |
| Redistribution and use in source and binary forms, with or without |
| modification, are permitted provided that the following conditions |
| are met: |
| </para> |
| |
| <orderedlist numeration="arabic"> |
| <listitem><para> |
| Redistributions of source code must retain the above copyright |
| notice, this list of conditions and the following disclaimer. |
| </para></listitem> |
| <listitem><para> |
| Redistributions in binary form must reproduce the above copyright |
| notice, this list of conditions and the following disclaimer in the |
| documentation and/or other materials provided with the distribution. |
| </para></listitem> |
| <listitem><para> |
| Neither the name of the copyright holders nor the names of its |
| contributors may be used to endorse or promote products derived from |
| this software without specific prior written permission. |
| </para></listitem> |
| </orderedlist> |
| |
| <para> |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
| LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF |
| THE POSSIBILITY OF SUCH DAMAGE. |
| </para> |
| </blockquote> |
| </sect2> |
| |
| <sect2> |
| <title>DOM4J</title> |
| <para>&FindBugs; uses <ulink url="http://dom4j.org">DOM4J</ulink>, which is |
| distributed under the following license:</para> |
| |
| <blockquote> |
| <para> |
| Copyright 2001 (C) MetaStuff, Ltd. All Rights Reserved. |
| </para> |
| |
| <para> |
| Redistribution and use of this software and associated documentation |
| ("Software"), with or without modification, are permitted provided that |
| the following conditions are met: |
| </para> |
| |
| <orderedlist numeration="arabic"> |
| <listitem><para> |
| Redistributions of source code must retain copyright statements and |
| notices. Redistributions must also contain a copy of this document. |
| </para></listitem> |
| <listitem><para> |
| Redistributions in binary form must reproduce the above copyright |
| notice, this list of conditions and the following disclaimer in the |
| documentation and/or other materials provided with the distribution. |
| </para></listitem> |
| <listitem><para> |
| The name "DOM4J" must not be used to endorse or promote products |
| derived from this Software without prior written permission |
| of MetaStuff, Ltd. For written permission, please contact |
| <email>dom4j-info@metastuff.com</email>. |
| </para></listitem> |
| <listitem><para> |
| Products derived from this Software may not be called "DOM4J" nor may |
| "DOM4J" appear in their names without prior written permission of |
| MetaStuff, Ltd. DOM4J is a registered trademark of MetaStuff, Ltd. |
| </para></listitem> |
| <listitem><para> |
| Due credit should be given to the DOM4J Project (<ulink url="http://dom4j.org/">http://dom4j.org/</ulink>). |
| </para></listitem> |
| </orderedlist> |
| |
| <para> |
| THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' |
| AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, |
| THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS |
| CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
| PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| </para> |
| </blockquote> |
| |
| </sect2> |
| |
| </sect1> |
| |
| </chapter> |
| |
| |
| </book> |
