The Great Ant Tutorial – a great jump start

Apache Ant is a powerful way to convert your developmental structures to deployment structures. It is declarative and all the command line tasks used for deploying an application are represented by simple XML elements. Without much details, this tutorial would breeze you through the steps on how to build a web application using a single XML build file and nothing else. If you have not yet understood what is the use of Ant, read my article on Development and Deployment Structures – the perfect way to build web applications.

I would use the same analogy of my development structure as mentioned in the above linked article i.e. my development structure consists of the following directories:

  1. web – place for all my JSP, HTML, JavaScripts and Stylesheets. You can provide subdirectories as required for each of the different set of files
  2. src – place for my java class files consisting of POJO’s or servlets.
  3. etc – place for all config files like the most common web.xml
  4. lib – place for all the necessary jar files to run my application. I even have included servlet-api.jar in this directory since you may have to deploy your web application in a remote server after compiling.
  5. build – a temporary directory for keeping the compiled files
  6. dist – a place to put in the finally packaged war file (distribution)
  7. ant– place for my build.xml file and external properties file

All these directories are present in a parent directory called “WebApp“. The three things you have to keep in mind for making an Ant build file are –

  1. tasks – which correspond to your command line tasks like javac, war etc. A group of tasks can be executed in a sequence by specifying targets.
  2. target – It is like a function where you put reusable tasks so that it can be called later without duplicating them.
  3. property – this element is used to define variables in your build file which is useful when the value like project_name or folder_name keeps on changing.

One of the most awesome features of Ant is that you can keep the properties file externally inside of defining all the variables within the build file. This properties file consists of all the required variables and their values in the form of name-value pairs and is simple text file. In this tutorial I would be using an external properties file.

For the tutorial I have used the following:

  1. Java version 1.5
  2. Apache Tomcat 5.0
  3. Apache Ant 1.6.5

Okay we are now good to go with the great Ant tutorial. For this make a file with the name “build.properties“. This would be our external variables file.

root.dir=..
lib.dir=lib
src.dir=com
conf.dir=etc
web.content=web
project.name=WebApp
build.dir=build

NOTE: you must hit the ENTER key for starting a new line after the last line or Ant will give you an error “BUILD FAILED for some unknown reason

It is not necessary to put in the name with the dot. You can have a name as “projectName” but there should be no quotes for the value. i.e it should NOT be projectName=”WebApp”

To make a build file we have to remember what is to be done for the deployments. To make things simple just make the modules (targets) necessary for the complete web application deployment which are

  1. clean – remove all prior deployments of the same application if made
  2. init – make the necessary structure for deployment as per the vendor’s
  3. compile – compile your servlets or POJO‘s
  4. copy – put the compiled files and web content in the deployment structre as created during init
  5. war – make the war file and open the browser

Start making the build.xml file in the ant folder as follows:

<project name="AppBuilder" default="war" basedir="..">
	<property file="ant/build.properties"/>
</project>

Now we have to set the classpath for the servlet-api.jar to compile our servlets so put the servlet-api.jar in the lib directory of your development structure. Check the property “default” in the <project> element. It states the LAST module (target) inside the build file. In our case it is “war

All the following XML elements will now go inside the <project></project> element created above. So put the classpath setting element,

<path id="classpath">
 	<fileset dir="${lib.dir}" includes="servlet-api.jar"/>
</path>

Here you need to set all the necessary jars to your classpath for successful compilation of the java source files. ${lib.dir} is used to retrive the value of the “lib.dir” i.e lib

Now we will start with out targets (modules) as mentioned in the list above :

1. clean

<target name="clean">
	<echo>Cleaning the ${build.dir}</echo>
	<delete dir="${build.dir}"/>
</target>

Here I am removing my build dir in case it was present earlier with compiled files
The <echo> element is only for displaying what you are doing in the command line.

2. init

<target name="init" depends="clean">
	<echo>Creating the build directory</echo>
	<mkdir dir="${build.dir}/WEB-INFclasses"/>
	<mkdir dir="${build.dir}/WEB-INFlib"/>
</target>

Here I am creating the normal deployment structure required for tomcat namely WebApp/WEB-INF/classes, etc. It doesn’t matter if the folder WEB-INF existed before making the folder classes. Ant automatically creates all the necessary parent folders if they don’t exist.

3. compile

<target name="compile" depends="init">
	<echo>Compile the source files</echo>
	<javac srcdir="${src.dir}" destdir="${build.dir}/WEB-INF/classes">
		<classpath refid="classpath"/>
	</javac>
</target>

Most important step and the most error giving step. Make sure that all the classpath have been set in the above <path> element. If all are proper then the all files in “src.dir” will be compiled successfully and moved to the build\WebApp\WEB-INF\classes. Just check the property “depends” of the <target> element here. This property is used to chain the modules (targets) in a sequential manner.

4. copy

<target name="copy" depends="compile">
	<copy todir="${build.dir}/WEB-INF">
		<fileset dir="${conf.dir}"/>
	</copy>
	<copy todir="${build.dir}">
		<fileset dir="${web.content}"/>
	</copy>
	<copy todir="${build.dir}/WEB-INF/lib">
		<fileset dir="${lib.dir}"/>
	</copy>
</target>

Here I am just copying my complied classes and web content files inside the corresponding deployment structure.

5. war

<target name="war" depends="copy">
	<echo>Building the war file</echo>
	<war destfile="${dist.dir}/${project.name}.war" webxml="${build.dir}/WEB-INF/web.xml">
		<fileset dir="${build.dir}"/>
	</war>
</target>

This is the final module (target) in my build.xml file which makes the WebApp.war required for the deployment. “war” is an Ant task for which you provide the path of the web.xml file and the directory which contains the deployment structure i.e in our case “build” directory. The destfile is the final location and name of the war file which would become dist\WebApp.war after the script has run.

Running the above script
Keep the build.properties and build.xml files in the ant folder. Make sure that the ANT_HOME environment variable is set to your ant‘s installation bin directory. Now, all you have to do is run the ant command on the build file as,

C:\> cd WebAppant\ant
C:\WebAppant\ant> ant

That’s it. If successful your development will finally become a fully packaged WebApp.war.

Final Words
Thus, we have made a complete packaged war file from our source with a single XML file and the wonderful Ant tool which is ready to be deployed in the tomcat manager. We can further dig deeper and make complex build.xml using the complete set of elements that Ant provides. But this tutorial was just to get you started with using Apache Ant. If you have any difficulty in understanding the individual elements please read their detailed explanation in the Apache Ant documentation.

Resources
If you have any problem in making the build.xml or build.properties please download them from here. (Right click and select “Save as ….”)

80 thoughts on “The Great Ant Tutorial – a great jump start

  1. Hi,

    Really its a very great tutorial.

    Well, in the build.xml, we need to change the web.xml path. Since will delete all the files, the web.xml file gets disappeared with it builds war file.

    By creating com\WEB-INF\web.xml file, I was able to create war file.

    Once again, kudos to your effor & approach.

  2. Hi,

    Really its a very great tutorial.

    Well, in the build.xml, we need to change the web.xml path. Since clean ->’delete dir=”${build.dir}”‘ will delete all the files, the web.xml file gets disappeared with it builds war file.

    By creating com\WEB-INF\web.xml file, I was able to create war file.

    Once again, kudos to your effor & approach.

  3. Wrong Wrong Wrong and wrong. This tutorial assumes the reader knows everything about deployments and it’s a whole waste of time.

    Have a look at this mumbo-jumbo:

    “Check the property “default” in the element. It states the LAST module (target) inside the build file. In our case it is “war” ”

    WTF????

  4. Stephane, I am not able to understand your agony. I have mentioned in the tutorial that if you are not aware of the deployment structures concept then it has been linked for your reference.

    If you are looking for any specific clarification you are free to ask your doubt.

  5. I’m not a native speaker (?) of the English language, but when writing “inside of defining…” shouldn’t it be “instead of defining….” ?

  6. The section “2. init” code says “/WEB-INFclasses” and “/WEB-INFlib” – shouldn’t it be “/WEB-INF/classes” and “/WEB-INF/lib” ?

  7. Thanks Sridhar. I’m glad you found it helpful.

    Bubba, I think there is some conflict in the WordPress plugin which displays the code. I will try to correct it. Thanks for bringing it to my notice.

  8. This article really helped a beginner like me. I am glad I did find this 🙂

    Kudos to ur work put into this 🙂

  9. Ant is something which cannot be learnt from books. Its something we learn with our application and requirement. The style in which Ant is used varies with each developer.

    I suggest u to incorporate ANT task for generation of docs as well to make ur example complete 🙂

  10. hi Nitin

    One thing i have realized by using ANT is that it helps you improving the design of java class packaging, designing loose coupled application etc.

    Nitin it would be better if you can provide some more stuff on ant for the situation like when u have dependent class packages environment.
    for example ..
    if class B of PKG2 extends class A of PKG1 in such scenarios we have to compile class A of PKG1 so that when we call the build.xml file from PKG2 the same complied class would be available.

    Also can u please include some more stuff related to few task categories of ANT.

    e.g
    some conditional stuff or
    etc.

    🙂

  11. Hi nitinpai. This is a very good tutorial and it really helped me. But “in the build.xml, we need to change the web.xml path. Since will delete all the files, the web.xml file gets disappeared with it builds war file. ” It took me some time to find out this. Anyway very useful tutorial.. Thanks a lotttttttt. 🙂 Please keep posting like this.

  12. From where did you copy this one dude ?? ant tutorial is available in n number of websites, looks like u have cut and pasted something, there are hell a lot of errors in your tut, first correct them

    any howz good job pai

  13. Shekhar,

    I am against copy pasting any articles and please don’t raise false accusation on presumptions. A little look here and there would help if you know about Ant articles which are already available. Of course many people work on Ant and would have written about it. I did not create any new Ant Tasks myself. I just have simplified their explanation.

    If there are errors please report them.

  14. Good one..
    I couldnt find any reference of wsejbdeploy command .. can you provide me any info on it

  15. It is great. I am new to Ant. It gives us a kick start to use Ant. This foundation is more than enough for going some thing complex with Ant.

  16. hi,

    good tutorial, but it’s possible to insert de regular expressions to change de code in build-time?

    Thanks.

  17. @jordi – I am not sure if regular expressions can be used inside Ant or not. If you could state a particular situation where you are required to use expression I’ll try to come up with a solution.

  18. hi Nitinpai,

    I need to add a buildVersion in my source code, like a string

    (String buildVersion =/*[BuildVersion]*/ “date”/*[/BuildVersion]*/), if I want to change this in buildTime I can find the labels “/*[BuildVersion]*/” but the ‘date’ change each re-build. For this I want use the regular expressions.

    Thanks.

  19. so if we are using an IDE such as eclipse or Netbeans, we are sheilded from ant processes you discuss above? i am really new at this and find that i can never really debug things with the IDE’s, e.g. the build file for netbeans is MASSIVE, it makes me so confused… when something goes wrong i don’t know where to begin..

  20. Hi all,
    Thank author very much!
    It is a really good tutorial. I followed this and it worked perfectly. If we use IDE like JBuilder or Eclipse, it’s hard to find what’s really inside the deployment. With Ant, everything seems clearer.

  21. The use was property file was a good idea on the hand deployment structure of the build.xml could have arranged a bit easier.

  22. @kazi – property files are the best whenever you have to provide some frequently changing details like say username and password for application login, especially in the development stage.

  23. Hey, this is really great tutorial. I was looking for something like this to start with ant and it helped me a lot.

  24. Excellent!!!
    Author has presented it in a very simple and easy way. Even the minute details also mentioned, which helps a lot if one is stuck with small silly problems.
    He as mentioned that also like giving a new line space in property files.
    Thanks a lot.

  25. Thanks a lot. I am just new to ant and it helped me a lot. I am able to create the war file and it is a nice jump start!!

    Keep it up in helping beginners like me.

    Thanks a lot.

  26. Hi nitinpai. Thank you for this nice and succint ant tutorial. I’m trying to build a web application stack using struts2, spring, and mybatis with the use of ant and I really find this very helpful indeed. Again, thank you.

  27. A great tutorial. I need to export a web project to jar file. For example webapp.jar file. Also, is it possible to include jar files in lib folder to webapp.jar file???
    Thanks

  28. Hi Nitin,

    I am new to this and trying to understand a script I already have:

    I am not getting how a few variables are used when i dont see them defined as property anywhere

    Example:

    I can find above property used ‘untarpackage’ defined in the property file as 1 – so this is fine.

    BUT in following:

    In above target we are using this property ‘available.myhome.tar’ in IF but I dont see how and where it is picking it from?

  29. The following minor changes are needed to make the tutorial work:

    1) Change the src.dir’s value to src instead of com since the tutorial asked to create the directory src instead of com but the property file uses com instead of src
    2) create a dummy file web.xml inside the etc directory.

    With the above changes, the simple run of ant will create the WebApp.war.

    A good tutorial with something like the above two things to update.

    Thanks

  30. Hi Nitinpai,

    I appreciate your work.It was really very nice tutorial to give a kick start while learning ant.

    The scripts can obviously be customized easily as per accordance with particular project, but still you gave nice overview.

    Good work and Thanks a lot 🙂

  31. Very good article. Pretty straightforward.
    I think I can start using Ant just by reading this tutorial.

    Thank you very much 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *