Setting API Baselines in Eclipse

by rgrunber

At, when a project graduates from Incubation, it sheds its 0.N release number for a 1.0 release. Along with this comes the need to solidify its API.

When working on larger projects, with many contributors it can be tricky to know at what point an API breakage has occured. A project can have many different sub-projects, each with its own different set of committers. Add to this, the fact that not all API issues are trivial and we have a recipe for problems to creep in.

No one really wants to be the API police, going around to hunt down problems, and luckily there’s a way to avoid this. Committers can monitor changes to the API themselves.

Eclipse has a handy plugin development feature called “API Baselines”, which allows us to define a set of plugins against which we can compare for changes in API.

We’ll need to find plug-ins for our project with the version we wish to compare against. In this case the 1.0 version is located in this p2 repository, which I’ll just copy over to the local system :

$ eclipse -nosplash -verbose -application org.eclipse.equinox.p2.artifact.repository.mirrorApplication -source ${repoPath} -destination file:/home/rgrunber/linuxtools-1.0

We open Eclipse, and go to Window -> Preferences -> Plug-in Development -> API Baselines.

Click “Add A Baseline” and browse for the folder where we stored our plugins. We’ll just need to give a name to the baseline, and click “Finish”.

We can click “Apply” and it’ll ask us to do a full build, so why not.

Now that we’ve got a working baseline, let’s create a separate Problems view just for these kinds of issues.

Bring up the Problems View, right click on upside-down triangle at the top-right of the view, and go to “New Problems View”.

We’ll name the view “API Baseline Problems”. Once it’s created, go to the same location as before, but for this new menu, and click “Configure Contents”.

Create a new configuration and call it “API Warnings/Errors”. The scope will be “On any element”. The severity will be for Errors, Warnings, and Info, and we’ll only check off “API Problems” in Types.

Once we click ok, this view will show us just the API problems on projects when compared with the baseline we’ve set.

Of course a lot of this is configurable and a matter of preference, but in a few simple steps, we now have the ability to monitor the evolution of our project’s API.