Difference between revisions of "PDE/API Tools/User Guide"

From Eclipsepedia

< PDE‎ | API Tools
Jump to: navigation, search
 
(15 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{API_Tools}}
 +
 
== Current State ==
 
== Current State ==
  
API tooling has recently been integrated into the Eclipse SDK and lives in the PDE project. This guide shows developers how to set up and use API tooling features in daily development scenarios.
+
API tooling has been integrated into the Eclipse SDK and lives in the PDE project. This guide shows developers how to set up and use API tooling features in daily development scenarios.
 +
 
 +
[[PDE/API Tools/Target Environment/User Guide|Execution Environments User Guide]]
  
 
== API Tooling Setup ==
 
== API Tooling Setup ==
  
API tooling provides a builder that reports API usage and binary compatibility errors in the workspace. You must configure bundles/projects that you want API tooling to report errors on and you must define an API profile that can be used as a baseline (i.e. workspace projects are compared to the baseline in order to report binary compatibility errors, missing @since tags, incorrect version numbers, etc.).
+
API tooling provides a builder that reports API usage and binary compatibility errors in the workspace. You must configure bundles/projects that you want API tooling to report errors on and you must define an API baseline to compare against workspace projects (to report compatibility errors, missing @since tags, incorrect version numbers, etc.).
  
 
<h4>Define an API Baseline</h4>
 
<h4>Define an API Baseline</h4>
Line 11: Line 15:
 
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.
 
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 baselines are managed on the '''Plug-in Development > API Baselines''' preference page. Here you can create, edit, and delete API baselines. You can select one baseline as the 'default' - this is the baseline that the workspace will be compared against.
  
[[Image:Api_profiles_pref_page.PNG | The API profile preference page]]
+
[[Image:Api_profiles_pref_page_2.PNG | The API profile preference page]]
  
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 specifying the root location of the plug-ins.
+
Use the '''Add Baseline...''' button to open a wizard to define a baseline. Any Eclipse SDK can be used as a baseline simply by giving it a name 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 some problems may not be detected when this information is missing. For example, if you are implementing an interface that originates from a binary required plug-in, API tooling cannot verify that the interface is allowed to implemented unless the API description metadata is present.
+
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 baseline without the metadata, although some problems may not be detected when this information is missing. For example, if you are implementing an interface that originates from a binary required plug-in, API tooling cannot verify that the interface is allowed to implemented unless the API description metadata is present.
  
 
<h4>Configure Bundles for API Tooling</h4>
 
<h4>Configure Bundles for API Tooling</h4>
  
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).
+
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). You can use content assist to insert tags with appropriate comments.
  
 
'''Note''': API tooling can insert Javadoc tags into source code based on existing '''component.xml''' files.
 
'''Note''': API tooling can insert Javadoc tags into source code based on existing '''component.xml''' files.
Line 52: Line 56:
 
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.
 
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.
  
[[Image:Api_errors_warnings_page.PNG | Api errors and warnings preference page]]
+
[[Image:Api_errors_pref.PNG | API errors and warnings preference page]]
  
 
<h4>Filtering Known Problems</h4>
 
<h4>Filtering Known Problems</h4>
Line 66: Line 70:
  
 
[[Image:Api_tooling_problem_filters_page.PNG | The API problem filters property page (for projects)]]
 
[[Image:Api_tooling_problem_filters_page.PNG | The API problem filters property page (for projects)]]
 +
 +
== Ant Tasks ==
 +
 +
API Tools provides a number of ant tasks to integrate the tooling into your build process. For more details see [[PDE/API Tools/Tasks|Ant Tasks]].
 +
 +
[[Category:API]]
 +
[[Category:PDE]]

Latest revision as of 09:54, 14 February 2012

API Tools
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Contents

[edit] Current State

API tooling has been integrated into the Eclipse SDK and lives in the PDE project. This guide shows developers how to set up and use API tooling features in daily development scenarios.

Execution Environments User Guide

[edit] API Tooling Setup

API tooling provides a builder that reports API usage and binary compatibility errors in the workspace. You must configure bundles/projects that you want API tooling to report errors on and you must define an API baseline to compare against workspace projects (to report 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 baselines are managed on the Plug-in Development > API Baselines preference page. Here you can create, edit, and delete API baselines. You can select one baseline as the 'default' - this is the baseline that the workspace will be compared against.

The API profile preference page

Use the Add Baseline... button to open a wizard to define a baseline. Any Eclipse SDK can be used as a baseline simply by giving it a name 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 baseline without the metadata, although some problems may not be detected when this information is missing. For example, if you are implementing an interface that originates from a binary required plug-in, API tooling cannot verify that the interface is allowed to implemented unless the API description metadata is present.

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). You can use content assist to insert tags with appropriate comments.

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.

Context menu item to start the tooling setup wizard

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

Main page of the API tooling setup wizard, presented as a refactoring

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'.

A preview of changes made during a typical setup

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.

[edit] 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).

The tooling breaks down the types of problems reported into one of three categories:

  1. Usage Problems - restricted code is being called by unauthorized plugins
  2. Binary Incompatibilities - changes between versions are not binary compatible
  3. Version Problems - plugin versions or code versions (@since tags) not correct

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 and warnings preference page

Filtering Known Problems

Sometimes you will have API problems that are "known problems" or are "approved" API breakages. API tooling has support to allow you to filter these problems from your workspace.

You can add a filter for a specific api problem using the Eclipse 'quickfix' mechanism on any api problem marker.

Examples of API problems in the problems view


Once a filter has been added you can edit / remove it from the 'Api Problem Filters' project property page.

The API problem filters property page (for projects)

[edit] Ant Tasks

API Tools provides a number of ant tasks to integrate the tooling into your build process. For more details see Ant Tasks.