Binary distribution:

decorum-0.4.0.jar

Mercurial repository (source):

http://hg.trapdoor.org/decorum/

Rename decorum-version.jar to decorum.jar and follow the instructions below.

Decorum is a simple dependency extension to ant. It does the following:

• Constructs classpaths using a simple list of dependencies.
• Matches jars to the required version (eg “any” “1.0” “1.2.3+”)
• Builds the dependencies if no jar is present.

First place the jar in the library directory, and use a taskdef to install the extension (here we use a lib.dir property):

<project ...>
...
  <!-- Import Decorum -->
  <taskdef name="dependencies" classname="org.trapdoor.decorum.Decorum">
    <classpath location="${lib.dir}/decorum.jar" />
  </taskdef>
...
</project>

Next, define a dependencies element. It should have an id to identify id (you can have multiple elements):

<project ...>
...
  <dependencies id="deps">
  </dependencies>
...
</project>

We have to tell decorum where to look for jars, so either add a libdir attribute:

<dependencies id="deps" libdir="${lib.dir}">

or use nested libdir elements (which work the same way as any other path list):

<dependencies id="deps">
  <libdir>
    <pathelement location="${lib.dir}" />
    <pathelement location="${modules.dir}" />
    <path refid="other.path" />
  </libdir>
  ...
</dependencies>

Let’s add a dependency:

<dependencies id="deps">
  ...
  <dependency name="log4j" />
</dependencies>

decorum will now look for log4j.jar or log4j-<version>.jar in any of the libdir paths.

What if we need a specific version? For example, junit 4 doesn’t work with java 1.4:

<dependencies id="deps">
  ...
  <dependency name="junit" version="3.2.8" />
</dependencies>

But what if they release 3.2.9? Let’s improve this:

<dependencies id="deps">
  ...
  <dependency name="junit" version="3.9-" />
</dependencies>

That will allow any version equal or less than 3.9 (decorum “does the right thing” with dotted versions. Ie 3.9 is less than 3.8.10 etc).

More often we will have a minimum version requirement:

<dependencies id="deps">
  ...
  <dependency name="cojen" version="1.2+" />
</dependencies>

Specifying a version disables the ability to match a non-versioned jar (log4j.jar, junit.jar, cojen.jar,...), but if we want to allow this behaviour too, add the anyversion attribute:

<dependencies id="deps">
  ...
  <dependency name="flakey-lib" version="1.1" />
</dependencies>

This will require exactly version 1.1 unless you override it by putting a non-versioned jar in the lib directory. This feature is obviously to be used with caution.

Lets use our generated classpath in a simple javac task:

<target name="compile">
  <javac srcdir="${src.dir}" destdir="${build.dir}/classes" classpathref="path.deps" />
</target>

See how a classpath ref called path.<id> was defined? You can obviously add to this classpath as normal; for example to include non-jar’d classes:

...
<classpath>
  <path refid="path.deps" />
  <path location="${build.dir}/classes" />
</classpath>
...

If your project trees are siblings, and decorum cannot find an appropriate jar, you can tell it to build one:

<dependency name="myotherproject">
  <build />
</dependency>

If myotherproject is elsewhere, you can pass a base attribute to build:

<dependency name="myotherproject">
  <build base="./subprojects/myotherproject" />
</dependency>

<dependency name="myotherproject">
  <build base="../myotherproject-new" />
</dependency>

As the above example shows, the likely usage of the base attribute is to define a different top-level project directory, or to temporarily use a different version of the project tree.

A better way to achieve the former is to define the decorum.basedir property before the taskdef:

<project ...>

  <property name="decorum.basedir" value="./subprojects" />

  <taskdef name="dependencies" classname="org.trapdoor.decorum.Decorum">
  ...
  </taskdef>

  <dependencies id="deps">
  ...
    <dependency name="myotherproject">
      <build />
    </dependency>
  </dependencies>
...
</project>

And a better way to make temporary changes would be to pass a project-specific property on the commandline:

ant jar -Ddecorum.myotherproject.basedir=../myotherproject-new

Sometimes you may want to set properties on a sub-build. The most common example would be to tell the sub-project to use the parent’s library directory. You can do this by adding a param nested element:

    <dependency name="myotherproject">
      <build>
        <param name="lib.dir" value="${lib.dir}" />
      </build>
    </dependency>

You can also use a copy nested element:

    <dependency name="myotherproject">
      <build>
        <copy property="lib.dir" />
      </build>
    </dependency>

Perhaps the project relies on a third party jar that relies on other third party jars. The project may or may not use them directly too. At the moment, this is purely notational - to help the reader of the build file understand what depends on what - and to aid copy and paste. In the future, this may be more intelligent:

<dependencies id="deps">
...
  <dependency name="util" />
  <dependency name="biglib">
    <dependency name="util" />
    <dependency name="logging" />
  </dependency>
</dependencies>

In the above example, the main project depends on “biglib”. “biglib” depends on “util” and “logging”, and the main project also depends on “util” directly. At the moment this is actually equivalent to specifying the “util” and “logging” libraries as direct dependencies of the main project.

Attributes:

• id - A unique identifier which forms the basis of the path name.
• excludes - a comma-separated list of targets which don’t need dependency checking (usually “init,clean”)
• libpath - a single path in which to search for jars. Can be combined or replaced with nested libdir elements.

Nested Elements

• libdir - A path-type element which defines where to search for jars.
• dependency - Defines a single dependency.

See the ant Path-Like Structures

Attributes

• name - The name of the project. Forms a basis of the jar name.
• version - The required version (optional). May be:
  • 1.0 - Exact version
  • 1.2.3+ - At least version 1.2.3
  • 3.2 - No more than version 3.2
• anyversion - Set to true to allow project.jar as well as project-version.jar. This has no effect if no version is defined, as it is always enabled.
• required - Set to false to add to the path if present, but ignore (don’t fail build) if not. Use sparingly.

Nested Elements

• build - A specification on whether (and how) to build the dependency if a jar cannot be found.

Attributes

• base - If defined, it should point to the project base directory. Otherwise ${decorum.basedir}/project is assumed if the decorum.basedir property is set, and ../project otherwise.
• dest - Place to copy the generated jar file. If you set this to some libdir included in the dependencies element, it will stop further recompilation.
• distdir - The distribution directory where the generated jar is to be found (relative to base).

Nested Elements

• param - Defines properties to pass to the sub-build. Works just like the param inside antcall. See property task documentation.