Difference between revisions of "PDE/API Tools/Resources"

From Eclipsepedia

< PDE‎ | API Tools
Jump to: navigation, search
(New page: == Articles == There are currently no articles. == Examples == === Running an API use scan (IDE) === In the IDE API use scans can be run from the External tools dialog. The benefits of...)
 
(Examples)
Line 3: Line 3:
 
There are currently no articles.
 
There are currently no articles.
  
== Examples ==
+
= Examples =
  
=== Running an API use scan (IDE) ===
+
== Running an API use scan (IDE) ==
  
In the IDE API use scans can be run from the External tools dialog. The benefits of providing the scanning as an external tools are many, the foremost being 1. you can create as many different configurations as you want for scanning different distributions of your products and 2. each configuration can have its own persisted settings.
+
In the IDE API use scans can be run from the External tools dialog. The benefits of providing the scanning as an external tool are many, the foremost being: 1. you can create as many different configurations as you want for scanning different distributions of your products and 2. each configuration can have its own persisted settings.
  
=== Running an API use scan (commandline) ===
+
[[Image:Usescan-ext-dialog.png|The external tools dialog showing a use scan configuration]]
 +
 
 +
=== Creating a new scan configuration ===
 +
 
 +
To create a new use scan configuration simply double-click the API Use Report configuration type.
 +
 
 +
=== Configuring the new use scan ===
 +
 
 +
There are a few items that are required for a use scan to run:
 +
#You must select what you want to analyze, which can be either an API baseline, target definition or a directory of bundles. You can only select one option, with each option allowing you to configure it. I.e. you can go to the API baselines preference page to edit existing baselines if you select analyzing an API baseline.
 +
#You must specify where the scan results will be outputted. The UI allows you to browse for a desired location or you can enter it in manually. If the given report location does not exist it will be created for you.
 +
 
 +
There are more options that can be configured but are not required for a scan to complete, they include:
 +
*'''Search for > References to''' - this field allows you to specify the name (or matching RegEx) of the bundle that you want to see references to. Consider the following example: <pre>org\.eclipse.*</pre> In this example we are saying that we want to see all references to any bundle that starts with the name <code>org.eclipse.</code>.
 +
*'''Search for > API references''' - this option allows you to scan for API references.
 +
*'''Search for > Internal references''' - this option allows you to scan for internal references.
 +
*'''Search in > Bundles matching''' - this field allows you to specify the name (or matching RegEx) of the bundle(s) that you want to scan for references from i.e. a search scope. Consider the following example: <pre>.*</pre> In this example we are saying that we want to search in all bundles whose name matches any character sequence. The same effect can be achieved leaving the field blank. Consider another example:<pre>com\.test.*</pre> In this example only bundles whose name starts with <code>com.test</code> will be scanned for references.
 +
*'''Reporting > Clean report directory before reporting new results''' - this option allows you to clear out an existing report location prior to the scan reporting any results. It should be noted that this option will completely remove the specified report directory if it exists, with all child directories being recursively removed as well.
 +
*'''Reporting > Create HTML reports''' - this option will convert all of the XML output into formatted HTML and place it in <code><report location>\html</code>
 +
*'''Reporting > Clean HTML report location''' - this option allows you to clear out an existing HTML location prior to creating new reports. It should be noted that this option will completely remove the specified HTML directory if it exists, with all child directories being recursively removed as well.
 +
*'''Reporting > Open report when search completes''' - opens the HTML report when searching has completed.
 +
 
 +
 
 +
== Running an API use scan (commandline) ==
  
 
From the commandline the only option available to run a use scan is to use Ant and our provided Ant task: ApiUseTask
 
From the commandline the only option available to run a use scan is to use Ant and our provided Ant task: ApiUseTask

Revision as of 14:15, 26 August 2009

Contents

Articles

There are currently no articles.

Examples

Running an API use scan (IDE)

In the IDE API use scans can be run from the External tools dialog. The benefits of providing the scanning as an external tool are many, the foremost being: 1. you can create as many different configurations as you want for scanning different distributions of your products and 2. each configuration can have its own persisted settings.

The external tools dialog showing a use scan configuration

Creating a new scan configuration

To create a new use scan configuration simply double-click the API Use Report configuration type.

Configuring the new use scan

There are a few items that are required for a use scan to run:

  1. You must select what you want to analyze, which can be either an API baseline, target definition or a directory of bundles. You can only select one option, with each option allowing you to configure it. I.e. you can go to the API baselines preference page to edit existing baselines if you select analyzing an API baseline.
  2. You must specify where the scan results will be outputted. The UI allows you to browse for a desired location or you can enter it in manually. If the given report location does not exist it will be created for you.

There are more options that can be configured but are not required for a scan to complete, they include:

  • Search for > References to - this field allows you to specify the name (or matching RegEx) of the bundle that you want to see references to. Consider the following example:
    org\.eclipse.*
    In this example we are saying that we want to see all references to any bundle that starts with the name org.eclipse..
  • Search for > API references - this option allows you to scan for API references.
  • Search for > Internal references - this option allows you to scan for internal references.
  • Search in > Bundles matching - this field allows you to specify the name (or matching RegEx) of the bundle(s) that you want to scan for references from i.e. a search scope. Consider the following example:
    .*
    In this example we are saying that we want to search in all bundles whose name matches any character sequence. The same effect can be achieved leaving the field blank. Consider another example:
    com\.test.*
    In this example only bundles whose name starts with com.test will be scanned for references.
  • Reporting > Clean report directory before reporting new results - this option allows you to clear out an existing report location prior to the scan reporting any results. It should be noted that this option will completely remove the specified report directory if it exists, with all child directories being recursively removed as well.
  • Reporting > Create HTML reports - this option will convert all of the XML output into formatted HTML and place it in <report location>\html
  • Reporting > Clean HTML report location - this option allows you to clear out an existing HTML location prior to creating new reports. It should be noted that this option will completely remove the specified HTML directory if it exists, with all child directories being recursively removed as well.
  • Reporting > Open report when search completes - opens the HTML report when searching has completed.


Running an API use scan (commandline)

From the commandline the only option available to run a use scan is to use Ant and our provided Ant task: ApiUseTask