Jump to: navigation, search

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

< PDE‎ | API Tools
 
(19 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{API_Tools}}
 +
 
== Current State ==
 
== 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 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.
  
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 [http://wiki.eclipse.org/PDE_UI_Incubator_ApiTools#Getting_the_Source_Code Getting the Source Code] for help on getting and building the bundles.
+
[[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 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.).
+
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 13: 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]]
+
[[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 version 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 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.
+
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 29: Line 31:
 
Using the '''PDE Tools > API Tooling Setup...''' action to configure your projects.
 
Using the '''PDE Tools > API Tooling Setup...''' action to configure your projects.
  
[[Image:Api_tooling_setup.PNG]]
+
[[Image:Api_tooling_setup.PNG | Context menu item to start the tooling setup wizard]]
  
 
A dialog appears allowing you to select projects you want to setup for API tooling.
 
A dialog appears allowing you to select projects you want to setup for API tooling.
  
[[Image:Api_tooling_setup_refactoring.PNG]]
+
[[Image:Api_tooling_setup_refactoring.PNG | 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'.
 
'''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'.
  
[[Image:Api_tooling_setup_preview.PNG]]
+
[[Image:Api_tooling_setup_preview.PNG | 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.
 
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.
Line 54: 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]]
+
[[Image:Api_errors_pref.PNG | API errors and warnings preference page]]
  
 
<h4>Filtering Known Problems</h4>
 
<h4>Filtering Known Problems</h4>
Line 62: Line 64:
 
You can add a filter for a specific api problem using the Eclipse 'quickfix' mechanism on any api problem marker.
 
You can add a filter for a specific api problem using the Eclipse 'quickfix' mechanism on any api problem marker.
  
[[Image:Api_tooling_problems.PNG]]
+
[[Image:Api_tooling_problems.PNG | 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.
 
Once a filter has been added you can edit / remove it from the 'Api Problem Filters' project property page.
  
[[Image:Api_tooling_problem_filters_page.PNG]]
+
[[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

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

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.

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)

Ant Tasks

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