Ant Tutorial: Our First Project with Apache Ant!

The prerequisites for this project can be found here.

The aim of this tutorial is to build a simple project that prints "Hello World" using eclipse. We will use Ant to compile the source code in the src folder and create the binaries in the dst folder. At the end of this project we will have a SayHello.class file in the dst folder that can be executed using $java SayHello

Create a project called ANT_HelloWorld
Create The Java Class to be executed:
Next, create a java class SayHello in the package com.abhi.tutorials. Lets just have a simple static main method that prints the magic words "Hello World!". The file now looks like this..

Ant:Hello World

The Build.xml file:
Pretty Easy! Huh! Now the ant file build.xml .What's build.xml? Its just the file that the ant command looks for when ant command is called from the prompt.
Create a build.xml file under the ANT_HelloWorld folder. Right click on the build.xml file and open it with Ant Editor. The following screen shots should help you out!

Ant: Open With Ant Editor-1

Ant: Open With Ant Editor-2

Writing The Ant Script:
Type the following ant script in the build.xml . You can ignore the first line since it will be auto generated by eclipse for you.
```
<?xml version="1.0" encoding="UTF-8"?>
<project name="SayHello" default="compile" basedir=".">
 <target name="compile">
  <javac srcdir="./src" destdir="./dst" /> 
 </target>
</project>
```
Don't worry if you don't understand what each line means! We'll see them one by one in the coming sections. Don't copy-paste the code but type them. It'll force your brain to register each and every token you type.

Executing the Ant Script:
Done Typing? Now open a command prompt and go to the directory ANT_HelloWorld. Check out this post for a handy short cut. And type ant and Enter. You must see the following output.
```
  
```
```
1:  C:\abtutorials\ANT_HelloWorld>ant  
2:  Buildfile: C:\abtutorials\ANT_HelloWorld\build.xml  
3:  compile:  
4:  BUILD FAILED  
5:  C:\abtutorials\ANT_HelloWorld\build.xml:4: destination directory "C:\abtutorials\ANT_HelloWorld\dst"  
6:   does not exist or is not a directory  
7:  Total time: 0 seconds  
```
Hmmm....Lets see what happened here line by line...
Line 1: The ant command typed. Nothing much here...
Line 2: Its saying the build file is build.xml in our project direrctory.
Line 3: The word compile with a colon Hey! That's familiar . We had that in the target tag in our build.xml
Line 4: Whoops! It says the build failed. But Why??
Line 5 and Line 6: It says the destination directory "C:\abtutorials\ANT_HelloWorld\dst" does not exist! Its also having a :4 printed after the build.xml. That number, my friend is the line number in build.xml where this error is occurring.
Line 7: Total time taken to run the script is 0 seconds...

Anatomy of the Ant Script:
Now's the time we'll analyze the build.xml script indepth. By this time you would have figured out some stuff going on behind the scene. Also we'll fix the problem that occurred in the previous step.
Here's the build script again!
```
<?xml version="1.0" encoding="UTF-8"?>
<project name="SayHello" default="compile" basedir=".">
 <target name="compile">
  <javac srcdir="./src" destdir="./dst" /> 
 </target>
</project> 
```
Line 1: That's an xml declaration. We wont be discussing about it much. As of now just have it in your mind that all XML files have this declaration as the first line.

Line2: That's the project tag. Each build.xml file should have one and only one of this.
This tag has these attributes :
name: I have decided to name this project as "SayHello". You can name it anything you want.
default: This attribute specifies the default target that needs to be executed when we type ant in the command prompt. What's a target? Its a bundle of logical operations or tasks that we use to build our project.
basedir: Any guesses, what this is? Yes, this is the base directory. It acts as a starting point for referring to other directories, something I have used in the coming lines in this file.See that "./src" and "./dst"? What is the base directory in our case? Its the single dot, "." meaning the current folder, in our case its the ANT_HelloWorld folder.

Line 3: The target tag. I'll repeat it again for you.. Its a bundle of logical operations or tasks that we use to build our project.In our example, we have a single attribute - name. We can have a number of targets under the project tag. Also, there a few other attributes and one of the most used attributes after name is called the depends attribute which we will discuss shortly.

Line 4: The javac tag with attributes srcdir and destdir. Pretty easy to figure out... Here javac
is called a task in ant terminology. What is a task? Coming straight from the Apache Ant User manual, the definition goes like this:
Task : A task is a piece of code that can be executed.
There are many other tasks which ant has to make our lives easier. We'll see some of them later.
Coming back to the javac task at hand, we have 2 attributes:
srcdir: The source directory where the java files are present. We have it as "./src" which is nothing but the folder ANT_HelloWorld/src , the place where our SayHello.java resides.
destdir: Yep, the destination directory. In our case its ANT_HelloWorld/dst.

But!Hey! Where's that directory? It doesn't exist! That's the reason ant complained "destination directory "C:\abtutorials\ANT_HelloWorld\dst" does not exist or is not a directory" Thats the root of our problem...
We'll correct this in the next step..
The rest of the lines are just ending tags of target and project.
Correct the Ant Script:
Lets solve the build error. For this we will create another target and name it as clean. The clean target will perform two tasks for us.
A. The first task is to remove the directory "./dst" which will clear the old class files. For this we'll use the delete task. No, it wont throw any error if the directory to be deleted doesn't exist.
B. Next is to create the directory "./dst" itself. We'll use the mkdir task for this.
The build file after adding the clean target looks like this....
```
<?xml version="1.0" encoding="UTF-8"?>
<project name="SayHello" default="compile" basedir=".">
 <target name="clean">
  <delete dir="./dst" />
  <mkdir dir="./dst" />
 </target>
 <target name="compile" >
  <javac srcdir="./src" destdir="./dst" />
 </target>
</project>
```
Now wait up! We aren't finished yet..
We need to link up the two targets compile and clean. The so that the clean target executes before the compile.
We now add the depends attribute to the compile target with its value set to clean. What does this mean?
It means , the compile target should execute after the clean target is executed. The execution chain will be clean --> compile even when compile is the default target.
The complete build file without any errors is below:
```
<?xml version="1.0" encoding="UTF-8"?>
<project name="SayHello" default="compile" basedir=".">
 <target name="clean">
  <delete dir="./dst" />
  <mkdir dir="./dst" />
 </target>
 <target name="compile" depends="clean">
  <javac srcdir="./src" destdir="./dst" />
 </target>
</project>
```

Rebuild:
Now we'll run the build file as we did before.Go to the folder ANT_HelloWorld and type ant. You will see the following output as in the screenshot below.

Ant execution after Correction

Note that the delete task is not being called. That's because there's no directory named dst as yet to be deleted. If you run the same ant command again the delete task will show up.

Now go ahead and run the class SayHello by going to the dst directory. The sample run is shown below.....

Sample Run

Calling the target in the ant command :
Before we end this tutorial. I would like to show one more thing... We can call a desired target from the ant command itself. In the following screen we call the clean target directly..

Notice that the only clean target gets executed.

Hope this tutorial helped you in getting a kick start in your ant learning!

Abhi

Wednesday, October 31, 2012

Ant Tutorial: Our First Project with Apache Ant!

2 comments:

Total Pageviews