Twitter github

API is like a box of chocolates…

Ok, maybe API isn’t like a box of chocolates, but it’s something important, usually very hard to craft and even harder to maintain. However, I felt like I needed to use the tagline since I saw Forrest Gump recently.

API is also one of those things that I come to love and respect about Eclipse. In my personal opinion, the care the Eclipse teams takes in its API’s can be attributed to the success of Eclipse over time. For a person outside of Eclipse committership, it’s difficult to appreciate the diligence the Eclipse team takes in regards to APIs. On top of the time it takes to craft good APIs, it’s even more difficult to maintain them over time! There are all these silly little rules you have to follow to make sure you don’t break any clients.

Well, I’m happy to announce that the PDE team is attempting to graduate the API Tools project from the PDE Incubator for 3.4M5.

What is the API Tools project? Well, the goal of the project is to assist developers in API maintenance by reporting API issues such as binary incompatibilities, incorrect plug-in version numbers, missing or incorrect @since tags, and usage of non-API code between plug-ins. For those who don’t understand what this means, let me show you pictures.

The PDE API Tools let you work against API Profiles:

In this case, I setup my API “baseline” to be against the Eclipse 3.2.2 SDK. This means that all the code I’m developing should not break any APIs found in the 3.2.2 version of Eclipse. The next step would be to tweak some compiler settings in regards to see how I want errors reported:

Now that everything is setup, I was working on some PDE code and did something stupid… I modified the signature of an API method and forgot that would break my clients (ooops!) and cause many nasty bug reports to come in. Never fear, PDE API Tools is there to save my day:

Kind of cool, huh? It blows me away at least. It may not be perfect yet, but the API Tooling is a step in the right direction. Just imagine being told that you should increment your plug-in version because you modified your API in some shape or fashion. Wow!

In my mind, the beautiful modularity story Eclipse (OSGi) has combined with this type of tooling is solidifying Eclipse as an impressive runtime technology. When I have to step outside plug-in development sometimes to work with web technologies, I feel a bit like a luddite using punch cards.