Εργασία Ant ανάλυσης API

Σκοπός

Αυτή η εργασία εκτελεί μια ολοκληρωμένη ανάλυση API, ενός προφίλ API σχετικό με μια γραμμή βάσης - συμπεριλαμβανομένης της χρήσης API, της δυαδικής συμβατότητας και της επικύρωσης του αριθμού εκδοχής δέσμης. Το προφίλ αποτελεί την τρέχουσα κατάσταση ενός προϊόντος που βρίσκεται σε στάδιο ανάπτυξης. Γίνεται σύγκριση του προφίλ με μια γραμμή βάσης API για δυαδική συμβατότητα (συνήθως με την προηγούμενη έκδοση του προϊόντος).

Η ανάλυση δεν περιλαμβάνει την επικύρωση του προσδιοριστικού @since, καθώς η επαλήθευση πραγματοποιείται σε δυαδικά αρχεία κλάσης (δεν γίνεται ανάλυση του πρωτογενούς κώδικα).

Χρήση

Περιγραφή

Το όνομα της εργασίας Ant είναι: apitooling.analysis. Προκειμένου να χρησιμοποιηθεί, το αρχείο jar apitooling-ant.jar πρέπει να βρίσκεται στην ίδια διαδρομή κλάσεων Ant.

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

Παράμετροι

Γνώρισμα Περιγραφή Απαιτείται
baseline Αυτό το γνώρισμα καθορίζει τη θέση της γραμμής βάσης παραπομπής.

Μπορεί να είναι αρχείο .zip, .jar, .tgz, .tar.gz ή ένας κατάλογος που αντιστοιχεί στο φάκελο εγκατάστασης του Eclipse. Αυτός είναι ο κατάλογος στον οποίο υπάρχει το Eclipse ως εκτελέσιμο αρχείο.

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ναι
profile Αυτό το γνώρισμα καθορίζει τη θέση του τρέχοντος προϊόντος ή προφίλ, το οποίο θέλετε να συγκρίνετε με τη γραμμή βάσης παραπομπής.

Μπορεί να είναι αρχείο .zip, .jar, .tgz, .tar.gz ή ένας κατάλογος που αντιστοιχεί στο φάκελο εγκατάστασης του Eclipse. Αυτός είναι ο κατάλογος στον οποίο υπάρχει το Eclipse ως εκτελέσιμο αρχείο.

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ναι
report Ορίστε τη θέση εξόδου όπου θα δημιουργηθούν οι αναφορές.

Μετά την ολοκλήρωση της εργασίας, οι αναφορές είναι διαθέσιμες σε αυτόν τον κατάλογο με τη χρήση μιας δομής παρόμοιας με τον κεντρικό κατάλογο φίλτρου. Δημιουργείται ένας υποφάκελος για κάθε στοιχείο που παρουσιάζει προβλήματα προς αναφορά. Κάθε υποφάκελος περιέχει ένα αρχείο με το όνομα "report.xml".

Ένας ειδικός φάκελος με το όνομα "allNonApiBundles" δημιουργείται σε αυτόν το φάκελο, ο οποίος επίσης περιέχει ένα αρχείο με το όνομα "report.xml". Στο αρχείο εμφανίζονται όλες οι δέσμες που δεν χρησιμοποιούν εργαλεία API.

Υπάρχει επίσης ένα αρχείο "counts.xml" το οποίο δημιουργείται στον κατάλογο αναφορών και το οποίο περιέχει μια σύνοψη των προβλημάτων που παρουσιάστηκαν.

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ναι
φίλτρα Ορίστε τον κεντρικό κατάλογο των φίλτρων API που θα χρησιμοποιηθούν κατά την ανάλυση.

Το όρισμα είναι ο κεντρικός κατάλογος των αρχείων .api_filters που πρέπει να χρησιμοποιηθούν για το φιλτράρισμα πιθανών προβλημάτων που έχουν δημιουργηθεί από την ανάλυση των εργαλείων API.
Ο κεντρικός κατάλογος καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ο κεντρικός κατάλογος πρέπει να περιλαμβάνει την ακόλουθη δομή:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
Όχι
excludelist Ορίστε τη θέση της λίστας εξαιρέσεων.

Η θέση της λίστας εξαιρέσεων καθορίζει ένα αρχείο κειμένου στο οποίο εμφανίζονται οι δέσμες που θα εξαιρεθούν από την ανάλυση. Από προεπιλογή, αναλύονται όλες οι δέσμες του προφίλ. Τα γνωρίσματα λίστας συμπεριλήψεων και εξαιρέσεων μπορούν να χρησιμοποιηθούν για την επιλεκτική συμπερίληψη ή εξαίρεση δεσμών. Η λίστα συμπεριλήψεων παρέχει το αρχικό σύνολο με τις δέσμες που θα αναλυθούν (αν παραλειφθεί, συμπεριλαμβάνονται όλες οι δέσμες). Στη συνέχεια εφαρμόζεται η λίστα εξαιρέσεων. Κάθε γραμμή του αρχείου καθορίζει ένα από τα εξής:
  • ένα όνομα δέσμης
  • μια κανονική έκφραση για την αναζήτηση ονομάτων δεσμών (γραμμές που αρχίζουν με "R:")
  • ένα σχόλιο (γραμμές που αρχίζουν με '#')

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ακολουθεί ένα παράδειγμα λίστας εξαιρέσεων:
 # ΔΕΣΜΕΣ DOC
 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
 # ΔΕΣΜΕΣ ΕΚΤΟΣ ECLIPSE
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Όχι
includelist Ορίζει τη θέση της λίστας συμπεριλήψεων.

Η θέση της λίστας συμπεριλήψεων καθορίζει ένα αρχείο κειμένου στο οποίο εμφανίζονται οι δέσμες που θα συμπεριληφθούν στην ανάλυση. Από προεπιλογή, αναλύονται όλες οι δέσμες του προφίλ. Τα γνωρίσματα λίστας συμπεριλήψεων και εξαιρέσεων μπορούν να χρησιμοποιηθούν για την επιλεκτική συμπερίληψη ή εξαίρεση δεσμών. Η λίστα συμπεριλήψεων παρέχει το αρχικό σύνολο με τις δέσμες που θα αναλυθούν (αν παραλειφθεί, συμπεριλαμβάνονται όλες οι δέσμες). Στη συνέχεια εφαρμόζεται η λίστα εξαιρέσεων. Κάθε γραμμή του αρχείου καθορίζει ένα από τα εξής:
  • ένα όνομα δέσμης
  • μια κανονική έκφραση για την αναζήτηση ονομάτων δεσμών (γραμμές που αρχίζουν με "R:")
  • ένα σχόλιο (γραμμές που αρχίζουν με '#')

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ακολουθεί ένα παράδειγμα λίστας συμπεριλήψεων:
 # ΔΕΣΜΕΣ DOC
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 R:org.eclipse.platform.doc.*
 # ΔΕΣΜΕΣ ΕΚΤΟΣ ECLIPSE
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Όχι
preferences Ορίστε τις προτιμήσεις για την εργασία.

Οι προτιμήσεις χρησιμοποιούνται για τη ρύθμιση της σοβαρότητας των προβλημάτων. Στη σοβαρότητα των προβλημάτων μπορούν να αποδοθούν τρεις πιθανές τιμές: Παράβλεψη, Προειδοποίηση ή Σφάλμα. Το σύνολο των προβλημάτων που έχει εντοπιστεί, καθορίζεται από τα αντίστοιχα κλειδιά προτιμήσεων προβλημάτων στα εργαλεία API.
Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής. Εάν η συγκεκριμένη θέση δεν υπάρχει, δεν θα γίνει ορισμός των προτιμήσεων.
Οι γραμμές που ξεκινούν με το χαρακτήρα '#' παραβλέπονται. Το αρχείο προτιμήσεων έχει την ακόλουθη μορφή:
 #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
 ...
Τα κλειδιά βρίσκονται στο αρχείο org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Όχι
debug Ορίστε την τιμή για τον εντοπισμό και τη διόρθωση σφαλμάτων.

Οι πιθανές τιμές είναι: true, false
Η προεπιλεγμένη τιμή είναι false.
Όχι
eefile Ορίστε το αρχείο περιβάλλοντος εκτέλεσης που θα χρησιμοποιηθεί.

Από προεπιλογή, χρησιμοποιείται ένα αρχείο περιβάλλοντος εκτέλεσης που αντιστοιχεί σε περιβάλλον εκτέλεσης JavaSE-1.6.

Η μορφή του αρχείου περιγράφεται σε αυτή τη σελίδα wiki.

Το αρχείο ορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Όχι

Παραδείγματα

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

Εκτελεί την εργασία που δημιουργεί τα αρχεία report.xml στο φάκελο D:\reports\xml. Θα χρησιμοποιηθεί η λίστα εξαιρέσεων και τα αρχεία .api_filter που βρίσκονται στη θέση D:\exclude_list_external.txt και D:\filters για τη μείωση του αριθμού των προβλημάτων προς αναφορά.

Η σοβαρότητα των προβλημάτων θα δημιουργηθεί όπως ορίζεται από το αρχείο D:\tests_api\org.eclipse.pde.api.tools.prefs.

Εφόσον έχει ενεργοποιηθεί ο εντοπισμός και η διόρθωση σφαλμάτων, θα εμφανιστεί κάποια ρουτίνα ιχνηλασίας εντοπισμού και διόρθωσης σφαλμάτων στην κονσόλα Ant.

Σχετικές παραπομπές

Εργασία Ant αναστολής API
Εργασία Ant δημιουργίας αρχείων
Εργασία Ant χρήσης API
Εργασία Ant μετατροπής αναφορών ανάλυσης
Εργασία Ant μετατροπής αναφορών αναστολής API
Εργασία Ant μετατροπής αναφορών χρήσης API
Εργασία Ant κατάργησης ΑΡΙ
Εργασία Ant μετατροπής αναφορών κατάργησης API