| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2008, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/> |
| <meta http-equiv="Content-Style-Type" content="text/css"/> |
| <link rel="stylesheet" href="../../../apache_style.css" type="text/css"/> |
| <title>API Tools Analysis Ant Task</title> |
| <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"> </script> |
| </head> |
| <body> |
| <h1> API Analysis Ant Task </h1> |
| <h2>Purpose</h2> |
| <p>This task runs a complete API analysis of an API profile relative to a baseline - including API use, binary compatibility, and bundle version number validation. The profile is the current state of a product under development. The profile is compared to an API baseline for binary compatibility (usually the previous release of a product). </p> |
| <p>The analysis does not include @since tag validation as all verification is performed on binary class files (source is not analyzed). </p> |
| |
| <h2>Usage</h2> |
| <h3>Description</h3> |
| <p>The name of the Ant task is: <code>apitooling.analysis</code>. To be used, the jar file <code>apitooling-ant.jar</code> has to be on the Ant |
| classpath.</p> |
| <div style="text-align: left;"> |
| <pre style="margin-left: 40px"> |
| <b><font color="#0000ff"><apitooling.analysis |
| baseline=<font color="#008000">"..."</font> |
| profile=<font color="#008000">"..."</font> |
| report=<font color="#008000">"..."</font> |
| filters=<font color="#008000">"..."</font> |
| excludelist=<font color="#008000">"..."</font> |
| includelist=<font color="#008000">"..."</font> |
| preferences=<font color="#008000">"..."</font> |
| debug=<font color="#008000">"..."</font> |
| eefile=<font color="#008000">"..."</font> |
| /></font></b> |
| </pre> |
| </div> |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">baseline</td> |
| <td valign="top">This attribute specifies the location of the reference baseline. |
| <br/><br/>It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the |
| directory is which you can find the Eclipse executable. |
| <br/><br/>The location is specified using an absolute path. |
| </td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">profile</td> |
| <td valign="top">This attribute specifies the location of the current product or profile that you want to compare against the reference baseline. |
| <br/><br/> |
| It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the |
| directory is which you can find the Eclipse executable. |
| <br/><br/>The location is specified using an absolute path. |
| </td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">report</td> |
| <td valign="top">Set the output location where the reports will be generated. |
| <br/><br/> |
| Once the task is completed, reports are available in this directory using a structure similar to the filter root. A sub-folder is created |
| for each component that has problems to be reported. Each sub-folder contains a file called "report.xml". |
| <br/><br/>A special folder called "allNonApiBundles" is also created in this folder which also contains a file called "report.xml". |
| This file lists all the bundles that are not using the API Tools nature. |
| <br/><br/>There is also a "counts.xml" file created in the report directory that contains a summary of the problems found. |
| <br/><br/>The location is specified using an absolute path. |
| </td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">filters</td> |
| <td valign="top">Set the root directory of API filters to use during the analysis. |
| <br/><br/> |
| The argument is the root directory of the .api_filters files that should be used to filter potential problems created by |
| the API Tools analysis. |
| <br/>The root is specified using an absolute path. |
| <br/>The root needs to contain the following structure: |
| <pre> |
| root |
| | |
| +-- component name (i.e. org.eclipse.jface) |
| | |
| +--- .api_filters |
| </pre> |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">excludelist</td> |
| <td valign="top">Set the exclude list location. |
| <br/><br/>The exclude list location specifies a text file listing bundles to be excluded from the analysis. |
| By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to |
| selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, |
| all bundles are included), and the exclude list is then applied. |
| Each line of the file specifies one of: |
| <ul> |
| <li>a specific bundle name</li> |
| <li>a regular expression to match against bundle names (lines being with "R:")</li> |
| <li>a comment (lines being with '#')</li> |
| </ul> |
| <br/>The location is specified using an absolute path. |
| <br/>Following is an example exclude list: |
| <pre> |
| # DOC BUNDLES |
| org.eclipse.jdt.doc.isv |
| org.eclipse.jdt.doc.user |
| org.eclipse.pde.doc.user |
| org.eclipse.platform.doc.isv |
| org.eclipse.platform.doc.user |
| # NON-ECLIPSE BUNDLES |
| com.ibm.icu |
| com.jcraft.jsch |
| R:javax\..* |
| ... |
| </pre> |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">includelist</td> |
| <td valign="top">Set the include list location. |
| <br/><br/>The include list location specifies a text file listing bundles to be included in the analysis. |
| By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to |
| selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, |
| all bundles are included), and the exclude list is then applied. |
| Each line of the file specifies one of: |
| <ul> |
| <li>a specific bundle name</li> |
| <li>a regular expression to match against bundle names (lines being with "R:")</li> |
| <li>a comment (lines being with '#')</li> |
| </ul> |
| <br/>The location is specified using an absolute path. |
| <br/>Following is an example include list: |
| <pre> |
| # DOC BUNDLES |
| org.eclipse.jdt.doc.isv |
| org.eclipse.jdt.doc.user |
| org.eclipse.pde.doc.user |
| R:org.eclipse.platform.doc.* |
| # NON-ECLIPSE BUNDLES |
| com.ibm.icu |
| com.jcraft.jsch |
| R:javax\..* |
| ... |
| </pre> |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">preferences</td> |
| <td valign="top">Set the preferences for the task. |
| <br/><br/> |
| The preferences are used to configure problem severities. Problem severities have three possible values: Ignore, Warning, or Error. The set of problems detected is defined by corresponding problem preference keys in API tools. |
| <br/>The location is specified using an absolute path. If the given location doesn't exist, the preferences won't be set. |
| <br/> |
| Lines starting with '#' are ignored. The format of the preferences file looks like this: |
| <pre> |
| #Thu Nov 20 17:35:06 EST 2008 |
| ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore |
| ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore |
| ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore |
| ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore |
| ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning |
| API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore |
| API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore |
| CLASS_ELEMENT_TYPE_ADDED_METHOD=Error |
| CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore |
| CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore |
| CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore |
| ... |
| </pre> |
| The keys can be found in org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes. |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">debug</td> |
| <td valign="top">Set the debug value. |
| <br/><br/>The possible values are: <code>true</code>, <code>false</code> |
| <br/>Default is <code>false</code>. |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">eefile</td> |
| <td valign="top">Set the execution environment file to use. |
| <br/><br/>By default, an execution environment file corresponding to a JavaSE-1.6 execution environment is used. |
| <br/><br/>The format of the file is described in this <a href="http://wiki.eclipse.org/index.php/Execution_Environment_Descriptions" target="blank">wiki page</a>. |
| <br/><br/>The file is specified using an absolute path. |
| </td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| |
| <h3>Examples</h3> |
| |
| <pre> |
| <b><font color="#0000ff"><apitooling.analysis |
| baseline=<font color="#008000">"D:\eclipse\3.4.1\eclipse"</font> |
| profile=<font color="#008000">"D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"</font> |
| report=<font color="#008000">"D:\reports\xml"</font> |
| filters=<font color="#008000">"D:\filters"</font> |
| excludelist=<font color="#008000">"D:\exclude_list_external.txt"</font> |
| preferences=<font color="#008000">"D:\tests_api\org.eclipse.pde.api.tools.prefs"</font> |
| debug=<font color="#008000">"true"</font> |
| /></font></b> |
| </pre> |
| <p>This will run the task creating <code>report.xml</code> files inside the folder <code>D:\reports\xml</code>. |
| It will use the exclude list and the <code>.api_filter</code> files located in <code>D:\exclude_list_external.txt</code> and |
| <code>D:\filters</code> to reduce the number of problems to report.</p> |
| <p>Problem severities will be generated as specified by <code>D:\tests_api\org.eclipse.pde.api.tools.prefs</code>.</p> |
| <p>Since debug is enabled, some debug tracing will show up in the Ant console.</p> |
| |
| <p><img src="../../../images/ngrelr.png" alt="Related reference" border="0"/></p> |
| <p><a href="apifreeze-ant-task.htm">API Freeze Ant Task</a> |
| <br/><a href="filegeneration-ant-task.htm">File Generation Ant Task</a> |
| <br/><a href="apiuse-ant-task.htm">API Use Ant Task</a> |
| <br/><a href="analysis-reportconversion-ant-task.htm">Analysis Report Conversion Ant Task</a> |
| <br/><a href="apifreeze-reportconversion-ant-task.htm">API Freeze Report Conversion Ant Task</a> |
| <br/><a href="apiuse-reportconversion-ant-task.htm">API Use Report Conversion Ant Task</a> |
| <br/><a href="deprecation-ant-task.htm">API Deprecation Ant Task</a> |
| <br/><a href="deprecation-reportconversion-ant-task.htm">API Deprecation Report Conversion Ant Task</a> |
| </p> |
| </body> |
| </html> |
