Running Clirr as an Ant Task

clirr is distributed as an Ant task. The following text assumes that you are familiar with Ant. To run clirr, you typically

  • compile the current version of the library you want to check, resulting in one or more jar file
  • tell ant about the clirr ant task
  • download the compatibility baseline release of your software from a central location via http (if it is not available in your local filesystem already)
  • run the clirr task

To do this you will need an ant snippet similar to the following: 

<target name="checkbinarycompatibility" depends="build">

  <!-- buildtools.classpath should contain clirr.jar and the libraries it depends on -->

  <taskdef classpathref="buildtools.classpath" resource="clirrtask.properties"/>

  <property name="jar.baseline" value="${ant.project.name}-${compatibility.baseline.version}.jar"/>

  <get src="${url.libbase}/${ant.project.name}/${jar.baseline}" dest="build/tmp/${jar.baseline}"/>

  <clirr>
    <origfiles dir="build/tmp" includes="${jar.baseline}"/>
    <newfiles dir="build/lib" includes="${jar.buildresult}"/>

    <!-- <formatter type="xml" outfile="build/clirr.xml" /> -->
    <!-- TODO: example for 3rd party classpath -->
  </clirr>

</target>

Parameters

Attribute Description Required Default
failOnWarning Whether task execution should fail (break the build) on warnings No No
failOnError Whether task execution should fail (break the build) on errors No Yes

Parameters specified as nested elements

newFiles

A FileSet that describes the current version that should be checked against the compatibility baseline.

Clirr works with FileSets instead of individual jar files to allow splitting up or combining library distributions. An example is log4j, the 1.3.0 release splits up the earlier log4j.jar into several jar files.

origFiles

A FileSet that describes the compatibility baseline to check against.

newClassPath

The 3rd party ClassPath that is referenced by the checked library version (newFiles). Any class or interface that occurs as a baseclass, parameter type or method return type must be included here.

origClassPath

The 3rd party ClassPath that is referenced by the compatibility baseline version (origFiles). Any class or interface that occurs as a baseclass, parameter type or method return type must be included here.

Often the origClassPath is the same as the newClassPath. In these cases you can specify these paths using the refid attribute to avoid duplicating the classpath information. Please refer to the ant manual for details.

formatter

A formatter that generates Clirr output. Multiple formatters can be specified. Available attributes for each formatter element:

Attribute Description Required Default
type The formatter type. Available types are plain and xml No plain
outfile The file to write to. If not specified, output is written to stdout No stdout

If no formatter is specified, Clirr will write it's findings to stdout in plain format.