Apache Ant

Apache ANT : Apache ANT www.scmGalaxy.com scmGalaxy Author: Rajesh Kumar info@scmGalaxy.com

Course Objectives : www.scmGalaxy.com scmGalaxy Course Objectives Understand the need for ANT in configuration management Understand when to use ANT Be able to write a build file for an enterprise application using common ANT tasks Understand how to use ANT tasks to deploy an application on an application server Understand how to iteratively improve build scripts

Expectations : www.scmGalaxy.com scmGalaxy Expectations My expectations Ensure that you are able to read and understand an ANT build XML Ensure you are able to write an ANT build file that completes all tasks starting from getting the latest from a repository to deploying an application on an app server Ensure you are able to deploy on JBOSS using ANT build script Ensure you understand continuously improvement of a build script Your expectations ?

Objectives of a build tool : www.scmGalaxy.com scmGalaxy Objectives of a build tool To enable conversion of source code into executable code To provide facilities to compile and link multiple files in the right order based on dependencies between the files To have an option to recompile a file only if necessary To be able to compile large number of files in a relatively short time Examples – Make, ANT, Scons (better version of Make utility)

Introduction to ANT : www.scmGalaxy.com scmGalaxy Introduction to ANT Evolution of ANT What is ANT ? Advantages of using ANT

Evolution of ANT : www.scmGalaxy.com scmGalaxy 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 ? : www.scmGalaxy.com scmGalaxy What is ANT ? Ant is a Java-based build tool. Simply put, ANT executes tasks configured in a build XML file. A task is a Java object that extends the org.apache.tools.ant.Task class. To run ANT on a build.xml, the ant.bat batch file will be invoked from the /bin folder. This batch file will invoke ANT Java programs that will do the job.

What is ANT ? : www.scmGalaxy.com scmGalaxy What is ANT ? 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. 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy ANT basics There are an enormous number of core and optional tasks built into ANT for a variety of purposes. Moreover, third party tools or application servers provide their own ANT tasks as well. 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 : www.scmGalaxy.com scmGalaxy Build XML Let’s delve into understanding what goes into writing a build XML for a project.

Build XML - Project element : www.scmGalaxy.com scmGalaxy Build XML - Project element A build XML file starts with the “Project” root element. Sample: “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 : www.scmGalaxy.com scmGalaxy Build XML – Target element A “target” is a bunch of “tasks” that need to be executed. Sample: “name” attribute is mandatory and indicates the name of the target

Build XML– Target element : www.scmGalaxy.com scmGalaxy Build XML– Target element This target has tasks to compile web components. javac copy

Build XML– Target element : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy Build XML– Target element This means that “init” will be executed first even before “compile” This means that ANT will execute “compile” first and “copyFiles” next before executing “package”. … … … …

Build XML– Target element : www.scmGalaxy.com scmGalaxy Build XML– Target element Some rules to follow while defining targets ANT will execute the targets defined in the “depends” attribute from left to right Sample … Here “compile” will get executed first and then “copyFiles”

Build XML– Target element : www.scmGalaxy.com scmGalaxy Build XML– Target element A target can get executed earlier when an earlier target depends on it Sample 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 : www.scmGalaxy.com scmGalaxy Build XML– Target element A target will get executed only once even if it is referenced by multiple targets Sample Here D depends on B and C depends on B. Yet B will be executed only once.

Build XML– Target element : www.scmGalaxy.com scmGalaxy 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: 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 : www.scmGalaxy.com scmGalaxy Build XML– Target element A target will not execute if the property in it’s “unless” attribute is set. Sample: 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 : www.scmGalaxy.com scmGalaxy Build XML– Task element A task is a program that can be executed. A task will look like this :

Build XML– Task element : www.scmGalaxy.com scmGalaxy Build XML– Task element Sample 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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: using a separate properties file with name value pairs and referencing the file in the build file.

Build XML– Properties : www.scmGalaxy.com scmGalaxy 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 ${compileDir} will print out build\bin

Build XML– Properties : www.scmGalaxy.com scmGalaxy 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 task. For example, ${os.name} expands to the name of the operating system.

Build XML– Properties : www.scmGalaxy.com scmGalaxy 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 This reads the property file mentioned in the “file” attribute This reads the properties at the mentioned URL This reads the properties at the mentioned resource A property can refer to another property using the “refid” attribute Referred property : Referring property:

Build XML– Properties : www.scmGalaxy.com scmGalaxy 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}/

Discussion : www.scmGalaxy.com scmGalaxy Discussion What do you think are the steps that ought to exist in a build XML if a project has to be built ? The build file must start from getting the latest source code from a repository The build file must end with deployment on an app server.

Steps in a build XML : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy Demo 0 – CVS and build TODO

Implementing the steps (contd) : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy Implementing the steps (contd) Compile the source code

DEMO 1 –Compile an application : www.scmGalaxy.com scmGalaxy DEMO 1 –Compile an application Prepare Compile EJB classes Compile Web classes Compile application client classes E:\training_material\BuildAndRelease\app\BuildAndReleaseDemo\FirstBuild.xml E:\training_material\BuildAndRelease\app\BuildAndReleaseDemo\build.properties

Some useful ANT Tasks – File tasks : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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

Some useful ANT Tasks – Compile tasks : www.scmGalaxy.com scmGalaxy 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

Some useful ANT Tasks - Execution Tasks : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks - Execution Tasks To use a PMD task, you would need to do this rulesets/imports.xml ANT provides execution tasks such as “taskdef” and “typedef” to help execute these tasks.

Some useful ANT Tasks - Execution Tasks : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks - Execution Tasks TaskDef 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 makes a task called pmd available to Ant. The class net.sourceforge.pmd.ant.PMDTask implements the task.

Some useful ANT Tasks - Execution Tasks : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks - Execution Tasks Exec Executes a system command Sample:

Some useful ANT Tasks - Execution Tasks : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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

Some useful ANT Tasks - Execution Tasks : www.scmGalaxy.com scmGalaxy 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 :

Some useful ANT Tasks - Execution Tasks : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks - Execution Tasks These 2 targets have the same effect :

Some useful ANT Tasks - Execution Tasks : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks - Execution Tasks Java Executes a Java class within the running (Ant) VM or forks another VM if specified

Exercise 1 : : www.scmGalaxy.com scmGalaxy Exercise 1 : Write simple ANT build file to prepare, compile EJB, compile Web Refer to exercise document for more details

Implementing the steps (contd) : www.scmGalaxy.com scmGalaxy Implementing the steps (contd) Build the compiled code into libraries

Some useful ANT Tasks – Archive Tasks : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks – Archive Tasks Archive Tasks Jar This task helps to create Java archives. Sample : 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 : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks - Archive Tasks Ear This task is an extension of the jar task It helps create enterprise archives Sample : The application XML to use can be specified here using the “appxml” attribute

Some useful ANT Tasks - Archive Tasks : www.scmGalaxy.com scmGalaxy 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 :

Some useful ANT Tasks - Archive Tasks : www.scmGalaxy.com scmGalaxy 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.

Some useful ANT Tasks - Pre-process Tasks : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks - Pre-process Tasks Pre-process Tasks Import Imports another build file into the current project. On execution it will read another Ant file into the same project. This means that it basically works as if the imported file was contained in the importing file, minus the top tag. The import task may only be used as a top-level task. This means that it may not be used in a target. Sample : Imports targets from the common-targets.xml file that is in a parent directory.

Integrating ANT script with JBoss Application server : www.scmGalaxy.com scmGalaxy Integrating ANT script with JBoss Application server Deployment on JBOSS application server can be done from the build script The JBOSS server can be started and stopped from the build script by using the “exec” task to run the start and stop JBOSS batch files.

Implementing the steps (contd) : www.scmGalaxy.com scmGalaxy Implementing the steps (contd) Deploy the software

Demo 2 : Package and deploy an enterprise application : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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).

Demo 3 : www.scmGalaxy.com scmGalaxy Demo 3 Integrate ANT build script with PMD Integrate ANT build script with JUNITs Integrate ANT build script with javadoc Display FORK example FourthBuild.xml

Exercise 3 : www.scmGalaxy.com scmGalaxy Exercise 3 Integrate with Junit Integrate with PMD

Some useful ANT Tasks : www.scmGalaxy.com scmGalaxy Some useful ANT Tasks Other Property Tasks LoadProperties Loads contents of a properties file as ANT properties Sample

Demo 4 : www.scmGalaxy.com scmGalaxy Demo 4 Environment specific properties ThirdBuild.xml devBuild.properties prodBuild.properties Config/dev/users.properties Config/prod/users.properties

Exercise 4 : www.scmGalaxy.com scmGalaxy Exercise 4 Environment specific properties Refer to exercise document for more details

Iterative improvement of build script : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy 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 : www.scmGalaxy.com scmGalaxy 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) : www.scmGalaxy.com scmGalaxy 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 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 ??

Monitoring the build process using ANT : www.scmGalaxy.com scmGalaxy Monitoring the build process using ANT Use , to output valuable information to a medium such as console or file during the build. Values of properties, tasks completed, target parameter values and any other information useful to detect the flow of the build can be outputted. To send out emails after build, use the tag in the build. Start ANT with a different logger such as mail logger, XML logger. To use Log4J for ANT logging, pass the Log4J listener when running ANT.

Good reads : www.scmGalaxy.com scmGalaxy Good reads http://www.webreference.com/reviews/ant/3.html Maven - http://maven.apache.org/ Ivy - http://www.jaya.free.fr/ivy/ http://www.martinfowler.com/articles/continuousIntegration.html

Summary : www.scmGalaxy.com scmGalaxy Summary We explored : The need for ANT ANT tasks ANT build script integration with JBOSS application server Continuous integration using ANT Improving an ANT build script

Slide 86 : www.scmGalaxy.com Thank You ! Author: Rajesh Kumar rajeshkumar.raj06@gmail.com