Defining the ANT Tasks

Before you can use the Animal Sniffer ANT Tasks you need to inform ANT about these tasks. There are several techniques for defining custom tasks in ANT. Our preferred technique (and the technique that we will assume you use) is to use a namespace and the antlib.xml from within the Animal Sniffer ANT Tasks jar file, for example:

<project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
  ...  
  <typedef uri="antlib:org.codehaus.mojo.animal_sniffer">
    <classpath path="lib/${pom.xml.project.artifactId}-${pom.xml.project.parent.version}.jar"/>
  </typedef>
  ...
</project>

Note: if you want to use any of the other techniques for importing ANT tasks, we (Maven developers) assume that you (ANT developer) know how to convert our examples into the technique you are using. This namespace based techique is the way the authors of this document know.

Checking a classes against an API signature

In order to check your classes against an API signature, you use the check-signature task:

<project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
  ...
  <target ...>
    ...
    <as:check-signature signature=".../my-signature.sig">
      <path path="classes"/>
    </as:check-signature>
    ...
  </target>
  ...
</project>

The path provided will be recursively searched for jar files and class files, all of which will be checked against the supplied signature.

When you run the check-signature task as in the above example, the task will fail if your classes reference any class, method or field that is not either:

• in the signatures; or
• on the path you provided

If you have compiled your classes against a classpath that you have already verified against the signature of your target platform, you can speed up the checking process by giving the check-signature task the classpathRef of your compile classpath. For example, if you are checking a web application against signatures for the Java EE Servlet specification, you might reference the classpath of the WEB-INF/lib folder when checking your WEB-INF/classes path. The following example illustrates how to achieve this:

<project ... xmlns:as="antlib:org.codehaus.mojo.animal_sniffer">
  ...
  <target ...>
    ...
    <as:check-signature signature=".../javaee-servlet.sig" classpathRef="webLibs">
      <path path="build/web/WEB-INF/classes"/>
    </as:check-signature>
    ...
  </target>
  ...
</project>

For more detailed examples of how to configure this task see:

• Checking signatures.

Generating API signatures

To generate the signatures of an API, simply invoke the build-signatures tasks providing the path of the API you want to generate the signatures for, e.g.

<project ... xmlns:animal-sniffer="antlib:org.codehaus.mojo.animal_sniffer">
  ...
  <target ...>
    ...
    <as:build-signatures destfile="dist/api.sig">
      <path>
        <fileset dir="classes"/>
        <fileset dir="lib" includes="log4j.jar"/>
      </path>
    </as:build-signatures>
    ...
  </target>
  ...
</project>

For more detailed examples of how to configure this goal see:

• Generating signatures