SpotBugsの実行

SpotBugsには、グラフィカルユーザインターフェイス (GUI) とコマンドラインユーザインターフェイスの2つのユーザインターフェイスがあります。この章では、それぞれのユーザインタフェースを実行する方法について説明します。

クイックスタート

WindowsでSpotBugsを実行するときは、%SPOTBUGS_HOME%\lib\spotbugs.jar ファイルをダブルクリックしてSpotBugs GUIを起動します。

Unix、Linux、macOSでは、 $SPOTBUGS_HOME/bin/spotbugs スクリプト、または java -jar $SPOTBUGS_HOME/lib/spotbugs.jar コマンドでSpotBugs GUIを実行します。

GUIの使い方は SpotBugs GUIの使い方を参照してください。

SpotBugs の実行

この節では、SpotBugsプログラムを起動する方法について説明します。SpotBugs を起動するためには、直接、またはラッパースクリプトを使用する2つの方法があります。

SpotBugs の直接起動

SpotBugsを実行するためには、JVM (Java) 実行可能ファイルの -jarコマンドラインスイッチを使用して $SPOTBUGS_HOME/lib/spotbugs.jar を直接実行する方法を推奨します。(バージョン1.3.5以前の SpotBugsでは、SpotBugsを起動するためのラッパースクリプトが必要でした。)

SpotBugsを直接起動する一般的な構文は次のようになります。

java [JVM arguments] -jar $SPOTBUGS_HOME/lib/spotbugs.jar options...

ユーザインタフェースの選択

最初のコマンドラインオプションは、実行するSpotBugsユーザインタフェースの選択です。指定可能な値は次のとおりです。

-gui:: グラフィカルユーザインタフェース (GUI) の実行
-textui:: コマンドラインユーザインタフェースの実行
-version:: SpotBugs のバージョン番号の表示
-help:: SpotBugsコマンドラインユーザインタフェースに関するヘルプ情報の表示
-gui1:: オリジナルSpotBugsグラフィカルユーザインタフェース (廃止されている) の実行

Java 仮想マシン (JVM) の引数

Java仮想マシンのいくつかの引数は、SpotBugs を起動するときに役立ちます。

-XmxNNm:: Javaヒープサイズの最大値をNNメガバイトに設定します。SpotBugs は、通常大量のメモリを必要とします。巨大なプロジェクトでは、1500メガバイトを使用することは珍しいことではありません。
-Dname=value:: Javaシステムプロパティを設定します。たとえば、GUIメッセージを日本語で表示したいときは -Duser.language=ja 引数を使用します。

ラッパースクリプトを使用した SpotBugs の起動

SpotBugsを実行するもう一つの方法は、ラッパースクリプトを使うことです。

Unix系システムでは、次のコマンドを使用してラッパースクリプトを起動します。

$ $SPOTBUGS_HOME/bin/spotbugs options...

Windows では、次のコマンドを使用してラッパースクリプトを起動します。

C:\My Directory>%SPOTBUGS_HOME%\bin\spotbugs.bat options...

Unix系システムとWindowsのどちらでも、$SPOTBUGS_HOME/bin ディレクトリを環境変数 PATH に追加するだけで、spotbugs コマンドを使用して SpotBugs を起動できます。

ラッパースクリプトのコマンドラインオプション

SpotBugs ラッパースクリプトは、次のようなコマンドラインオプションをサポートしています。留意すべきは、これらのコマンドラインオプションは、SpotBugs プログラム自体では処理されません。それらはラッパースクリプトによって処理されます。

-jvmArgs args:

JVMに渡す引数を指定します。たとえは、JVM プロパティを設定したいとします。

$ spotbugs -textui -jvmArgs "-Duser.language=ja" myApp.jar

-javahome directory:

SpotBugsの実行に使用する JRE(Javaランタイム環境) があるディレクトリを指定します。

-maxHeap size:

Java ヒープサイズの最大値をメガバイトで指定します。デフォルトは256です。巨大なプログラムやライブラリを解析するためには、より多くのメモリが必要になることがあります。

-debug:

ディテクタの実行トレースと解析したクラスを標準出力に出力します。予期しない解析エラーのトラブルシューティングに役立ちます。

-property name=value:

このオプションはシステムプロパティを設定します。SpotBugs は、システムプロパティを使用して解析オプションを設定します。解析プロパティを参照してください。複数のプロパティを設定したいときは、このオプションを複数回使用します。注：ほとんどのWindows のバージョンでは、name=value 文字列を引用符で囲む必要があります。

コマンドラインオプション

この節では、SpotBugsでサポートされているコマンドラインオプションについて説明します。これらのコマンドラインオプションは、SpotBugs を直接起動するとき、またはラッパースクリプトを使用するときに使えます。

共通のコマンドラインオプション

これらのオプションは、GUI とコマンドラインユーザインタフェースの両方で使えます。

-effort[:min|less|default|more|max]:: 解析力を設定します。-effort:minは精度を向上させるがメモリ消費量も増やす解析を無効にします。SpotBugs を実行するためのメモリが不足したり、解析が完了するまでに異常に長い時間がかかるときは、このオプションを試してみると良いでしょう。詳細は解析力を参照してください。
-project project:: 解析するプロジェクトを指定します。指定するプロジェクトファイルは、GUIインタフェースを使用して作成したものでなければなりません。拡張子は、通常 .fb または .fbp です。
-pluginList <jar1[;jar2...]>:: Specify list of plugin Jar files to load.
-home <home directory>:: Specify SpotBugs home directory.
-adjustExperimental:: Lower priority of experimental Bug Patterns.
-workHard:: Ensure analysis effort is at least 'default'.
-conserveSpace:: Same as -effort:min (for backward compatibility).

GUI オプション

これらのオプションは、グラフィカルユーザインタフェースだけで受け入れられます。

-look:plastic|gtk|native:: Swing のルック & フィールを設定します。

テキスト UI オプション

これらのオプションは、テキストユーザインタフェースだけで受け入れられます。

-sortByClass=filepath:

報告されたバグインスタンスをクラス名でソートします。

SpotBugs 4.5.0以降では、このオプションはファイルパスを受け取るようになりました。-sortByClass=path/to/spotbugs.txt のように使用します。複数のレポートを出力するために -xml=spotbugs.xml -sortByClass=spotbugs.txt などと設定することもできます。

-include filterFile.xml:

filterFile.xml で指定したフィルタと一致するバグインスタンスだけを報告します。フィルタファイルを参照してください。

-exclude filterFile.xml:

filterFile.xml で指定したフィルタと一致するもの以外のすべてのバグインスタンスを報告します。フィルタファイルを参照してください。

-onlyAnalyze com.foobar.MyClass,com.foobar.mypkg.*:

与えられたコンマ区切りのクラスとパッケージでバグを見つけるための解析を制限します。フィルタリングとは異なり、このオプションは明示的に一致しないクラスやパッケージの解析を回避します。大規模なプロジェクトの場合、解析を実行するために必要な時間が大幅に短縮されます。(しかしながら、アプリケーション全体でディテクタを実行していないので不正確な結果を返してしまうかもしれません）クラスは、パッケージも含んだ完全なクラス名を使用して指定する必要があります。パッケージは、パッケージの中のすべてのクラスをインポートする Java import文と同じ方法で指定する必要があります (つまり、パッケージの完全な名前に .* を追加します)。 .* を .- に換えるとすべてのサブパッケージも解析できます。

-low:

すべてのバグを報告します。

-medium:

優先度が中・高のバグを報告します。デフォルトの設定です。

-high:

優先度が高のバグを報告します。

-relaxed:

ざっくりとした報告をするモードです。多くのディテクタにおいて、このオプションは誤検出を回避するために使用されるヒューリスティックを抑制します。

-xml=filepath:

バグレポートをXMLとして生成します。生成されたXMLデータは、後でGUIで見ることができます。。このオプションは -xml:withMessages として指定することもできます。このオプションを使用すると出力された XML ファイルには人間が読める警告を説明するメッセージが含まれるようになります。この方法で生成されたXML ファイルは簡単にレポートに変換できます。

SpotBugs 4.5.0以降では、このオプションはファイルパスを受け取るようになりました。-xml:withMessages=path/to/spotbugs.xml のように使用します。複数のレポートを出力するために -xml=spotbugs.xml -html=spotbugs.html と設定することもできます。

-html=filepath:

HTML出力を生成します。デフォルトでは、SpotBugsはdefault.xsl XSLTスタイルシートを使用してHTML を生成します。このファイルは、spotbugs.jar、SpotBugs ソース、バイナリ配布物で見つけられます。このオプションのバリエーションには -html:plain.xsl、-html:fancy.xsl、-html:fancy-hist.xsl が含まれます。plain.xsl スタイルシートはJavascriptやDOM を使用していません。古いウェブブラウザや印刷のためにうまく動作するかもしれません。fancy.xsl スタイルシートはナビゲーションのためのDOMとJavascript、視覚的表現のためのCSSを使用します。fancy-hist.xsl は、fancy.xsl スタイルシートが進化したものです。バグのリストを動的にフィルタリングするために DOM と Javascript をフル活用します。

独自のXSLTスタイルシートを指定してHTMLへの変換を実行したいときは、-html:myStylesheet.xsl としてオプションを指定します。ここで myStylesheet.xsl は使用するスタイルシートのファイル名です。

SpotBugs 4.5.0以降では、このオプションはファイルパスを受け取るようになりました。-html:fancy-hist.xsl=path/to/spotbugs.html のように使用します。複数のレポートを出力するために -xml=spotbugs.xml -html=spotbugs.html などと設定することもできます。

-sarif=filepath:

バグレポートを SARIF 2.1.0 形式として出力します。

SpotBugs 4.5.0以降では、このオプションはファイルパスを受け取るようになりました。-sarif=path/to/spotbugs.sarif のように使用します。複数のレポートを出力するために -xml=spotbugs.xml -sarif=spotbugs.sarif などと設定することもできます。

-emacs=filepath:

バグレポートを Emacs 形式として生成します。

-xdocs=filepath:

Apache Maven で使用するためのxdoc XML 形式のバグレポートを生成します。

-output filename:

This argument is deprecated. Use report type option like -xml=spotbugs.xml instead.

-outputFile filename:

This argument is deprecated. Use report type option like -xml=spotbugs.xml instead.

-nested[:true|false]:

このオプションは、解析されるファイルとディレクトリのリストにあるネストされたjar/zip ファイルのスキャンを有効また無効にします。デフォルトでは、ネストされた jar/zip ファイルのスキャンが有効になっています。無効にしたいときは、コマンドライン引数に -nested:false を追加します。

-auxclasspath classpath:

解析のための補助クラスパスを設定します。補助クラスパスには解析するプログラムで使用するクラスを含むディレクトリと jar ファイルをすべて指定します。バグの解析対象にはなりません。

-auxclasspathFromInput:

標準入力から解析のための補助クラスパスを読み、それぞれの行を解析のための補助クラスパスに新規登録します。

-auxclasspathFromFile filepath:

ファイルから解析のための補助クラスパスを読み、それぞれの行を解析のための補助クラスパスに新規登録します。

-analyzeFromFile filepath:

ファイルから解析するファイルを読み、それぞれの行を解析のためのクラスパスに新規登録します。

-userPrefs edu.umd.cs.findbugs.core.prefs:

使用するユーザ設定ファイルを設定します。上記のオプションの一部が上書きされる可能性があります。最初の引数としてuserPrefs を指定すると、後続のオプションで上書きすることになります。最後の引数として指定すると以前のオプションを上書きすることになります。このオプションの背後にある根拠は、コマンドライン実行で SpotBugs Eclipse プロジェクトの設定を再利用するためです。

-showPlugins:

Show list of available detector plugins.

Output options

-timestampNow:: Set timestamp of results to be current time.
-quiet:: Suppress error messages.
-longBugCodes:: すべてのバグを報告します。
-progress:: Display progress in terminal window.
-release <release name>:: Set the release name of the analyzed application.
-maxRank <rank>:: Only report issues with a bug rank at least as scary as that provided.
-dontCombineWarnings:: Don't combine warnings that differ only in line number.
-train[:outputDir]:: Save training data (experimental); output dir defaults to '.'.
-useTraining[:inputDir]:: Use training data (experimental); input dir defaults to '.'.
-redoAnalysis <filename>:: Redo analysis using configuration from previous analysis.
-sourceInfo <filename>:: Specify source info file (line numbers for fields/classes).
-projectName <project name>:: Descriptive name of project.
-reanalyze <filename>:: Redo analysis in provided file.

Output filtering options

-bugCategories <cat1[,cat2...]>:: Only report bugs in given categories.
-excludeBugs <baseline bugs>:: Exclude bugs that are also reported in the baseline xml output.
-applySuppression:: fbpファイルによって指定された抑制フィルタにマッチするバグを出力から除きます。

Detector（Visitor）設定用オプション

-visitors <v1[,v2...]>:: 指定されたVisitorのみを実行します。
-omitVisitors <v1[,v2...]>:: 指定されたVisitorを実行しません。
-chooseVisitors <+v1,-v2,...>:: 指定されたDetectorを有効化したり無効化したりします。
-choosePlugins <+p1,-p2,...>:: 指定されたプラグインを有効化したり無効化したりします。
-adjustPriority <v1=(raise|lower)[,...]>:: 指定した警告の優先度を変更します。

プロジェクト設定用オプション

-sourcepath <source path>:: 解析対象クラスのソースコードが保管されているパスを指定します。
-exitcode:: プロセスのステータスコードを設定します。
-noClassOk:: 対象クラスが指定されなかった場合にからの警告ファイルを出力します。
-xargs:: クラスファイルやjarファイルの一覧を、コマンドラインオプションではなく標準入力から読み込みます。
-bugReporters <name,name2,-name3>:: バグレポーターを明示的に有効化したり無効化したりできます。
-printConfiguration:: 設定を出力した後に、解析を実行せずに終了します。