API Tooling From The Commandline

API tools has a very nice set of tools for analyzing API, creating .api_description files and scanning for API / internal use to mention but a few tasks. Using these tools currently requires you to make the apitooling-ant jar file available in an Eclipse environment or have them as part of a build process.

We though it would be nice to be able to run the tools from the command line as well. With that in mind we have provided a generalized Ant build file that can be used to do just that. The build file in question is available from CVS in the org.eclipse.pde.api.tools project in the scripts folder. Also available in the scripts folder is a properties which is needed to map the task names to the task classes that provide them.

The build file is fairly simple and has a plethora of comments to help you out. It performs 3 main tasks:
1. it builds the Ant classpath based on an Eclipse install
2. it extracts the apitooling-ant.jar from the API tools project jar
3. it runs whichever task you specifiy in the 'run' target

Here is a sample use of the build file for running the API use scans from the command line:

<project name="apiusetask" basedir="." default="run">
    <property name="scope" value="/eclipse/eclipse_3.4.2/">
    <property name="baseline" value="/eclipse/eclipse.tar.gz">
    <property name="xml.report.loc" value="/eclipse/apiuse-commandline/xml">
    <property name="html.report.loc" value="/eclipse/apiuse-commandline/html">
    <property name="exclude.list.loc" value="/eclipse/exclude.txt">
    <property name="eclipse.install.dir" value="/eclipse/eclipse/plugins">
    <property name="eclipse.lib.dir" value="/eclipse/lib">
    <property name="apiuse.task.props" value="/eclipse/lib/apiuse_tasks.properties">
   
    <target name="init" depends="extract-apitoolingjar">
        <taskdef file="${apiuse.task.props}">
            <classpath>
                <fileset dir="${eclipse.install.dir}">
                    <include name="*.jar">
                </fileset>
                <fileset dir="${eclipse.lib.dir}">
                    <include name="*.jar">
                </fileset>
            </classpath>
        </taskdef>
    </target>
    <target name="extract-apitoolingjar">
        <unjar overwrite="true" dest="${eclipse.lib.dir}">
            <fileset dir="${eclipse.install.dir}">
                <include name="org.eclipse.pde.api.tools_*.jar">
            </fileset>
            <patternset>
                <include name="**/*.jar">
            </patternset>
        </unjar>
        <move file="${eclipse.lib.dir}/lib/apitooling-ant.jar"
                     overwrite="true"     
                     todir="${eclipse.lib.dir}"/>
        <delete dir="${eclipse.lib.dir}/lib/" includeemptydirs="true">
    </target>
    <target name="run" depends="init">
        <apiuse
            baseline="${baseline}"
            scope="${scope}"
            report="${xml.report.loc}"
            excludelist="${exclude.list.loc}"
            considerinternal="true"
            considerapi="true"
            includenonapiprojects="true"
            debug="true"
        />
        <apiuse_reportconversion
            xmlfiles="${xml.report.loc}"
            htmlfiles="${html.report.loc}"
            debug="true"
        />
    </target>
</project>

To actually run the given build file you must have Ant available on the command line (obviously) and then run the following:

  root%>ant -buildfile <build file name>