=======================================================================
Java Program Compilation with Ant                              May 2006
=======================================================================

What is Ant?
---------------------

Ant is a platform-independent scripting tool that lets you construct
your build scripts in much the same fashion as the "make" tool in
C or C++. Ant support a large number of built-in tasks including
creation/removal of directories, copying files from one
location to another, and compilation of java sourc code files.

Many of the compilation details, such as the setting of the classpath
can be embedded in the scripting file itself.

Where can I get Ant?
---------------------

See http://ant.apache.org/resources.html

=======================================================================
Example 1. Apples: Fruit and Computers
=======================================================================

Let's consider a program that draws upon classes in two
packages. The directory and source code file names are:

Package                  Directory and Source Code
--------------------------------------------------
Base directory
        package fruit 
                         /fruit/Apple.java
                         /fruit/Orange.java
        package computer 
                         /computer/Apple.java
--------------------------------------------------

The details of Apple.java and Orange.java are as follows:

/*
 *  ===================================================
 *  Apple.java: An apple is a piece of fruit...
 *  ===================================================
 */ 

package fruit;

public class Apple {

      // Constructor

      public Apple() {}

      // Return description the fruit...

      public String toString() {
         String s = "An Apple is a type of Fruit!!!";
         return s;
      }

      public static void main ( String [] args ) {
         Apple a = new Apple();
         System.out.println( a );
      }
}

/*
 *  ===================================================
 *  Orange.java: An orange is a piece of fruit...
 *  ===================================================
 */ 

package fruit;

public class Orange {

      // Constructor

      public Orange() {}

      // Return description the fruit...

      public String toString() {
         String s = "An Orange is a type of Fruit!!!";
         return s;
      }

      public static void main ( String [] args ) {
         Orange a = new Orange();
         System.out.println( a );
      }
}

For the computer package, Apple.java contains:

/*
 *  ===================================================
 *  Apple.java: Apple is a computer company ....
 *  ===================================================
 */ 

package computer;

public class Apple {

      // Constructor

      public Apple() {}

      // Return description the fruit...

      public String toString() {
         String s = "Apple is a computer company!!!";
         return s;
      }

      public static void main ( String [] args ) {
         Apple a = new Apple();
         System.out.println( a );
      }
}

The key point here is the Apple.java appears in both packages!
Finally, we have a test program that imports both packages
and then calls methods in the appropriate classes.

Here are the test program details:

/*
 *  ===================================================
 *  TestApple.java: The Apple Test program ....
 *  ===================================================
 */ 

import fruit.*;
import computer.*;

public class TestApple {
      public static void main ( String [] args ) {

         // Create an apple using the complete path name...

         fruit.Apple a = new fruit.Apple();
         System.out.println( a );

         // Create an orange using the abbreviated path name.

         Orange or = new Orange();
         System.out.println( or );

         // Create an apple computer object .....

         computer.Apple c = new computer.Apple();
         System.out.println( c );
      }
}

==============================================================

Standard Approach to Program Compilation
----------------------------------------

First we set the classpath to the base directory: 

   setenv CLASSPATH $PWD

Then simply type:

   javac TestApple.java

The files before and after compilation are as follows:

   Before Compilation              After Compilation
   -------------------------------------------------
   TestApple.java                     TestApple.java
   fruit/Apple.java                 fruit/Apple.java
   fruit/Orange.java               fruit/Orange.java
   computer/Apple.java           computer/Apple.java
                                     TestApple.class
                                   fruit/Apple.class
                                  fruit/Orange.class
                                computer/Apple.class
   -------------------------------------------------

Running the program
---------------------

   java TestApple

Basic Program Compilation with Ant
----------------------------------------

Now let's repeat the compilation, but this time use a buildfile
and ant. The details of "build.xml" are as follows:

<project>

    <target name="clean">
        <delete dir="build"/>
    </target>

    <target name="compile">
        <mkdir dir="build/classes"/>
        <javac srcdir="fruit" destdir="build/classes"/>
    </target>

    <target name="jar">
        <mkdir dir="build/jar"/>
        <jar destfile="build/jar/Fruit.jar" basedir="build/classes">
            <manifest>
                <attribute name="Main-Class" value="fruit.Apple"/>
            </manifest>
        </jar>
    </target>

    <target name="run">
        <java jar="build/jar/Fruit.jar" fork="true"/>
    </target>

</project>

This script file has four targets:

   clean   -- remove the contents of the build directory
   compile -- compile the source code files
       jar -- generate jar files from the class files
       run -- execute the program (needs a manifest file).

Compiling the Program
---------------------

To compile the program, just type:

Script started on Sun May  7 10:59:08 2006
prompt >>
prompt >> ant compile
Buildfile: build.xml

compile:
    [mkdir] Created dir:
            /Users/austin/ence200.d/java.d/package-and-ant.d/build/classes
    [javac] Compiling 2 source files to
            /Users/austin/ence200.d/java.d/package-and-ant.d/build/classes

BUILD SUCCESSFUL
Total time: 2 seconds
prompt >>

The file structure after compilation is:

prompt >> ls -lsR
total 40
16 -rw-r--r--   1 austin  austin  7036 May  7 10:57 README.txt
 8 -rw-r--r--   1 austin  austin   693 May  7 10:28 TestApple.java
 0 drwxr-xr-x   3 austin  austin   102 May  7 10:59 build
 8 -rw-r--r--   1 austin  austin   593 May  7 10:39 build.xml
 0 drwxr-xr-x   4 austin  austin   136 May  7 10:28 computer
 0 drwxr-xr-x   4 austin  austin   136 May  7 10:54 fruit
 8 -rw-r--r--   1 austin  austin    25 May  7 10:28 mainclass.mf

./build:
total 0
0 drwxr-xr-x   3 austin  austin  102 May  7 10:59 classes

./build/classes:
total 0
0 drwxr-xr-x   4 austin  austin  136 May  7 10:59 fruit

./build/classes/fruit:
total 16
8 -rw-r--r--   1 austin  austin  437 May  7 10:59 Apple.class
8 -rw-r--r--   1 austin  austin  439 May  7 10:59 Orange.class

./computer:
total 16
8 -rw-r--r--   1 austin  austin  540 May  7 10:28 Apple.class
8 -rw-r--r--   1 austin  austin  542 May  7 10:28 Apple.java

./fruit:
total 16
8 -rw-r--r--   1 austin  austin  538 May  7 10:28 Apple.java
8 -rw-r--r--   1 austin  austin  544 May  7 10:28 Orange.java
prompt >>
prompt >> exit
Script done on Sun May  7 10:59:41 2006

Creating Jar files
---------------------

Just type:

    prompt >> ant jar

The compilation output and abbreviated file structure is as follows:

Script started on Sun May  7 11:06:05 2006
prompt >> ant jar
Buildfile: build.xml

jar:
    [mkdir] Created dir:
            /Users/austin/ence200.d/java.d/package-and-ant.d/build/jar
      [jar] Building jar:
            /Users/austin/ence200.d/java.d/package-and-ant.d/build/jar/Fruit.jar

BUILD SUCCESSFUL
Total time: 1 second
prompt >> 

prompt >> ls -lsR
total 40
 0 drwxr-xr-x   4 austin  austin   136 May  7 11:06 build

./build:
total 0
0 drwxr-xr-x   3 austin  austin  102 May  7 10:59 classes
0 drwxr-xr-x   3 austin  austin  102 May  7 11:06 jar

./build/jar:
total 8
8 -rw-r--r--   1 austin  austin  1242 May  7 11:06 Fruit.jar

prompt >>
prompt >> exit
Script done on Sun May  7 11:06:34 2006

To run the program:
---------------------

    prompt >> ant run

This generates the output:

Script started on Sun May  7 11:09:39 2006
prompt >> ant run
Buildfile: build.xml

run:
     [java] An Apple is a type of Fruit!!!

BUILD SUCCESSFUL
Total time: 1 second
prompt >>
prompt >> exit
Script done on Sun May  7 11:09:47 2006

The equivalent keyboard command is:

    prompt >> java -jar build/jar/Fruit.jar

Compile, jar and run 
---------------------

All three steps can be achieved in one step:

    prompt >> ant compile jar run

=======================================================================
