docs/org.eclipse.wst.doc.isv/html/eclipse_scanner.html - webtools/webtools.releng - Gitiles

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <meta
   http-equiv="Content-Type"
   content="text/html; charset=iso-8859-1">

 <title>Eclipse API Scanner</title>

 <link
   rel="stylesheet"
   type="text/css"
   href="sources/formate.css">
 </head>
 <body>
 <p class="ueberschrift">Introduction</p>
 <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="scanner_req.html">here</a>, and the design document <a
   href="scanner_doc.html">here</a>.</p>
 <p class="ueberschrift">Downloading and running the Eclipse API scanner</p>
 <p>A binary version of the Eclipse API scanner is available here:</p>
 <a
   href="http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/apiscanner.zip">Download
 the Eclipse API scanner</a>
 .
 <p>The source of the Eclipse API scanner is also available in CVS: <i>(http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/?cvsroot=WebTools_Project)</i>.</p>
 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>Running the Eclipse API scanner from the command line environment</p>
 <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="scanner_doc.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:</p>
 <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>
 <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:</p>
 <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></p>
 <p>Running the Eclipse API scanner within Eclipse</p>
 <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="sources/figure01.gif"
   alt=""></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="sources/figure02.gif"
   alt=""></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="sources/figure03.gif"
   alt=""></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">
 http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/components/?cvsroot=WebTools_Project</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>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<meta
	http-equiv="Content-Type"
	content="text/html; charset=iso-8859-1">

	<title>Eclipse API Scanner</title>

	<link
	rel="stylesheet"
	type="text/css"
	href="sources/formate.css">
	</head>
	<body>
	<p class="ueberschrift">Introduction</p>
	<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="scanner_req.html">here</a>, and the design document <a
	href="scanner_doc.html">here</a>.</p>
	<p class="ueberschrift">Downloading and running the Eclipse API scanner</p>
	<p>A binary version of the Eclipse API scanner is available here:</p>
	<a
	href="http://www.eclipse.org/downloads/download.php?file=/webtools/downloads/apiscanner.zip">Download
	the Eclipse API scanner</a>
	.
	<p>The source of the Eclipse API scanner is also available in CVS: <i>(http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/?cvsroot=WebTools_Project)</i>.</p>
	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>Running the Eclipse API scanner from the command line environment</p>
	<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="scanner_doc.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:</p>
	<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>
	<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:</p>
	<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></p>
	<p>Running the Eclipse API scanner within Eclipse</p>
	<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="sources/figure01.gif"
	alt=""></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="sources/figure02.gif"
	alt=""></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="sources/figure03.gif"
	alt=""></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">
	http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.wtp.releng/apitools/components/?cvsroot=WebTools_Project</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>