Ant-oppgave for API-bruk

Formål

Denne oppgaven kjører et komplett søk i en gitt basis for å opprette en rapport for API-bruk.

Analysen utelater bunter som ikke er aktivert for API-verktøy.

Bruk

Beskrivelse

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

<apitooling.apiuse
	location="..."
	scopepattern="..."
	referencepattern="..."
	report="..."
	considerinternal="..."
	considerapi="..."
	considerillegaluse="..."
	apipatterns="..."
	internalpatterns="..."
	archivepatterns="..."
	excludelist="..."
	includelist="..."	
	debug="..."
/>

Parametere

Attributt Beskrivelse Obligatorisk
location Dette attributtet oppgir plasseringen av det gjeldende produktet som du vil gjennomsøke med tanke på API-bruk.

Det kan være en *.zip-, *.jar-, *.tgz- eller *.tar.gz-fil eller en katalog som inneholder et produkt eller en samling med bunter.

Plasseringen oppgis med en absolutt bane.
Ja
scopepattern Dette attributtet oppgir et regulært uttrykksmønster som skal brukes til å velge hvilke bunter det skal søkes i på plasseringen.

Følgende angir for eksempel at det bare skal søkes etter API-bruk i Eclipse-bunter:
org.eclipse.*
Mønsteret må være et riktig formatert regulært uttrykk slik det er definert her.
Nei
referencepattern Dette attributtet oppgir et regulært uttrykksmønster som skal brukes til å filtrere søkeresultatene. Bare API-bruk som refererer til en bunt som samsvarer med filteret, blir rapportert.

Følgende angir for eksempel at det bare skal rapporteres bruk som refererer til kode i JDT:
org.eclipse.jdt.*
Mønsteret må være et riktig formatert regulært uttrykk slik det er definert her.
Nei
report Angi utdataplasseringen hvor rapportene skal genereres.

Når du har fullført denne oppgaven, blir rapportene tilgjengelige i en hierarkisk struktur i denne katalogen. Det opprettes en undermappe for hver komponent som blir referert til av en annen bunt. Hver undermappe inneholder en fil som heter [buntnavn].xml. I denne mappen finnes det en annen undermappe (som heter [referansebuntnavn].xml) for hver bunt som refererer til bunten i overmappen. I mappen til referansebunten finnes det en mappe som er én av tre følgende undermapper (API, PRIVATE eller OTHER), og denne mappen inneholder type-, metode- eller feltreferanser av det slaget.

Det skrives tre andre spesialfiler til rapportkatalogen. Disse filene heter counts.xml, not_searched.xml og no_apidescription.xml og inneholder henholdsvis informasjon om antall referanser som ble funnet, bunter fra basisen som ikke ble gjennomsøkt etter bruksinformasjon, og de som ikke inneholder *.api_description-filer.

Plasseringen oppgis med en absolutt bane.

Eksempel:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- bundle name with usage
   		|
   		+--referencing bundle name
   			|
   			+-- [API or PRIVATE or OTHER]
   				|
   				+--[type_ or method_ or field_]references.xml
Ja
considerinternal Avgjør om interne referanser skal vurderes under søket.

Standardverdien er false.
Nei
considerapi Avgjør om API-referanser skal vurderes under søket.

Standardverdien er false.
Nei
considerillegaluse Avgjør om ugyldige API-bruksreferanser skal vurderes under søket.

Standardverdien er false.
Nei
apipatterns En kommadelt liste over pakkenavnmønstre (regulære uttrykk) som skal vurderes som API-pakker.

Som standard brukes API-beskrivelser i skannede bunter, men dette kan brukes til å overstyre eller legge til API-pakker.
Nei
internalpatterns En kommadelt liste over pakkenavnmønstre (regulære uttrykk) som skal vurderes som private pakker.

Som standard brukes API-beskrivelser i skannede bunter, men dette kan brukes til å overstyre eller legge til private pakker.
Nei
archivepatterns En kommadelt liste over arkiv-IDer som skal ignoreres under skanningen.

En arkiv-ID har formatet [bunt-ID]:[bane til arkiv].
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:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
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:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Nei
filters Angi rotkatalogen til API-filtrene som skal brukes under bruksskanningen.

Argumentet er rotkatalogen til *.api_filters-filene som skal brukes til å filtrere referanser.

.api_filters-filene oppgir bestemte problemer som skal ignoreres under API-analysen. Under bruksskanningen blir problemfiltrene konvertert til en liste over referanser som blir filtrert fra bruksskanningsresultatene.

Roten oppgis med en absolutt bane.
Roten må inneholde følgende struktur:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
Nei
debug Angi feilsøkingsverdien.

Mulige verdier er true og false
Standardverdien er false.
Nei

Eksempler

	<apitooling.apiuse
		location="/eclipse/eclipse.tar.gz"
		scopepattern=".*"
		referencepattern="org\.eclipse.*"
		report="/eclipse/apiuse-both/XML"
		considerinternal="true"
		considerapi="true"
		considerillegaluse="true"
		archivepatterns="org.eclipse.test.bundle:/libs/contributed.jar"
		excludelist="D:\exclude_list_external.txt"
		debug="true"
	/>

Dette kjører oppgaven som oppretter *.xml-filer i mappen /eclipse/apiuse-both/XML. Oppgaven søker gjennom alle bunter på produktstedet - definert av det regulære uttrykket .* - søker etter alle referanser til bunter med identifikatorer som begynner med org.eclipse (definert av det regulære uttrykket org\.eclipse.*). Den bruker ekskluderingslistefilen i D:\exclude_list_external.txt til å redusere antall problemer som rapporteres.

Under skanning blir klassefiler funnet i arkivet /libs/contributed.jar i org.eclipse.test.bundle oversett.

Hvis feilsøking er aktivert, vises feilsøkingssporing i Ant-konsollen.

Beslektet referanse

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