| <?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> |
| A binary version of the Eclipse API scanner is available here: |
| </p> |
| <p> |
| <a href="http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/apiscanner.zip">Download the Eclipse API scanner</a>. |
| </p> |
| |
| <p> |
| The source of the Eclipse API scanner is also available in |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/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> |
| |
| <h3>Running the Eclipse API scanner from the command line environment</h3> |
| <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> |
| |
| <h3>Running the Eclipse API scanner within Eclipse</h3> |
| <p> |
| The Eclipse API scanner is also available as two Eclipse plug-ins. Therefore, you can overlay |
| them on top of an Eclipse driver and use them to check API violations as you develop your |
| product/plug-ins. To get these plug-ins, go to: |
| </p> |
| <p> |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/?cvsroot=WebTools_Project">http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/?cvsroot=WebTools_Project</a> |
| </p> |
| <p> |
| and 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. They provide an |
| editor for editing component.xml files. |
| </p> |
| <p><img src="./figure01.gif"/></p> |
| <p> |
| They will also scan the plug-ins in your workspace and generate API violations in the problems |
| views. The figure below shows a plug-in in my workspace called <b>org.eclipse.sample</b>. |
| I have also created a component.xml file for this plugin. |
| </p> |
| <p><img src="./figure02.gif"/></p> |
| <p> |
| In the next figure, I have added a reference to one of the Eclipse internal class. The |
| Eclipse API scanner will flag this as an API violation and display it in the problems |
| view. |
| </p> |
| <p><img src="./figure03.gif"/></p> |
| <p> |
| You can find some sample component.xml files |
| <a href="http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/components/?cvsroot=WebTools_Project">here</a>. |
| </p> |
| <p> |
| <b>Disclaimer:</b> these sample component.xml files are provided as an example only. They |
| <b>DO NOT</b> reflect the actual APIs provided by the Eclipse projects. |
| </p> |
| |
| </body> |
| </html> |
