Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "PDE/API Tools"

< PDE
(Links)
(77 intermediate revisions by 10 users not shown)
Line 1: Line 1:
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:  
+
{{API_Tools}}
 +
 
 +
== 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 <code>@since</code> 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.  
 
* 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 version numbers for plug-ins (bundles) based on the Eclipse versioning scheme.  
* Update @since 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 is currently '''under construction'''. One of the interesting features of the tool is its ability to produce and process class file stubs (i.e. minimal class files with just member signatures and reference information). The comparison and reference analysis tools can process standard class files or class file stubs. The stubs allow “API components” to be produced that are smaller than the original code intended for distribution. The class file stubs can be used as libraries to compile against, but not run.
+
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).
More information on the [http://wiki.eclipse.org/ApiTools_Architecture architecture] of API tooling can be found here.
+
  
== Getting Started ==
+
== Planning ==
  
<h4>Getting the Source Code</h4>
+
All planned items (and wishes) can be found on our [[PDE/Plan/3.6#API Tools|3.6 plan]] page.
  
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.
+
== Links ==
  
# Add the CVS server to your repositories view (:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse).
+
[[PDE/API Tools/Tasks|Ant Tasks]] - Description of the Ant Tasks available in API Tools
# Expand the server and "HEAD" elements in the tree.
+
# Navigate to the "pde-incubator/api-tooling/plugins" folder.
+
# Check out the the '''org.eclipse.pde.api.tools.releng''' project.
+
# In your Package Explorer, select the '''projectSet.psf''' file in the root folder of the "org.eclipse.api.tools.releng project".
+
# Select '''File > Import'''. On the first page of the import wizard select '''Team > 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".
+
 
+
The PDE API Tools projects and tests will be added to your workspace.
+
 
+
<h4>Rununing the JUnit Tests</h4>
+
 
+
The JUnit tests run as standard JUnit tests (i.e. not JUnit plug-in tests). However, the tests require two VM arguments:
+
 
+
# -DrequiredBundles={path to directory containing standard Eclipse plug-ins}
+
# -Dee.file={path to an .ee file}
+
 
+
For example, <code>-DrequiredBundles=c:\sdk20071031-0010\eclipse\plugins -Dee.file=c:\jdk1.5.0_10\bin\j2se1-5.ee</code>.
+
 
+
The required bundles are used as a pool when resolving required bunldes for test bunldes 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>
+
 
+
The tests can be run individually, or you can run them all from the APIToolsTestSuite class.
+
 
+
<h4>Bugs and Enhancement Requests</h4>
+
 
+
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=%5Bapi+tooling%5D&classification=Eclipse&product=PDE&component=Incubators&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=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 the '''Eclipse PDE Incubators''' component of Bugzilla and have '''[api tooling]''' included in the title.
+
 
+
== 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.
+
 
+
<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 help the user fix such problems.
+
 
+
<h4>API Usage Reporting (Batch Mode)</h4>
+
 
+
<h4>API Usage Reporting (IDE Mode)</h4>
+
 
+
<h4>API Usage Searching (IDE Mode)</h4>
+
 
+
<h4>Building API Components & Profies</h4>
+
 
+
<h4>Extensible Javadoc Tags, API Visibilities & Restrictions</h4>
+
Clients can provide their own javadoc tags via the '''apiJavadocTags''' extension point.
+
 
+
Extensible javadoc tags allow clients to specify what kind of Java member the tag will apply to. The Java members supported in extensible javadoc tags are:
+
 
+
# Interfaces
+
# Classes / Enums
+
# Methods
+
# Fields
+
 
+
The platform provides a default set of tags. The tags and the Java members they apply to are:
+
 
+
# '''@noimplement''' which applies to interfaces
+
# '''@noextend''' which applies to classes and methods
+
# '''@noreference''' which applies to classes, methods and fields
+
# '''@noinstantiate''' which applies to classes
+
 
+
== Links ==
+
  
[http://wiki.eclipse.org/ApiTools_Architecture API Tooling Architecture] - High level description of the tooling's architecture
+
[[PDE/API_Tools/Javadoc_Tags|Javadoc Tags]] - Description of the Javadoc tags supported by API Tools ad what they mean.
  
[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 12:03, 15 May 2013

API Tools
Website
Download
Community
Mailing ListForumsIRCmattermost
Issues
OpenHelp WantedBug Day
Contribute
Browse Source

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

Javadoc Tags - Description of the Javadoc tags supported by API Tools ad what they mean.

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.

Back to the top