This blog has permanently moved to

Contact Form | Email Address

© 2018 All rights reserved by Boseji

Thank you for all your support.

Sunday, November 3, 2013

Setting up Ant for Java: Let the Ant do the hardwork

We have been working on some Java based projects recently. The compile mechanism of Java is a bit different from the way each of the IDEs implement them. We have used Netbeans-IDE and Eclipse. We figured that both have radically different way of implementing the compile time and jar time constrains. However we wanted some thing as simple as "make clean" and "make compile". That's when we came across Ant.

Apache Ant is internal build system used by many of the IDEs, this is the build framework in the world of Java. Kind of like 'make' for Java but apparently bit easier than makefiles. We need a consistent build framework across our Linux, Mac OS and Windows. We made a generic build system and configured in the way to make building Java projects a breeze.

In this article we would be discussing how we went about setting up the all the three system to have a common build framework for our up coming project jNeelSer which would be detailed later.

[1] Obtain Java

The  Ant framework is written in Java and hence to execute the same we would need to have Java compiler and run time available. To do this we simply get the JDK and place it into our path.
One can obtain the Java SE JDK from the Oracle Website. For now one can use the Latest JDK Java SE 7 releases.
A word of caution for the Linux users - if one intend to use the JDK to compile Android and use it for general purpose Java programming then they need to have JDK 6 version separately for Android from the Oracle Java Archive and if JDK 7 is used for development then the Path needs to appended accordingly. We actually do this so we will show how to do this in the next steps.

[2] Obtain Ant

The Ant package is available in binary form at Apache Ant website. Its designed in such a way that one can easily run it in any platform. So to setup extract the Ant package into the desired directory.
We are using Ant 1.9.2. So we have the directory apache-ant-1.9.2/bin and we add this to our Path in all the three platforms. Its easy to understand the Zipped version is for windows and the .tar.gz & .tar.bz2 are for Linux or MacOS.

[3] Ant Environment Script

In order the Ant build system to work one needs to setup the system Environment in the correct way.
Lets try to spend a moment to understand the system variable and what they mean:
  • JAVA_HOME = Location of the Java Installed Directory. Not the 'bin' directory but the root directory of Java installation.
    Eg. JAVA_HOME=C:\jdk1.6.0_45 and not C:\jdk1.6.0_45\bin
  • ANT_HOME = Location of the Ant Installed Directory. Again not the 'bin' but the extracted directory.
    Eg. ANT_HOME=/home/efb/local/apache-ant-1.9.2 and not /home/efb/local/apache-ant-1.9.2/bin
  • PATH = Need to be modified to add the Ant as well as Java ahead of all parsing. We will show this how
 Now lets look at how we can configure these environment variables:
Windows Batch file script (Save this text into a .bat file replacing the 'path' strings):
For Linux / MacOS we can create a small shell script to do this:
However this also means that the file needs to executable, so below is the command:
chmod +x antconf.sh

Next lets progress with writing a simple build script.

[4] Writing the Build Script for Ant

The Ant build framework is written in Java and uses XML based format to write the build scripts. This is a complete paradigm shift from the conventional Makefile business that we have seen countless number of times. Have a look at the basic framework of the build script:

Here the first XML tag defines the usual DTD as per the W3C. This is similar to the one used in any conventional XML data file.
Next the header <Project> gives details about the project that we plan to compile/build. Its important to remember the name specified by the parameter 'name="jNeelSer"' gives the project its true name. The compiled output would use this parameter to name the file build output.
The parameter 'basedir="."' helps to determine the path to the source code base where the build.xml is present.

Forgot to mention that  build.xml is the default name of the build script for Ant.

The 'default="compile"' option helps to determine the default step to be performed when the build is invoked.
Here is the complete source for the jNeelSerial project, we would use this as an example to detail the way of writing the Ant build script.
In the above build script there are many additional tags that help to define more information about the project and help in correct build generation.
  • Fail tag shown in line 26 is used to declare that one can use this build script with 1.8.0 or higher version of Ant build.
  • Property Tag shown in line 34 is used to fine the source and build location directories using the location value. The Property tag can also have other values if needed.
  • Target Tag shown in line 38 is like a configuration which contains a set of actions to be perfomed when the build is invoked. One can also add some description to each of the targets if needed as shown in the Compile configuration. Lets have a detailed look at this:
    • Init configuration: This is the Initial target that helps to create the necessary directories or build related info before hand.
    • Compile configuration: This is used to actually build the classes for the source code with the correct Class path. This build target need to run the Init in case it was not explicitly called.
    • jar configuration: This is used to generate the executable manifest information and create the required JAR file that contains the supporting libraries in one place. jNeelSerial uses the jSSC library stored in the lib directory. Again Jar depends on the Compile configuration as the class files to be packaged need to be available.
    • clean configuration: This is used to clear the build and intermediate directories.
  • mkdir Tag shown in line 42 helps to create directories with reference to build.xml file directory path as the reference.
  • delete Tag shown in line 67 can be used to delete files(use file attribute) or directories (use dir attribute)
  • javac Tag shown in line 48 is the most important tag that actually performs the compilation. The srcdir attribute helps to locate the java source code. The destdir attribute specified the location where the compiled classes should be placed. The includeantruntime attribute helps to run the java compilation under ant system control to help produce useful output of the commands being executed.
    • Classpath Tag in line 49 helps to define and include the necessary classes/packages and their locations. It require the Pathelement Tag to declare the paths. There can be two types - Package/Class locations(Eg. Line 50) or Absolute includes (Eg. Line 51)
  • jar Tag shown in line 58 is used to generate the executable java archive. In this the destfile attribute defines the destination jar file and the basedir attribute specifies the location for the class files complied earlier.
    • Manifest Tag in line 59 is used to define the default executable class which contains the 'main'. This is achived by using the Attribute Tag for 'Main-Class' with the value of the exact class with namespace.
    • zipgroupfileset Tag in line 62 helps to include some additional files if needed into the final jar. In the above example shows how to specify the directory and include files using a wildcard sequence.
This concludes the description of he build script.
Now how to run this thing.

[5] Running the Build

In order to run the build, first we need to use the scripts that we wrote earlier to setup the Ant build environment inside a Terminal window. Then change directory to the desired project directory and run the ant command.
Here is the syntax:
ant [target]
Here the important point is that [target] should be a valid one specified in the build.xml file. And this is run in the directory of the project containing the build.xml file.
In our above example for jNeelSerial there are 3 main targets - compile, jar and clean
In case the file name of the build script is different then use the following syntax:
ant -f [build script.xml] [target]

For example in jNeelSerial the name of the build script is make.xml and hence the command would be:
ant -f make.xml compile

Hope that you like this tutorial, let us know your feedback on this article.