What's 'API Baseline' in Eclipse PDT

Question

Since upgrading to Eclipse 3.7, the Eclipse PDE plugin wants me to specify an 'API Baseline' for all my Eclipse Plugin projects.

However there seems to be no documentation which actually explains what 'API Baseline' stands for here, and what is it used for.

Could somebody please explain?

Consistency

Answer 1

API Baseline are intended to help you maintain plugins that others can use. The API Tools help you create compatible API versions. Follow the link that Sumit Singh posted to get an explanation on how to use them.

The Problem:

1. You create your plugin and release version 1 to the public.
2. Millions of people will use your plugin and create their own code that depends on the API of your plugin.
3. You release version 2 to the public. By mistake you change the API of your plugin.
4. Millions of people update to the new version and have to adapt their code. Thousands of programs fail. People are sad.

The Solution:

1. You create your plugin, annotate its API and release version 1 to the public.
2. Millions of people will use your plugin and create their own code that depends on the API of your plugin.
3. You declare version 1 of your plugin to be the API-Baseline that your code changes are automatically compared against. Any break in the API is presented to you before you release your plugin or run your tests. You release version 2 without any API changes.
4. Millions of people can update your plugin in their application, because the new plugin release is binary compatible to the previous one.
5. You declare version 2 of your plugin ....

Summary

If you develop a plugin just for your personal use and are not interested to maintain a compatible API, you can follow the advices to disable the warnings.

When you develop plugins for a community, e. g. the eclipse plugins themselves, it is essential that you keep API incompatibilities to a minimum. Then you will follow the advice and set the baseline to 4.2 when you develop for 4.3. The API tools will help you make 4.3 an enjoyment for all current 4.2 users.

Please note, that the API Tools are for the developers of the plugins that will be used by others. They are not addressed at the users of those plugins.

Holotype

This should be the top answer, not the lazy copy-paste one above... – Tempi

Answer 2

From the PDE API Tools User Guide:

An API baseline defines the state you want to compare your development workspace bundles against for the purposes of binary compatibility, bundle version numbers, and @since tags. For example, if you are developing bundles for Eclipse 3.4, you will use Eclipse 3.3 as your baseline.

Discouragement

i dont get it. if i am developing for eclipse 3.4, then why use 3.3 as baseline instead of 3.4? – Consistency

Eclipse 3.3 is being used as the reference here; the intent is to understand what changes in the plugin for Eclipse 3.4 will not be compatible with the version of the plugin for Eclipse 3.3 – Discouragement

@Consistency - I think that that is a mistake in the 2nd sentence. Ignore that sentence, and just base your understanding on the first one. – Cirone