Difference between revisions of "PDE/API Tools"

From Eclipsepedia

< PDE
Jump to: navigation, search
(Testing)
m (Links)
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Infobox
+
{{API_Tools}}
| name = Api Tooling
+
| website= http://www.eclipse.org/pde/pde-api-tools/
+
| download = http://download.eclipse.org/eclipse/downloads/
+
| list = pde-ui-dev
+
| newsgroup = eclipse.platform
+
| product = PDE
+
| component = API+Tools
+
}}
+
  
 
== Introduction ==
 
== Introduction ==
Line 17: Line 9:
 
* Update <code>@since</code> tags for newly added classes, interfaces, methods, etc.  
 
* Update <code>@since</code> tags for newly added classes, interfaces, methods, etc.  
 
* Provide new Javadoc tags and code assist to annotate types with special restrictions.  
 
* Provide new Javadoc tags and code assist to annotate types with special restrictions.  
* Leverage existing information (in MANIFEST.MF) to define the visibility of packages between bundles.  
+
* Leverage existing information (in <code>MANIFEST.MF</code>) to define the visibility of packages between bundles.  
 
* Identify usage of non-API code between plug-ins.
 
* Identify usage of non-API code between plug-ins.
 
* Identity leakage of non-API types into API.
 
* Identity leakage of non-API types into API.
 +
* Identify usage of code from a JRE outside the bounds of the one specified in the bundle configuration (<code>MANIFEST.MF</code>).
  
 
== Present state  ==
 
== Present state  ==
  
API tooling was released to the Eclipse SDK in the PDE project during the [http://www.eclipse.org/eclipse/development/eclipse_project_plan_3_4.html Eclipse 3.4] release. Our milestone development timeline corresponds to that of the Eclipse SDK (currently in the 3.6 stream). All planned items (and wishes) can be found on our [[PDE/Plan/3.6#API Tools|3.6 plan]] page.
+
API tooling was released to the Eclipse SDK in the PDE project during the [http://www.eclipse.org/eclipse/development/eclipse_project_plan_3_4.html Eclipse 3.4] release. Our milestone development time line corresponds to that of the Eclipse SDK (currently in the 3.6 stream).
  
== Getting Started  ==
+
== Planning ==
  
==== User Guide ====
+
All planned items (and wishes) can be found on our [[PDE/Plan/3.6#API Tools|3.6 plan]] page.
 
+
API tooling is under construction. Here's a link to the bleeding edge [[API_Tools/User_Guide|user guide]] to help get you started.
+
 
+
==== Getting the Source Code ====
+
 
+
The source code for this implementation is available from the '''dev.eclipse.org''' CVS server in the '''/cvsroot/eclipse''' respository. You need to check out three projects from '''HEAD'''. There is a team project set file to assist you with this.
+
 
+
#Add the CVS server to your repositories view (:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse).
+
#Expand the server and "HEAD" elements in the tree.
+
#Check out the the '''/org.eclipse.pde.api.tools.doc''' project.
+
#In your Package Explorer, select the '''projectSet.psf''' file (for extssh access) or '''pserverProjectSet.psf''' file (for pserver access) in the root folder of the "/org.eclipse.pde.api.tools.doc project".
+
#Select '''File &gt; Import'''. On the first page of the import wizard select '''Team &gt; Team Project Set''' and press "Next".
+
#On the second page of the wizard, the "org.eclipse.pde.api.tools.releng\projectSet.psf" should already be specified as the file to import. If not, choose it. Press "Finish".
+
#When asked for a user name and password although you chose the '''pserverProjectSet.psf''', just enter '''anonymous''' as user name and leave the password field empty.
+
 
+
The PDE API Tools projects and tests will be added to your workspace.
+
 
+
 
+
 
+
==== Bugs and Enhancement Requests ====
+
 
+
The API tooling project uses [https://bugs.eclipse.org/bugs/ Bugzilla] for tracking bugs and enhancement requests. [https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&classification=Eclipse&product=PDE&component=API+Tools&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= Active API tooling bugs] can be found with this query. All bugs should be filed in with the '''Eclipse''' project, '''PDE''' product, under the '''API Tools''' component.
+
 
+
== Testing ==
+
 
+
Manual testing must be done for all aspects of API tooling. To help with what should be tested (and what is the expected result) you can refer to the
+
test script page [http://wiki.eclipse.org/Api_Tooling_Testing API Tooling Testing]
+
 
+
==== Running the JUnit Tests ====
+
 
+
The JUnit tests run as standard JUnit tests (it can also run as JUnit plug-in tests). However, the tests require one mandatory VM argument:
+
 
+
#-DrequiredBundles={path to directory containing standard Eclipse plug-ins}
+
 
+
One optional VM argument can be:
+
 
+
#-Dee.file={path to an .ee file}
+
 
+
For example:
+
<pre>-DrequiredBundles=${eclipse_home}/plugins -Dee.file=/VMs/SUN-1.6.0_04/sun-1-6u4.ee</pre>
+
The required bundles are used as a pool when resolving required bundles for test bundles in the suite. The .ee file describes the execution environment required by API profiles in the test suite. Our tests require a J2SE-1.5 profile. A sample .ee file has the following contents:
+
<pre>-Djava.home=${ee.home}\..
+
-Dee.bootclasspath=..\jre\lib\rt.jar;..\jre\lib\jsse.jar;..\jre\lib\jce.jar;..\jre\lib\charsets.jar
+
-Dee.language.level=1.5
+
-Dee.class.library.level=J2SE-1.5
+
</pre>
+
A zip file containing pre-configured ee files is available [[:Image:Ee-files.zip|here]]. Each of the ee files in the archive are designed to be placed in the install directory of the corresponding VM.
+
 
+
For example the sun-1-6u3.ee file should be placed in the directory where the sun 1.6.0 update 3 VM is installed:
+
<pre>C:
+
  /VMs
+
      /sun16u3
+
        /jre
+
        /bin
+
        ...
+
        sun-1-6u3.ee
+
[[|]]</pre>
+
If the ee file is not specified, a default one is generated using the Execution Environment 1.5. The tests can be run individually, or you can run them all from the APIToolsTestSuite class.
+
 
+
== Use Cases ==
+
 
+
These are the use cases API tooling is designed to support.
+
 
+
<h4>Binary Compatibility Reporting (Batch Mode)</h4>
+
 
+
Two versions of the same API profile are compared for [http://wiki.eclipse.org/Evolving_Java-based_APIs_2 binary compatibility]. An xml file is produced summarizing any incompatibilities. The comparison tool can be invoked from the command line as a stand alone Java application specifying the profiles to compare and which parts of the profiles to consider (for example, only compare portions of the profile that are deemed to be API).
+
 
+
The report includes errors regarding component version identifiers that have not been incremented properly. As well, if source code is available for the "newer" API profile, the report includes missing @since Javadoc tags.
+
 
+
An exclude list should be added to filter out the cases where the binary incompatibility is "under control", i.e. approved by the PMC.
+
The best way to maintain the exclude list would be to have a javadoc tag in the source code that mentions why this is a breakage. Something like:
+
@breakage-addition ......
+
@breakage-remove Type#member .....
+
 
+
The removals would be located on the parent of the removed member.
+
 
+
Updating the source code improves the traceability of a breakage and allows readers of the source code to get a better picture without the need to check another document.
+
 
+
<h4>Binary Compatibility Reporting (IDE Mode)</h4>
+
 
+
Workspace projects are compared to a baseline API profile for binary compatibility. Incompatibilities are flagged in source files using markers (that also appear in the Problems view). The user configures the severity of errors produced. A set of external API profiles are managed in the workspace and one is specfied as the baseline against which workspace projects are compared. The user defines the workspace API profile as combination of workspace projects and external API components.
+
 
+
Compatibility errors are updated incrementally or in full depending on the build setting in the workspace (i.e. auto-build vs. manual/full build). Error markers are also produced for components with incorrect version numbers and missing @since Javadoc tags. Quick fixes are available to address the problems.
+
 
+
An exclude list should be added to filter out the cases where the binary incompatibility is "under control", i.e. approved by the PMC.
+
The best way to maintain the exclude list would be to have a javadoc tag in the source code that mentions why this is a breakage. Something like:
+
@breakage-addition ......
+
@breakage-remove Type#member .....
+
 
+
The removals would be located on the parent of the removed member.
+
 
+
Updating the source code improves the traceability of a breakage and allows readers of the source code to get a better picture without the need to check another document.
+
 
+
<h4>API Usage Reporting (Batch Mode)</h4>
+
 
+
The most common API usage report locates illegal use of APIs among components in a single API profile - i.e. access to non-API types, methods, and fields; and illegal extension, implementing, or instantiating. The API usage scanner can be invoked as a stand alone Java application to examine all or specific portions of an API profile for illegal API use. An xml file is produced as output.
+
 
+
The API scanner should also support scanning for use of a specific component. For example, rather than scanning component X to determine what use it makes of other APIs, scan a profile to find all uses of the API in X.
+
 
+
Another interesting scan would be to report what parts of a profile or component would be broken when migrating to another version of a required component. For example, the internals of a component often change or can be removed in a newer release of the component.
+
 
+
<h4>API Usage Reporting (IDE Mode)</h4>
+
 
+
The Eclipse SDK already provides compiler warnings for discouraged accesses between bundles - which is the same as referencing non-API code. Rather than duplicate this effort, the integrated tooling could just report illegal implementing, subclassing, and instantiation. Problem markers would be created incrementally, similar to the support for binary compatibility.
+
 
+
<h4>API Usage Searching (IDE Mode)</h4>
+
 
+
Similar to the extensive search facility provided by JDT for searching projects in the workspace, API tooling could support searching of API profiles. This would allow to search for all uses of a component, type, method, etc., from an API profile or component.
+
 
+
<h4>Version Management</h4>
+
 
+
In addition to reporting missing @since tags and incorrect bundle version numbers (based on the Eclipse bundle versionion scheme), the tooling will provide quick fixes to correct these problems.
+
 
+
As well, the tooling will assist developers on determining compatible version ranges of required bundles (plug-ins). Developers often increment the lower bound of version ranges of required bundles in each major release. Usually this makes sense (for example, the debug platform's UI bundle usually requires the latest debug core bundle). However, sometimes this is uneccessary, and a bundle may run perfectly fine with an older version of a required bundle. Given a range of versions of a required bundle, API tooling will be able to determine which versions of the bundle satisfy API (and non-API) accesses.
+
 
+
<h4>Building API Components & Profies</h4>
+
 
+
Provide a mechanism to export API components. This could be used in a build process or from the IDE.
+
 
+
<h4>Javadoc Tags, API Visibilities & Restrictions</h4>
+
 
+
The platform provides a default set of javadoc tags. The tags and the Java members they apply to are:
+
 
+
# @noreference - Indicates that other bundles must not reference this member by name. I.e., the member is internal.  This tag is intended to be used very rarely when a public class wants to restrict access to one of its members, but is not intended for general usage. This tag is ignored on all other members except for method declarations and non-final field declarations.
+
# @noimplement - Indicates that other bundles must not implement this interface. This tag is ignored for all types except for interfaces.
+
# @noextend - Indicates that other bundles must not extend the class or interface it appears on. This tag is ignored for all members that are not interfaces or classes.
+
# @noinstantiate - Indicates that other bundles must not create instances of this class. This tag is ignored for all other types that are not classes.
+
# @nooverride - Indicates that other bundles must not extend (re-implement with a call to the overridden parent) or re-implement (with no call to the overridden parent) this method. This tag is ignored for all other members except method declarations.
+
  
 
== Links ==
 
== Links ==
  
[http://wiki.eclipse.org/ApiTools_Architecture API Tooling Architecture] - High level description of the tooling's architecture
+
[[PDE/API Tools/Tasks|Ant Tasks]] - Description of the Ant Tasks available in API Tools
  
[http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs Evolving Java-based APIs] - What is considered an API in Eclipse.
+
[[ApiTools Architecture|API Tooling Architecture]] - High level description of the tooling's architecture.
  
== Resources ==
+
[[Evolving Java-based APIs]] - What is considered an API in Eclipse.
  
[https://bugs.eclipse.org/bugs/ Eclipse Bugzilla] - Eclipse bug tracking database.
+
[[Version Numbering]] - Guidelines on versioning plug-ins
  
[http://wiki.eclipse.org/index.php/PDE_UI_Incubator PDE Incubator] - New projects that might be incorporated into PDE in future.
+
[[PDE/Incubator]- New projects that might be incorporated into PDE in future.
  
 
[http://www.eclipse.org/pde/pde-ui/ PDE UI Home Page] - The main PDE UI web site.
 
[http://www.eclipse.org/pde/pde-ui/ PDE UI Home Page] - The main PDE UI web site.
  
[[Category:API|API Tooling]]
+
[[Category:API|API Tools]]
[[Category:Equinox|API Tooling]]
+
[[Category:Equinox|API Tools]]
 +
[[Category:PDE|API Tools]]
 +
[[Category:Eclipse_Project|API Tools]]

Revision as of 08:32, 12 October 2011

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

Contents

Introduction

API tooling will assist developers in API maintenance by reporting API defects such as binary incompatibilities, incorrect plug-in version numbers, missing or incorrect @since tags, and usage of non-API code between plug-ins. The tooling will be integrated in the Eclipse SDK and will be used in the automated build process. Specifically, the tooling is designed to do the following:

  • Identify binary compatibility issues between two versions of a software component or product.
  • Update version numbers for plug-ins (bundles) based on the Eclipse versioning scheme.
  • Update @since tags for newly added classes, interfaces, methods, etc.
  • Provide new Javadoc tags and code assist to annotate types with special restrictions.
  • Leverage existing information (in MANIFEST.MF) to define the visibility of packages between bundles.
  • Identify usage of non-API code between plug-ins.
  • Identity leakage of non-API types into API.
  • Identify usage of code from a JRE outside the bounds of the one specified in the bundle configuration (MANIFEST.MF).

Present state

API tooling was released to the Eclipse SDK in the PDE project during the Eclipse 3.4 release. Our milestone development time line corresponds to that of the Eclipse SDK (currently in the 3.6 stream).

Planning

All planned items (and wishes) can be found on our 3.6 plan page.

Links

Ant Tasks - Description of the Ant Tasks available in API Tools

API Tooling Architecture - High level description of the tooling's architecture.

Evolving Java-based APIs - What is considered an API in Eclipse.

Version Numbering - Guidelines on versioning plug-ins

PDE/Incubator - New projects that might be incorporated into PDE in future.

PDE UI Home Page - The main PDE UI web site.