Jump to: navigation, search

Difference between revisions of "PDE UI Incubator ApiTools Compare"

(What's a repository?)
(Do I need to specify something else?)
Line 65: Line 65:
 
[[Image:ApiToolsOptions.JPG|center]]
 
[[Image:ApiToolsOptions.JPG|center]]
  
 +
<ul>
 +
<li>Report APIs modified in backward-compatible way - only breaking changes will be detected and reported if this box is unchecked.</li>
 +
<li>Report missing source containers - uncheck this option if you compare one bundle against the snapshot made from a whole product.</li>
 +
<li>Report additions on interfaces as API breakage - adding new method to an interface is a breaking change, but a lot of interfaces in Eclipse has a soft "do not implement this interface" rule which make it OK. Uncheck this box to reduce the amount of noise generated; check this box to report this as a breaking change.</li>
 +
<li>Exclude known differences - the file containing known differences can be placed in the repository to eliminate those differences from subsequent comparison results.</li>
 +
</ul>
  
 
== Getting the Pieces ==
 
== Getting the Pieces ==

Revision as of 18:08, 2 February 2007

API Comparison Tool

What is it for?

The tool compares APIs exposed by two versions of your product. It reports changes that might break backward compatibility and provides a list of backward-compatible modifications.

Reports are produced as XML and HTML files. Here is the sample report showing APIs modified in a way that might break backward compatibility:

ApiToolsBreakageReport.JPG

and here is the sample report on backward compatible API changes:

ApiToolsCompatibleReport.JPG

What’s an API?

Good question. For starters here are some links; more information will be added later to this section.

Evolving Java-based APIs - What is considered an API in Eclipse

How to Use the Eclipse API - APIs in Eclipse from consumer's view point

Binary Compatibility - The Java Language Specification

API Javadoc tags - Potential way to work with "soft" rules used in Eclipse

How does the tool work?

The tool contains two operations: create an API snapshot and compare the code against API snapshot.

Both operations can be accessed via menus or run in a batch mode.

The dialog to create API snapshot looks like this:

ApiToolsCollect.JPG

And the dialog to compare code with the API snapshot looks like this:

ApiToolsCompare.JPG

Batch processing

The tool can be used in the batch mode. The command line is:

ApiTools { -create | -compare } -control <control_file_name>

Control file is an XML file that specifies repository location, location of the input or output, and a few options. Those files can be created from UI dialogs using "Export" commands.

What's a repository?

Repository is a place where the tool stores API snapshots. At present the only type of repository supported is a folder on the file system. The location of the folder should be specified in the "Repository" tab:

ApiToolsRepository.JPG

Do I need to specify something else?

For comparison, report location should be specified on the "Report" tab:

ApiToolsReport.JPG

This is the folder where XML and HTML reports will be placed by the tool.

While not a requirement, check the options tab:

ApiToolsOptions.JPG
  • Report APIs modified in backward-compatible way - only breaking changes will be detected and reported if this box is unchecked.
  • Report missing source containers - uncheck this option if you compare one bundle against the snapshot made from a whole product.
  • Report additions on interfaces as API breakage - adding new method to an interface is a breaking change, but a lot of interfaces in Eclipse has a soft "do not implement this interface" rule which make it OK. Uncheck this box to reduce the amount of noise generated; check this box to report this as a breaking change.
  • Exclude known differences - the file containing known differences can be placed in the repository to eliminate those differences from subsequent comparison results.

Getting the Pieces

Source code is stored in the PDE incubator (:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse) in the HEAD/pde-incubator/api-tooling/plugins.

There are two plug-ins:

  • org.eclipse.pde.api.tools
  • org.eclipse.pde.api.tools.ui

The Eclipse 3.3M4 or later should be used to compile those plug-ins.

Resources

Eclipse Bugzilla - Eclipse bug tracking database.

PDE Incubator - New projects that might be incorporated into PDE in future.

PDE UI Home Page - The main PDE UI web site.