Usando SpotBugs como tarefa Ant

Este capítulo descreve como integrar o SpotBugs em um script de construção para Ant, que é uma ferramenta popular de construção e implantação Java. Ao usar o SpotBugs em uma tarefa no seu script de construção Ant, o SpotBugs pode ser executado automaticamente em seu código Java.

A tarefa Ant teve uma contribuição generosa de Mike Fagan.

Instalando a tarefa Ant

Para instalar a tarefa Ant, basta copiar $SPOTBUGS_HOME/lib/spotbugs-ant.jar no subdiretório lib da instalação do Ant.

Nota

É altamente recomendável que você use a tarefa Ant com a versão incluída do SpotBugs. Não garantimos que o arquivo Jar da tarefa Ant funcionará com qualquer versão do SpotBugs diferente daquela incluída.

Modificando o build.xml

Para adicionar o SpotBugs no build.xml (o script de construção para Ant), você precisa adicionar a definição da tarefa. Isso pode ser feito da forma:

<taskdef
    resource="edu/umd/cs/findbugs/anttask/tasks.properties"
    classpath="path/to/spotbugs-ant.jar" />

A definição da tarefa especifica que quando um elemento spotbugs é visto no build.xml, ele deve usar a classe indicada para executar a tarefa.

Depois de adicionar a definição da tarefa, você pode definir um alvo para usar a tarefa spotbugs. A seguir, é apresentado um exemplo que pode ser adicionado ao build.xml para a biblioteca Apache BCEL.

<property name="spotbugs.home" value="/export/home/daveho/work/spotbugs" />

<target name="spotbugs" depends="jar">
  <spotbugs home="${spotbugs.home}"
            output="xml"
            outputFile="bcel-sb.xml" >
    <auxClasspath path="${basedir}/lib/Regex.jar" />
    <sourcePath path="${basedir}/src/java" />
    <class location="${basedir}/bin/bcel.jar" />
  </spotbugs>
</target>

O elemento SpotBugs deve ter o atributo home definido para o diretório no qual o SpotBugs está instalado; em outras palavras, $SPOTBUGS_HOME. Veja Instalação.

Este destino irá executar o SpotBugs em bcel.jar, que é o arquivo Jar produzido pelo script de construção BCEL. (Ao torná-lo dependente do destino “jar” garantimos que a biblioteca está totalmente compilada antes de executar SpotBugs nele.) A saída do SpotBugs será salva no formato XML em um arquivo chamado bcel-sb.xml. Um arquivo Jar auxiliar, Regex.jar, é adicionado ao classpath aux, porque é referenciado pela biblioteca BCEL. Um caminho é especificado para que os dados dos bugs salvos tenham referências precisas ao código-fonte BCEL.

Executando a tarefa

O exemplo abaixo apresenta uma chamada do Ant a partir da linha de comando, usando o alvo do SpotBugs definido anteriormente.

[daveho@noir]$ ant spotbugs
Buildfile: build.xml

init:

compile:

examples:

jar:

spotbugs:
 [spotbugs] Running SpotBugs...
 [spotbugs] Bugs were found
 [spotbugs] Output saved to bcel-sb.xml

BUILD SUCCESSFUL
Total time: 35 seconds

Como os resultados dos bugs foram salvos em um arquivo XML, nós podemos usar o SpotBugs GUI para visualizar os resultados; veja Execução do SpotBugs.

Parâmetros

Esta seção descreve os parâmetros que podem ser especificados quando usando o FindBugs como tarefa.

class

Um elemento aninhado opcional que especifica quais classes analisar. O elemento de classe deve especificar um atributo de localização que nomeia o arquivo (jar, zip, etc.), diretório ou arquivo de classe a ser analisado. Vários elementos de classe podem ser especificados como filhos de um único elemento do SpotBugs.

Além disso, a tarefa SpotBugs pode conter um ou mais elementos do conjunto de arquivos que especificam os arquivos a serem analisados. Por exemplo, você pode usar um conjunto de arquivos para especificar que todos os arquivos jar em um diretório devem ser analisados.

auxClasspath

Um elemento aninhado opcional que especifica um caminho de classe (arquivos Jar ou diretórios) contendo classes usadas pela biblioteca ou aplicativo analisado, mas que você não deseja analisar. É especificado da mesma forma que o elemento de caminho de classe do Ant para a tarefa Java.

sourcePath

Um elemento aninhado opcional que especifica um caminho de diretório de origem contendo arquivos de origem usados para compilar o código Java que está sendo analisado. Ao especificar um caminho de origem, qualquer saída de bug XML gerada terá informações de origem completas, o que permite a visualização posterior na GUI.

home

Um atributo obrigatório. Deve ser definido com o nome do diretório onde o SpotBugs está instalado.

quietErrors

Um atributo booleano opcional. Se verdadeiro, relatórios de erros de análise sérios e classes ausentes serão suprimidos na saída do SpotBugs. O valor default é falso.

reportLevel

Um atributo opcional. Este atributo especifica o limite de confiança/prioridade para relatar problemas. Se definido como baixo, a confiança não é usada para filtrar bugs. Se definido como médio (valor default), os problemas de baixa confiança são suprimidos. Se definido como alto, apenas bugs de alta confiança são relatados.

output

Atributo opcional. Este atributo especifica o formato de saída. Se definido como xml (por default), a saída será no formato XML. Se definido como “xml:withMessages”, a saída será no formato XML acrescentado com mensagens legíveis. (Você deve usar este formato se planeja gerar um relatório usando uma folha de estilo XSL.) Se definido como “html”, a saída será formatada em HTML (por default, a folha de estilo é default.xsl). Se definido como texto, a saída será em formato de texto ad-hoc. Se definido como emacs, a saída será no formato de mensagem de erro Emacs. Se definido como xdocs, a saída será xdoc XML para uso com Apache Maven.

stylesheet

Atributo opcional. Esse atributo especifica a folha de estilo a ser usada para gerar a saída html quando a saída é definida como html. As folhas de estilo incluídas na distribuição FindBugs incluem default.xsl, fancy.xsl, fancy-hist.xsl, plain.xsl e summary. xsl. O valor default é default.xsl, caso nenhum atributo de folha de estilo seja fornecido.

sort

Atributo opcional. Se o atributo de saída for definido como text, então o atributo sort especifica se os bugs relatados são ou não classificados por classe. O valor default é verdadeiro true.

outputFile

Atributo opcional. Se especificado, nomeia o arquivo de saída no qual a saída do FindBugs será salva. Por padrão, a saída é exibida diretamente pelo Ant.

debug

Atributo booleano opcional. Se definido como verdadeiro true, o SpotBugs imprime as informações de diagnóstico sobre quais classes estão sendo analisadas e quais detectores de padrões de bug estão sendo executados. O valor default é falso false.

effort

Define o nível de esforço de análise. O valor especificado deve ser min, default ou max. Consulte Command-line Options <running.html#command-line-options>: para obter mais informações sobre como definir o nível de análise.

conserveSpace

Synonym for effort="min".

workHard

Synonym for effort="max".

visitors

Atributo opcional. Este atributo especifica uma lista separada por vírgulas de detectores de bug que devem ser executados. Os detectores de bug são especificados por seus nomes de classe, sem qualquer qualificação de pacote. Por default, todos os detectores não desabilitados são executados.

omitVisitors

Atributo opcional. Este atributo especifica uma lista separada por vírgulas de detectores de bug. É como o atributo visitors, exceto que especifica detectores que não serão executados.

chooseVisitors

Atributo opcional. Este atributo especifica uma lista separada por vírgulas de detectores de bug prefixados com “+” or “-” para ativá-los ou desativá-los.

excludeFilter

Atributo opcional. Este atributo especifica o nome do arquivo de um filtro para definir os bugs que não devem ser reportados. Veja Arquivos de filtro.

excludePath

Um elemento aninhado opcional. Este elemento especifica o caminho contendo os filtros que definem os bugs que não devem ser reportados. Veja Arquivos de filtro.

includeFilter

Atributo opcional. Este atributo especifica o nome do arquivo de um filtro para definir os bugs que devem ser reportados. Veja Arquivos de filtro.

includePath

Um elemento aninhado opcional. Este elemento especifica o caminho contendo os filtros que definem os bugs que devem ser reportados. Veja Arquivos de filtro.

projectFile

Atributo opcional. Este atributo especifica o nome de um arquivo de projeto. Arquivos de projeto são criados pela GUI do FindBugs e especificam classes, entradas de caminho de classe auxiliar e diretórios de origem. Ao nomear um projeto, você não precisa especificar nenhum elemento de classe, nem precisa especificar os atributos``auxClasspath`` ou sourcePath. Veja Execução do SpotBugs para saber como criar um projeto.

jvmargs

Atributo opcional. Este atributo especifica os argumentos que devem ser passados para a máquina virtual Java usada para executar o SpotBugs. Você pode precisar deste atributo para especificar sinalizadores para aumentar a quantidade de memória que a JVM pode usar se você estiver analisando um programa muito grande.

systemProperty

Elemento aninhado opcional. Se especificado, define uma propriedade do sistema. O atributo name especifica o nome da propriedade do sistema e o atributo value especifica o valor da propriedade do sistema.

timeout

Atributo opcional. Este atributo especifica a quantidade de tempo, em milissegundos, que o processo Java com SpotBugs pode ser executado antes de ser considerado interrompido e encerrado. O valor default é 600.000 milissegundos, ou seja, dez minutos. Observe que para programas muito grandes, o SpotBugs pode levar mais de dez minutos para concluir sua análise.

failOnError

Atributo booleano opcional. Define quando se deve abortar o processo de construção caso haja um erro ao executar o SpotBugs. O valor default é falso false.

errorProperty

Atributo opcional que especifica o nome de uma propriedade que será definida como verdadeira true se ocorrer um erro durante a execução do SpotBugs.

warningsProperty

Atributo opcional que especifica o nome de uma propriedade que será definida como verdadeira true se quaisquer avisos forem relatados pelo SpotBugs no programa analisado.

userPreferencesFile

Atributo opcional. Este atributo define o caminho do arquivo de preferências do usuário a ser usado, o que pode sobrescrever algumas das opções acima. Especificar o userPreferencesFile como primeiro argumento significa que algumas opções posteriores irão sobrescrevê-lo, já que o último argumento sobrescreve algumas opções anteriores). O raciocínio desta opção é reutilizar as configurações do projeto Eclipse do SpotBugs para execução em linha de comando.

nested

Atributo opcional que ativa ou desativa a verificação de arquivos jar e zip aninhados encontrados na lista de arquivos e diretórios a serem analisados. Por default, a verificação de arquivos jar/zip aninhados está ativada.

setExitCode

Atributo booleano opcional. Se o código de saída deve ser retornado a tarefa Ant principal. O valor default é verdadeiro true.