Difference between revisions of "PDE/API Tools"

Revision as of 12:46, 9 November 2007

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.

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. More information on the architecture of API tooling can be found here.

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

1. Add the CVS server to your repositories view (:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse).
2. Expand the server and "HEAD" elements in the tree.
3. Navigate to the "pde-incubator/api-tooling/plugins" folder.
4. Check out the the org.eclipse.pde.api.tools.releng project.
5. In your Package Explorer, select the projectSet.psf file in the root folder of the "org.eclipse.api.tools.releng project".
6. Select File > Import. On the first page of the import wizard select Team > Team Project Set and press "Next".
7. 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.

Rununing the JUnit Tests

The JUnit tests run as standard JUnit tests (i.e. not JUnit plug-in tests). However, the tests require two VM arguments:

1. -DrequiredBundles={path to directory containing standard Eclipse plug-ins}
2. -Dee.file={path to an .ee file}

For example, -DrequiredBundles=c:\sdk20071031-0010\eclipse\plugins -Dee.file=c:\jdk1.5.0_10\bin\j2se1-5.ee.

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:

-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

The tests can be run individually, or you can run them all from the APIToolsTestSuite class.

Bugs and Enhancement Requests

The API tooling project uses Bugzilla for tracking bugs and enhancement requests. 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 caes API tooling is intended to support.

Binary Compatibility Reporting (Batch Mode)

Two versions of the same API profile are compared for binary compatibility. An html report is produced summarizing any incompatibilities. The comparison tool can be invoked from the command line as a stand alone Java application.

Binary Compatibility Reporting (IDE Mode)

API Usage Reporting (Batch Mode)

API Usage Reporting (IDE Mode)

API Usage Searching (IDE Mode)

Building API Components & Profies

Links

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

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

Resources

Eclipse Bugzilla - Eclipse bug tracking database.

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

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