Clirr Core

Running Clirr as an Ant Task

The clirr-core module contains 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 either contain
        clirr-core-uber.jar or alternatively
        clirr-core.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
failOnBinWarning	Whether task execution should fail (break the build) on warnings about binary compatibility issues	No	No
failOnBinError	Whether task execution should fail (break the build) on binary compatibility errors	No	Yes
failOnSrcWarning	Whether task execution should fail (break the build) on warnings about source code compatibility issues	No	No
failOnSrcError	Whether task execution should fail (break the build) on source compatibility 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, presumably the 1.3.0 release will split 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.

apiclasses

A PatternSet that defines which classes form the API. By default all classes are included.

The API is often only a subset from the set of public classes in a jar file. For example, the Eclipse project has package naming conventions that signal which classes must not be used outside a module, even though they are technically public.

Example:

  <clirr>
        <origfiles dir="build/tmp" includes="${jar.baseline}"/>
        <newfiles dir="build/lib" includes="${jar.buildresult}"/>
        <apiclasses>
              <exclude name="**/internal/**"/>
              <exclude name="**/examples/**"/>
              <exclude name="**/tests/**"/>
        </apiclasses>
  </clirr>

Project Documentation