Ant (First Steps) - Web Tutorial

by Michael Thomas

On the ANT Home page, you can download the whole ANT site (all content, tutorials & examples) !!!

Objectives

Use ANT to build your first simple java project (creates a JAR file) - delete & create directories, compile files, create JAR files and run the MAIN-CLASS in a JAR file.

Fast Track

You may want to download the whole ANT site (on the ANT Home Page) and just look at and run the examples.

List of files and brief description.

Topic	Info
Directory Structure	Directories tutorial_firststeps_ant\src - 2 simple Java Classes that output to the Java console. tutorial_firststeps_ant\build - all files that are created during a build. tutorial_firststeps_ant\build\classes - complied classes. tutorial_firststeps_ant\build\jar - JAR file
Main Example Files	tutorial_firststeps_jar - list of files ANT Files: HelloWorld_build_ant.bat - The ANT Build example!!! HelloWorld_build_ant_build.xml - The ANT build.xml file. HelloWorld_build_ant_buildoptions.bat - Optional examples of calling specific targets in the build. HelloWorld_build_ant_run_jar.bat - If you want to run the class using java.exe and not jar.exe. ANT replaces this whole process! (these files are in the download) _setpathjdk.bat - batch file to check the JAVA_HOME environment variables HelloWorld_build_1_compile.bat - compile the ".java" files. HelloWorld_build_2_jar.bat - create the ".jar" file. HelloWorld_build_2_jar_manifest.txt - the manifest.mf config file for the JAR. HelloWorld_build_3_run.bat - runs the classes HelloWorld_build_4_run_jar.bat - automatically runs the main class in the JAR.

Hello World ANT Tutorial

Remember, you can download (see top) all of the content of this Tutorial including all of the example files to save you time if you want to setup this example on your local computer.
Create the following directory structure:

tutorial_firststeps_jar
tutorial_firststeps_jar\src
tutorial_firststeps_jar\src\firststeps

Create the following 2 .java files and place them in the directory: tutorial_firststeps_jar\src\firststeps

Filename: tutorial_firststeps_jar\src\firststeps\HelloWorld1.java

package firststeps;

public class HelloWorld1 {
  public static void main(String[] args) {
    System.out.println("Hello World #1");
  }
}

Filename: tutorial_firststeps_jar\src\firststeps\HelloWorld1.java

package firststeps;

public class HelloWorld2 {
  public static void main(String[] args) {
    System.out.println("Hello World #2");
  }
}

We have 2 core files that we will create have Ant build a project: a batch file & an XML build file.
build.xml - the default config file Ant will look for to build the project.
If you don't specify an xml build file Ant will look for "build.xml". For this Tutorial we will create a build file with a different name and tell Ant to use it when we run the batch file. Also notice that a "dtd" is not used. Also, it's optional to place the following in the first line of the xml file: <?xml version="1.0"?>
Build filename: HelloWorld_build_ant.xml
Batch filename: HelloWorld_build_ant.bat

Create the following build file: HelloWorld_build_ant.xml

HelloWorld_build_ant.xml

HelloWorld_build_ant.xml - click here to view the contents so you can view the contents and cut-n-paste if needed.

Here is a repeat of the contents of the file for your viewing, but I suggest clicking the link above!

<project name="HelloWorld" basedir="." default="main">

<property name="src.dir" value="src"/>
<property name="srcfp_firststeps.dir" value="src/firststeps/_vti_cnf" description="FrontPage publishing directory."/>
<property name="build.dir" value="build"/>
<property name="classes.dir" value="${build.dir}/classes"/>
<property name="jar.dir" value="${build.dir}/jar"/>
<property name="main-class" value="firststeps.HelloWorld1"/>

<target name="clean" description="Deletes directories that the build will create.">
    <delete dir="${build.dir}"/>
    <delete dir="${srcfp_firststeps.dir}" description="FrontPage publishing directory. Errors if it's not deleted!" />
</target>

<target name="compile" description="Compiles all .java files.">
    <mkdir dir="${classes.dir}"/>
    <javac srcdir="${src.dir}" destdir="${classes.dir}"/>
</target>

<target name="jar" depends="compile" description="Creates the JAR file with a Main-Class.">
    <mkdir dir="${jar.dir}"/>
    <jar destfile="${jar.dir}/${ant.project.name}.jar" basedir="${classes.dir}">
      <manifest>
        <attribute name="Main-Class" value="${main-class}"/>
      </manifest>
    </jar>
</target>

<target name="run" depends="jar" description="Runs the main-class in the JAR file.">
    <java jar="${jar.dir}/${ant.project.name}.jar" fork="true"/>
</target>

<target name="clean-build" depends="clean,jar" description="Could clean up!"/>

<target name="main" depends="clean,run"/>

</project>

XML Build file tags & elements.
- project tag - every build file must have this tag. This also applies a name to the project.
- property tag - use these properties like a variable that holds data you want to refer to through out the build file.
  Refer to the property with: ${<property name>}
  Notice how you can build a property with the value of another property:
  <property name="build.dir" value="build"/>
  <property name="classes.dir" value="${build.dir}/classes"/>
- target tag - this is the main sections of your build file that ANT will run. You can specify and dependencies targets that must complete without errors. Also, when debugging the build file you can have Ant run specific targets (examples listed below in the file: HelloWorld_build_ant_buildoptions.bat).
  -projecthelp - this command line option will list all of the targets and the description if one exists.
  Here is the list of target sections:
```
 clean        Deletes directories that the build will create.
 compile      Compiles all .java files.
 jar          Creates the JAR file with a Main-Class.
 run          Runs the main-class in the JAR file.
 clean-build  Could clean up!
```
- target clean - deletes all of the directories that the build will create.
- target compile - creates the necessary directories under "build" directory to place the compiled classes.
- target jar - creates a JAR file with the MAIN-CLASS entry in the manifest.mf file to launch the class: firststeps.HelloWorld1
- target run - runs the MAIN-CLASS from the JAR file it created.
- target clean-build - not doing much right now but could do some cleanup in the future.
- target main - require tag and the name must match the default property of the project tag.
Create the following batch file: HelloWorld_build_ant.bat
HelloWorld_build_ant.bat
call ant -buildfile HelloWorld_build_ant.xml -projecthelp call ant -buildfile HelloWorld_build_ant.xml pause
- call ant -buildfile HelloWorld_build_ant.xml -projecthelp - reads the build file and displays info about the project.
- call ant -buildfile HelloWorld_build_ant.xml - runs all of the target tags in the build file: HelloWorld_build_ant.xml
  -buildfile - this command line option allows you to specify a file. If not specified it looks for the default: build.xml
  Ant Command Line Help - For a list of command line options

Run the batch file you just created: HelloWorld_build_ant.bat - Ant will read the build file and complete all of the target tags. For example: clean (delete directories), compile (create directories and compile), create the JAR file (and create the directory), run the main-class in the Jar, etc....

The DOS window output should look like this:

ant -buildfile HelloWorld_build_ant.xml -projecthelp                            
Buildfile: HelloWorld_build_ant.xml                                             
                                                                                
Main targets:                                                                   
                                                                                
Other targets:                                                                  
                                                                                
 clean                                                                          
 clean-build                                                                    
 compile                                                                        
 jar                                                                            
 main                                                                           
 run                                                                            
Default target: main                                                            
Buildfile: HelloWorld_build_ant.xml                                             
                                                                                
clean:                                                                          
   [delete] Deleting directory C:\_data\webs\A\michael-thomas.com\tech\apache\an
t\tutorial_firststeps_ant\build                                                 
                                                                                
compile:                                                                        
    [mkdir] Created dir: C:\_data\webs\A\michael-thomas.com\tech\apache\ant\tuto
rial_firststeps_ant\build\classes                                               
    [javac] Compiling 2 source files to C:\_data\webs\A\michael-thomas.com\tech\
apache\ant\tutorial_firststeps_ant\build\classes                                
                                                                                
jar:                                                                            
    [mkdir] Created dir: C:\_data\webs\A\michael-thomas.com\tech\apache\ant\tuto
rial_firststeps_ant\build\jar                                                   
      [jar] Building jar: C:\_data\webs\A\michael-thomas.com\tech\apache\ant\tut
orial_firststeps_ant\build\jar\HelloWorld.jar                                   
                                                                                
run:                                                                            
     [java] Hello World #1                                                      
                                                                                
main:                                                                           
                                                                                
BUILD SUCCESSFUL                                                                
Total time: 1 second                                                            
Press any key to continue . . .

Optional: Create a batch file to run the main class created by Ant using java.exe

HelloWorld_build_ant_run_jar.bat

call _setpathjdk.bat
rem Run the class defined in the manifest file created during the Jar build.
java -jar build\jar\HelloWorld.jar
pause

Optional: Running specific targets in a Build file - here is an example of calling a specific target inside of the Ant build file. This can be handy when debugging issues. Just add/remove the "rem" (comments for dos) command for the lines you want to comment out or run.

HelloWorld_build_ant_buildoptions.bat

call ant -buildfile HelloWorld_build_ant.xml -projecthelp
rem call ant -buildfile HelloWorld_build_ant.xml clean
rem call ant -buildfile HelloWorld_build_ant.xml clean compile
rem call ant -buildfile HelloWorld_build_ant.xml clean compile jar
rem call ant -buildfile HelloWorld_build_ant.xml clean compile jar run
rem call ant -buildfile HelloWorld_build_ant.xml run
rem ******** Run all of the targets in the build file *******
call ant -buildfile HelloWorld_build_ant.xml
pause

Finished - go have another cup of Java!