Recently, a few people have come to me ask how Eclipse maintains its API and versions. The intent of this question was to see what lessons there are to be learned for other OSGi-based applications. If we step back a bit, in essence, Eclipse is a large OSG application. On top of that, Eclipse is a platform where people build their own OSGi applications on… it’s an OSGi party. As a result, there are many people dependent on the API Eclipse produces so the management of this API is important. If breaking API changes were common, people would have less desire to build on the platform. To help with this problem, Eclipse developed PDE API Tools.

I’ll discuss four main areas around API management that API Tools can help you with.

API Comparisons

I have seen some discussion of people wanting to know what new APIs were part of the Eclipse Galileo release. While it’s pretty easy to see the new and noteworthy items for the latest Eclipse release, it’s difficult to dive into and see what actual classes and methods were modified. To help alleviate this problem, PDE API Tools has the ability to produce API comparison reports to show exactly what has changed. I have mentioned the API Tooling view in a past blog entry for those who are interested.

API Compatibility

One thing that’s important is being able to see binary compatibility issues between a build and a baseline. This is currently possible within the Eclipse IDE if you use PDE API Tools in the workspace, however, if you wanted to generate a report via an Ant task you can do that. As a sample, I generated a report against Eclipse 3.4.2 and Eclipse 3.5:

<?xml version="1.0" encoding="UTF-8"?>
<project name="api_analysis_reporting" default="run" basedir=".">
    <property name="baseline" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.4.2/eclipse" />
	<property name="profile" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.5/eclipse" />
	<property name="report_location" value="${baseline}/api" />
	<property name="html_report_location" value="${baseline}/api-html"/>
 
	<target name="run">
	    <apitooling.analysis
	      	baseline="${baseline}"
	    	profile="${profile}"
	      	report="${report_location}"
	      	debug="true"
	     />
	    <apitooling.analysis_reportconversion
	      	htmlfiles="${html_report_location}"
	      	xmlfiles="${report_location}"
	      	debug="true"
	    />
	  </target>
</project>

API Freeze

Another aspect that’s important to Eclipse is the concept of an API Freeze.

Towards the end of the Eclipse release, we implement an API Freeze which means that no new API can be added or modified after this point. Why have an API Freeze? Well, it helps ensure stable APIs for consumers looking to adopt a new version of Eclipse. From a producer point of view, how do you ensure that the API Freeze is actually enforced? Developers are human and make mistakes. Developers can be also be sneaky by modifying API.

To help enforce an API Freeze, PDE API Tools has the ability to produce freeze reports:

<?xml version="1.0" encoding="UTF-8"?>
<project name="api_freeze_reporting" default="run" basedir=".">
    <property name="baseline" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.4.2/eclipse" />
	<property name="profile" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.5/eclipse" />
	<property name="report_location" value="${baseline}/api" />
	<property name="html_report_location" value="${baseline}/api-html"/>
 
	<target name="run">
	    <apitooling.apifreeze
	      	baseline="${baseline}"
	    	profile="${profile}"
	      	report="${report_location}"
	      	debug="true"
	     />
	    <apitooling.apifreeze_reportconversion
	      	htmlfile="${html_report_location}"
	      	xmlfile="${report_location}"
	      	debug="true"
	    />
	  </target>
</project>

As part of the Galileo release, we used freeze reports as a way to ensure API stability as we converged.

API Usage

From the consumer point of view, it’s interesting to see how people are consuming your APIs. To help with this, API Tools has the ability to run usage reports against a set of bundles. Awhile ago, I blogged about this topic and produced a report against most of the bundles included in the Galileo release:

<?xml version="1.0" encoding="UTF-8"?>
<project name="api_use_reporting" default="run" basedir=".">
    <property name="baseline" value="/Users/chrisaniszczyk/eclipses/eclipse-galileo" />
    <property name="report_location" value="${baseline}/api" />
	<property name="html_report_location" value="${baseline}/api-html"/>
 
	<target name="run">
	    <apitooling.apiuse
	      	baseline="${baseline}"
	    	proceedonerror="true"
	      	report="${report_location}"
	      	considerinternal="true"
	      	considerapi="true"
	      	debug="true"
	     />
	    <apitooling.apiuse_reportconversion
	      	htmlfiles="${html_report_location}"
	      	xmlfiles="${report_location}"
	      	debug="true"
	    />
	  </target>
</project>

I hope this helps and allows you to understand and adopt PDE API Tools.

Also, the PDE team is currently in the planning stages for the next release.

Please file any bugs if you have issues or suggestions so the PDE team can act on them.

Related posts:

• Improved Target Platform Management, Eclipse Galileo Feature #3
• OSGi Tool Summit Recap
• Eclipse, OSGi, Galileo and Release Trains
• OSGi Tooling BOF @ EclipseCon
• PDE’s Automated Management of Dependencies

Tags: api, galileo, OSGi, pde