Tarefa ant de análise de Ferramentas API

Finalidade

Esta tarefa executa uma análise completa da API de um perfil da API relativo a uma linha de base - incluindo a utilização da API, compatibilidade binária e validação do número de versão do lote. O perfil é o estado actual de um problema em desenvolvimento. O perfil é comparado com uma linha de base da API considerando a compatibilidade binária (normalmente, a edição anterior de um produto).

A análise não inclui a validação do identificador @since, uma vez que todas as verificações são efectuadas em ficheiros de classe binária (a origem não é analisada).

Utilização

Descrição

O nome da tarefa ant é: apitooling.analysis. Para ser utilizada, o ficheiro jar apitooling-ant.jar tem de estar no caminho de classe de ant.

<apitooling.analysis
	baseline="..."
	profile="..."
	report="..."
	filters="..."
	excludelist="..."
	includelist="..."
	preferences="..."
	debug="..."
		eefilee="..."
/>

Parâmetros

Atributo Descrição Necessário
baseline Este atributo especifica a localização da linha de base de referência.

Pode ser um ficheiro .zip, .jar, .tgz ou .tar.gz, ou um directório que corresponda a um pasta de instalação do Eclipse. Este directório é onde se encontra o executável do Eclipse.

A localização é especificada utilizando um caminho absoluto.
Sim
profile Este atributo especifica a localização do produto actual ou o perfil que pretende comparar com a linha de base de referência.

Pode ser um ficheiro .zip, .jar, .tgz ou .tar.gz, ou um directório que corresponda a um pasta de instalação do Eclipse. Este directório é onde se encontra o executável do Eclipse.

A localização é especificada utilizando um caminho absoluto.
Sim
report Define a localização da saída de dados em que os relatórios são gerados.

Após a conclusão da tarefa, existem relatórios disponíveis no directório indicado que utilizam uma estrutura semelhante à raiz do filtro. É criada uma subpasta para cada componente que tem problemas para ser comunicados. Cada subpasta contém um ficheiro chamado "report.xml".

É igualmente criada nesta pasta uma pasta especial chamada "allNonApiBundles" que contém um ficheiro chamado "report.xml". Este ficheiro lista todos os lotes que não estão a utilizar a natureza das Ferramentas da API.

Também existe um ficheiro "counts.xml" criado no directório do relatório que contém um resumo dos problemas encontrados.

A localização é especificada utilizando um caminho absoluto.
Sim
filtros Define o directório da raiz dos filtros da API a ser utilizado durante a análise.

O argumento é o directório raiz dos ficheiros .api_filters que devem ser utilizados para filtrar potenciais problemas criados pela análise das Ferramentas da API.
A raiz é especificada utilizando um caminho absoluto.
A raiz precisa de conter a seguinte estrutura:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
Não
excludelist Define a localização da lista de exclusão.

A localização da lista de exclusões especifica um ficheiro de texto que lista os lotes a excluir da análise. Por predefinição, todos os lotes no perfil serão analisados. Os atributos da lista de exclusões e inclusões podem ser utilizados, de forma selectiva, para incluir e excluir lotes. A lista de inclusões dissemina o conjunto de lotes a analisar (quando omitidos, todos os lotes são incluídos), e a lista de exclusões é então aplicada. Cada linha do ficheiro especifica:
  • um nome de lote específico
  • uma expressão regular para corresponder relativamente a nomes de lotes (linhas que começam por "R:")
  • um comentário (linhas que começam por '#')

A localização é especificada utilizando um caminho absoluto.
A seguir encontra-se um exemplo de uma lista de exclusões:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 org.eclipse.platform.doc.isv
 org.eclipse.platform.doc.user
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Não
includelist Defina a localização da lista de inclusões.

A localização da lista de inclusões especifica um ficheiro de texto que lista os lotes a incluir da análise. Por predefinição, todos os lotes no perfil serão analisados. Os atributos da lista de exclusões e inclusões podem ser utilizados, de forma selectiva, para incluir e excluir lotes. A lista de inclusões dissemina o conjunto de lotes a analisar (quando omitidos, todos os lotes são incluídos), e a lista de exclusões é então aplicada. Cada linha do ficheiro especifica:
  • um nome de lote específico
  • uma expressão regular para corresponder relativamente a nomes de lotes (linhas que começam por "R:")
  • um comentário (linhas que começam por '#')

A localização é especificada utilizando um caminho absoluto.
A seguir encontra-se um exemplo de uma lista de inclusões:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 R:org.eclipse.platform.doc.*
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Não
preferências Define as preferências para a tarefa.

As preferências são utilizadas para configurar níveis de gravidade de problemas. Existem três valores possíveis para o nível de gravidade de problemas: Ignorar, Aviso ou Erro. O conjunto de problemas detectado é definido pelas chaves de preferências de problemas correspondentes nas ferramentas da API.
A localização é especificada utilizando um caminho absoluto. Se a localização indicada não existir, as preferências não serão estabelecidas.
As linhas que começam por '#' são ignoradas. O formato do ficheiro de preferências é semelhante ao seguinte:
 #Thu Nov 20 17:35:06 EST 2008
 ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore
 ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore
 ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning
 API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore
 API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore
 CLASS_ELEMENT_TYPE_ADDED_METHOD=Error
 CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore
 CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore
 CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore
 ...
As chaves podem ser encontradas em org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Não
debug Define o valor de depuração.

Os valores possíveis são: true, false
A predefinição é false.
Não
eefile Define o ficheiro do ambiente de execução a ser utilizado.

Por predefinição, é utilizado um ficheiro de ambiente de execução que corresponde a um ambiente de execução Java SE-1.6.

O formato do ficheiro é descrito na página wiki .

O ficheiro é especificado utilizando um caminho absoluto.
Não

Exemplos

	<apitooling.analysis
		baseline="D:\eclipse\3.4.1\eclipse"
		profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
		report="D:\reports\xml"
		filters="D:\filters"
		excludelist="D:\exclude_list_external.txt"
		preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs"
		debug="true"
	/>

Isto irá executar a tarefa criando ficheiros report.xml dentro da pasta D:\reports\xml. Irá utilizar a lista de exclusão e os ficheiros .api_filter que se encontram em D:\exclude_list_external.txt e D:\filters para reduzir o número de problemas do relatório.

As gravidades dos problemas serão geradas conforme especificado por D:\tests_api\org.eclipse.pde.api.tools.prefs.

Uma vez que a depuração está activada, aparecerá alguma indicação de rastreio na consola ant.

Referência relacionada

Tarefa ant de congelamento da API
Tarefa ant de geração de ficheiros
Tarefa ant de utilização da API
Tarefa ant de conversão de relatórios de análise
Tarefa ant de conversão de relatórios de congelamento da API
Tarefa ant de conversão de relatórios de utilização da API
Tarefa ant de desactualização da API
Tarefa ant de conversão de relatórios de desactualização da API