Ant Build Tasks

What is Ant?

Ant has become the defacto standard for automating the build process of Java projects. It is similiar to the tool make but is written in Java and uses XML for its script syntax. The Ant documentation states that it is kind of like make, without make's wrinkles.

The NekoStyle package contains a number of processors that are available as Ant tasks to provide functionality not available with Ant's built-in tasks. The following sections detail the Ant tasks provided with NekoStyle and demonstrates how to use them.

Using Custom Tasks Within Ant

Ant makes it easy to add new functionality to an Ant build script by using Java's run-time type information. However, in order to use these new tasks, you must first define the task so that Ant recognizes the new XML tags used within the build script.

To define a new task, add a <taskdef> element to the top of the Ant build script. This element must specify two attributes. The name attribute defines a new element name for use within the Ant build script to be associated with the custom task. This name should be unique from the names of the built-in tasks. The classname attribute specifies the fully qualified classname of the custom Ant task. For the task to work within Ant, the class files for the custom task must be available to the JVM running Ant. In other words, put your custom code in the Ant classpath.

The following example defines a new task called "custom" that uses an imaginary custom Ant task:

<project default='all' basedir='.'>
 <taskdef name='custom' classname='MyCustomTask'/>
 ...
</project>

Now the new task can be used within any target. For example:

 <target name='all'>
  <custom/> 
 </target>

The attributes and sub-elements used within the new task element are determined by the task. The following sections for each NekoStyle Ant task details the attributes and sub-elements that are allowed for the task.

The Pipeline Task

The NekoStyle Pipeline processor can be used as an Ant task to invoke a set of XML transformations. Any transformation that can be performed with the NekoStyle Pipeline processor can also be performed using the included Ant task — the only limitation is the the variety of NekoStyle processors available within the JVM running the Ant build script.

For many cases, though, the processors included with the NekoStyle package are sufficient to accomplish a majority of typical file transformations. In fact, the documentation that you are reading right now was generated by the NekoStyle Pipeline processor. The XML source for the documentation can be found within the src/style/doc/ directory and the various XSLT stylesheets for dynamically generating additional pipeline commands and converting the output to HTML can be found in the src/style/doc/xslt/ directory.

Usage

To use the Pipeline task within Ant, define an element for the task in your Ant build script. For example:

<project default='all' basedir='.'>
 <taskdef name='nekostyle' classname='org.cyberneko.style.ant.Pipeline'/>
 ...
</project>

Then you can call this task within your build targets. For example:

 <target name='all'>
  <nekostyle filename='path/pipeline.xml'>
   <property name='given'  value='Andy'/>
   <property name='family' value='Clark'/>
  </nekostyle>
 </target>

Attributes

The Pipeline task supports the following attributes:

filename

The name of the pipeline document to process. This parameter is required.

verbose

Values "true" or "false" determine whether the processor produces verbose output. The default value is "true".

Sub-Elements

The Pipeline task supports the following sub-elements:

<property name='...' value='...'/>

Defines a parameter to be passed to the Pipeline processor. Both the "name" and "value" attributes are required.