Jump to: navigation, search

PDE/API Tools/User Guide

Current State

API tooling is still under construction and currently lives in the PDE incubator project. This guide is intended to be an example of how we intend developers to use API tooling rather than how it is used today. Some form of the tooling will be available in Eclipse 3.4, starting with the M5 milestone build.

API tooling bundles (plug-ins) are not available as binary downloads. You have to build the plug-ins yourself if you want to use them. See Getting the Source Code for help on getting and building the bundles.

API Tooling Setup

API tooling provides a builder that reports API usage and binary compatibility errors in the workspace. You must configure bundles that you want API tooling to report errors on and you must define an API profile that can be used as an API baseline (i.e. workspace projects are compared to the baseline in order to report binary compatibility errors, missing @since tags, incorrect version numbers, etc.).

Define an API Baseline

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.

API profiles are managed on the Plug-in Development > API Profiles preference page. Here you can create, edit, and delete API profiles. You can select one profile as the 'default' profile - this is the profile that will be used as the baseline.

Api profiles pref page.PNG

Use the New... button to open a wizard to define a profile. Any Eclipse SDK can be used as a profile simply by giving it a name and version and specifying the root location of the plug-ins.

Note: Currently, Eclipse builds do not contain API description metadata that assists API tooling. This information will be added to builds sometime during the 3.4 development cycle. An SDK can be used as a profile/baseline without the metadata, although this may cause some extra problems to appear in the workspace (for example compatability errors). We also intend to produce special versions of older builds (for example, Eclipse 3.3) that contain some API description metadata in them.

Configure Bundles for API Tooling

API tooling provides a builder that analyzes bundles and reports API errors. You need to configure existing projects to use the builder (this effectively adds the "API Tooling" nature to your project). As well, you need to describe the API of your bundle. Special API Javadoc tags can be placed on classes, interfaces, and methods to describe their API (@noimplement, @noinstantiate, @noextend).

Note: API tooling can insert Javadoc tags into source code based on existing component.xml files.

Using the PDE Tools > API Tooling Setup... action to configure your projects.

Api tooling setup.PNG

A dialog appears allowing you to select projects you want to setup for API tooling.

Api tooling setup wizard.PNG

Note: By default, component.xml files are deleted from your workspace after corresponding Javadoc tags are inserted into source code. There is a checkbox to disable this option. You can also preview the text changes that will be made, by clicking 'next'.

Api tooling setup preview.PNG

After pressing finish, Javadoc tags will be inserted and the API Tooling nature (and builder) will be added to your projects. API problems will now appear in the workspace where appropriate. You should manually examine your source code after tags have been inserted to ensure correctness.

API Problems

Once your projects have been configured for API tooling and an API baseline has been selected, API problems will be created during project builds (auto and full builds).

Adjusting Problem Severities

Similar to the way you can set compiler problem severities (error vs. warning vs. ignore), API tooling provides an API Errors/Warnings preference page that allows you to configure API problem severities. You can configure the problem severities on a per project basis as well, by using the API Errors/Warnings property page for a project, available from the Properties... action.

Api errors warnings page.PNG

Filtering Known Problems

Sometimes you will have API problems that are "known problems" or are "approved" API breakages. API tooling will soon have support to allow you to filter these problems from your workspace. Stay tuned. For now you can configure problem severities to Warning or Ignore to work around this problem.