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.