此任务相对于基线对 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”文件,此文件包含所发现问题的总结。 使用绝对路径来指定此位置。 |
是 |
| filters | 设置在分析期间要使用的 API 过滤器的根目录。
参数是 .api_filters 文件的根目录,应当使用该参数对“API 工具”分析所产生的潜在问题进行过滤。 使用绝对路径来指定此根目录。 根目录需要包含以下结构:
root
|
+-- component name (i.e. org.eclipse.jface)
|
+--- .api_filters
|
否 |
| excludelist | 设置排除列表位置。 排除列表位置指定将不对其进行分析的文本文件列表捆绑软件。缺省情况下,将对概要文件中的所有捆绑软件进行分析。可以使用包括和排除列表属性来有选择地包括和排除捆绑软件。包括列表确定要分析的捆绑软件集(如果省略了,那么将包括所有捆绑软件),然后应用排除列表。此文件的每一行指定下列其中一项:
使用绝对路径来指定此位置。 以下是排除列表的一个示例: # 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\..* ... |
否 |
| includelist | 设置包括列表位置。
包括列表位置指定要对其进行分析的文本文件列表捆绑软件。缺省情况下,将对概要文件中的所有捆绑软件进行分析。可以使用包括和排除列表属性来有选择地包括和排除捆绑软件。包括列表确定要分析的捆绑软件集(如果省略了,那么将包括所有捆绑软件),然后应用排除列表。此文件的每一行指定下列其中一项:
使用绝对路径来指定此位置。 以下是包括列表的一个示例: # 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\..* ... |
否 |
| 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" />
这将运行在 D:\reports\xml 文件夹中创建 report.xml 文件的任务。
它将使用分别位于 D:\exclude_list_external.txt 和 D:\filters 中的排除列表与 .api_filter 文件来减少要报告的问题数。
将按照 D:\tests_api\org.eclipse.pde.api.tools.prefs 中所指定那样来生成问题严重性。
因为已启用调试,所以某些调试跟踪将显示在 Ant 控制台中。

API 冻结 Ant 任务
文件生成 Ant 任务
API 使用 Ant 任务
分析报告转换 Ant 任务
API 冻结报告转换 Ant 任务
API 使用报告转换 Ant 任务
API 不推荐 Ant 任务
API 不推荐报告转换 Ant 任务