Ant-taak API-analyse

Doel

Deze taak start de volledige API-analyse van een API-profiel in relatie tot een basislijn. Hiertoe behoren API-gebruik, binaire compatibiliteit en controle van bundelversienummers. Het profiel is de huidige status van een product in ontwikkeling. Het profiel wordt gecontroleerd op binaire compatibiliteit met een API-basislijn (meestal de vorige versie van een product).

De analyse kent geen @since-tagvalidatie omdat alle controles worden uitgevoerd op binaire klassenbestanden (de bron wordt niet geanalyseerd).

Gebruik

Beschrijving

De naam van de Ant-taak is: apitooling.analysis. Om deze te kunnen gebruiken, moet het jar-bestand apitooling-ant.jar in het Ant-klassenpad staan.

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

Parameters

Kenmerk Beschrijving Verplicht
baseline Dit kenmerk geeft de locatie van de desbetreffende basislijn aan.

Dit kan een bestand met de extensie zip, jar, tgz of tar.gz zijn, maar ook een directory die correspondeert met de Eclipse-installatiemap. Dit is de directory waarin het uitvoerbare Eclipse-bestand is opgeslagen.

De locatie wordt opgegeven als absoluut pad.
True
profile Dit kenmerk geeft de locatie aan van het huidige product of profiel dat u wilt vergelijken met de basislijn.

Dit kan een bestand met de extensie zip, jar, tgz of tar.gz zijn, maar ook een directory die correspondeert met de Eclipse-installatiemap. Dit is de directory waarin het uitvoerbare Eclipse-bestand is opgeslagen.

De locatie wordt opgegeven als absoluut pad.
True
report Het instellen van de uitvoerlocatie waar de rapporten worden gegenereerd.

Als de taak is voltooid, zijn de rapporten in deze directory beschikbaar in een boomstructuur die lijkt op filterhoofddirectory. Er wordt een submap gemaakt voor alle componenten waarvoor problemen moeten worden gerapporteerd. Elke submap bevat een bestand met de naam "report.xml".

Er wordt ook een speciale map met de naam "allNonApiBundles" gemaakt in deze map. Deze bevat ook een bestand met de naam "report.xml". In dit bestand staan alle bundels die geen gebruik maken van het API-Toolconcept.

There is also a "counts.xml" file created in the report directory that contains a summary of the problems found.

De locatie wordt opgegeven als absoluut pad.
True
filters Instellen van de hoofddirectory voor API-filters die tijdens de analyse moeten worden gebruikt.

The argument is the root directory of the .api_filters files that should be used to filter potential problems created by the API Tools analysis.
De hoofddirectory wordt opgegeven als absoluut pad.
De hoofddirectory moet de volgende structuur hebben:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
Nee
excludelist Instelling van de locatie van de uitsluitingslijst.

The exclude list location specifies a text file listing bundles to be excluded from the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a regular expression to match against bundle names (lines being with "R:")
  • a comment (lines being with '#')

De locatie wordt opgegeven als absoluut pad.
Following is an example exclude list:
 # 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\..*
 ...
Nee
includelist Set the include list location.

The include list location specifies a text file listing bundles to be included in the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a regular expression to match against bundle names (lines being with "R:")
  • a comment (lines being with '#')

De locatie wordt opgegeven als absoluut pad.
Following is an example include list:
 # 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\..*
 ...
Nee
preferences Instellen van de eigenschappen van de taak.

De voorkeuren worden gebruikt om de probleemseverity te configureren. Er zijn drie mogelijke waarden voor de probleemseverity: Ignore, Warning en Error. De aangetroffen probleemset wordt gedefinieerd met corresponderende probleemvoorkeurensleutels in API-tools.
De locatie wordt opgegeven als absoluut pad. Als de gegeven locatie niet bestaat, kunnen er geen voorkeuren worden ingesteld.
Regels die beginnen met het teken '#' worden genegeerd. De indeling van het voorkeurenbestand ziet er als volgt uit:
 #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
 ...
De sleutels zijn te vinden in org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Nee
debug Instellen van de foutopsporingswaarde.

De mogelijke waarden zijn true en false.
De standaardwaarde is false.
Nee
eefile Instellen van de uitvoeringsomgeving.

Standaard wordt een uitvoeringsomgevingsbestand gebruikt dat correspondeert met een JavaSE-1.6-uitvoeringsomgeving.

De indeling van het bestand wordt beschreven in deze wikipagina.

Het bestand wordt opgegeven als absoluut pad.
Nee

Voorbeelden

	<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"
	/>

Hiermee wordt de taak gestart voor het maken van report.xml-bestanden in de map D:\reports\xml. De uitsluitingslijst en de .api_filter-bestanden in D:\exclude_list_external.txt en D:\filters worden gebruikt om het aantal te rapporteren problemen te verminderen.

De probleemseverity wordt gegenereerd aan de hand van D:\tests_api\org.eclipse.pde.api.tools.prefs.

Omdat de foutopsporing is ingeschakeld, zijn er enige foutopsporingsgegevens te zien in de ant-console.

Verwante onderwerpen

Ant-taak API blokkeren
Ant-taak Bestanden genereren
API Use Ant Task
Ant-taak Analyserapport converteren
Ant-taak API-blokkeringsrapport converteren
Ant-taak API-gebruiksrapport converteren
Ant-taak API-depreciëring
Ant-taak API-depreciëringsrapport converteren