Ant

Ant

Ant is a Java based build tool, similar to make, but with better support for the cross platform issues involved with developing Java applications. Ant is the build tool of choice for all Java projects at Apache and many other Open Source Java projects. Ant can be configured to compile your java source code files, build your deployment JAR and WAR files, unit-test code and create projects javadoc documentation.

Ant 1.6.0 adds a lot of new features, most prominently support for XML namespaces as well as a new concept of Ant libraries that makes use of namespaces to avoid name clashes of custom tasks.

Advantages of Ant

  • Build IN Java, USING Java, and FOR Java
  • Supports Java Tools (javac, javadoc, etc.)
  • XML Build File is Easier to Build, Read, and Maintain than MAKE file
  • Easier to Extend
  • Supports Cross Platform Java Development
  • Ant is much faster than using MAKE ? Each command is a new process
  • Ant runs within the JVM
  • Each command is executed from within JVM
  • Tools like javac are new threads – not new process
  • Compiling large number of java source files is MUCH,MUCH faster with Ant
  • Ant's Debug Options are very helpful
  • XML much easier to read than MAKEFILE
  • User does not need to know all command line interface options to tools that can be called programmatically
  • Even OS-Specific commands can be setup in 'TaskDefs' and/or included from other sources
Installing Ant

Regardless of platform, downloading Ant is the first step to installing the software. The files can be downloaded to a temporary directory and then uncompressed to any desired directory. After the download step, the process differs depending on whether you've downloaded the binary distribution or the source distribution.
Ant does not provide an installation program; it runs from wherever you choose to copy the files and directories. Lists the directories that ultimately get created under your main Ant directory.

Directories provided with Ant
bin - Batch files, Perl scripts, and shell scripts for running Ant.
docs - Ant documentation.
lib - Libraries required by Ant to run.
src - Source code for Ant. Provided only in the source distribution.


Binary Installation
The term "binary" just means that everything is compiled and packaged into JAR files for easy execution — you don't need to compile Ant from source.
Steps to install Installation of the binary distribution:
1. Unzip (or untar) the distribution to the desired directory.
2. Set the ANT_HOME environment variable to point to to the ant installation directory.
3. Set the JAVA_HOME environment variable to point to the JDK location.
4. Add ANT_HOME/bin to your system's PATH environment variable.

The ant script uses the ANT_HOME and JAVA_HOME environment variables to configure the CLASSPATH used by the JVM running Ant. If these variables are not set, the startup script attempts to infer the correct values, subject to operating system limitations.

Source Installation
Installing the Ant source distribution requires a little more work than installing the binary distribution. As expected, downloading and uncompressing the distribution is the first step.
You generally want to place the source files in a directory separate from any existing Ant installations. Next, ensure that JAVA_HOME points to the JDK distribution. As with the binary installation, you should also set ANT_HOME and update your PATH.
type the following command from the source distribution directory:


build -Ddist.dir=destination_directory dist (Windows)
build.sh -Ddist.dir=destination_directory dist (Unix)

The build script creates a complete binary distribution of Ant in the specified destination directory. When omitted, dist.dir defaults to build.


Ant Basics

Each 'Project' has a Build File, Default build file name is 'build.xml', Can Specify any name with '-buildfile' command line option, Ant's buildfiles are written in XML.

The first or root element of any buildfile is always the tag. No buildfile can be without one nor can it have more than one.


...


The tag has three attributes: name, default, and basedir.

  • The name attribute gives the project a name.
  • The default attribute refers to a target name within the buildfile. If you run Ant without specifying a target on the command line, Ant executes the default target. If the default target doesn't exist, Ant returns an error.
  • The basedir attribute defines the root directory of a project. Typically, it is ".", the directory in which the buildfile resides, regardless of the directory you're in when you run Ant. However, basedir can also define different points of reference.

Each buildfile contains one project and at least one (default) target. Examples are: 'compile', 'test', 'install', 'clean', etc.
...

The tag has three attributes: name, depends, if, unless, descriptiondefault, and basedir.

  • The name attribute gives the target a name.
  • The depends attribute are a comma-separated list of names of targets on which this target depends.
  • The if attribute the name of the property that must be set in order for this target to execute.
  • The unless attribute the name of the property that must not be set in order for this target to execute.
  • The description attribute a short description of this target's function.

Targets must have a name and may have several additional attributes that determine when and if the target actually gets executed. The target is made up of one or more Tasks like invoke a command or another program. Targets can have Dependencies, examples: 'install' depends on 'compile', Targets can handle cascading dependencies, each Dependency is handled only once, dependency executed only if required.

It should be noted, however, that Ant's depends attribute only specifies the order in which targets should be executed - it does not affect whether the target that specifies the dependency(s) gets executed if the dependent target(s) did not (need to) run.

Ant tries to execute the targets in the depends attribute in the order they appear (from left to right). Keep in mind that it is possible that a target can get executed earlier when an earlier target depends on it.A target gets executed only once, even when more than one target depends on it .

A is a piece of code that can be executed.
A task can have multiple attributes (or arguments, if you prefer). The value of an attribute might contain references to a property. These references will be resolved before the task is executed. Tasks have a common structure:

where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute.

Each task element of the buildfile can have an id attribute and can later be referred to by the value supplied to this. The value has to be unique. Each Task is bound to a Java class file that Ant executes, passing to it any arguments or sub-elements defined with that task. The Ant tool is extensible and it allows you to create your own tasks

Typical build.xml Tasks
init, sets properties, prepare, creates directories, build, builds the system, package, creates jar file, install, installs an application to Tomcat or other engine, deploy, deploy a WAR engine, reload, update previously installed application engine, redeploy.


Properties

A project can have a set of properties. These might be set in the buildfile by the property task, or might be set outside Ant. A property has a name and a value; the name is case-sensitive. Properties may be used in the value of task attributes. This is done by placing the property name between "${" and "}" in the attribute value. For example, if there is a "builddir" property with the value "build", then this could be used in an attribute like this: ${builddir}/classes. This is resolved at run-time as build/classes.

Built-in Properties
Ant provides access to all system properties as if they had been defined using a task. For example, ${os.name} expands to the name of the operating system. For a list of system properties see the Javadoc of System.getProperties.
In addition, Ant has some built-in properties:

basedir the absolute path of the project's basedir (as set with the basedir attribute of ).
ant.file the absolute path of the buildfile.
ant.version the version of Ant
ant.project.name the name of the project that is currently executing; it is set in the name attribute of .
ant.java.version the JVM version Ant detected; currently it can hold
the values "1.1", "1.2", "1.3" and "1.4".

Using Ant

Ant is a Java based build tool, similar to make, but with better support for the cross platform issues involved with developing Java applications. Ant is the build tool of choice for all Java projects at Apache and many other Open Source Java projects. Ant can be configured to compile your java source code files, build your deployment JAR and WAR files, unit-test code and create projects javadoc documentation.

Ant 1.6.0 adds a lot of new features, most prominently support for XML namespaces as well as a new concept of Ant libraries that makes use of namespaces to avoid name clashes of custom tasks.

Advantages of Ant

  • Build IN Java, USING Java, and FOR Java
  • Supports Java Tools (javac, javadoc, etc.)
  • XML Build File is Easier to Build, Read, and Maintain than MAKE file
  • Easier to Extend
  • Supports Cross Platform Java Development
  • Ant is much faster than using MAKE ? Each command is a new process
  • Ant runs within the JVM
  • Each command is executed from within JVM
  • Tools like javac are new threads – not new process
  • Compiling large number of java source files is MUCH,MUCH faster with Ant
  • Ant's Debug Options are very helpful
  • XML much easier to read than MAKEFILE
  • User does not need to know all command line interface options to tools that can be called programmatically
  • Even OS-Specific commands can be setup in 'TaskDefs' and/or included from other sources
Running Ant

Command Line
If you've installed Ant as described in the Installing Ant section, running Ant from the command-line is simple: just type ant.

When no arguments are specified, Ant looks for a build.xml file in the current directory and, if found, uses that file as the build file and runs the target specified in the default attribute of the tag. To make Ant use a build file other than build.xml, use the command-line option -buildfile file, where file is the name of the build file you want to use

If you use the -find [file] option, Ant will search for a build file first in the current directory, then in the parent directory, and so on, until either a build file is found or the root of the filesystem has been reached. By default, it will look for a build file called build.xml. To have it search for a build file other than build.xml, specify a file argument.

Note: If you include any other flags or arguments on the command line after the -find flag, you must include the file argument for the -find flag, even if the name of the build file you want to find is build.xml.


You can also set properties on the command line. This can be done with the -Dproperty=value option, where property is the name of the property, and value is the value for that property. If you specify a property that is also set in the build file (see the property task), the value specified on the command line will override the value specified in the build file. Defining properties on the command line can also be used to pass in the value of environment variables - just pass -DMYVAR=%MYVAR% (Windows) or -DMYVAR=$MYVAR (Unix) to Ant. You can then access these variables inside your build file as ${MYVAR}. You can also access environment variables using the property task's environment attribute.

Options that affect the amount of logging output by Ant are:
-quiet, which instructs Ant to print less information to the console;
-verbose, which causes Ant to print additional information to the console;
-debug, which causes Ant to print considerably more additional information.
It is also possible to specify one or more targets that should be executed. When omitted, the target that is specified in the default attribute of the project tag is used.
The -projecthelp option prints out a list of the build file's targets. Targets that include a description attribute are listed as "Main targets", those without a description are listed as "Subtargets", then the "Default" target is listed.

Command-line Options Summary
ant [options] [target [target2 [target3] ...]]

Options:

-help, -h print this message
-projecthelp, -p print project help information
-version print the version information and exit
-diagnostics print information that might be helpful to diagnose or report problems.
-quiet, -q be extra quiet
-verbose, -v be extra verbose
-debug, -d print debugging information
-emacs, -e produce logging information without adornments
-lib specifies a path to search for jars and classes
-logfile use given file for log
-l use given file for log
-logger the class which is to perform logging
-listener add an instance of class as a project listener
-noinput do not allow interactive input
-buildfile use given buildfile
-file use given buildfile
-f use given buildfile
-D= use value for given property
-keep-going, -k execute all targets that do not depend on failed target(s)
-propertyfile load all properties from file with -D properties taking precedence
-inputhandler the class which will handle input requests
-find (s)earch for buildfile towards the root of
-s the filesystem and use it

Ant tasks

The following tables provide a short description of each task.

  • Archive Tasks (Jar, Ear, Tar, War, GZip, Zip etc.)
  • Audit/Coverage Tasks (JDepend, JPorbe, MMetrics, etc. )
  • Compile Tasks (javac, jspc, rmic etc.)
  • Deployment Tasks (ServerDeploy)
  • Documentation Tasks (Javadoc, Stylebook)
  • EJB Tasks
  • Execution Tasks (Ant, Antcall, Exec, Java, Sleep etc.)
  • File Tasks (Attrib, Copy, Copydir, delete, Mkdir etc.)
  • Java2 Extensions Tasks (Jarlib-available, Jarlib-display etc.)
  • Logging Tasks (Record)
  • Mail Tasks (Mail, MimeMail)
  • Miscellaneous Tasks (Echo, GenKey, Script, Sql etc.)
  • .NET Tasks
  • Pre-process Tasks (ANTLR, AntStructure, Import, Xslt/Style etc.)
  • Property Tasks (Available, Basename, BuildNumber, LoadFile etc.)
  • Remote Tasks (FTP, Telnet etc. )
  • SCM Tasks (Cvs, CvsChangeLog, CVSPass etc.)
  • Testing Tasks (Junit, JunitReport, Test)
  • Visual Age for Java Tasks


Core tasks

  • Ant
  • AntCall
  • AntStructure
  • Apply/ExecOn
  • Available
  • Basename
  • BuildNumber
  • BUnzip2
  • BZip2
  • Checksum
  • Chmod
  • Concat
  • Condition
  • Supported conditions
  • Copy
  • Copydir
  • Copyfile
  • Cvs
  • CvsChangeLog
  • CVSPass
  • CvsTagDiff
  • Defaultexcludes
  • Delete
  • Deltree
  • Dependset
  • Dirname
  • Ear
  • Echo
  • Exec
  • Fail
  • Filter
  • FixCRLF
  • GenKey
  • Get
  • GUnzip
  • GZip
  • Import
  • Input
  • Jar
  • Java
  • Javac
  • Javadoc/Javadoc2
  • LoadFile
  • LoadProperties
  • Mail
  • MacroDef
  • Manifest
  • Mkdir
  • Move
  • Parallel
  • Patch
  • PathConvert
  • PreSetDef
  • Property
  • Record
  • Rename
  • Replace
  • Rmic
  • Sequential
  • SignJar
  • Sleep
  • Sql
  • Style
  • Subant
  • Sync
  • Tar
  • Taskdef
  • Tempfile
  • Touch
  • TStamp
  • Typedef
  • Unjar
  • Untar
  • Unwar
  • Unzip
  • Uptodate
  • Waitfor
  • War
  • WhichResource
  • XmlProperty
  • Xslt
  • Zip
Optional tasks

  • .NET Tasks
  • ANTLR
  • Attrib
  • Cab
  • Chgrp
  • Chown
  • Clearcase Tasks
  • Continuus/Synergy Tasks
  • Depend
  • EJB Tasks
  • Echoproperties
  • FTP
  • IContract
  • Image
  • Jarlib-available
  • Jarlib-display
  • Jarlib-manifest
  • Jarlib-resolve
  • JavaCC
  • Javah
  • JspC
  • JDepend
  • JJDoc
  • JJTree
  • Jlink
  • JProbe Coverage
  • JUnit
  • JUnitReport
  • Metamata Metrics
  • Metamata Audit
  • MimeMail
  • MParse
  • Native2Ascii
  • NetRexxC
  • Perforce Tasks
  • PropertyFile
  • Pvcs
  • RenameExtensions
  • ReplaceRegExp
  • RExec
  • Rpm
  • ServerDeploy
  • Setproxy
  • Scp
  • Script
  • Scriptdef
  • Sound
  • SourceOffSite
  • Splash
  • Sshexec
  • Starteam Tasks
  • Stylebook
  • Symlink
  • Telnet
  • Test
  • Translate
  • Visual Age for Java Tasks
  • Microsoft Visual SourceSafe Tasks
  • Weblogic JSP Compiler
  • XmlValidate
Ant command line arguments

Several tasks take arguments that will be passed to another process on the command line. To make it easier to specify arguments that contain space characters, nested arg elements can be used.

value - a single command-line argument; can contain space characters.
file - The name of a file as a single command-line argument; will be replaced with the absolute filename of the file.
path - A string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Ant will convert it to the platform's local conventions.
pathref - Reference to a path defined elsewhere. Ant will convert it to the platform's local conventions.
line - a space-delimited list of command-line arguments.


It is highly recommended to avoid the line version when possible. Ant will try to split the command line in a way similar to what a (Unix) shell would do, but may create something that is very different from what you expect under some circumstances.

Examples

is a single command-line argument containing a space character.

represents two separate command-line arguments.

is a single command-line argument with the value \dir;\dir2;\dir3 on DOS-based systems and /dir:/dir2:/dir3 on Unix-like systems.


Command-line Options Summary
ant [options] [target [target2 [target3] ...]]


Options:

-help, -h Displays help information describing the Ant command and its options
-projecthelp, -p Print project help information
-version Print the version information and exit
-diagnostics Print information that might be helpful to diagnose or report problems.
-quiet, -q Suppresses most messages not originated by an echo task in the buildfile
-verbose, -v Displays detailed messages for every operation during a build.
-debug, -d Print debugging information
-emacs, -e Produce logging information without adornments
-lib Specifies a path to search for jars and classes
-logfile Use given file for log
-l Use given file for log
-logger Specifies a class to handle Ant logging.
-listener Add an instance of class as a project listener
-noinput Do not allow interactive input
-buildfile Use given buildfile
-file Use given buildfile
-f Use given buildfile
-D= Defines a property name-value pair on the command line.
-keep-going, -k execute all targets that do not depend on failed target(s)
-propertyfile load all properties from file with -D properties taking precedence
-inputhandler the class which will handle input requests
-find Search for buildfile towards the root of the filesystem and use it

No comments:

Post a Comment