# API Analysis Command Line Application

## Purpose

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).

## Usage

### Description

The name of the application task is: `org.eclipse.pde.api.tools.apiAnalyzer`. To be used, the bundle file `org.eclipse.pde.api.tools` in version superior or equals to `1.1.800` has to be installed in the Eclipse Platform instance. Once the Platform is properly configured, the application can be started with commands like:

`eclipse -application org.eclipse.pde.api.tools -project /path/to/project -depednencies /path/to/list/of/dependencies.txt -baseline default -failOnError`

### Application Arguments

Attribute | Description | Required
project | 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 `.project`, `MANIFEST.MF`... files. | Yes
dependencyList | This attribute specifies a path to a file containing a list of depenencies that will be used as default target platform. 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. | Yes
baseline | This attribute specifies the location of the reference baseline. It can be the absolute path to a directory or a to a `.target` file, or `default`. If `default`, the current platform running the API Tools will be used as baseline. | No. If omitted, similar to `default`
failOnError | Report API compliance errors as a failure (non-`0` exit code) | No

### Examples

In a Tycho-enabled `pom.xml` file:

    <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>

This will run API analysis and fail the build in case an error is found.

### Related references

API Analysis Ant Task