Chapter 6. Extending via Ant

Quokka is essentially a plugin architecture, so it is natural for it to use Ant's facilities to extend quokka.

As you have probably encountered by now, quokka looks for a build.xml file along side the build-quokka.xml file.

Note: build.xml may be renamed as long as the quokka project file matches, e.g. myproject.xml and myproject-quokka.xml would be considered a matching pair.

The contents of build.xml are automatically imported into the quokka project using Ant's import task. All of the standard inbuilt tasks are supported.

6.1. Using Ant optional tasks

To use optional tasks you need to:

  1. Ensure that the optional library you require is in the repository

  2. Add both the Ant optional .jar and the dependent library to your project as dependencies and assign them to the in-built ant-types path.

Quokka will then add the ant-types path to the relevant class loaders for tasks, making the library available. e.g. If you want to use the Ant scp task to copy files to a remote server, you need to add the following entries to your build-quokka.xml file:

<dependency group="apache.ant" name="jsch" version="1.7" paths="ant-types"/>
<dependency group="sf.jsch" version="0.1.35" paths="ant-types"/>

You can then just use it as usual in your build.xml file:

<target name="remote-copy">
    <scp file="${file}" todir="${user}:${password}${host}:${tofile}"/>
</target>

6.2. Target Dependencies

Targets you add can also have dependencies, using the standards depends attribute of target. However, there are situations where you'd like a target outside of your control to depend on your target. e.g. If you would like your target to occur between the compile and test targets defined by the life cycle plugin, you really need to add your target to the depends attribute of test.

You can't do this directly, but you can use the built-in dependency-of task to achieve the same thing. The dependency-of target should be embedded within your target with the targets attribute set to a comma separated list of targets that need to depend on your target. Below is an example:

<target name="after-compile-before-test" depends="compile">
    <dependency-of targets="lifecycle:pre-test"/>

    <echo>Hello from "after-compile-before-test"</echo>
</target>

There are several things to note. Firstly, the targets specified should be fully qualified, including the plugin's name space. Secondly, the target is pre-test, not test. When inserting targets between life cycle targets it is important to use the pre-* targets. This ensures your target will be executed before any implementations of the target by plugins.

6.3. Built-in Ant extensions

Quokka bundles a few additional built-in Ant tasks to make scripting with Ant a little less cumbersome. This includes:

Control flow tasks

The if, for, switch, run-target and var tasks from the ant-contrib library are included (documented here).

buildpath

The buildpath tasks creates a path containing projects to build to be used with subant, taking into account project inter-dependencies. See here for more information

copy-path

The copy-path task will copy a project path to a specified directory, optionally renaming them to a given pattern. Attributes are:

id

Mandatory. The id of the path to copy.

toDir

Mandatory. The directory to copy the files from the path to

pattern

Optional. A pattern made of variables in #{variable}, where the variables are group, name, type, version and extension. The default is #{group}_#{name}_#{type}_#{version}.#{extension}.

input-unless-set

Requests the user to input the value of a property unless it is already set. Useful for interactive tasks where the user may optionally supply values at the command line. Attributes are:

property

Mandatory. The name of the property to set

message

Optional. The message to use a prompt for input. Defaults to "Enter a value for '${property}':"

validargs

Optional. The comma separated set of valid responses that can be entered. If set, the input task will loop until one of the valid args is entered.

Remember the built-in properties that quokka sets as well. In particular, each project path is available as a property that can be easily converted into an Ant path data type.

6.4. Ant targets within dependency sets

Standard Ant targets can also be bundled with dependency sets. This effectively provides a quick a dirty way of writing plugins using nothing but Ant tasks. See Creating Dependency Sets for more information.