API Analysis Ant Task

Purpose

This task runs a complete API analysis of an API profile relative to a baseline - including API use, binary compatibility, and bundle version number validation. The profile is the current state of a product under development. The profile is compared to an API baseline for binary compatibility (usually the previous release of a product).

The analysis does not include @since tag validation as all verification is performed on binary class files (source is not analyzed).

Usage

Description

The name of the Ant task is: apitooling.analysis. To be used, the jar file apitooling-ant.jar has to be on the Ant classpath.

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

Parameters

Attribute Description Required
baseline This attribute specifies the location of the reference baseline.

It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the directory is which you can find the Eclipse executable.

The location is specified using an absolute path.
Yes
profile This attribute specifies the location of the current product or profile that you want to compare against the reference baseline.

It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the directory is which you can find the Eclipse executable.

The location is specified using an absolute path.
Yes
report Set the output location where the reports will be generated.

Once the task is completed, reports are available in this directory using a structure similar to the filter root. A sub-folder is created for each component that has problems to be reported. Each sub-folder contains a file called "report.xml".

A special folder called "allNonApiBundles" is also created in this folder which also contains a file called "report.xml". This file lists all the bundles that are not using the API Tools nature.

There is also a "counts.xml" file created in the report directory that contains a summary of the problems found.

The location is specified using an absolute path.
Yes
filters Set the root directory of API filters to use during the analysis.

The argument is the root directory of the .api_filters files that should be used to filter potential problems created by the API Tools analysis.
The root is specified using an absolute path.
The root needs to contain the following structure:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
No
excludelist Set the exclude list location.

The exclude list location specifies a text file listing bundles to be excluded from the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a regular expression to match against bundle names (lines being with "R:")
  • a comment (lines being with '#')

The location is specified using an absolute path.
Following is an example exclude list:
 # 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\..*
 ...
No
includelist Set the include list location.

The include list location specifies a text file listing bundles to be included in the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a regular expression to match against bundle names (lines being with "R:")
  • a comment (lines being with '#')

The location is specified using an absolute path.
Following is an example include list:
 # 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\..*
 ...
No
preferences Set the preferences for the task.

The preferences are used to configure problem severities. Problem severities have three possible values: Ignore, Warning, or Error. The set of problems detected is defined by corresponding problem preference keys in API tools.
The location is specified using an absolute path. If the given location doesn't exist, the preferences won't be set.
Lines starting with '#' are ignored. The format of the preferences file looks like this:
 #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
 ...
The keys can be found in org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
No
debug Set the debug value.

The possible values are: true, false
Default is false.
No
eefile Set the execution environment file to use.

By default, an execution environment file corresponding to a JavaSE-1.6 execution environment is used.

The format of the file is described in this wiki page.

The file is specified using an absolute path.
No
processunresolvedbundles Set whether bundles with resolver errors should be analyzed.

If set, bundles that have resolver errors (such as missing dependencies) will be included in the analysis. The errors may affect the results so a list of resolver errors is included in the xml output and warnings will be added to the html during report conversion.

The possible values are: true, false
Default is true.
No

Examples

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

This will run the task creating report.xml files inside the folder D:\reports\xml. It will use the exclude list and the .api_filter files located in D:\exclude_list_external.txt and D:\filters to reduce the number of problems to report.

Problem severities will be generated as specified by D:\tests_api\org.eclipse.pde.api.tools.prefs.

Since debug is enabled, some debug tracing will show up in the Ant console.

Related reference

API Freeze Ant Task
File Generation Ant Task
API Use Ant Task
Analysis Report Conversion Ant Task
API Freeze Report Conversion Ant Task
API Use Report Conversion Ant Task
API Deprecation Ant Task
API Deprecation Report Conversion Ant Task