Denne opgave udfører en fuldstændig søgning i en bestemt grundlinje for at oprette en rapport over API-anvendelse.
Analysen indeholder ikke bundter, som ikke er API-værktøjsaktiveret.
Navnet på Ant-opgaven er: apitooling.apiuse
. For at kunne bruges skal JAR-filen apitooling-ant.jar
findes i Ant-classpath.
<apitooling.apiuse location="..." scopepattern="..." referencepattern="..." report="..." considerinternal="..." considerapi="..." considerillegaluse="..." apipatterns="..." internalpatterns="..." archivepatterns="..." excludelist="..." includelist="..." debug="..." />
Attribut | Beskrivelse | Påkrævet |
location |
Denne attribut angiver placeringen af det aktuelle produkt, hvor du vil søge efter API-anvendelse.
Det kan være en .zip-, .jar-, .tgz- eller .tar.gz-fil eller et bibliotek, der indeholder et produkt eller en samling af bundter. Placeringen angives ved hjælp af en absolut sti. |
Ja |
scopepattern |
Attributten angiver et regulært udtryksmønster, der bruges til at vælge, hvilke bundter på placeringen der skal søges i.
Følgende scanner f.eks. kun efter API-anvendelse i Eclipse-bundter: org.eclipse.*Mønsteret skal være et korrekt formateret regulært udtryk som defineret her. |
Nej |
referencepattern |
Attributten angiver et regulært udtryksmønster, der skal bruges til at filtrere søgeresultaterne. Kun API-anvendelse, der refererer til et bundt, som matcher filteret, bliver rapporteret.
Følgende rapporterer f.eks. kun rapportanvendelse, der refererer til kode i JDT: org.eclipse.jdt.*Mønsteret skal være et korrekt formateret regulært udtryk som defineret her. |
Nej |
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 hierarkisk struktur. Der oprettes en underfolder for alle komponenter, der et andet bundt, som refererer til det. De enkelte underfoldere indeholder en fil, der hedder "[bundtnavn].xml". I denne folder er der en anden underfolder (med navnet "[refererende bundtnavn].xml") for hvert bundt, der refererer til bundtet i den overordnede folder. I den refererende bundtfolder er der én ud af tre underfoldere (API, PRIVATE eller OTHER), som indeholder type-, metode- eller feltreferencer af denne slags. Tre andre specielle filer skrives i rapportbiblioteket. Det er "counts.xml", "not_searched.xml" og "no_apidescription.xml", og de indeholder oplysninger om antallet af fundne referencer samt bundter fra grundlinjen, som der henholdsvis ikke er søgt i efter anvendelsesoplysninger, og som ikke indeholder .api_description-filer. Placeringen angives ved hjælp af en absolut sti. Eksempel: rod | +-- "not_searched.xml" +-- "no_apidescription.xml" +-- "counts.xml" +-- bundtnavn med syntaks | +--refererende bundtnavn | +-- [API eller PRIVATE eller OTHER] | +--[type_ eller method_ eller field_]references.xml |
Ja |
considerinternal | Om interne referencer skal tages i betragtning under søgningen.
Standardværdien er false . |
Nej |
considerapi | Om API-referencer skal tages i betragtning under søgningen.
Standardværdien er false . |
Nej |
considerillegaluse | Om referencer til ugyldig API-brug skal tages i betragtning under søgningen.
Standardværdien er false . |
Nej |
apipatterns | En kommasepareret liste over pakkenavnemønstre (regulære udtryk), der skal betragtes som API-pakker.
Som standard bruges API-beskrivelser i de scannede bundter, men dette kan bruges til at tilsidesætte eller tilføje API-pakker. |
Nej |
internalpatterns | En kommasepareret liste over pakkenavnemønstre (regulære udtryk), der skal betragtes som private pakker.
Som standard bruges API-beskrivelser i de scannede bundter, men dette kan bruges til at tilsidesætte eller tilføje private pakker. |
Nej |
archivepatterns | En kommasepareret liste over arkiv-id'er, der skal ignoreres under scanningen.
En arkiv-id har formatet: [bundt-id]:[sti til arkiv] . |
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: # EXCLUDED BUNDLES R:org\.eclipse\..*\.doc\..* ... |
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: # INCLUDED BUNDLES R:org\.eclipse\..* ... |
Nej |
filters | Angiver det rodbibliotek med API-filtre, der skal bruges brugsscanningen.
Argumentet er rodbiblioteket for de .api_filters-filer, der skal bruges til at filtrere referencer. .api_filters-filerne angiver specifikke problemer, der skal ignoreres under API-analysen. Under brugsscanningen bliver problemfiltrene konverteret til en liste over referencer, der bliver filtreret fra brugsscanningsresultaterne. Rod angives ved hjælp af en absolut sti. Roden skal have følgende struktur: rod | +-- komponentnavn (dvs. org.eclipse.jface) | +--- .api-filtre |
Nej |
debug | Angiv fejlfindingsværdien.
Mulige værdier er: true , false
Standardværdien er false . |
Nej |
<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" />
Herved køres den opgave, som opretter *.xml
-filer i folderen /eclipse/apiuse-both/XML
.
Opgaven søger i alle bundter på produktplaceringen - defineret af det regulære udtryk .*
- efter alle referencer til bundter, hvis id starter med org.eclipse (defineret af det regulære udtryk org\.eclipse.*
).
Opgaven bruger exclude-listefilen på placeringen D:\exclude_list_external.txt
til at mindske antallet af problemer, der skal rapporteres.
Under scanningen bliver klassefiler, som findes i arkivet /libs/contributed.jar i org.eclipse.test.bundle, ignoreret.
Hvis fejlfinding er aktiveret, bliver der vist fejlfindingssporing i Ant-konsollen.
Ant-opgave: API-frys
Ant-opgave: Generering af fil
Ant-opgave: Konvertering af analyserapport
Ant-opgave: Konvertering af API-frysrapport
Ant-opgave: API-forældelse
Ant-opgave: Konvertering af API-forældelsesrapport
Ant-opgave: Konvertering af API-brugsrapport