Apache ANT

Introduction to ANT

1. Evolution of ANT
2. What is ANT ?
3. Advantages of using ANT

Evolution of ANT

• ANT evolved from the UNIX based build utility called "MAKE".
• ANT was initially created by James Duncan Davidson as a part of TOMCAT and contributed to the Apache Jakarta Project.
• It later was promoted to an individual project under Apache
• ANT stands for "Another Neat Tool"
• Latest release of ANT is 1.7.0

What is ANT ?

1. Ant is a Java-based build tool.
2. Simply put, ANT executes tasks configured in a build XML file.
3. A task is a Java object that extends the org.apache.tools.ant.Task class.
4. To run ANT on a build.xml, the ant.bat batch file will be invoked from the <ANT_HOME>/bin folder.
5. This batch file will invoke ANT Java programs that will do the job.

What is ANT ?

1. ANT has the "lib" folder that contains the ANT Java archives (Jar) files.
• For e.g.: ant.jar contains Java classes for all built-in task definitions such as Javac, delete and so on.
2. Ant is extended using Java classes. To extend ANT, one has to write one's own Java task class that extends the org.apache.tools.ant.Task class.

Advantages of using ANT

• ANT is not OS specific unlike MAKE which is UNIX specific
• ANT executes it's tasks as JAVA programs which makes it platform independent
• ANT tasks support JAVA project structures which eases it's use with JAVA/J2EE applications
• For eg:
• Manifest in a jar file
• Web-inf in a war file
• ANT is extensible. ANT tasks can be extended to create customized tasks.
• Using ANT to build an application involves writing a simple configuration XML file. ANT will do the rest.

Advantages of using ANT

• ANT integrates well with editors such as Eclipse, IntelliJ IDEA. You may almost never need to go the command-prompt to deal with ANT.
• ANT can invoke third party plug-in tasks
• For eg : PMD which is a tool to review code can be invoked as a third party plug-in in an ANT build file.
• ANT has support from most application servers
• For eg: WebLogic app server provides a "wlserver" Ant task that enables you to start, reboot, shutdown, or connect to a WebLogic Server instance
• There is NAnt for .NET projects which works pretty much like ANT. If you know one, you know the other.

ANT basics

• Configurations for a project build are written in XML files in ANT
• To build an application, an ANT user has to write a simple configuration XML file. ANT will do the rest.
• ANT parses the build XML files using it's own JAXP compliant parser
• ANT executes tasks referred in the build XML to build an application
• Tasks are wrapped up by targets.
• The tasks are sequenced by creating dependencies amongst targets. If target B is dependant on target A, target B cannot start until and unless target A is complete.

ANT basics

1. There are an enormous number of core and optional tasks built into ANT for a variety of purposes.
2. Moreover, third party tools or application servers provide their own ANT tasks as well.
3. A custom task can be written and used in a build XML to be invoked by ANT although you may almost never need to write one.

Build XML

• Let's delve into understanding what goes into writing a build XML for a project.

Build XML - Project element

• A build XML file starts with the "Project" root element.
• Sample:

  <project name="test" default="compile" basedir=" . ">

• "name" is an optional attribute used to specify the name of the project for which the build file is being written.
• "default" is an optional attribute used to define a target that will be executed by default. If this attribute is not defined, ANT will use an implicit target to execute all top level tasks. "basedir" attribute is used to define a base directory which will be a start point for all paths in the XML. In case this attribute is not defined, the parent directory of the build XML will be taken as the "basedir".
• A "project" has one or more "target" elements within it.

Build XML - Target element

• A "target" is a bunch of "tasks" that need to be executed.
• Sample:
  <target name="A"/>
• "name" attribute is mandatory and indicates the name of the target

Build XML - Target element

• This target has tasks to compile web components.
• javac
• copy

						<target name="compile-web">
     <javac srcdir="${src}" destdir="${build}">
           <include name="**/web/**"/>        
     </javac>            
     <copy todir="${build}">
     	<fileset dir="web">
        	<include name="**/*.properties" />
      	</fileset>
    </copy>
</target>
							
						

Build XML - Target element

• A "target" can depend on one or more "targets".
• The dependencies on other target(s) for a target is defined using the "depends" attribute.
• ANT will decide the order of processing of targets in a build XML using these dependencies between targets.
• In this example,
• "compile" depends on "init"
• "package" depends on "compile" and "copyFiles"

Build XML - Target element

						<target name="init">
    ....
</target>
<target name="copyFiles">
  ....
</target>
<target name="compile" depends="init">
	....
</target>
<target name="package" depends="compile, copyFiles">
	....
</target>
						

Build XML- Target element

• A target can get executed earlier when an earlier target depends on it
• Sample

							<target name="A"/> 
<target name="B" depends="A"/> 
<target name="C" depends="B"/> 
<target name="D" depends="C,B,A"/>
							

• Here D depends on C,B and A, C depends on B, and B depends on A. So first A is executed, then B, then C, and finally D.

BUILD XML- TARGET ELEMENT

• A target will get executed only once even if it is referenced by multiple targets
• Sample

							<target name="A"/> 
<target name="B" depends="A"/> 
<target name="C" depends="B"/> 
<target name="D" depends="C,B,A"/>
							

• Here D depends on B and C depends on B. Yet B will be executed only once.

BUILD XML- TARGET ELEMENT

• "if" and "unless" rules on a target
• The execution of a target can be forced to depend on a property using the "if" attribute " or the "unless" attribute
• A target will execute if the property in it's "if" attribute is set.
• Sample:

<target name="compileEJB" if="EJBModule"/>

-The target "compileEJB" will be executed only if the property "EJBModule" has some value in the build XML. The value could be even an empty string.

Build XML- Target element

• A target will not execute if the property in it's "unless" attribute is set.
• Sample:

								<target name="compileAllModules" unless="ModuleList"/>

• The target "compileAllModules" will be executed only if the property "ModuleList" is not set.
• If "depends" and "if/unless" are set on a target, the "depends" will executed first

Build XML - Task element

• A task is a program that can be executed.
• A task will look like this :

					<taskname attribute1="value1" attribute2="value2".....attributeN="valueN"/>

Build XML - Task element

• Sample

						<javac srcdir="${src}" destdir="${build}" source="${source.version}" target="${target.version}">
      <include name="**/appclient/**"/>
  		<exclude name="**/*.properties" />
      <classpath refid="classpath" />
 </javac>

• Javac is a task with attributes such as "srcdir".
• The task supports elements within it such as "include" and "exclude".
• This task is a JAVA class in ant.jar under "lib" directory of ANT under the package "org.apache.tools.ant.taskdefs".

Build XML- Properties

• There is a need to refer to the code directory structure in the build XML
• Environment specific data such as JDK_HOME, application server installation location, database URL, server IP, port may be referenced in the build tasks.
• External property files may need to be referenced in the build XML.
• System properties such as java.home, os.name may be required in the build XML.
• ANT properties cater to all these needs and much more.

Build XML- Properties

• Properties are name-value pairs.
• Properties can be set in an ANT build file by
  • using a task called "property" under the "project" element
  • Sample:

  <property name="libDirectory" value="./lib"/>

  • using a separate properties file with name value pairs and referencing the file in the build file.

  <property file="../common/build.properties"/>

Build XML- Properties

• Property values can be accessed in the build XML using the "${propertyName}" syntax
• For eg : If a property is defined like this,
compileDir=build\bin
• then, this task

	<echo>${compileDir}</echo>

• will print out

Build XML- Properties

• Built-in properties
• Ant provides access to all system properties(such as os.name and java.home) and ANT specific properties (such as basedir and ant.home) as if they had been defined using a <property> task.
• For example, ${os.name} expands to the name of the operating system.

Build XML- Properties

• Notes about ANT properties
• Properties are case sensitive.
• Properties once set for a build cannot be changed again
• Multiple ways to define properties
• This sets the property value to a property

<property name="propertyName" value="propertyValue"/>

• This reads the property file mentioned in the "file" attribute

<property file="./config/file1.properties"/>

• This reads the properties at the mentioned URL

<property url="http://www.site.com/prop/site.properties"/>

Build XML- Properties

Continued

• This reads the properties at the mentioned resource

<property resource="org/apache/tools/ant/taskdefs/file1.properties"/>

• A property can refer to another property using the "refid" attribute

Referred property :<property name="try" value="tryValue" id="tryId"/>
Referring property :<property name="tryAgain" refid="tryId"/>

Build XML- Properties

• In-file property expansion is very useful.
• Sample:

						build.compiler=jikes 
deploy.server=localhost 
deploy.port=8080
deploy.url=http://${deploy.server}:${deploy.port}/

Steps in a build XML

• Get the source. You may need to download or fetch the source from a source code repository. For this, you might need to know the tag or version of the source code you want to build.
• Prepare a build area. You will probably want to create a set of directories, perhaps according to some standard directory structure.
• Configure the build. In this step, you will determine what optional components can be built based on the current environment.

Steps in a build XML(continued)

• Compile the source code
• Build the compiled code into libraries
• Deploy the software
• Validate the source code with a standard style guide
• Run the system's tests to validate the build
• Build the documentation for the software
• All along these steps, all relevant properties files must be updated

Implementing the steps

• Get the source. You may need to download or fetch the source from a source code repository. For this, you might need to know the tag or version of the source code you want to build.

Demo 0 - CVS and build

• TO DO

Implementing the steps (contd)

• Prepare a build area. You will probably want to create a set of directories, perhaps according to some standard directory structure.
• Configure the build. In this step, you will determine what optional components can be built based on the current environment.

Implementing the steps (contd)

• Compile the source code

Some useful ANT Tasks - File tasks

• File Tasks
• Copy - copies files or directories to another file or directory
• Delete - deletes files or directories
• Filter - sets a token filter for a project
• Mkdir - creates a directory
• Move - Moves files or directories to another file or directory

Some useful ANT Tasks - Compile tasks

• Compile Tasks
• Javac
• Compiles the specified source file(s) within the running (Ant) VM, or in another VM if the fork attribute is specified
• "srcdir" - location of java files
• "destdir" - location where class files need to be kept

<javac srcdir="${src}" destdir="${build}" source="1.4" target="1.5">    	
	<include name="**/exception/*"/>           
	<classpath refid="classpath" />     
</javac>

Some useful ANT Tasks - Compile tasks

• "source" - the java version of the source files
• "target" indicates java version of class files to be generated
• include and classpath elements help to define what files to include in he compile activity and the classpath for the compile activity

<javac srcdir="${src}" destdir="${build}" source="1.4" target="1.5">    	
	<include name="**/exception/*"/>           
	<classpath refid="classpath" />     
</javac>

Some useful ANT Tasks - Execution Tasks

• ANT has a vast set of built-in tasks.
• However, when a third party framework or a tool tries to bring in compatibility with ANT, it provides ANT tasks that help build or use it's code.
• For e.g. : "net.sourceforge.pmd.ant.PMDTask" class is available as a part of the PMD jar which is a code review tool

Some useful ANT Tasks - Execution Tasks

• To use a PMD task, you would need to do this

<taskdef name="pmd" classname="net.sourceforge.pmd.ant.PMDTask" classpathref="pmdClasspath" />
	<pmd shortFilenames="true">
	<ruleset>rulesets/imports.xml</ruleset>
	<formatter type="html" toFile="PMDReport/pmd_report.html" linkPrefix="http://pmd.sourceforge.net/xref/" />
	<fileset dir="${src}">
	<include name="**/*.java" />
	</fileset>
</pmd>

Some useful ANT Tasks - Execution Tasks

• TypeDef
  • Adds a task or a data type definition to the current project such that this new type or task can be used in the current project.
  • We already know tasks
  • Data types are things like paths or filesets
  • Sample:
  typedef name="urlset" classname="com.mydomain.URLSet"/>
  • The data type "urlset" is now available to Ant. The class com.mydomain.URLSet implements this type.

Some useful ANT Tasks - Execution Tasks

• TypeDef
  • Is a form of TypeDef
  • Adds a task definition to the current project, such that this new task can be used in the current project.
  • Sample

    <taskdef name="pmd" classname="net.sourceforge.pmd.ant.PMDTask" classpathref="pmdClasspath" />

    makes a task called pmd available to Ant. The class net.sourceforge.pmd.ant.PMDTask implements the task.

Some useful ANT Tasks - Execution Tasks

• There may be a need to execute system commands from within a build file.
• Files ending with .exe, .cmd, .bat and other files in the PATHEXT environment variable can be executed from an ANT build file.
• ANT provides execution tasks to do this such as "exec" to do this.

Some useful ANT Tasks - Execution Tasks

• Exec
• Executes a system command
• Sample:

<target name="exec">
	<exec executable="ant.bat">
		<arg line="-buildfile FirstBuild.xml" />
	</exec>		
</target>

Some useful ANT Tasks - Execution Tasks

• There may be a need to pass parameters to a target while it is getting invoked in an ANT build script.
• ANT provides execution tasks to achieve this such as "ANTCALL".

Some useful ANT Tasks - Execution Tasks

• AntCall
• It helps execute a target inside a build file by passing parameters to it.
• Must not be used outside a target
• Sample

<target name="default"> 
	<antcall target="echoMessage"> 
		<param name="param1" value="value"/> 
	</antcall> 
</target> 
<target name=" echoMessage "> 
	<echo message="param1=${param1}"/> 
</target>

Some useful ANT Tasks - Execution Tasks

• The ant.bat effect can be obtained using the "ant" execution task.
• The "ant" execution task helps execute a build file which is the same as executing the ant.bat file.
• Can be used to modularize a build script.
• One maina build can be written for the whole project.
• One build each can be written for each sub module in the project.
• The main build can invoke each sub build.
• Sample :

<ant antfile="subproject/subbuild.xml" target="compile"/>

Some useful ANT Tasks - Execution Tasks

• These 2 targets have the same effect :

<target name="exec">
		<exec executable="ant.bat">
			<arg line="-buildfile FirstBuild.xml" />
		</exec>		
	</target>
	<target name="ant">
		<ant antfile="FirstBuild.xml" />
	</target>

Some useful ANT Tasks - Execution Tasks

• Java
• Executes a Java class within the running (Ant) VM or forks another VM if specified

<java classname="test.Main"> 
	<arg value="-h"/> 
	<classpath> 
		<pathelement location="dist/test.jar"/> 
	</classpath> 
</java>

Exercise 1 :

• Write simple ANT build file to prepare, compile EJB, compile Web
• Refer to exercise document for more details

Implementing the steps (contd)

• Build the compiled code into libraries

Some useful ANT Tasks - Archive Tasks

• Archive Tasks
• Jar
• This task helps to create Java archives.
• Sample :

<jar destfile="${dist}/lib/app.jar"> 
	<fileset dir="${build}/classes" excludes="**/T.class" /> 
</jar>

• The manifest file to use in the jar can be specified using a "manifest" attribute.
• Alternately, manifest details can be provided inline using the manifest element.

Some useful ANT Tasks - Archive Tasks

• Ear
• This task is an extension of the jar task
• It helps create enterprise archives
• Sample :

  <ear destfile="build/myapp.ear" appxml="src/metadata/application.xml"> 
  	<fileset dir="build" includes="*.jar,*.war"/>
  </ear>

• The application XML to use can be specified here using the "appxml" attribute

Some useful ANT Tasks - Archive Tasks

• War
• An extension of jar that creates web application archives
• Files in WEB-INF/lib, WEB-INF/classes and WEB-INF will be "warred".
• Sample :

<war destfile="myapp.war" webxml="src/metadata/myapp.xml"> 
	<fileset dir="src/html/myapp"/> 
	<lib dir="thirdparty/libs"> 
		<exclude name="jdbc1.jar"/>
	</lib> 
	<classes dir="build/main"/> 
	<zipfileset dir="src/gifs" prefix="images"/>

Some useful ANT Tasks - Archive Tasks

• Zip and Tar
• These help create archives such as .zip and .tar
• Unzip, Unjar, Untar, Unwar
• These help unzip a zip, war, jar or tar file.

Demo 2 : Package and deploy an enterprise application

• package EJB
• package Web
• package app client
• package EAR
• deploy onto JBOSS
• import earlier build file into this one for compile activities.
• SecondBuild.xml, jboss-build.properties

Exercise 2

• Package EJB into a jar.
• Package WEB into a war
• Package the jars and wars into an ear
• Deploy onto JBOSS
• import earlier build file into this one for compile activities.

Implementing the steps (contd)

• Validate the source code with a standard style guide
• Run the system's tests to validate the build
• Build the documentation for the software

Some useful ANT Tasks

• EJB Tasks
• Ejbjar - This task is designed to support building of EJB jar files. Supports major application servers such as WL, JBoss, Iplanet, WS
• Specific tasks are written to support WebLogic app server
• Ejbc
• Wlrun
• Wlstop

• Deployment Tasks
• ServerDeploy
• The serverdeploy task is used to run a "hot" deployment tool for vendor-specific J2EE server.
• The task requires nested elements which define the attributes of the vendor-specific deployment tool being executed.

Some useful ANT Tasks

• Mail Tasks
• Mail - Send SMTP mail
• Testing Tasks
• Junit - runs tests from the JUnit testing framework
• JunitReport - Merge the individual XML files generated by the JUnit task and eventually apply a stylesheet on the resulting merged document to provide a browsable report of the testcases results.
• Remote Tasks
• FTP - implements a basic FTP client that can send, receive, list, delete files, and create directories
• Telnet - Task to automate a remote telnet session

Some useful ANT Tasks

• Documentation Tasks
• Javadoc - Generates code documentation using the javadoc tool
• SCM Tasks
• Has support to integrate with
  • Cvs
  • ClearCase
  • Continuus
  • Microsoft Visual SourceSafe
  • Perforce
  • Pvcs
  • SourceOffSite
  • StarTeam

Some useful ANT Tasks

• Miscellaneous Tasks
• Echo - Echoes a message to the current loggers and listeners. Level of echo can be set such as error, debug, warning etc
• Fail - used to exit the current build based on some condition
• Input - Allows user interaction during the build process by prompting for input
• Sql - Executes a series of SQL statements via JDBC to a database
• Tstamp - sets the standard DSTAMP, TSTAMP, and TODAY properties according to the default formats
• XmlValidate - checks that XML files are valid (or only well formed).

Iterative improvement of build script

• All of what we do in a build script is not done on day one.
• A build script must evolve based on needs
• If the application is to be setup on a new environment, then environment specific code has to be added to the build script
• If the deployment architecture changes, then modularization of the code will change which will involve build script changes.
• As new modules are added to the code, the build script will evolve.
• If a new web service is added to the code, build script will have to be updated.

Iterative improvement of build script (contd)

• Testing tasks, documentation tasks, remote tasks, SCM tasks will all be added as iterative improvement to the build.

ANT best practices

• Make a build XML readable
• Targets should be meaningful
• Keep the build XML formatted always
• Document the build well through XML comments or target descriptions
• Put build.xml in the top-level project directory. This simplifies all relative path references to all other directories in the build.xml simple.
• It may be a good idea to break up a large build file into smaller logical build files invoked by a master build xml in the root directory. However, do not over-engineer.

ANT best practices (contd)

• Provide a "clean" target that will clean up the directory structure and bring it to it's original state. Make this an independent target.
• Build in a pyramid structure. Build the utilities and shared code first. Create a jar out of it. Build the next layer of code using the utility jar's. Create a jar out of this layer. Continue with other layers similarly. This enforces the right dependencies in the code. For e.g. : An EJB will never use a servlet. If it does, the build will throw an error when the EJB jar is being compiled and created (because the dependent servlet jar will not have been created yet)

ANT best practices (contd)

• Reuse paths in the build file.
• Define dependencies on targets aptly. Too many dependencies will slow down the build. Too few may cause the programmer to do more work in invoking targets and is also error prone.
• Use a separate properties file for configurable information
• Do not refer to system paths in the build such as "c:/tempDir". If there is a need to do this, use a separate properties file.
• Always version control your build and tag it along with the rest of the code.
• Programmers can use any IDE they want as long as they use the common build file for building.

ANT best practices (contd)

• Ensure that your build file only compiles if the source has changed. This will take you a long way in optimizing the build time.

Environment specific properties

• Use default and overridable properties files
• Default will have all properties with default values.
• Some of these will be overridden in the overridable properties file.
• Be sure to load the overridable properties file before the default in the build XML (because properties are immutable)

Environment specific properties (contd)

• There could be innumerable types of properties in your application
• application based - users.properties
• Tool based - log4j.properties
• Database related - connection.properties
• Build related - build.properties
• Ant properties
• system properties

Environment specific properties (contd)

• Identify the environment specific ones and arrive at a strategy on how they will be maintained environment-wise
• Whether multiple files will exist - one for each environment
• One file will exist and build will create a new temporary environment specific file every time.
• Any other strategy ??