Ant-Task für API-Analyse

Zweck

Diese Task führt eine vollständige API-Analyse eines API-Profils relativ zu einer Referenzkonfiguration aus - einschließlich einer Validierung der API-Verwendung, Binärkompatibilität und Versionsnummer des Produktpakets. Als Profil dient der aktuelle Status eines Produkts, das sich in der Entwicklung befindet. Das Profil wird mit einer API-Referenzkonfiguration hinsichtlich der Binärkompatibilität (in der Regel mit dem Vorgängerrelease eines Produkts) verglichen.

Die Analyse schließt keine Validierung von '@since'-Tags ein, da die gesamte Überprüfung für binäre Klassendateien erfolgt (die Quelle wird nicht analysiert).

Verwendung

Beschreibung

Der Name der Ant-Task ist apitooling.analysis. Für ihre Verwendung muss sich die JAR-Datei apitooling-ant.jar im Ant-Klassenpfad befinden.

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

Parameter

Attribut Beschreibung Erforderlich
baseline Dieses Attribut gibt die Position der Referenzkonfiguration an.

Es kann eine Datei mit der Dateierweiterung '.zip', '.jar', '.tgz' bzw. '.tar.gz' oder ein Verzeichnis angegeben werden, das dem Eclipse-Installationsordner entspricht. Dies ist das Verzeichnis, in dem sich die ausführbare Eclipse-Datei befindet.

Die Position wird mit einem absoluten Pfad angegeben.
Ja
profile Dieses Attribut gibt die Position des aktuellen Produkts oder Profils an, das mit der Referenzkonfiguration verglichen werden soll.

Es kann eine Datei mit der Dateierweiterung '.zip', '.jar', '.tgz' bzw. '.tar.gz' oder ein Verzeichnis angegeben werden, das dem Eclipse-Installationsordner entspricht. Dies ist das Verzeichnis, in dem sich die ausführbare Eclipse-Datei befindet.

Die Position wird mit einem absoluten Pfad angegeben.
Ja
report Gibt die Ausgabeposition an, in der die Berichte generiert werden.

Nach Abschluss der Task sind die Berichte in diesem Verzeichnis verfügbar. Hierbei wird eine Struktur verwendet, die dem Stammverzeichnis des Filters ähnlich ist. Für jede Komponente, für die Probleme bzw. Fehler gemeldet werden müssen, wird ein Unterordner erstellt. Jeder Unterordner enthält eine Datei namens 'report.xml'.

Es wird ein besonderer Ordner namens 'allNonApiBundles' in diesem Ordner erstellt, der ebenfalls eine Datei 'report.xml' enthält. In dieser Datei werden alle Produktpakete aufgelistet, die die Gattung der API-Tools nicht verwenden.

Es ist außerdem eine im Berichtsverzeichnis erstellte Datei "counts.xml" vorhanden, die eine Zusammenfassung der gefundenen Probleme enthält.

Die Position wird mit einem absoluten Pfad angegeben.
Ja
filters Gibt das Stammverzeichnis der API-Filter an, die bei der Analyse verwendet werden sollen.

Das Argument ist das Stammverzeichnis der Dateien des Typs '.api_filters', die zum Filtern potenzieller Probleme bzw. Fehler verwendet werden sollen, die durch die API-Toolanalyse erstellt wurden.
Das Stammverzeichnis wird mit einem absoluten Pfad angegeben.
Das Stammverzeichnis muss die folgende Struktur enthalten:
 stammverzeichnis
  |
  +-- komponentenname (d. h. org.eclipse.jface)
         |
         +--- .api_filters
Nein
excludelist Gibt die Position der Ausschlussliste an.

Die Position der Ausschlussliste gibt eine Textdatei an, in der Produktpakete aufgelistet sind, die aus der Analyse ausgeschlossen werden sollen. Standardmäßig werden alle Produktpakete im Profil analysiert. Durch die Einschluss- und Ausschlusslistenattribute können Produktpakete selektiv ein- und ausgeschlossen werden. Die Einschlussliste gibt die Ausgangsgruppe der zu analysierenden Produktpakete an. (Wenn sie nicht angegeben wird, werden alle Produktpakete eingeschlossen.) Anschließend wird die Ausschlussliste auf diese Gruppe angewendet. Jede Zeile der Datei gibt einen der folgenden Informationstypen an:
  • Einen bestimmten Produktpaketnamen
  • Einen regulären Ausdruck, der mit Produktpaketnamen abgeglichen wird (Zeilen, die mit "R:" beginnen)
  • Einen Kommentar (Zeilen, die mit '#' beginnen)

Die Position wird mit einem absoluten Pfad angegeben.
Das folgende Beispiel zeigt eine Ausschlussliste:
 # 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\..*
 ...
Nein
includelist Gibt die Position der Einschlussliste an.

Die Position der Einschlussliste gibt eine Textdatei an, in der Produktpakete aufgelistet sind, die in die Analyse eingeschlossen werden sollen. Standardmäßig werden alle Produktpakete im Profil analysiert. Durch die Einschluss- und Ausschlusslistenattribute können Produktpakete selektiv ein- und ausgeschlossen werden. Die Einschlussliste gibt die Ausgangsgruppe der zu analysierenden Produktpakete an. (Wenn sie nicht angegeben wird, werden alle Produktpakete eingeschlossen.) Anschließend wird die Ausschlussliste auf diese Gruppe angewendet. Jede Zeile der Datei gibt einen der folgenden Informationstypen an:
  • Einen bestimmten Produktpaketnamen
  • Einen regulären Ausdruck, der mit Produktpaketnamen abgeglichen wird (Zeilen, die mit "R:" beginnen)
  • Einen Kommentar (Zeilen, die mit '#' beginnen)

Die Position wird mit einem absoluten Pfad angegeben.
Das folgende Beispiel zeigt eine Einschlussliste:
 # 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\..*
 ...
Nein
preferences Gibt die Benutzervorgaben für die Task an.

Die Benutzervorgaben werden zum Konfigurieren von Fehlerbewertungen verwendet. Für Fehlerbewertungen sind die folgenden drei Werte möglich: 'Ignorieren', 'Warnung' oder 'Fehler'. Die Gruppe der festgestellten Probleme wird in den API-Tools durch entsprechende Benutzervorgabenschlüssel für Probleme definiert.
Die Position wird mit einem absoluten Pfad angegeben. Wenn die angegebene Position nicht existiert, wird die Benutzervorgabe nicht angegeben.
Zeilen, die mit '#' starten, werden ignoriert. Das Format der Benutzervorgabendatei sieht wie folgt aus:
 #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
 ...
Die Schlüssel befinden sich in 'org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes'.
Nein
debug Gibt den Wert für die Debugfunktion an.

Folgende Werte sind möglich: true und false.
Der Standardwert ist false.
Nein
eefile Gibt die Ausführungsumgebungsdatei an, die verwendet werden soll.

Standardmäßig wird eine Ausführungsumgebungsdatei verwendet, die einer JavaSE-1.6-Ausführungsumgebung entspricht.

Das Format der Datei wird auf dieser Wiki-Seite mit Beschreibungen der Ausführungsumgebung erläutert.

Die Datei wird mit einem absoluten Pfad angegeben.
Nein

Beispiele

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

Hierdurch wird die Task ausgeführt, durch die report.xml-Dateien im Ordner D:\reports\xml erstellt werden. Die Task verwendet die Ausschlussliste D:\exclude_list_external.txt und die Dateien des Typs .api_filter im Verzeichnis D:\filters, um die Anzahl der zu meldenden Probleme bzw. Fehler zu senken.

Fehlerbewertungen werden wie durch D:\tests_api\org.eclipse.pde.api.tools.prefs angegeben generiert.

Da die Debugfunktion aktiviert ist, wird in der Ant-Konsole die Tracefunktion für die Fehlerbehebung angezeigt.

Zugehörige Referenzinformationen

Ant-Task für API-Freeze
Ant-Task für Dateigenerierung
Ant-Task für API-Verwendung
Ant-Task für Analyseberichtskonvertierung
Ant-Task für API-Freeze-Berichtskonvertierung
Ant-Task für API-Verwendungsberichtskonvertierung
Ant-Task für eingestellte API-Unterstützung
Ant-Task für Konvertierung von Berichten zu eingestellter API-Unterstützung