API - Ant-analyseopgave

Formål

Denne opgave udfører en fuldstændig API-analyse af en API-profil i forhold til en grundlinje - herunder API-brug, binær kompatibilitet og validering af bundtversionsnummer. Profilen er den aktuelle tilstand af et produkt under udvikling. Profilen sammenlignes med en API-grundlinje for binær kompatibilitet (normalt den tidligere release af et produkt).

Analysen inkluderer ikke validering af @since-kode, da al kontrol udføres på binære klassefiler (kilden analyseres ikke).

Brug

Beskrivelse

Navnet på Ant-opgaven er: apitooling.analysis. For at kunne bruges skal JAR-filen apitooling-ant.jar findes i Ant-classpath.

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

Parametre

Attribut Beskrivelse Påkrævet
baseline Denne attribut angiver placeringen af referencegrundlinjen.

Det kan være en .zip-, .jar-, .tgz-, .tar.gz-fil eller et bibliotek, der svarer til Eclipse-installationsfolderen. Det er i dette bibliotek, at du kan finde den eksekvérbare Eclipse-fil.

Placeringen angives ved hjælp af en absolut sti.
Ja
profile Denne attribut angiver placeringen af det aktuelle produkt eller den aktuelle profil, som du vil sammenligne med referencegrundlinjen.

Det kan være en .zip-, .jar-, .tgz-, .tar.gz-fil eller et bibliotek, der svarer til Eclipse-installationsfolderen. Det er i dette bibliotek, at du kan finde den eksekvérbare Eclipse-fil.

Placeringen angives ved hjælp af en absolut sti.
Ja
report Angiv den outputplacering, hvor rapporterne bliver genereret.

Når opgaven er udført, er rapporterne tilgængelige i dette bibliotek ved hjælp af en struktur, der ligner filterroden. Der oprettes en underfolder for alle komponenter, der har problemer, som skal rapporteres. De enkelte underfoldere indeholder en fil, der hedder "report.xml".

Der oprettes også en særlig folder, som hedder "allNonApiBundles", i denne folder. Den indeholder også en fil med navnet "report.xml". Denne fil indeholder en liste over alle de bundter, der ikke bruger API-værktøjsnaturen.

Filen "counts.xml" oprettes også i rapportbiblioteket. Den indeholder en oversigt over de fundne problemer.

Placeringen angives ved hjælp af en absolut sti.
Ja
filters Angiver det rodbibliotek med API-filtre, der skal bruges under analysen.

Argumentet er rodbiblioteket for de .api_filters-filer, der skal bruges til at filtrere potentielle problemer, som er oprettet af API-værktøjsanalysen.
Rod angives ved hjælp af en absolut sti.
Roden skal have følgende struktur:
 rod |
  +-- komponentnavn (dvs. org.eclipse.jface)
         |
         +--- .api-filtre
Nej
excludelist Angiv placeringen af exclude-listen.

Placeringen af exclude-listen angiver en tekstfil med de bundter, der skal udelades fra analysen. Som standard analyseres alle bundterne i profilen. Attributter for include- og exclude-lister kan bruges til selektivt at medtage og udelade bundter. Include-listen tilfører det bundtsæt, der skal analyseres (når den ikke angives, medtages alle bundter), og exclude-listen anvendes derefter. Linjerne i filen angiver et af følgende:
  • et specifikt bundtnavn
  • et regulært udtryk, som skal matches med bundtnavne (linjer, der starter med "R:")
  • en kommentar (linjer, der starter med '#')

Placeringen angives ved hjælp af en absolut sti.
Her er et eksempel på en exclude-liste:
 # 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 Angiv placeringen af include-listen.

Placeringen af include-listen angiver en tekstfil med de bundter, der skal medtages i analysen. Som standard analyseres alle bundterne i profilen. Attributter for include- og exclude-lister kan bruges til selektivt at medtage og udelade bundter. Include-listen tilfører det bundtsæt, der skal analyseres (når den ikke angives, medtages alle bundter), og exclude-listen anvendes derefter. Linjerne i filen angiver et af følgende:
  • et specifikt bundtnavn
  • et regulært udtryk, som skal matches med bundtnavne (linjer, der starter med "R:")
  • en kommentar (linjer, der starter med '#')

Placeringen angives ved hjælp af en absolut sti.
Her er et eksempel på en include-liste:
 # 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
preferences Angiver indstillingerne for opgaven.

Indstillingerne bruges til at konfigurere problemniveauer. Problemniveauer har tre mulige værdier: Ignore, Warning eller Error. Det problemsæt, der registreres, er defineret af tilsvarende problemindstillingsnøgler i API-værktøjer.
Placeringen angives ved hjælp af en absolut sti. Hvis den angivne placering ikke findes, bliver indstillingerne ikke angivet.
Linjer, der starter med '#', ignoreres. Formatet af indstillingsfilen ser sådan ud:
 #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
 ...
Nøglerne findes i org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Nej
debug Angiv fejlfindingsværdien.

Mulige værdier er: true, false
Standardværdien er false.
Nej
eefile Angiv den udførelsesmiljøfil, der skal bruges.

Som standard bruges en udførelsesmiljøfil, svarende til et JavaSE-1.6-udførelsesmiljø.

Formatet af filen er beskrevet på denne wikiside.

Filen angives ved hjælp af en absolut sti.
Nej

Eksempler

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

Herved køres den opgave, som opretter report.xml-filer, i folderen D:\reports\xml. Opgaven bruger exclude-listen og .api_filter-filerne i D:\exclude_list_external.txt og D:\filters til at mindske antallet af problemer, der skal rapporteres.

Problemniveauer genereres som angivet af D:\tests_api\org.eclipse.pde.api.tools.prefs.

Da fejlfinding er aktiveret, bliver der vist fejlfindingssporing i Ant-konsollen.

Relaterede referencer

Ant-opgave: API-frys
Ant-opgave: Generering af fil
Ant-opgave: API-brug
Ant-opgave: Konvertering af analyserapport
Ant-opgave: Konvertering af API-frysrapport
Ant-opgave: Konvertering af API-brugsrapport
Ant-opgave: API-forældelse
Ant-opgave: Konvertering af API-forældelsesrapport