Úloha Ant analýzy API

Účel

Tato úloha spustí úplnou analýzu rozhraní API v profilu API relativně k úrovni baseline - včetně používání rozhraní API, binární kompatibility a ověření čísla verze balíku. Profil je aktuální stav vyvíjeného produktu. Profil se porovná s úrovní baseline API pro binární kompatibilitu (obvykle s předchozí verzí produktu).

Analýza nezahrnuje ověření značky @since, protože veškerá verifikace se provádí na binárních souborech tříd (zdrojový text se neanalyzuje).

Použití

Popis

Název úlohy Ant je: apitooling.analysis. Chcete-li ji použít, soubor JAR apitooling-ant.jar musí být v cestě ke třídě nástroje Ant.

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

Parametry

Atribut Popis Nezbytné
baseline Tento atribut určuje umístění referenční úrovně baseline.

Může to být soubor .zip, .jar, .tgz, .tar.gz nebo adresář, který odpovídá instalačnímu adresáři Eclipse. To je adresář, v němž se nachází spustitelný soubor Eclipse.

Umístění se zadává pomocí absolutní cesty.
Ano
profile Tento atribut určuje umístění aktuálního produktu nebo profilu, který chcete porovnat vůči referenční úrovni baseline.

Může to být soubor .zip, .jar, .tgz, .tar.gz nebo adresář, který odpovídá instalačnímu adresáři Eclipse. To je adresář, v němž se nachází spustitelný soubor Eclipse.

Umístění se zadává pomocí absolutní cesty.
Ano
report Nastavte umístění výstupu, kam se vygenerují sestavy.

Jakmile bude úloha dokončena, v tomto adresáři budou k dispozici sestavy ve struktuře, která se podobá kořenovému adresáři filtrů. Pro každou komponentu s problémy, které se mají hlásit, se vytvoří podsložka. Každá podsložka obsahuje soubor s názvem "report.xml".

Také se v této složce vytvoří speciální složka s názvem "allNonApiBundles", která rovněž obsahuje soubor s názvem "report.xml". Tento soubor obsahuje seznam všech balíků, které nepoužívají charakter modulu API Tools.

V adresáři sestav je vytvořen rovněž soubor "counts.xml", který obsahuje souhrn nalezených problémů.

Umístění se zadává pomocí absolutní cesty.
Ano
filters Nastavte kořenový adresář filtrů API, které se mají při analýze použít.

Argumentem je kořenový adresář souborů .api_filters, které se mají použít k filtrování potenciálních problémů vytvořených analýzou modulu API Tools.
Kořen se zadává pomocí absolutní cesty.
Kořen musí mít následující strukturu:
 kořen
  |
  +-- název komponenty (tj. org.eclipse.jface)
         |
         +--- .api_filters
Ne
excludelist Nastavte umístění vylučovacího seznamu.

Umístění vylučovacího seznamu určuje textový soubor obsahující seznam balíků, které se mají vyloučit z analýzy. Standardně se analyzují všechny balíky v profilu. Atributy zahrnovacího a vylučovacího seznamu lze použít k selektivnímu zahrnutí a vyloučení balíků. Seznam zahrnutí naplní sadu balíků, které se mají analyzovat (když je vynechán, zahrnou se všechny balíky), a poté se použije vylučovací seznam. Každý řádek souboru určuje jedno z následujících:
  • Specifický název balíku.
  • Regulární výraz k porovnání s názvy balíků (řádky s "R:").
  • Komentář (řádky s '#').

Umístění se zadává pomocí absolutní cesty.
Následuje příklad vylučovacího seznamu:
 # 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\..*
 ...
Ne
includelist Nastavte umístění seznamu zahrnutí.

Umístění seznamu zahrnutí určuje textový soubor obsahující seznam balíků, které se mají zahrnout do analýzy. Standardně se analyzují všechny balíky v profilu. Atributy zahrnovacího a vylučovacího seznamu lze použít k selektivnímu zahrnutí a vyloučení balíků. Seznam zahrnutí naplní sadu balíků, které se mají analyzovat (když je vynechán, zahrnou se všechny balíky), a poté se použije vylučovací seznam. Každý řádek souboru určuje jedno z následujících:
  • Specifický název balíku.
  • Regulární výraz k porovnání s názvy balíků (řádky s "R:").
  • Komentář (řádky s '#').

Umístění se zadává pomocí absolutní cesty.
Následuje příklad seznamu zahrnutí:
 # 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\..*
 ...
Ne
preferences Nastavte předvolby úlohy.

Předvolby se používají k nakonfigurování závažností problémů. Závažnosti problémů mají tři možné hodnoty: ignorovat (Ignore), varování (Warning) nebo chyba (Error). Sada zjištěných problémů se definuje pomocí příslušných klíčů předvoleb problémů v nástrojích API.
Umístění se zadává pomocí absolutní cesty. Pokud zadané umístění neexistuje, předvolby se nenastaví.
Řádky začínající znakem '#' se ignorují. Formát souboru předvoleb vypadá takto:
 #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
 ...
Klíče se nacházejí v org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
Ne
debug Nastavte hodnotu ladění.

Možné hodnoty jsou: true, false
Výchozí hodnota je false.
Ne
eefile Nastavte soubor prováděcího prostředí, který se má použít.

Standardně se použije soubor prováděcího prostředí odpovídající prováděcímu prostředí JavaSE-1.6.

Formát souboru je popsán na této stránce wiki.

Soubor se určuje pomocí absolutní cesty.
Ne

Příklady

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

Tím se spustí úloha, která vytvoří soubory report.xml ve složce D:\reports\xml. Ke snížení počtu hlášených problémů se použije vylučovací seznam v souboru D:\exclude_list_external.txt a soubory .api_filter umístěné v adresáři D:\filters.

Závažnosti problémů se budou generovat podle specifikace v D:\tests_api\org.eclipse.pde.api.tools.prefs.

Vzhledem k tomu, že je povoleno ladění, na konzole Ant se zobrazí určitá ladicí trasování.

Související odkazy

Úloha Ant zmrazení API
Úloha Ant generování souboru
Úloha Ant použití API
Úloha Ant převodu sestavy analýzy
Úloha Ant převodu sestavy zmrazení API
Úloha Ant převodu sestavy využití API
Úloha Ant nepřípustnosti rozhraní API
Úloha Ant převodu sestavy nepřípustnosti rozhraní API