Tomasz Nazar - Ant tutorial [English]

Basics of Ant

What is Ant?

Just like they say in official Ant tutorial:
From Ant's documentation:

Apache Ant is a Java-based build tool. In theory, it is kind of like make, without wrinkles.

Ant is java build tool, designed to help people with automation. If you know make tool, it will be easier for you to understand it.
Ant is written entirely in Java, so it is portable. You can use the same file inside Linux, Windows, Solaris, etc..

What is the design of Ant?

To work with Ant, one has to create its config file. Config files are written in XML. Config file (usually called: build.xml) has its own structure. The root of XML file is a <project> tag. It consists of several targets. Each <target> consists of several tasks.

<project name="project_name" basedir="." default="default">

    <target name="default">
        <task1 param1="value" />
        <task2>
            <type param="value" />
        </task2>
    </target>

    <target name="target2">
        <task1 />
        <task3 />
    </target>

    <target name="targetN">
    </target>

</project>

What is <target>?

We define target as our logic target, the things we want Ant will do for us. For example, target could be one of: compile, make a file archive, send an email.
We can achieve target, with different ways. For example in real life, when we want to go to country Poland, we can do it in different ways. We can fly, we can go by train or we can go by sea to France, and then by train to Poland. So our target is "to go to Poland". We can get there in different ways. But, at the end we'll be in Poland anyway. Each step of the journey is called <task>.
The task is:

going by train
flying
going by sea
preparing to the journey by packing up

Each <target>, can depend on other <target>. For example, if we want to start some work in Poland, first we have to go to Poland, second we have to find some house to live in, third to find a job. If we can't find a house, we can't start looking for a job...

What is <task>?

A <task> in Ant is simple, little job, which will be performed. Simple tasks are: making a directory, copying a file, reading properties file or joining to files. There are more advanced tasks, such as: sending an email, compiling some source files, making an archive.
Each task can have some parameters or can depend on some other tasks.
Ant has a lot of built-in tasks (almost 70 built-in, and plenty of tasks available to download from Ant's site. You won't have to write your own. Some other people made it easier for you. They rewritten almost all simple Unix/Dos commands operating on files, like: copy, delete, mkdir, concat, etc..

So, how the simple config file for Ant looks like?

<?xml version="1.0" encoding="iso-8859-2"?>
<project name="Project name" basedir="." default="resources">
    <description>
        Some description here..
    </description>

    <property name="build.dir" location=".." />
    <property name="src.dir" location="src/" />

    <target name="prepare">
        <mkdir dir="${build.dir}" />
    </target>

    <target name="resources" depends="prepare">
        <copy todir="${build.dir}" >
            <fileset dir="${src.dir}">
                <exclude
                name="includes/**/*.swp" />
            </fileset>
        </copy>
    </target>

</project>

OK. Can we use custom constants within Ant's config file?

Yes, we can. They are called "properties".
We can define them directly in config file, by using <property> task or we can use built-in properties or we can read property file with properties.

Syntax for getting properties is:
${variable}, i.e. <mkdir>

We can read properties from config file:

build.properties:

        build.dir=build/
        dist.dir=dist/
        archive.filename=archive.tgz
        ...

built-in properties:

basedir
ant.file
ant.version
ant.project.name
ant.java.version

defining own properties

<property name="build.dir" location=".." />
<property name="src.dir" location="src/" />
<property name="archive.filename" value="archive.tgz" />

Using properties:

<echo> Sources are here: ${src} <echo>

What are the built-in tasks in Ant?

There are many of them. For a complete list, go to the original documentation Here are some examples:

Archive Tasks: <bzip2>, <gzip>, <tar>, <zip>, <jar>, <war>, <ear>, ...
Compile Tasks: <javac>, <rmic>, ...
Documentation Tasks: <javadoc>, <doxygen>
Deployment Tasks
Logging Tasks
Mail Tasks: <mail>
Miscellaneous Tasks: <echo>, <sound>, <splash>, <sql>, ...
.NET Tasks
Pre-process Tasks
Property Tasks
Remote Tasks: <ftp>, <telnet>
SCM Tasks: <cvs>, <cvspass>, <perforce>, <starteam>, ...
Testing Tasks: <junit>, <junitreport>, <test>
Visual Age for Java Tasks

And what about invoking a task on a group of files?

To choose a group of files we should use Ant's task called: <fileset> or <filelist> (there are also tasks to select group of directories: <dirset>).

Hint!
The tasks: <DirSet>, <FileList>, <FileSet>, <File Mappers>, <FilterChains> and <FilterReaders>, <FilterSet>, <PatternSet>, <Selectors>, <XMLCatalog> are the Core types of Ant tasks.

Here is an example of using <fileset>:

<!-- ... -->
<fileset dir="${server.src}" case sensitive  ="yes" >
    <include name="**/*.java"/>
    <exclude name="**/*Test*"/>
</fileset>
<!-- ... -->

This will consist of files with suffix: .java, but without files within some *Test directory (where '*' means anything).

As we can see it is simple to choose some files inside our dir structure.

Show me use of some simple task now, please..

Here you are.

First simple example: Task <javac> compiles files from underlying source directories.

    <target name="compile" depends="...">
        <javac
            destdir="${build.classes.dir}"
            deprecation="on">

            <include name="**/*.java" />
            <src path="${src.main.dir}" />
            <src path="${src.prevayler.dir}" />
            <src path="${src.ant.dir}" />

        </javac>
    </target>

Second simple example:
There is a task, called: <copy> which copies files or directories to another place:

<copy file="myfile.txt" todir="../some/other/dir"/>

Third example:

<copy todir="../dest/dir" >
<fileset dir="src_dir" >
<exclude name="**/*.java"/>
</fileset>
</copy>

There also exists task, which allows user to run some JUnit tests:

<junit>
<test name="my.test.TestCase" />
</junit>

More advanced:

<junit printsummary="yes" haltonfailure="yes">
    <classpath>
      <pathelement location="${build.tests}" />
      <pathelement path="${java.class.path}" />
    </classpath>

    <formatter type="plain" />

    <test name="my.test.TestCase" haltonfailure="no" outfile="result" >
        <formatter type="xml" />
    </test>

    <batchtest fork="yes" todir="${reports.tests}">
        <fileset dir="${src.tests}">
        <include name="**/*Test*.java" />
        <exclude name="**/AllTests.java" />
        <!-- ... -->

Advanced Ant: Ant tasks

Task to generate MasterTest file

I wrote simple, useful task which generates a Java class for running several other JUnit classes. File representing the class has structure which we can generate by finding files with Test substring in file's name. Ant can be helpful here.
Here is a page with task source, and a page with task usage.

The file to generate is:

package nthx.some_project.tests;

import nthx.some_project.order.action.tests.UpdateWorkingDaysInWorkstandActionTest;
import nthx.some_project.order.action.tests.AddWorkingDaysToWorkstandActionTest;
        /** 
         *  many imports more..
         *  cut here 
         */
import junit.framework.*;

public class MasterTest extends TestCase {

    public static Test suite() {
        TestSuite result = new TestSuite();

        result.addTest(new TestSuite(StringUtilsTest.class));
        result.addTest(new TestSuite(OrderTest.class));
        /** 
         *  50 lines more..
         *  cut here 
         */
        result.addTest(new TestSuite(UpdateWorkersExperiencesBeanTest.class));
        result.addTest(new TestSuite(InsertWorkerBeanTest.class));
        return result;
    }

How this WWW page was created

GTML: As on 19.07.2003 these pages have been generated with GTML tool. Read more about the tool
Building WWW pages with Ant: This page (along with others) could be built using the Ant. I used simple mechanism of joining files (header, content, footer) into one single HTML file.
Because of on each file we can perform the same steps, we can invoke a script on every file. So there is config file for generating these pages. But watch out!. Do not use the methods used in the file. I had little time to make the script (i was looking for some Javascript power in Ant - and spent too much time for nothing :( ) - so I decided, to leave it in that form, and repair sometime.

Acknowledgements

Thank you: I thank all the people used this tutorial in their work. Hope it was useful enough.
I would be very glad to improve this tutorial if there is need for it. In any case of critique for this document please use form at the bottom of the page to give me feedback. It is always welcome!

References

Official Ant site: http://jakarta.apache.org/ant
Official Ant manual: http://ant.apache.org/manual/index.html
Article at JavaWorld: Automate your build process using Java and Ant
Article at IBM/developerworks: Automating the build and test process

Ant tutorial

Contents

Basics of Ant

Advanced Ant: Ant tasks

How this WWW page was created

Acknowledgements

References