Zadanie Ant analizy interfejsu API

Przeznaczenie

To zadanie wykonuje pełną analizę interfejsu API dla profilu interfejsu API względem wersji bazowej - włącznie z użyciem interfejsu API, zgodnością binarną oraz sprawdzaniem poprawności numeru wersji pakunku. Profil to bieżący stan tworzonego produktu. Profil zostaje porównany z wersją bazową interfejsu API pod kątem zgodności binarnej (zwykle z wcześniejszą wersją produktu).

Analiza nie obejmuje sprawdzania poprawności znacznika @since, ponieważ weryfikacja jest wykonywana na plikach klasy binarnej (kod źródłowy nie jest analizowany).

Opis

Opis

Nazwa zadania Ant to apitooling.analysis. Aby możliwe było jego użycie, plik JAR apitooling-ant.jar musi znajdować się w ścieżce klas narzędzia Ant.

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

Parametry

Atrybut Opis Wymagany
baseline Ten atrybut określa położenie wersji bazowej odniesienia.

Może to być plik .zip, .jar, .tgz lub .tar.gz albo katalog odpowiadający folderowi instalacyjnemu platformy Eclipse. Jest to katalog, w którym znajduje się plik wykonywalny platformy Eclipse.

Położenie jest określane przy użyciu pełnej ścieżki.
Tak
profile Ten atrybut określa położenie bieżącego produktu lub profilu, który ma zostać porównany z wersją bazową odniesienia.

Może to być plik .zip, .jar, .tgz lub .tar.gz albo katalog odpowiadający folderowi instalacyjnemu platformy Eclipse. Jest to katalog, w którym znajduje się plik wykonywalny platformy Eclipse.

Położenie jest określane przy użyciu pełnej ścieżki.
Tak
report Ustawia położenie wyjściowe, w którym będą generowane raporty.

Po zakończeniu zadania raporty będą dostępne w tym katalogu o strukturze przypominającej katalog główny filtrów. Dla każdego komponentu z problemami, które wymagają raportowania, tworzony jest podfolder. Każdy podfolder zawiera plik o nazwie report.xml.

W tym folderze tworzony jest także specjalny folder o nazwie allNonApiBundles, który zawiera plik o nazwie report.xml. W tym pliku znajduje się lista wszystkich pakunków, które nie używają rodzaju Narzędzia interfejsu API.

W katalogu raportów tworzony jest także plik counts.xml zawierający podsumowanie znalezionych problemów.

Położenie jest określane przy użyciu pełnej ścieżki.
Tak
filtry Ustawia katalog główny filtrów interfejsu API, które mają być używane podczas analizy.

Argumentem jest katalog główny plików .api_filters, które powinny być używane do filtrowania potencjalnych problemów wynikających z analizy narzędzi interfejsu API.
Katalog główny jest określany przy użyciu pełnej ścieżki.
Katalog główny musi zawierać następującą strukturę:
 root
  |
  +-- nazwa komponentu (tzn. org.eclipse.jface)
         |
         +--- .api_filters
Nie
excludelist Ustawia położenie listy wykluczeń.

Położenie listy wykluczeń określa plik tekstowy zawierający pakunki do wykluczenia z analizy. Domyślnie analizowane są wszystkie pakunki w profilu. Atrybutów listy włączeń i wykluczeń można używać do selektywnego włączania i wykluczania pakunków. Lista włączeń określa zbiór pakunków, które mają być analizowane (jej pominięcie oznacza włączenie wszystkich pakunków). Po niej jest stosowana lista wykluczeń. Każdy wiersz pliku określa jeden z następujących elementów:
  • konkretna nazwa pakunku,
  • wyrażenie regularne porównywane z nazwami pakunków (wiersze zaczynające się od łańcucha „R:”),
  • komentarz (wiersze zaczynające się od znaku „#”).

Położenie jest określane przy użyciu pełnej ścieżki.
Przykładowa lista wykluczeń:
 # PAKUNKI 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
 # PAKUNKI SPOZA ŚRODOWISKA ECLIPSE
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Nie
includelist Ustawia położenie listy włączeń.

Położenie listy włączeń określa plik tekstowy zawierający pakunki do uwzględnienia w analizie. Domyślnie analizowane są wszystkie pakunki w profilu. Atrybutów listy włączeń i wykluczeń można używać do selektywnego włączania i wykluczania pakunków. Lista włączeń określa zbiór pakunków, które mają być analizowane (jej pominięcie oznacza włączenie wszystkich pakunków). Po niej jest stosowana lista wykluczeń. Każdy wiersz pliku określa jeden z następujących elementów:
  • konkretna nazwa pakunku,
  • wyrażenie regularne porównywane z nazwami pakunków (wiersze zaczynające się od łańcucha „R:”),
  • komentarz (wiersze zaczynające się od znaku „#”).

Położenie jest określane przy użyciu pełnej ścieżki.
Przykładowa lista włączeń:
 # PAKUNKI DOC
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 R:org.eclipse.platform.doc.*
 # PAKUNKI SPOZA ŚRODOWISKA ECLIPSE
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
Nie
preferences Ustawianie preferencji zadania.

Preferencje służą do konfigurowania istotności problemów. Istotność problemu może mieć jedną z trzech wartości: Ignorowanie, Ostrzeżenie lub Błąd. Zestaw wykrywanych problemów jest definiowany przez powiązane klucze preferencji problemów w narzędziach interfejsu API.
Położenie jest określane przy użyciu pełnej ścieżki. Jeśli dane położenie nie istnieje, preferencje nie zostaną ustawione.
Wiersze zaczynające się od znaku # są ignorowane. Format pliku preferencji jest następujący:
 #czw 20 lis 2008 17:35:06 EST
 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
 ...
Klucze można znaleźć w pliku org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Nie
debug Ustawia wartość debugowania.

Możliwe wartości to: true, false.
Wartość domyślna to false.
Nie
eefile Ustawia plik środowiska wykonawczego, który ma być używany.

Domyślnie plik środowiska wykonawczego odpowiada używanemu środowisku wykonawczemu JavaSE-1.6.

Format pliku jest opisany na tej stronie wiki.

Położenie jest określane przy użyciu pełnej ścieżki.
Nie

Przykłady

	<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:\lista_wykluczeń_zewnętrznych.txt"
		preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs"
		debug="true"
	/>

Spowoduje to uruchomienie zadania tworzącego pliki report.xml w folderze D:\raporty\xml. Zadanie będzie używać listy wykluczeń i plików .api_filter znajdujących się w pliku D:\lista_wykluczeń_zewnętrznych.txt i w folderze D:\filtry, aby zredukować liczbę problemów do zgłoszenia.

Poziomy istotności problemów będą generowane zgodnie z opisem w pliku D:\tests_api\org.eclipse.pde.api.tools.prefs.

Ponieważ włączone jest debugowanie, część danych śledzenia debugowania będzie wyświetlana w konsoli narzędzia Ant.

Informacje pokrewne

Zadanie Ant blokowania interfejsu API
Zadanie Ant generowania pliku
Zadanie Ant użycia interfejsu API
Zadanie Ant konwersji raportu analizy
Zadanie Ant konwersji raportu blokowania interfejsu API
Zadanie Ant konwersji raportu użycia interfejsu API
Zadanie Ant deaktualizowania interfejsu API
Zadanie Ant konwersji raportu deaktualizowania interfejsu API