Thursday, February 3, 2011

Self help with API Tooling Reports (Part I): Generating the API Use report

API Tools is part of Plug-in Development Environment. It provides tooling support for tracking and managing your APIs and dependencies and can generate various reports. The Eclipse help discusses here about how to set it up.

What we will discuss here is how to generate various reports and making sense out of them.

Generating the API Use report

API Use report is the simplest of the report. It tells what APIs are referenced (used) by a given profile. A profile can be an API Baseline, a Target Definition or a directory containing an Eclipse product or just some plug-ins.

PDE provides an External Tools configuration wizard to run this report. The wizards can be launched from the Run menu -> External Tools -> External Tools Configurations...

This will open the External Tools Configurations wizard. Select 'API Use Report' from the left pane and press the 'New' launch configuration button.

The snapshot below shows the settings for an RCP product.

You can choose an API Baseline, a Target Definition or a directory to run the report on. The report is a set of XML files. To make it human readable, there is an option to generate HTML report out of any existing API Use report.

Search For
Here you control what to look out for. The 'References to' takes a regular expression which will be used to match the APIs source. In this example the report will lookout only for the API originating out of bundles whose name starts with 'org.eclipse.'
API references: The APIs used in your product
Internal references: Marks the non-API - one coming from internal packages.
Illegal API Use: Usage that breaks the restrictions marked using JavaDoc tags.

Search In
This controls the search scope. The APIs references will be searched only in the plug-ins that match the regex provided here,

This is self explanatory. The report will be churned out as a hierarchy of.folders and XMLs in the output location. And if checked for 'Create HTML reports', they will be generated too. The report is saved inside the folder 'XML' in the report output location. While the HTML reports are inside the folder named 'HTML'.