Apache Ant is a Java-based build tool. What does it do? In laymans terms it carries out a series of selectable tasks that are commonly repeated when using software. In the case of Website, the tasks are simple. Two transforms using XSLT, with the saxon as the xslt engine (you may choose another one) and a file transfer between a local machine and a remote server.

You may need to install ant. The manual discusses this at length. Section 2 also discusses adding an extra file to the ant lib directory to provide the ftp facility.

ant has a little of its own terminology. A project is a 'system', or a series of tasks related to one job. You might have one project per Website for instance. A property is a way of accessing information which is defined once and used many times. For instance, the server where your files are to be uploaded may be defined in a property, as may the location on your disk where you keep the xml files for a Website. A target as used by ant means a single task that must be done. Website has 3 phases, 3 tasks, so there are 3 targets. The ant manual talks about tasks. When you are specifying something you want done, you use one of the tasks as the contents of a target.

In order to control what tasks are required of ant, a build file is created. An ant build file is an xml file with a root element of project. The file is best named build.xml. This is given to the ant program and controls its operation. Within the project root element you will find property elements and target elements. So a very simple build file for ant looks something like Example 7

<project 
     name="mywebsite"   
     default="help">                     
<!-- docbook location: 
    Everything is found relative to this for docbook stuff -->
 <property name="docbookHome" value="/sgml/docbook"/>     <!--  -->
 <!--Initial processing: If needed.  -->
 <!--  -->
 <target name="init">                 
	<echo message="Do initialisational things" />                          
  <tstamp>
   <format property="TODAY_UK" pattern="d-MMM-yyyy" locale="en"/>
  </tstamp>
 <echo>building on ${TODAY_UK}</echo>
 </target>

<target name="main" depends="init">   
....
</target>

<target name="help">
<echo> Usage..... </echo>
....

</target>


</project>  

Although it doesn't do much, this example is a valid build file for ant. The example provided in Section 8 is however both complete and functional - although the properties may need to be adjusted to work with your directory layout if different from the examples in this document. The way in which ant is used is fairly straightforward. Within the installation is a directory (/apps/ant/bin) which contains a script or batch file (ant, or ant.bat). This is quite complex internally, but very easy to use! Firstly make sure you can access the /apps/ant/bin directory easily. This is normally done by adding the /apps/ant/bin directory to the PATH environment variable. Then, in order to run ant, with a Website (or any project), open a command window or terminal and type cd to change directory to the one in which the build file (build.xml) is found. From there, simply type

>ant 

and the ant program will look for a file named build.xml in the same directory.

The next question is which task or target will ant choose? This is done in a strict sequence that is worth learning about. Note the default attribute on the project element? That specifies what target will be run first, unless overridden by the command line. This is done quite simply by specifying which target should be run, e.g. to run the main target, simply run ant with the command ant main. Simple as that. Any target can be selected this way. This brings up dependencies. Assume for the example that the 'main' target cannot be run without running the 'init' target (for whatever reason). Then the depends attribute starts to be of use. If I run ant with this build.xml file and specify the 'main' target, then ant will step back and run 'init' target first, followed by the 'main' target. For a Website this can be quite useful. With three targets, layout, main and upload, if the latter two depend on the first in that sequence, we can type in ant upload, knowing that the layout phase and the main build phase will be run prior to upload. Dependencies can be useful, but they can also hinder. Think about it before inserting a whole string of dependencies! Try one and see if it works. It isn't hard to modify.

Of particular interest is the XSLT/Style ant task, described fully in the manual (at this page). This will be shown later.