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]:
Set analysis effort level. The -effort:min disables several analyses that increase precision but also increase memory consumption. You may want to try this option if you find that SpotBugs with the -effort:less still runs out of memory, or takes an unusually long time to complete its analysis. The -effort:less disables some analyses that increase precision but also increase memory consumption. You may want to try this option if you find that SpotBugs with the -effort:more/-effort:default runs out of memory, or takes an unusually long time to complete its analysis. The -effort:more runs several analyses to find bugs, this is the -effort:default. The -effort:max enable analyses which increase precision and find more bugs, but which may require more memory and take more time to complete. See 解析力.
-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:
報告されたバグインスタンスをクラス名でソートします。
-include filterFile.xml:
filterFile.xml で指定したフィルタと一致するバグインスタンスだけを報告します。フィルタファイル を参照してください。
-exclude filterFile.xml:
filterFile.xml で指定したフィルタと一致するもの以外のすべてのバグインスタンスを報告します。フィルタファイル を参照してください。
-onlyAnalyze com.foobar.MyClass,com.foobar.mypkg.*:
与えられたコンマ区切りのクラスとパッケージでバグを見つけるための解析を制限します。フィルタリングとは異なり,このオプションは明示的に一致しないクラスやパッケージの解析を回避します。大規模なプロジェクトの場合,解析を実行するために必要な時間が大幅に短縮されます。(しかしながら,アプリケーション全体でディテクタを実行していないので不正確な結果を返してしまうかもしれません。) クラスは,パッケージも含んだ完全なクラス名を使用して指定する必要があります。パッケージは,パッケージの中のすべてのクラスをインポートする Java import 文と同じ方法で指定する必要があります (つまり,パッケージの完全な名前に .* を追加します)。 .* を .- に換えるとすべてのサブパッケージも解析できます。
-low:
すべてのバグを報告します。
-medium:
優先度が中・高のバグを報告します。デフォルトの設定です。
-high:
優先度が高のバグを報告します。
-relaxed:
ざっくりとした報告をするモードです。多くのディテクタにおいて,このオプションは誤検出を回避するために使用されるヒューリスティックを抑制します。
-xml:
バグレポートを XML として生成します。生成された XML データは,後で GUI で見ることができます。。このオプションは -xml:withMessages として指定することもできます。このオプションを使用すると出力された XML ファイルには人間が読める警告を説明するメッセージが含まれるようになります。この方法で生成された XML ファイルは簡単にレポートに変換できます。
-html:

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 は使用するスタイルシートのファイル名です。

-emacs:
バグレポートを Emacs 形式として生成します。
-xdocs:
Apache Maven で使用するための xdoc XML 形式のバグレポートを生成します。
-output filename:
指定されたファイルに出力を生成します。
-outputFile filename:
この引数は推奨されません。代わりに -output を使用してください。
-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:
Report long bug codes.
-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 configureation 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:
Exclude any bugs that match suppression filter loaded from fbp file.

Detector (visitor) configuration options

-visitors <v1[,v2...]>:
Run only named visitors.
-omitVisitors <v1[,v2...]>:
Omit named visitors.
-chooseVisitors <+v1,-v2,...>:
Selectively enable/disable detectors.
-choosePlugins <+p1,-p2,...>:
Selectively enable/disable plugins.
-adjustPriority <v1=(raise|lower)[,...]>:
Raise/lower priority of warnings for given visitor(s)

Project configuration options

-sourcepath <source path>:
Set source path for analyzed classes.
-exitcode:
Set exit code of process.
-noClassOk:
Output empty warning file if no classes are specified.
-xargs:
Get list of classfiles/jarfiles from standard input rather than command line.
-bugReporters <name,name2,-name3>:
Bug reporter decorators to explicitly enable/disable.
-printConfiguration:
Print configuration and exit, without running analysis.