Cette analyse complètement un profil API par rapport à une ligne de base, notamment l'utilisation d'API, la compatibilité binaire et la validation du numéro de version du regroupement. Le profil est l'état en cours d'un produit en cours de développement. Le profil est comparé à une référence d'API (généralement la version précédente du produit )pour déterminer la compatibilité binaire .
L'analyse n'inclut pas la validation de la balise @since, car l'ensemble de la vérification est exécutée sur les fichiers de classe binaires (la source n'est pas analysée).
Le nom de la tâche Ant est apitooling.analysis. Pour qu'il puisse être utilisé, le fichier jar apitooling-ant.jar doit figurer dans le chemin d'accès aux classes Ant.
<apitooling.analysis baseline="..." profile="..." report="..." filters="..." excludelist="..." includelist="..." preferences="..." debug="..." eefile="..." />
| Attribut | Description | Obligatoire |
| baseline | Cet attribut définit l'emplacement de la ligne de base de référence.
Il peut s'agir d'un fichier .zip, .jar, .tgz, .tar.gz ou d'un répertoire qui correspond au dossier d'installation Eclipse. Il s'agit du répertoire dans lequel se trouve l'exécutable Eclipse. L'emplacement est défini en utilisant un chemin absolu. |
Oui |
| profile | Cet attribut définit l'emplacement du produit ou du profil en cours à comparer à la ligne de base de référence.
Il peut s'agir d'un fichier .zip, .jar, .tgz, .tar.gz ou d'un répertoire qui correspond au dossier d'installation Eclipse. Il s'agit du répertoire dans lequel se trouve l'exécutable Eclipse. L'emplacement est défini en utilisant un chemin absolu. |
Oui |
| report | Définit l'emplacement dans lequel les rapports sont générés.
A la fin de la tâche, les rapports sont disponibles dans ce répertoire en utilisant une structure similaire à la racine des filtres. Un sous-dossier est créé pour chaque composant pour lequel des incidents doivent être signalés. Chaque sous-dossier contient un fichier "report.xml". Le dossier spécial "allNonApiBundles" est également créé dans ce dossier qui contient également un fichier "report.xml". Ce fichier répertorie tous les regroupements qui n'utilisent pas la nature d'utilitaire d'API. Il existe également un fichier "counts.xml" créé dans le répertoire report qui contient un récapitulatif des problèmes détectés. L'emplacement est spécifié en utilisant un chemin absolu. |
Oui |
| filters | Définit le répertoire racine des filtres API à utiliser pendant l'analyse.
L'argument est le répertoire racine des fichiers .api_filters qui doivent être utilisés pour filtrer les incidents potentiels créés par l'analyse des utilitaires d'API. La racine est spécifiée en utilisant un chemin absolu. La racine doit contenir la structure suivante :
root
|
+-- component name (i.e. org.eclipse.jface)
|
+--- .api_filters
|
Non |
| excludelist | Définit l'emplacement de la liste d'exclusion.
L'emplacement de la liste d'exclusion indique les regroupements de fichier texte devant être exclus de l'analyse. Par défaut, tous les regroupements dans le profil sont analysés. Les attributs de liste d'inclusion et d'exclusion peuvent être utilisés pour inclure et exclure des regroupements de manière sélective. La liste d'inclusion est tirée de l'ensemble de regroupements devant être analysés (en cas d'omission, tous les regroupements sont inclus), et la liste d'exclusion est appliquée. Chaque ligne du fichier indique l'un des éléments suivants :
L'emplacement est défini en utilisant un chemin absolu. L'exemple ci-dessous illustre la liste d'exclusion : # 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\..* ... |
Non |
| includelist | Définit l'emplacement de la liste d'inclusion.
L'emplacement de la liste d'inclusion indique un fichier texte répertoriant les regroupements à inclure dans l'analyse. Par défaut, tous les regroupements dans le profil sont analysés. Les attributs de liste d'inclusion et d'exclusion peuvent être utilisés pour inclure et exclure des regroupements de manière sélective. La liste d'inclusion est tirée de l'ensemble de regroupements devant être analysés (en cas d'omission, tous les regroupements sont inclus), et la liste d'exclusion est appliquée. Chaque ligne du fichier indique l'un des éléments suivants :
L'emplacement est défini en utilisant un chemin absolu. L'exemple ci-dessous illustre la liste d'inclusion : # 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\..* ... |
Non |
| preferences | Définit les préférences de la tâche.
Les préférences permettent de configurer la gravité des incidents. Les incidents peuvent avoir les niveaux de gravité Ignorer, Avertissement ou Erreur. Le groupe d'incidents détectés est défini par les clés de référence d'incident correspondantes dans les utilitaires d'API. L'emplacement est défini en utilisant un chemin absolu. Si l'emplacement fourni n'existe pas, les préférences ne sont pas définies. Les lignes commençant par '#' sont ignorées. Le format du fichier des préférences se présente comme suit : #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 ...Les clés se trouvent dans org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes. |
Non |
| debug | Définit la valeur de débogage.
Les valeurs possibles sont true et false
La valeur par défaut est false.
|
Non |
| eefile | Définit le fichier d'environnement d'exécution à utiliser.
Par défaut, un fichier d'environnement d'exécution correspondant à un environnement d'exécution JavaSE-1.6 est utilisé. Le format du fichier est décrit dans cette page wiki. Le fichier est défini en utilisant un chemin absolu. |
Non |
<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" />
Cet exemple permet d'exécuter la tâche en créant des fichiers report.xml dans le dossier D:\reports\xml.
Il utilise la liste d'exclusion et les fichiers .api_filter situés dans D:\exclude_list_external.txt et
D:\filters pour réduire le nombre d'incidents à signaler.
La gravité des incidents est générée en fonction de ce qui est spécifié par D:\tests_api\org.eclipse.pde.api.tools.prefs.
Etant donné que le débogage est activé, un traçage de débogage apparaît dans la console Ant.

Tâche Ant de gel d'API
Tâche Ant de génération de fichier
Tâche Ant d'utilisation d'API
Tâche Ant de conversion de rapport d'analyse
Tâche Ant de conversion de rapport de gel d'API
Tâche Ant de conversion de rapport d'utilisation d'API
Tâche Ant de dépréciation d'API
Tâche Ant de conversion de rapport de dépréciation d'API