Turnleaf Design Ramblings of a junior developer

An intro to writing ANT Scripts

What is Ant?

A(nother) N(eat) T(ool) is a tool developed by the Apache Foundation for automating tasks in a project. It is primarily, though not exclusively used for Java projects. Most developers interaction with ant is through the xml specification, which is used to define specific operations.

The objective of this tutorial

Ant was designed with adaptability and expandability in mind, as a consequence it is used for many tasks and in many systems. As we get deeper in the dev environment series we will rely heavily on ant to make our lives easier and to carry out many important functions. For this tutorial however I will go cover what ant is primarily used for, building a project and creating a deliverable, in this case a jar file. This will provide a good intro into the usage of ant and how it works.

A simple ant script

So let go ahead and jump in, here is an ant script I wrote for one of my projects:

<project name="AntProject" default="build-jar" basedir=".">
        <property name="src" location="src" />
        <property name="build" location="build" />
        <property name="dist" location="dist" />

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

        <target name="compile" depends="init" description="compile the source ">
                <javac srcdir="${src}" destdir="${build}" />
        </target>

        <target name="build-jar" depends="compile" description="generate the distribution">
                <jar jarfile="${dist}/${ant.project.name}.jar" basedir="${build}">
                        <manifest>
                                <attribute name="Main-Class" value="com.ant.HelloWorld" />
                        </manifest>
                </jar>
        </target>
</project>

This is a simple build file, for a very (very) simple project which you can view here [http://turnleafdesign.googlecode.com/svn/!svn/bc/7/trunk/Ant%20Project/trunk/Ant%20Project/]. The script is fairly self explanatory but since this is a tutorial...

Project:

The default attribute refers to the target that is run by default when you run the ant build file. So if you were running in command line you would only need to type “ant” in the directory in which the build.xml file resides and the target”build-jar” would be ran. More relevant, from Eclipse (and I assume most other IDEs) you need only click the icon representing the build file to run the default target.

The basedir attribute represents the path from which ant builds off. The path is relative and follows the same conventions common to navigating file systems through the command line. A period represents the current directory in which the ant scripts resides (which is also the default).

Property:

A tag used to create variables, somewhat similar to Java variables in which you give them a name (though this is not required), a type, and a value. While only the location attribute is shown in the example above, there are many different attributes available.

Target:

Represents an executable operation in the ant script which can be ran from the command line (ant [target name]) or within an IDE. A target can run multiple tasks if needed, for example I could include mkdir, javac, and jar (all of which are considered tasks in ant) within the “init” target.

The depends attribute represents a target that must be run prior to executing the current target, so for the target “compile” to execute the target “init” must be executed. Multiple targets (separated by commas) can be included in the depends attribute with them running in order from left to right.

Mkdir, javac, jar

As briefly mentioned above, these represent tasks in ant. These are predefined operations that ant executes to carry out a task. Unsurprisingly there are a lot of tasks in the ant project. You can create your own as well [http://ant.apache.org/manual/develop.html].

A bit more about Jar and the jar task

The main purpose of this script is to build a jar, most with experience with Java know what a jar is but since this is a tutorial...

Jar is a file format specification developed by Sun which is based upon the zip format. The purpose of a jar is to aggregate many files, usually Java classes, into one archive. All jar files must contain a META-INF directory, and a manifest.mf file within that directory. The specification predominantly concerns what can be contained within the META-INF directory and the files there within. Java projects are often built into war and ear files, which when we get to that point I will go over.

Compared to the other tasks in the project there is a bit more going on with the jar task. So to better explain...

Jarfile represents the location where the jar file will be written

basedir represents the root directory of all the files that will be contained within the jar file

The manifest task is used to add additional metadata to the manifest.mf file, which is explained in more detail below.

The Manifest task and manifest.mf

Another task that is being executed which I did not touch on is the manifest task. In this example it is designating the main-class which is required in order to allow a jar to be executable (often jars are used as a source library for another project, and don't have (or designate) a main-class so they are not executable).

If you open up the jar file you see two directories; com and META-INF. META-INF as explained earlier is a standard directory in all jars, “com” represents a top level package name. Any number of other folder or files could be in here, depending up how the jar is built. But getting back on track; if you open up the META-INF directory you will see manifest.mf. This file contains metadata about the jar; manifest-version, ant-version, and created-by. All these are standard and are there to provide information as to how the jar was built. Also included is “Main-Class: com.ant.HelloWord,” this is really important because if you attempt to execute the jar the JVM will actually read this file looking for this property.

As we get deeper into this series we will utilize the manifest task more heavily to provide important metadata about the jars, wars, ears we will be building.

Tip of the iceberg

This is merely the tip of the proverbial iceberg. As suggested earlier we will increasingly rely on ant as we get deeper into the dev environment series. This tutorial will hopefully provide a good base for explaining what ant is doing for future reference.

Sources:

http://en.wikipedia.org/wiki/Apache_Ant

http://en.wikipedia.org/wiki/JAR_%28file_format%29

http://download-llnw.oracle.com/javase/1.5.0/docs/guide/jar/jar.html

http://ant.apache.org/manual/

Technorati Tags: ANT, Automation, Java

No related posts.