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:
報告されたバグインスタンスをクラス名でソートします。
-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 は使用するスタイルシートのファイル名です。

-sarif:
バグレポートを SARIF 2.1.0 形式として出力します。
-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:
すべてのバグを報告します。
-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:
設定を出力した後に、解析を実行せずに終了します。