API-verktyg - Ant-uppgiften Analysis

Ändamål

Uppgiften kör en fullständig API-analys av en API-profil relativt till en basnivå - inklusive API-användning, binär kompatibilitet samt validering av versionsnumret på samlingspaket. Profilen är det aktuella läget för en produkt under utveckling. Profilen jämförs med en API-basnivå för binär kompatibilitet (vanligen föregående release av en produkt).

Analysen innefattar inte validering av märkordet @since eftersom all verifiering utförs på binära klassfiler (källfiler analyseras inte).

Användning

Beskrivning

Ant-uppgiftens namn: apitooling.analysis. Om den ska kunna användas måste JAR-filen apitooling-ant.jar finnas i Ant-klassökvägen.

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

Parametrar

Attribut Beskrivning Obligatoriskt
baseline Attributet anger platsen för refererad basnivå.

Det kan vara en .zip-, .jar-, .tgz-, .tar.gz-fil eller en katalog som motsvarar installationskatalogen för Eclipse. Det är den katalog där alla körbara Eclipse-filer finns.

Platsen anges med en absolut sökväg.
Ja
profile Attributet anger platsen för aktuell produktprofil som ska jämföras med referensbasnivån.

Det kan vara en .zip-, .jar-, .tgz-, .tar.gz-fil eller en katalog som motsvarar installationskatalogen för Eclipse. Det är den katalog där alla körbara Eclipse-filer finns.

Platsen anges med en absolut sökväg.
Ja
report Utdataplats där rapporteran skapas.

När uppgiften har slutförts finns rapporterna i den här katalogen med en struktur som liknar filterroten. En undermapp skapas för varje komponent som har problem som ska rapporteras. Varje undermapp innehåller en fil med namnet report.xml.

En mapp med namnet allNonApiBundles skapas också i den här mappen och den innehåller också filen report.xml. Filen listar alla samlingsplaket som inte är av API-verktygsnatur.

I rapportkatalogen skapas också filen "counts.xml" som innehåller en sammanfattning av de problem som hittats.

Platsen anges med en absolut sökväg.
Ja
filter Rotkatalogen för API-filter som ska användas vid analysen

Argumentet är rotkatalogen i filerna .api_filters som ska användas för att filtrera potentiella problem som orsakas av API-verktygsanalysen.
Roten anges med en absolut sökväg.
Roten måste innehålla följande struktur:
 root
  |
  +-- komponentnamn (dvs. org.eclipse.jface)
         |
         +--- .api_filters
Nej
excludelist Platsen för exkluderingslistan

I exkluderingslistan anges en textfil där de samlingspaket som ska uteslutas från analysen listas. Som standard analyseras alla paket i profilen. Med inkluderings- och exkluderingslistattributen kan du välja vilka paket som ska tas med repektive uteslutas. Inkluderingslistan anger vilka paket som ska analyseras (om den utelämnas tas alla paket med), och sedan tillämpas exkluderingslistan. Varje rad i filen anger antingen:
  • ett specifikt samlingspaketnamn
  • ett reguljärt uttryck som matchas mot paketnamnen (rader som börjar med "R:")
  • en kommentar (rader börjar med #)

Platsen anges med en absolut sökväg.
Följande är ett exempel på en exkluderingslista:
 # 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\..*
 ...
Nej
includelist Platsen för inkluderingslistan.

I inkluderingslistan anges en textfil där de samlingspaket som ska tas med i analysen listas. Som standard analyseras alla paket i profilen. Med inkluderings- och exkluderingslistattributen kan du välja vilka paket som ska tas med repektive uteslutas. Inkluderingslistan anger vilka paket som ska analyseras (om den utelämnas tas alla paket med), och sedan tillämpas exkluderingslistan. Varje rad i filen anger antingen:
  • ett specifikt samlingspaketnamn
  • ett reguljärt uttryck som matchas mot paketnamnen (rader som börjar med "R:")
  • en kommentar (rader börjar med #)

Platsen anges med en absolut sökväg.
Följande är ett exempel på en inkluderingslista:
 # 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\..*
 ...
Nej
inställningar Ange inställningarna för uppgiften.

Inställningar används till att konfigurera problemallvarlighetsgrader. Problemallvarlighetsgraden kan ha något av följande tre värden: Ignore, Warning eller Error. Vilka problem som upptäcks definieras av motsvarande probleminställningsnycklar i API-verktygen.
Platsen anges med en absolut sökväg. Om platsen inte finns anges inte inställningen.
Rader som börjar med # ignoreras. Formatet på inställningsfilen ser ut så här:
 #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
 ...
Nycklarna finns i org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Nej
debug Felsökningsvärdet

Giltiga värden är true och false.
Standardvärdet är false.
Nej
eefile Den körningsmiljöfil som ska användas

Som standard används en körningsmiljöfil som motsvarar körningsmiljön JavaSE-1.6.

Formatet på filen beskrivs på den här wiki-sidan.

Filen anges med en absolut sökväg.
Nej

Exempel

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

Uppgiften som skapar report.xml-filer i mappen D:\reports\xml körs. Exkluderingslistan och .api_filter-filerna i D:\exclude_list_external.txt och D:\filters används för att minska antalet problem som ska rapporteras.

Problemallvarlighetsgraden genereras enligt D:\tests_api\org.eclipse.pde.api.tools.prefs.

Eftersom debug är aktiverat visas vissa felsökningsmeddelanden i Ant-konsolen.

Närliggande referenser

Ant-uppgiften API Freeze
Ant-uppgiften File Generation
Ant-uppgiften API Use
Ant-uppgiften Analysis Report Conversion
Ant-uppgiften API Freeze Report Conversion
Ant-uppgiften API Use Report Conversion
Ant-uppgiften API Deprecation
Ant-uppgiften API Deprecation Report Conversion