Execução do SpotBugs

O SpotBugs tem duas interfaces: uma interface gráfica de usuário (GUI) e uma em linha de comando. Este capítulo descreve como executar cada uma de suas interfaces.

Guia rápido

No Windows, dê um clique duplo no arquivo %SPOTBUGS_HOME%\lib\spotbugs.jar para iniciar o SpotBugs GUI

No Unix, Linux, ou macOS, execute o script $SPOTBUGS_HOME/bin/spotbugs ou execute o comando java -jar $SPOTBUGS_HOME/lib/spotbugs.jar para iniciar o SpotBugs GUI.

Consulte Usando a interface do SpotBugs para mais informações de como utilizar a GUI.

Execução do SpotBugs

Esta seção descreve como iniciar o programa SpotBugs. Existem duas maneiras de iniciar SpotBugs: diretamente ou com um script de wrapper.

Inicialização direta do SpotBugs

A maneira recomendada de executar SpotBugs é executar $SPOTBUGS_HOME/lib/spotbugs.jar diretamente, usando a opção de linha de comando -jar no executável JVM (Java). O SpotBugs nas versões 1.3.5 e anteriores exigiam um script de wrapper para iniciar SpotBugs.

A sintaxe geral para iniciar SpotBugs diretamente é:

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

Seleção da interface do usuário

A primeira opção de linha de comando é a seleção da interface de usuário do SpotBugs a ser executada. Os valores possíveis são:

-gui:

Executa uma interface gráfica do usuário (GUI)

-textui:

Executa a interface de usuário de linha de comando

-version:

Exibe o número da versão do SpotBugs

-help:

Visualiza as informações de ajuda sobre a interface de usuário da linha de comando do SpotBugs

-gui1:

Executa a interface gráfica de usuário original do SpotBugs (obsoleto)

Argumentos da Java Virtual Machine (JVM)

Diversos argumentos da máquina virtual Java são úteis ao iniciar SpotBugs.

-XmxNNm:

Define o tamanho máximo de heap Java para NN megabytes. O SpotBugs geralmente requer muita memória. Não é incomum usar 1500 megabytes para grandes projetos.

-Dname=value:

Define as propriedades do sistema Java. Por exemplo, se você deseja exibir as mensagens da GUI em japonês, use o argumento -Duser.language=ja.

Inicialização do SpotBugs usando um script de wrapper

Outra maneira de executar SpotBugs é usar um script de wrapper.

Em sistemas baseados no Unix, use o comando para iniciar o script de wrapper:

$ $SPOTBUGS_HOME/bin/spotbugs options...

No Windows, use o comando para ativar o script de wrapper.

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

Em ambos os sistemas do tipo Unix e Windows, você pode simplesmente adicionar o diretório $SPOTBUGS_HOME/bin em sua variável de ambiente PATH para, posteriormente, usar o comando spotbugs para inicializar o Spotbugs.

Opções de linha de comando do script de wrapper

O script de wrapper do SpotBugs oferece suporte às seguintes opções de linha de comando. Observe que essas opções de linha de comando não são tratadas pelo próprio programa SpotBugs. Eles são controlados pelo script de wrapper.

-jvmArgs args:

Especifica os argumentos a serem passados para a JVM. Por exemplo, suponha que você deseja definir uma propriedade JVM.

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

Especifica o diretório que contém o JRE (Java Runtime Environment) usado para executar o SpotBugs.

-maxHeap size:

Especifica o tamanho máximo de heap Java em megabytes. O padrão é 256. Pode ser necessária mais memória para analisar programas e bibliotecas grandes.

-debug:

Produz o rastreamento de execução do detector e a classe analisada para a saída padrão. Ajuda a solucionar erros de análise inesperados.

-property name=value:

Esta opção define as propriedades do sistema. O SpotBugs usa as propriedades do sistema para definir opções de análise. Consulte Propriedades de análise. Use esta opção várias vezes se desejar definir várias propriedades. Observação: a maioria das versões do Windows exige que você coloque a string name=value entre aspas.

Opções de linha de comando

Esta seção descreve as opções de linha de comando suportadas pelo SpotBugs. Essas opções de linha de comando estão disponíveis quando você inicia SpotBugs diretamente ou quando usa um script de wrapper.

Opções comuns de linha de comando

Essas opções estão disponíveis na GUI e na interface do usuário em linha de comando.

-effort[:min|less|default|more|max]:

Define o nível de esforço de análise. -effort:min desativa muitas análises que melhoram a precisão e aumentam o consumo de memória. Você pode querer usar essa opção quando, ao executar o Spotbugs com -effort:less, ainda ficar sem memória ou demorar bastante tempo para executar sua análise. O -effort:less desabilita algumas análises que melhoram a precisão e aumentam o consumo de memória. Você pode querer usar essa opção quando, ao executar o SpotBugs com -effort:more/-effort:default, ainda ficar sem memória ou demorar bastante tempo para executar sua análise. O -effort:more equivale ao -effort:default e executa muitas análises para encontrar bugs.O -effort:max habilita análises que aumentam a precisam e encontram mais bugs, mas podem consumir mais memória e tempo de execução. veja Esforço.

-project project:

Especifica o projeto a ser analisado. O arquivo de projeto especificado deve ter sido criado usando a interface GUI. A extensão geralmente termina em .fb or .fbp.

-pluginList <jar1[;jar2…]>:

Especifica a lista de arquivos Jar do plugin a serem carregados.

-home <home directory>:

Especifica o diretório inicial do SpotBugs.

-adjustExperimental:

Determina a prioridade inferior de padrões de bug experimentais.

-workHard:

Certifica que o esforço de análise seja pelo menos o padrão ‘default’.

-conserveSpace:

O mesmo que -effort:min (para compatibilidade com versões anteriores).

Opções de GUI

Essas opções são aceitas apenas na interface gráfica do usuário.

-look:plastic|gtk|native:

Define a aparência do Swing.

Opções de texto da IU

Essas opções são aceitas apenas na interface de usuário de texto.

-sortByClass=filepath:

Classifica as instâncias de bug relatadas por nome de classe.

From SpotBugs 4.5.0, this option receives a file path like -sortByClass=path/to/spotbugs.txt. It is also supported to set multiple reports like -xml=spotbugs.xml -sortByClass=spotbugs.txt.

-include filterFile.xml:

Relata apenas as instâncias de bug que correspondem ao filtro especificado em filterFile.xml. Veja Arquivos de filtro.

-exclude filterFile.xml:

Relata todas as instâncias de bug exceto aquelas que correspondem ao filtro especificado em filterFile.xml. Veja Arquivos de filtro.

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

Restrict analysis to find bugs to given comma-separated list of classes and packages. Unlike filtering, this option avoids running analysis on classes and packages that are not explicitly matched: for large projects, this may greatly reduce the amount of time needed to run the analysis. (However, some detectors may produce inaccurate results if they aren’t run on the entire application.) Classes should be specified using their full classnames (including package), and packages should be specified in the same way they would in a Java import statement to import all classes in the package (i.e., add .* to the full name of the package). Replace .* with .- to also analyze all subpackages. Items starting with ! are treated as exclusions, removing otherwise-included classes from analysis.

-low:

Relata todos os bugs.

-medium:

Relata bugs de média e alta prioridade. Essa é a configuração padrão.

-high:

Reporta bugs de alta prioridade.

-relaxed:

Um modo de fazer relatórios aproximados. Para muitos detectores, esta opção suprime a heurística usada para evitar falsos positivos.

-xml=filepath:

Gera um relatório de bug como XML. Os dados XML gerados podem ser visualizados posteriormente na GUI. Você pode usar essa opção como -xml:withMessages. Com esta opção, o arquivo XML de saída conterá uma mensagem legível explicando um aviso. Os arquivos XML gerados dessa forma podem ser facilmente convertidos em relatórios.

From SpotBugs 4.5.0, this option receives a file path like -xml:withMessages=path/to/spotbugs.xml. It is also supported to set multiple reports like -xml=spotbugs.xml -html=spotbugs.html.

-html=filepath:

Produz a saída HTML. Por padrão, o SpotBugs usa a folha de estilo XSLT default.xsl para gerar o HTML. Este arquivo pode ser encontrado em spotbugs.jar, no fonte do SpotBugs ou na distribuição binária. As variações dessa opção incluem -html:plain.xsl, -html:fancy.xsl e -html:fancy-hist.xsl. As folhas de estilo plain.xsl não usam Javascript ou DOM e podem funcionar bem para navegadores e impressões mais antigas. As folhas de estilo fancy.xsl usam DOM e Javascript para navegação e CSS para representação visual. A folha de estilo fancy-hist.xsl é uma evolução da fancy.xsl, que faz o uso do DOM e do Javascript para filtrar dinamicamente a lista de bugs.

Se você quer especificar seu estilo de folha XSLT próprio para realizar a transformação para HTML, especifique a opção -html:myStylesheet.xsl, onde myStylesheet.xsl é o nome do arquivo da folha de estilo que você quer usar.

From SpotBugs 4.5.0, this option receives a file path like -html:fancy-hist.xsl=path/to/spotbugs.html. It is also supported to set multiple reports like -xml=spotbugs.xml -html=spotbugs.html.

-sarif=filepath:

gera um relatório de bugs no formato SARIF 2.1.0.

From SpotBugs 4.5.0, this option receives a file path like -sarif=path/to/spotbugs.sarif. It is also supported to set multiple reports like -xml=spotbugs.xml -sarif=spotbugs.sarif.

-emacs=filepath:

Gera um relatório de bugs no formato Emacs.

-xdocs=filepath:

Gera um relatório de bugs no formato xdoc XML para uso com Apache Maven.

-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]:

Esta opção ativa ou desativa a varredura de arquivos jar e zip aninhados na lista de arquivos e diretórios a serem analisados. Por padrão, a varredura de arquivos jar e zip aninhados está ativada. Se você deseja desativá-lo, adicione -nested:false como argumento na linha de comando.

-auxclasspath classpath:

Define o caminho de classe auxiliar para análise. O caminho de classe auxiliar deve incluir todos os diretórios e arquivos jar que contém as classes usadas pelo programa a ser analisado, mas que você não deseja analisar para encontrar bugs

-auxclasspathFromInput:

Lê o caminho de classe auxiliar para análise a partir da entrada padrão, cada linha adiciona uma nova entrada com o caminho de classe auxiliar para análise.

-auxclasspathFromFile filepath:

Lê o caminho de classe auxiliar para análise do arquivo, cada linha adiciona uma nova entrada com o caminho de classe auxiliar para análise.

-analyzeFromFile filepath:

Lê o arquivo a ser analisado a partir do arquivo e registre cada linha no classpath para análise.

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

Define o arquivo de configuração do usuário a ser usado. Algumas das opções acima podem ser substituídas. Se você especificar userPrefs como o primeiro argumento, ele será substituído pelas opções subsequentes. Especificá-lo como o último argumento substituirá a opção anterior. A lógica por trás dessa opção é reutilizar as configurações do projeto SpotBugs Eclipse na execução da linha de comando.

-showPlugins:

Mostra a lista de plug-ins de detectores disponíveis.

Opções de saída

-timestampNow:

Defina a data e hora dos resultados como a hora atual.

-quiet:

Suprima mensagens de erro.

-longBugCodes:

Relata todos os bugs.

-progress:

Exibe o progresso na janela do terminal.

-release <release name>:

Define o nome da liberação do aplicativo analisado.

-maxRank <rank>:

Relata apenas problemas com uma classificação de bug pelo menos do mesmo nível especificado.

-dontCombineWarnings:

Não combina avisos que diferem apenas no número da linha.

-train[:outputDir]:

Salva os dados de treinamento (experimental); o padrão de saída do dir é ‘.’

-useTraining[:inputDir]:

Usa dados de treinamento (experimental); o padrão de entrada é ‘.’

-redoAnalysis <filename>:

Refaz a análise usando a configuração da análise anterior.

-sourceInfo <filename>:

Especifica informações do arquivo de origem (números de linha para campos/classes).

-projectName <project name>:

Nome descritivo do projeto.

-reanalyze <filename>:

Refaz a análise no arquivo fornecido.

Opções de filtragem de saída

-bugCategories <cat1[,cat2…]>:

Relata apenas os bugs de determinadas categorias.

-excludeBugs <baseline bugs>:

Exclui os bugs que também são relatados na saída xml.

-applySuppression:

Remove os bugs de saída que correspondem ao filtro de supressão especificado pelo arquivo fbp.

Opção de configuração do detector (visitor)

-visitors <v1[,v2…]>:

Executa apenas o visitor especificado.

-omitVisitors <v1[,v2…]>:

Não executa o visitor especificado.

-chooseVisitors <+v1,-v2,…>:

Habilita ou desabilita o Detector especificado.

-choosePlugins <+p1,-p2,…>:

Habilita ou desabilita o plugin especificado.

-adjustPriority <v1=(raise|lower)[,…]>:

Altera a prioridade do aviso especificado.

Opções para configurações do projeto

-sourcepath <source path>:

Especifica o caminho de origem das classes analisadas.

-exitcode:

Define o código de status do processo.

-noClassOk:

Gera um arquivo de aviso vazio se a classe de destino não é especificada.

-xargs:

Lê uma lista de arquivos de classe e jar a partir da entrada padrão em vez de opções de linha de comando.

-bugReporters <name,name2,-name3>:

Habilita ou desabilita explicitamente o relato de bugs.

-printConfiguration:

Depois de enviar as configurações, saia sem realizar a análise.