Ant-oppgave for API-analyse

Formål

Denne oppgaven kjører en komplett API-analyse av en API-profil relativt til en basis - inkludert API-bruk, binærkompatibilitet og nummervalidering av bunt-versjon. Profilen er den gjeldende tilstanden til et produkt som er under utvikling. Profilen sammenlignes med en API-basis med hensyn til binærkompatibilitet (vanligvis den forrige utgaven av et produkt).

Analysen inkluderer ikke @since-kodevalidering på grunn av at verifisering utføres på binære klassefiler (kilden analyseres ikke).

Bruk

Beskrivelse

Navnet på Ant-oppgaven er: apitooling.analysis. Når den skal brukes, må jar-filen apitooling-ant.jar være i Ant-klassebanen.

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

Parametere

Attributt Beskrivelse Obligatorisk
baseline Dette attributtet oppgir plasseringen av referansebasisen.

Det kan være en *.zip-, *.jar-, *.tgz- eller *.tar.gz-fil eller en katalog som tilsvarer installeringsmappen til Eclipse. Dette er katalogen hvor du finner den utførbare filen til Eclipse.

Plasseringen oppgis med en absolutt bane.
Ja
profile Dette attributtet oppgir plasseringen av det gjeldende produktet eller profilen som du vil sammenlikne med referansebasisen.

Det kan være en *.zip-, *.jar-, *.tgz- eller *.tar.gz-fil eller en katalog som tilsvarer installeringsmappen til Eclipse. Dette er katalogen hvor du finner den utførbare filen til Eclipse.

Plasseringen oppgis med en absolutt bane.
Ja
report Angi utdataplasseringen hvor rapportene skal genereres.

Når du har fullført denne oppgaven, blir rapportene tilgjengelige i denne katalogen i en struktur som likner på filterroten. Det opprettes en undermappe for hver komponent som har problemer som må rapporteres. Hver undermappe inneholder en fil som heter report.xml.

Det opprettes også en spesialmappe som heter allNonApiBundles i denne mappen, og denne mappen inneholder også en fil som heter report.xml. Denne filen inneholder en liste med alle buntene som ikke bruker API-verktøy-naturen.

Det finnes også en "counts.xml"-fil opprettet i report-katalogen, som inneholder et sammendrag av problemene som er funnet.

Plasseringen oppgis med en absolutt bane.
Ja
filters Angi rotkatalogen til API-filtrene som skal brukes under analysen.

Argumentet er rotkatalogen til *.api_filters-filene som skal brukes til å filtrere mulige problemer som er opprettet av API-verktøyanalysen.
Roten oppgis med en absolutt bane.
Roten må inneholde følgende struktur:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
Nei
excludelist Velg plasseringen til ekskluderingslisten.

Ekskluderingslisteplasseringen oppgir en tekstfil med en liste over bunter som skal ekskluderes fra analysen. Som standard blir alle bunter i profilen analysert. Attributtene for inkluderings- og ekskluderingsliste kan brukes til å velge bunter som skal inkluderes og ekskluderes. Inkluderingslisten initialiserer settet med bunter som skal analyseres (hvis den er utelatt, blir alle bunter inkludert), og deretter blir ekskluderingslisten brukt. Hver linje i filen oppgir ett av følgende:
  • et bestemt buntnavn
  • et regulært uttrykk som skal sammenliknes med buntnavn (linjer som begynner med "R:")
  • en kommentar (linjer som begynner med '#')

Plasseringen oppgis med en absolutt bane.
Nedenfor finner du et eksempel på en ekskluderingsliste:
 # 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\..*
 ...
Nei
includelist Angi plasseringen til ekskluderingslisten.

Inkluderingslisteplasseringen oppgir en tekstfil med en liste over bunter som skal inkluderes i analysen. Som standard blir alle bunter i profilen analysert. Attributtene for inkluderings- og ekskluderingsliste kan brukes til å velge bunter som skal inkluderes og ekskluderes. Inkluderingslisten initialiserer settet med bunter som skal analyseres (hvis den er utelatt, blir alle bunter inkludert), og deretter blir ekskluderingslisten brukt. Hver linje i filen oppgir ett av følgende:
  • et bestemt buntnavn
  • et regulært uttrykk som skal sammenliknes med buntnavn (linjer som begynner med "R:")
  • en kommentar (linjer som begynner med '#')

Plasseringen oppgis med en absolutt bane.
Nedenfor finner du et eksempel på en inkluderingsliste:
 # 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\..*
 ...
Nei
preferences Definer preferansene for oppgaven.

Preferansene brukes til å konfigurere alvorsgraden til problemene. Alvorsgraden til problemene har tre mulige verdier: Ignorer, Advarsel eller Feil. Settet med problemer som blir funnet, defineres av tilhørende problempreferansenøkler i API-verktøy.
Plasseringen oppgis med en absolutt bane. Hvis den angitte plasseringen ikke eksisterer, blir ikke preferansene definert.
Linjer som begynner med #, blir ignorert. Formatet på preferansefilen er slik:
 #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
 ...
Du finner nøklene i org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Nei
debug Angi feilsøkingsverdien.

Mulige verdier er true og false
Standardverdien er false.
Nei
eefile Angi utføringsmiljøfilen som skal brukes.

Som standard brukes en utføringsmiljøfil som tilsvarer et JavaSE-1.6-utføringsmiljø.

Formatet til filen er beskrevet på denne wiki-siden.

Filen oppgis med en absolutt bane.
Nei

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

Dette kjører oppgaven som oppretter report.xml-filer i mappen D:\reports\xml. Den bruker ekskluderingslisten og *.api_filter-filer i D:\exclude_list_external.txt og D:\filters til å redusere antall problemer som rapporteres.

Alvorsgradene til problemene genereres slik det er oppgitt i D:\tests_api\org.eclipse.pde.api.tools.prefs.

På grunn av at feilsøking er aktivert, vises noe feilsøkingssporing i Ant-konsollen.

Beslektet referanse

Ant-oppgave for API-frys
Ant-oppgave for filgenerering
Ant-oppgave for API-bruk
Ant-oppgave for konvertering av analyserapport
Ant-oppgave for konvertering av rapport for API-frys
Ant-oppgave for konvertering av rapport for API-bruk
Ant-oppgave for API-foreldelse
Ant-oppgave for konvertering av rapport for API-foreldelse