API Freeze Ant Task

Purpose

This task identifies APIs that have been added, modified, or removed relative to an API baseline. This task is intended to validate no API changes occur after an API freeze.

Usage

Description

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

<apitooling.apifreeze
	baseline="..."
	profile="..."
	report="..."
	excludelist="..."
	includelist="..."
	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 name of the report file to be generated.

It should be specified using an absolute path.
This must be a file location, not a directory.
Yes
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. In addition, this task supports listing members in the include and exclude lists. The include list seeds the set of bundles and members to be analyzed (when omitted, all bundles and members are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a specific member name
  • a regular expression to match against bundle or member names (lines being with "R:")
  • a comment (lines being with '#')

The location is specified using an absolute path.
Following is an example exclude list:
# ECLIPSE MEMBERS
org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
# ECLIPSE BUNDLES
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL
# NON-ECLIPSE BUNDLES
com.ibm.icu
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. In addition, this task supports listing members in the include and exclude lists. The include list seeds the set of bundles and members to be analyzed (when omitted, all bundles and members are included), and the exclude list is then applied. Each line of the file specifies one of:
  • a specific bundle name
  • a specific member name
  • a regular expression to match against bundle or member names (lines being with "R:")
  • a comment (lines being with '#')

The location is specified using an absolute path.
Following is an example include list:
# ECLIPSE MEMBERS
org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
# ECLIPSE BUNDLES
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL
# NON-ECLIPSE BUNDLES
com.ibm.icu
R:javax\..*
...
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.apifreeze
		baseline="D:\eclipse\3.4.1\eclipse"
		profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
		report="D:\report\report.xml"
		excludelist="D:\exclude_list.txt"
		debug="true"
	/>

This will run the task creating report.xml inside the folder D:\report. It will use the exclude list D:\exclude_list_external.txt to reduce the number of problems to report.

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

Related reference

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