Compare Ant Task

Purpose

This task runs a complete comparison of an API profile relative to a baseline.

Usage

Description

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

<apitooling.compare
	baseline="..."
	profile="..."
	report="..."
	excludelist="..."
	components="..."
	visibility="..."
	debug="..."
/>

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 report will be generated.

Once the task is completed, the report called "compare.xml" is available in this directory.

The location is specified using an absolute path.
Yes
excludelist Set the exclude list location.

The exclude list is used to know what bundles should excluded from the xml report generated by the task execution. The lines that start with '#' are ignored from the excluded elements.
The location is specified using an absolute path.
The format of the exclude list file looks like this:
 # 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
 javax.servlet
 javax.servlet.jsp
 # Exclude all pde bundles
 R:org\.eclipse\.pde\..*
 ...
The exclude list can contain regular expressions if the line starts with "R:".
No
debug Set the debug value.

The possible values are: true, false
Default is false.
No
components Set the components' list location.

The components' list contains all the components' names that must be compared. If omitted, all components from the given baseline are compared.
The location is specified using an absolute path.
The format of the components' list file looks like this:
 # 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
 # Include all pde bundles
 R:org\.eclipse\.pde\..*
 ...
The components' list can contain regular expressions if the line starts with "R:".
No
visibility Set the visibility value.

The possible values are: API, ALL
Default is API.
No

Examples

	<apitooling.compare
		baseline="D:\eclipse\3.4.1\eclipse"
		profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
		report="D:\reports\xml"
		excludelist="D:\exclude_list_external.txt"
		debug="true"
	/>

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

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 Report Conversion Ant Task