Ant-opgave: Problemer med API-brugsscanning

Formål

Denne opgave fortolker API-brugsscanningerne i en profil i forhold til en grundlinje. Den rapporterer referencerne til de typer, metoder og felter, som nu mangler i profilen.

Brug

Beskrivelse

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

<apitooling.apiusescanproblems
	profile="..."
	report="..."
	apiusescans="..."
	excludelist="..."
	includelist="..."
	preferences="..."
	debug="..."
/>

Parametre

Attribut Beskrivelse Påkrævet
profile Denne attribut angiver placeringen af det aktuelle produkt eller den aktuelle profil, som API-brugsscanningerne skal fortolkes i forhold til.

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. Der oprettes en underfolder for alle komponenter, der har problemer, som skal rapporteres. De enkelte underfoldere indeholder en fil, der hedder "report.xml".

Placeringen angives ved hjælp af en absolut sti.
Ja
apiusescans Attributten angiver den kommaseparerede liste over de placeringer af API-brugsscanninger, som du vil kontrollere op imod profilen.

Det kan være en .zip-fil eller et bibliotek, der svarer til API-brugsscanningsrapporten. Det er i dette bibliotek, at du kan finde XML-folderen i brugsscanningen.
Ja
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
 API_USE_SCAN_TYPE_SEVERITY=Error
 API_USE_SCAN_METHOD_SEVERITY=Error
 API_USE_SCAN_FIELD_SEVERITY=Error
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

Eksempler

	<apitooling.apiusescanproblems
		profile="D:\eclipse\3.7\eclipse"
		report="D:\reports\xml"
		apiusescans="D:\APIUseScan\ProductOne,D:\APIUseScan\ProductTwo"
		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. Typerne, metoderne og felterne fra brugsscanningerne bliver fortolket i profilen på placeringen D:\eclipse\3.7\eclipse, og de manglende bliver rapporteret. Opgaven bruger exclude-listefilen på placeringen D:\exclude_list_external.txt til at mindske antallet af bundter, som der skal rapporteres problemer for.

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-analyse
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