Bug 547206 - Make API Tools comparator available as Application
Change-Id: If113cccd87dffb647ff56062da46c3da9eb26a9a
Signed-off-by: Mickael Istria <mistria@redhat.com>
diff --git a/bundles/org.eclipse.pde.doc.user/reference/api-tooling/applications/analysis-application.htm b/bundles/org.eclipse.pde.doc.user/reference/api-tooling/applications/analysis-application.htm
new file mode 100644
index 0000000..e788fc2
--- /dev/null
+++ b/bundles/org.eclipse.pde.doc.user/reference/api-tooling/applications/analysis-application.htm
@@ -0,0 +1,140 @@
+<!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) Red Hat Inc. and others 2019. 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 application</title>
+<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"> </script>
+</head>
+<body>
+<h1> API Analysis Command Line Application</h1>
+<h2>Purpose</h2>
+<p>This application runs a complete API analysis of a Plugin project relative to a baseline - including API use, binary compatibility, and bundle version number validation. The profile is compared to an API baseline for binary compatibility (usually the previous release of a product). </p>
+
+<h2>Usage</h2>
+<h3>Description</h3>
+<p>The name of the application task is: <code>org.eclipse.pde.api.tools.apiAnalyzer</code>. To be used, the bundle file <code>org.eclipse.pde.api.tools</code> in version superior or equals to <code>1.1.800</code> has to be installed in the Eclipse Platform instance. Once the Platform is properly configured,
+the application can be started with commands like:</p>
+<p><code>eclipse -application org.eclipse.pde.api.tools -project /path/to/project -depednencies /path/to/list/of/dependencies.txt -baseline default -failOnError</code></p>
+<h3>Application Arguments</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">project</td>
+<td valign="top">This attribute specifies the location of the project to analyze. The project must be the a valid Eclipse Plugin project,
+that is a project with typical <code>.project</code>, <code>MANIFEST.MF</code>... files.
+</td>
+<td align="center" valign="top">Yes</td>
+</tr>
+<tr>
+<td valign="top">dependencyList</td>
+<td valign="top">This attribute specifies a path to a file containing a list of depenencies that will be used as default target platform.
+<br/><br/>
+The file must list the absolute path of dependencies (as jar files), either separated by new lines or colon (:). Tokens that are not
+absolute path to jar files are ignored.
+</td>
+<td align="center" valign="top">Yes</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 the absolute path to a directory or a to a <code>.target</code> file, or <code>default</code>.
+If <code>default</code>, the current platform running the API Tools will be used as baseline.
+</td>
+<td align="center" valign="top">No. If omitted, similar to <code>default</code></td>
+</tr>
+<tr>
+<td valign="top">failOnError</td>
+<td valign="top">Report API compliance errors as a failure (non-<code>0</code> exit code)</td>
+<td align="center" valign="top">No</td>
+</tr>
+</table>
+
+<h3>Examples</h3>
+
+In a Tycho-enabled <code>pom.xml</code> file:
+<pre>
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ [...]
+ <plugin>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>list-dependencies</id>
+ <goals>
+ <goal>list</goal>
+ </goals>
+ <phase>verify</phase>
+ <configuration>
+ <outputAbsoluteArtifactFilename>true</outputAbsoluteArtifactFilename>
+ <outputScope>false</outputScope>
+ <outputFile>${project.build.directory}/dependencies.txt</outputFile>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <groupId>org.eclipse.tycho.extras</groupId>
+ <artifactId>tycho-eclipserun-plugin</artifactId>
+ <version>1.4.0</version>
+ <executions>
+ <execution>
+ <id>api-analysis</id>
+ <goals>
+ <goal>eclipse-run</goal>
+ </goals>
+ <phase>verify</phase>
+ <configuration>
+ <applicationsArgs>
+ <!-- need to set workspace to a dir that's not a child of the project -->
+ <arg>-data</arg>
+ <args>${project.basedir}/../target/${project.artifactId}-apiAnalyzer-workspace</args>
+ <args>-application</args>
+ <args>org.eclipse.pde.api.tools.apiAnalysis</args>
+ <args>-project</args>
+ <args>${project.basedir}</args>
+ <args>-baseline</args>
+ <args>default</args>
+ <args>-dependencyList</args>
+ <args>${project.build.directory}/dependencies.txt</args>
+ <args>-failOnError</args>
+ </applicationsArgs>
+ <repositories>
+ <repository>
+ <id>eclipse-4.12</id>
+ <layout>p2</layout>
+ <url>https://download.eclipse.org/eclipse/updates/4.12-I-builds/</url>
+ </repository>
+ </repositories>
+ <dependencies>
+ <!-- This will constitute the default baseline -->
+ <dependency>
+ <artifactId>org.eclipse.sdk.ide</artifactId>
+ <type>p2-installable-unit</type>
+ </dependency>
+ </dependencies>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+</pre>
+<p>This will run API analysis and fail the build in case an error is found.</p>
+
+<h3 class="related">Related references</h3>
+<a href="../ant-tasks/analysis-ant-task.htm">API Analysis Ant Task</a>
+</body>
+</html>
diff --git a/bundles/org.eclipse.pde.doc.user/topics_Reference.xml b/bundles/org.eclipse.pde.doc.user/topics_Reference.xml
index 1efa568..b0aa7b9 100644
--- a/bundles/org.eclipse.pde.doc.user/topics_Reference.xml
+++ b/bundles/org.eclipse.pde.doc.user/topics_Reference.xml
@@ -17,36 +17,24 @@
<toc label="Reference">
<topic label="API Tools">
<topic label="API Tools Ant Tasks">
- <topic href="reference/api-tooling/ant-tasks/analysis-ant-task.htm" label="Analysis Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm" label="Analysis Report Conversion Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apifreeze-ant-task.htm" label="API Freeze Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm" label="API Freeze Report Conversion Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/deprecation-ant-task.htm" label="API Deprecation Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm" label="API Deprecation Report Conversion Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiuse-ant-task.htm" label="API Use Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Producer)">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiconsumeruse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Consumer)">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apimigration-ant-task.htm" label="API Use Migration Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm" label="API Use Migration Report Conversion Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/filegeneration-ant-task.htm" label="File Generation Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/compare-ant-task.htm" label="Compare Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-ant-task.htm" label="API Use Scan Problems Ant Task">
- </topic>
- <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-reportconversion-ant-task.htm" label="API Use Scan Problems Report Conversion Ant Task">
- </topic>
+ <topic href="reference/api-tooling/ant-tasks/analysis-ant-task.htm" label="Analysis Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/analysis-reportconversion-ant-task.htm" label="Analysis Report Conversion Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/apifreeze-ant-task.htm" label="API Freeze Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/apifreeze-reportconversion-ant-task.htm" label="API Freeze Report Conversion Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/deprecation-ant-task.htm" label="API Deprecation Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/deprecation-reportconversion-ant-task.htm" label="API Deprecation Report Conversion Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/apiuse-ant-task.htm" label="API Use Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/apiuse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Producer)"/>
+ <topic href="reference/api-tooling/ant-tasks/apiconsumeruse-reportconversion-ant-task.htm" label="API Use Report Conversion Task (Consumer)"/>
+ <topic href="reference/api-tooling/ant-tasks/apimigration-ant-task.htm" label="API Use Migration Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/apimigration-reportconversion-ant-task.htm" label="API Use Migration Report Conversion Task"/>
+ <topic href="reference/api-tooling/ant-tasks/filegeneration-ant-task.htm" label="File Generation Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/compare-ant-task.htm" label="Compare Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-ant-task.htm" label="API Use Scan Problems Ant Task"/>
+ <topic href="reference/api-tooling/ant-tasks/apiusescan-problems-reportconversion-ant-task.htm" label="API Use Scan Problems Report Conversion Ant Task"/>
+ </topic>
+ <topic label="API Tools Command Line Applications">
+ <topic href="reference/api-tooling/applications/analysis-application.html" label="API Analysis application"/>
</topic>
<topic href="reference/api-tooling/api_evolution.htm" label="API Evolution">
</topic>
