| <?xml version="1.0" encoding="utf-8"?> |
| <?xml-stylesheet type="text/xsl" href="../../wtp.xsl"?> |
| <html> |
| <head> |
| <title>Eclipse API Scanner</title> |
| <meta name="root" content="../../.." /> |
| </head> |
| <body> |
| |
| <h1>Eclipse API Scanner</h1> |
| <em>Updated 2005-02-07</em> |
| |
| <h2>Introduction</h2> |
| <p> |
| This document summarizes the usage of the Eclipse API scanner. |
| The goal of the Eclipse API scanner is to identify any internal API references in |
| any Eclipse-based products. You can view the requirements document |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.wtp.releng/apitools/api-usage-checking.html?rev=HEAD&cvsroot=WebTools_Project&content-type=text/html">here</a>, and the design document |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.wtp.releng/apitools/api-usage-checking-design.html?rev=HEAD&cvsroot=WebTools_Project&content-type=text/html">here</a>. |
| </p> |
| <p></p> |
| |
| <h2>Downloading and running the Eclipse API scanner</h2> |
| <p> |
| You can get the latest version of the Eclipse API scanner |
| <a href="http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/wtp-apiscanner.zip">here</a>. |
| </p> |
| <p> |
| The previous version of the Eclipse API scanner is available |
| <a href="http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/apiscanner.zip">here</a>. |
| </p> |
| |
| <p> |
| The source of the Eclipse API scanner is also available in |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/releng.builder/tools/apitools/?cvsroot=WebTools_Project">CVS</a>. |
| Check out the |
| <b>org.eclipse.wtp.releng.tools.component.core</b> project and the |
| <b>org.eclipse.wtp.releng.tools.component.ui</b> project. |
| </p> |
| |
| <h2>Running the Eclipse API scanner within Eclipse</h2> |
| <p> |
| The Eclipse API scanner is available as two Eclipse plug-ins. Therefore, you can overlay |
| them on top of an Eclipse driver and use them to scan you APIs for violations, javadoc |
| coverage and etc. |
| <ol> |
| <li>Download the latest |
| <a href="http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/wtp-apiscanner.zip">Eclipse API scanner</a> |
| and unzip it on top of your Eclipse driver.</li> |
| <li>Start Eclipse.</li> |
| <li>Go to preference and make sure your target platform is correct.</li> |
| <li>Load your plug-ins into the workspace.</li> |
| <li>Right click on a component.xml file > API > Scan for API violation. |
| It may take a few minutes when you run this action for the first time. This |
| is because the scanner needs to parse the APIs for your target platform. |
| Subsequence runs should be faster. Note that if you change your target |
| platform, you will get the same delay again.</li> |
| <li>After the action completes, the API violation report opens in a browser. |
| This report shows you all the API violations for plug-ins in the selected |
| compoennt. |
| <p><img src="./figure01.gif"/></p> |
| </li> |
| <li>Right click on the same component.xml file again > API > Scan |
| for Missing javadoc.</li> |
| <li>After the action completes, the Javadoc coverage report opens in a browser. |
| This report shows you plug-ins that have missing javadoc in them. |
| <p><img src="./figure02.gif"/></p> |
| </li> |
| |
| <!-- |
| <li>To generate a unit test coverage report, you need to download the |
| TPTP runtime and Agent Controller. Both of them are available from |
| <a href="http://www.eclipse.org/tptp/home/downloads/downloads.html">TPTP's download page</a>. |
| The following are links to the TPTP 4.0.0 runtime and Agent Controller: |
| <p> |
| http://download.eclipse.org/tptp/4.0.0/TPTP-4.0.0-200507181519/tptp.runtime-TPTP-4.0.0-200507181519.zip |
| http://download.eclipse.org/tptp/4.0.0/TPTP-4.0.0-200507181519/tptpdc.win_ia32-TPTP-4.0.0-200507181519.zip |
| </p> |
| </li> |
| <li>Unzip the TPTP runtime on top of your Eclipse driver.</li> |
| <li>Unzip the TPTP Agent Controller to somewhere on your file system.</li> |
| <li>Configure the TPTP Agent Controller by running: |
| <i><Agent Controller directory>/bin/SetConfig.bat</i> |
| <li> |
| <li>Start the TPTP Agent Controller by running: |
| <i><Agent Controller directory>/bin/RAServer.exe</i> |
| </li> |
| <li>Restart Eclipse.</li> |
| <li>When Eclipse is started. Switch to the Java perspective.</li> |
| <li>Open your JUnit testcase in the Java editor.<li> |
| <li>In the workbench toolbar, click the profile icon > select Profile... |
| <p><img src="./figure03.gif"/></p> |
| </li> |
| <li>Select JUnit Plug-in Test > New</li> |
| <li>Switch to the Profiling tab. Click on the Destination inner tab. |
| Check the "Send profiling data to a file" checkbox. Browse or enter a file. |
| Note that the generated file is a zip file, so your probably want to name |
| your file something .zip.</li> |
| <li>Click Profile to start profiling your JUnit testcase.</li> |
| <li>After your JUnit testcase completes, unzip the generated zip file. |
| You should see a .xml file in it.</li> |
| --> |
| |
| </ol> |
| </p> |
| |
| <!-- |
| <h2>Running the Eclipse API scanner from the command line</h2> |
| <p> |
| Before running the Eclipse API scanner, you should get yourself familiar with what is a |
| component. For a definition of component, visit the |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/org.eclipse.wtp.releng/apitools/api-usage-checking-design.html?rev=HEAD&cvsroot=WebTools_Project&content-type=text/html">design document</a>. |
| To begin, have your Eclipse components/plug-ins and your component.xml files ready. |
| The Eclipse API scanner will scan all the API references in each component and check whether |
| they are internal API references. An API violation report will be generated for each component. |
| To generate the API violation reports, run: |
| <pre> |
| genViolation.bat -eclipseDir <eclipseDir> -compXMLDir <compXMLDir> -compRefDir <compRefDir> -compVioDir <compVioDir> -genHTML -debug |
| </pre> |
| where: |
| <ul> |
| <li><b>eclipseDir</b> - a space separated list of directories containing the plug-ins |
| for your product. These directories do not have to include the base Eclipse plug-ins |
| (ex: org.eclipse.jdt.core). You only need the plug-ins that you want to generate API |
| violation reports for.</li> |
| <li><b>compXMLDir</b> - a space separated list of directories containing component.xml |
| files for your product. The Eclipse API scanner will generate an API violation report for each component.xml |
| found in these directories. So, if you do not want to generate violation reports for the |
| Eclipse components (ex: org.eclipse.jdt.core), do not include their component.xml files here.</li> |
| <li><b>compRefDir</b> - a space separated list of directories containing component.xml |
| files that your product/components depend on. For example, the component.xml files |
| for org.eclipse.jdt.core goes here.</li> |
| <li><b>compVioDir</b> - the output directory of the API violation reports.</li> |
| <li><b>genHTML</b> - generates the API violation report in HTML (default is XML format).</li> |
| <li><b>debug</b> - generates debug information (ex: line numbers).</li> |
| </ul> |
| For a list of all the options available, simply run genViolation.bat without any arguments. |
| Note that genViolation.bat uses relative paths. Therefore, if you want to run it |
| out-of-the-box, we must "cd" to genViolation.bat's directory before running it. Other |
| options include: |
| <ul> |
| <li><b>include</b> - a space separated list of package names to be included in the scan.</li> |
| <li><b>exclude</b> - a space separated list of package names to be excluded in the scan. |
| For example, if you specify "java.lang. sun.", then the API violation report will not include |
| internal API references to those two packages.</li> |
| <li><b>genAPI</b> - generates a component-api.xml file per component. This file lists all |
| the public APIs that a component has.</li> |
| <li><b>genUsage</b> - generates a component-use.xml file per component. This file lists all |
| the API references that a component has.</li> |
| <li><b>classRefOnly</b> - treats all API references as class reference. By default, |
| the Eclipse API scanner will categorize API references into different categories such |
| as class references, method references, field references and etc. By specifying this |
| option, all API references are consider class references. This speeds up the scanning |
| process.</li> |
| </ul> |
| </p> |
| <p> |
| To get you started more quickly, you can use <b>genComponent.bat</b> to generate a component.xml |
| file per plugin. Any packages with the word "internal" in it will be excluded from the generated |
| component.xml file. To generate default component.xml files, run: |
| <pre> |
| genComponent.bat -eclipseDir <eclipseDir> -compXMLDir <compXMLDir> |
| </pre> |
| where: |
| <ul> |
| <li><b>eclipseDir</b> - a space separated list of directories containing the plug-ins |
| for your product. Again, do not include base Eclipse plug-ins in here.</li> |
| <li><b>compXMLDir</b> - the output directory of the generated component.xml files.</li> |
| </ul> |
| </p> |
| --> |
| |
| </body> |
| </html> |