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).
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="..." />
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:
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:
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 |
<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.
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