development/apiscanner/apiscanner.xml - www.eclipse.org/webtools - Git at Google

 <?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&amp;cvsroot=WebTools_Project&amp;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&amp;cvsroot=WebTools_Project&amp;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 &gt; API &gt; 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 &gt; API &gt; 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>&lt;Agent Controller directory&gt;/bin/SetConfig.bat</i>
 <li>
 <li>Start the TPTP Agent Controller by running:
 <i>&lt;Agent Controller directory&gt;/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 &gt; select Profile...
 <p><img src="./figure03.gif"/></p>
 </li>
 <li>Select JUnit Plug-in Test &gt; 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&amp;cvsroot=WebTools_Project&amp;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 &lt;eclipseDir&gt; -compXMLDir &lt;compXMLDir&gt; -compRefDir &lt;compRefDir&gt; -compVioDir &lt;compVioDir&gt; -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 &lt;eclipseDir&gt; -compXMLDir &lt;compXMLDir&gt;
 </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>
	<?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>