Intro

  • This reference sheet is intended as a memory aid, and definitely won’t teach you Ant.
  • What it does provide is an overview of much of Ant’s functionality, with a bias towards those pieces that might be useful to Adobe Flex developers. In other words, it should answer the question “What can Ant do?”
  • Which section bullets are placed in, and order of bullets within sections, are arbitrary in some cases.
  • Author: Douglas McCarroll @

Abbreviations

  • :: Task::Attribute, e.g. Target::name
  • ac: Ant-Contrib
  • prop Ant property

Ant Tasks

General & Uncategorized Tasks

  • Import other build files into your build file (override targets if desired): Import
  • Call system commands: Exec, ac:ShellScript
  • Start another process & return control to Ant: ac:Forget
  • Generate code documentaion: JavaDoc, Stylebook
  • Send email: Mail
  • Telnet functionality: Telnet
  • Execute a command on a remote server using SSH: Sshexec
  • Add default excludes (default defaults are **/.svn etc.): Defaultexcludes
  • Suspend execution for a specified period: Sleep
  • Execute BSF supported script, e.g. ECMAScript, Python, XSLT, JRuby: Script
  • Math operations: ac:Math
  • Splash screen: Splash
  • End-of-build sounds: Sound
  • Read build number from file, increment, write new number: Buildnumber
  • Create and expand archives: See Archive Tasks section of Overview

Property/String Tasks

  • Load file's contents as properties: LoadProperties
  • Modify prop files: PropertyFile
  • Replace 'keys' in file with locale-specific strings: Translate
  • Set prop based on OS: ac:Osfamily
  • Copy from one prop to another: ac:Propertycopy
  • Select prop names that match a given RegExp and return them in a delimited list: ac:PropertySelector
  • Perform RegExp operations on a string, then set prop to result: ac:PropertyRegex
  • Sort string items in delimited list, set prop to result: ac:SortList
  • Encode a prop for use in a URL: ac:URLEncode

Program Flow Tasks

  • Mutable props: ac:Variable
  • Run Ant on a specified build file
  • Ant
  • ac:AntFetch (user can specify props that will also be set in original project)
  • Call one target from another:
  • AntCall
  • ac:AntCallBack (props set in called target available in calling target)
  • Run a set of tasks in parallel: Parallel
  • Block execution until a set of specified conditions become true: WaitFor
  • Run a set of tasks in sequence: Sequential
  • If: Target::if, Target::unless
  • If: Condition
  • Condition can be based on one or several Core Conditions and/or on Custom Conditions
  • Core Conditions:
  • equalsare two strings identical?
  • not nested condition false?
  • and all nested conditions true?
  • or any nested condition true?
  • xor odd number of nested conditions true?
  • available like Available task
  • uptodatelike Uptodate task
  • os
  • isset prop set?
  • checksum
  • http valid response from URL?
  • socket host:port has listener?
  • filesmatch
  • containsstring contains substring?
  • istrue string equals 'true', 'yes', or 'on'
  • isfalse string doesn't equal 'true', 'yes', or 'on'
  • isreference reference defined in project, can also check type
  • issignedjar file signed?
  • isfileselected see Selectors core type
  • typefound type defined?
  • scriptcondition use a supported script to determine true or false
  • length file(s)'s charcount =, <, >, <=, >= spec'd value?
  • isfailure executable returns failure code?
  • resourcecount resourcecollection's size =, <, >, <=, >= spec'd value?
  • resourcesmatch
  • hasmethod Java class has method, or field
  • matches string matches RegExp?
  • antversion
  • Looping: ac:ForEach, ac:For
  • Switch: ac:Switch
  • Run Ant in each subdirectory of the project directory that has build.xml, etc: SubAnt
  • Stop execution: Fail
  • Limit time allowed to task(s), if exceeded stop task(s) without stopping build: ac:Limit
  • Interactive user input from console: Input
  • Set the DSTAMP, TSTAMP, and TODAY properties: TStamp

File & Path Tasks

  • Convert path to FileSet: ac:Pathtofileset
  • Delete all spec’d target files if any target files are older than any source file: DependSet
  • Determine whether a target file is newer than a set of source files: Uptodate
  • If any of a set of target files is older than of a set of source files, executes nested Parallel or Sequential element: ac:OutOfDate
  • Change file props: Attrib
  • Generate checksums: Checksum
  • Concatenate files to new file or log file: Concat
  • Copying, Moving, Deleting files & folders, Creating folders: Copy, Move, Delete, Mkdir
  • Modify file to add or remove tabs, carriage returns, linefeeds, EOFs: FixCRLF
  • Get file from URL: Get
  • HTTP Post: ac:Post
  • Download a build file, or download and expand an archive file: ac:Importurl
  • FTP functionality: FTP
  • Interact with an HTTP server as a client, maintaining state between requests, etc: Ant-Contrib’s HttpClient, HttpState, PostMethod, GetMethod, HeadMethod
  • Copy files to or from a remote server using SSH: Scp
  • Replace strings in files, with and without RegExps: Replace, ReplaceRegExp
  • Sychronize contents of directories: Sync
  • Change modification time of a file: Touch
  • Generate temp file name: Tempfile
  • Create & edit ini files: ac:IniFile
  • Convert files from native encodings to ASCII with escaped Unicode: Native2Ascii
  • Determine whether a file or directory exists: Available
  • Extract filename from full or relative filepath: Basename
  • Extract folderpath from full or relative filepath: Dirname
  • Load file into prop: LoadFile
  • Set prop to (sequence of) URL(s) for file (or fileset): Makeurl
  • Convert paths from one OS syntax to another: PathConvert

Java:

  • Compile: Javac
  • Use hot deployment tools on J2EE containers: ServerDeploy
  • Execute Java class: Java
  • Enforce dependency rules: ac:VerifyDesign
  • Determine whether a jar is present in a FileSet or ExtensionSet: Jarlib-available
  • Determine whether a class or resource is available on a classpath: Whichresource
  • Display jar’s optional ‘package' and 'package specification' info: Jarlib-display
  • Generate a manifest that declares dependencies: Jarlib-manifest
  • Determine loc of jar that satisfies dependency: Jarlib-resolve
  • Execute SQL via JDBC: Sql
  • Various pre-process tasks - see Preprocess Tasks section of Overview
  • Determine whether a class exists in a classpath: Available
  • Determine whether a JVM resource exists at runtime: Available
  • Set Java's web proxy properties so that tasks and code run in the same JVM can have through-the-firewall access: setproxy

Writing & Modifying Tasks:

  • Add a task definition to the current project: Taskdef
  • Add data-type definition: Typedef
  • Define a macro task made up of other tasks: Macrodef
  • Generate a new task based on a current definition with some attributes or elements preset: Presetdef

XML:

  • Check that a file is valid or well formed: XmlValidate
  • XSLT processing: XSLT
  • Load properties from an XML file: XmlProperty

Not included here:

  • Additional Java tasks
  • CVS tasks
  • JUnit tasks
  • Unix tasks
  • .NET tasks
  • Patch task (diff files)
  • GenKey task (keys & keystores)
  • Rexec task (Apache remote rexec sessions)
  • Ant-Contrib’s AntServer, Assert, Relentless, RemoteAnt, RunTarget, TimeStamp, Throw, TryCatch tasks

Filter Task

Performs global search and replace in files, but can only search for 'filter tokens',

i.e. strings in this format: @myString@.

Best illustrated by example (from

<filters>

<filter token="MESSAGE" value="${message}"/>

</filters>

<target name="build" depends="init,clean">

<mkdir dir="${target}"/>

<copy file="${src}/DEMO.TXT" toFile="${target}/RESULT.TXT" filtering="true"/>

<loadfile srcFile="${target}/RESULT.TXT" property="result"/>

<echo message="${result}"/>

</target>

All instances of "@MESSAGE@" in DEMO.TXT will be replaced with ${message} in RESULT.TXT.

Core Concepts & Core Types

Directory Based tasks

  • Some tasks e.g. Javac, Zip and Translate are 'Directory Based'.
  • These tasks have an implicit FileSet, thus can be defined with the same nested elements as are used in a FileSet (or PatternSet, for that matter)

FileSet

  • A group of files defined by a) a base directory, and b) one or more nested PatternSets and Selectors
  • Includes implicit PatternSet, thus supports nested <include>, <includesfile>, <exclude>, <excludesfile> elements, plus PatternSet's attributes

DirSet

  • Same as FileSet, only a group of directories

FileList

  • Specifies an explicitely named group of files

PatternSet

  • A group of 'Patterns' with an id

Pattern

  • A path string, including wildcards, that is used to filter files
  • Example: "/?abc/*/*.java"
  • These are specified as <include> or <exclude> elements, using the 'name' attribute
  • Example Pattern #1: <include name="**/images/*"/>
  • Example Pattern #2: <exclude name="**/*.gif"/>

Permission

  • Relates to “security permissions granted or revoked to a specific part code executed in the JVM”

PropertySet

  • A group of properties with an id

I/O Redirection

  • Used with Apply, Exec & Java tasks
  • Specify input source, standard output & error output
  • Specify FilterChains
  • And much more

Resource

  • Abstraction of a "file-like resource"
  • For example:
  • propertyresourcean Ant prop
  • stringa Java string
  • file
  • zipentryarchived file system resources
  • javaresource
  • url

Resource Collection

  • Functionality for grouping, selecting, sorting, etc, see Manual for details

Selector

  • A mechanism for selecting files in a FileSet based on criteria other than file name
  • Can be defined outside targets, grouped within <selector> tag, or nested in FileSets
  • Use <selector> tag if you’ll refer to Ant properties
  • Selector Containers are Selectors that contain other Selectors
  • and all contained selectors select file?
  • majoritymajority of contained selectors select file?
  • none
  • not can contain only one selector
  • or
  • Core Selectors
  • containsdoes file contain specified string?
  • date select by date of modification
  • dependselect if newer than target files
  • depthselect based on number of directories down in directory tree
  • differentselect if different from another file, in contents and/or modDate
  • filenamesimilar to Filter task
  • presentselect if file does/doesn’t exist in another specified location
  • containsregexp
  • size
  • type select based on file vs. directory
  • modifieduses a cache.properties file to keep track of FTP’ed files and

compares checksups to see which have been modified

  • signedselectorsselects if file is signed
  • scriptselectoruse a supported script to determine whether to select
  • Custom Selectors can be written by user

FilterSets

  • A group of filters
  • Filters are token-value pairs similar to those used in Filter task
  • Can be specified or read in from a file

FilterChain

  • A group of ordered FilterReaders

FilterReader

  • An extension of java.io.FilterReader
  • In org.apache.tools.ant.filters
  • Ant includes built-in FilterReaders, can also be user-defined
  • Some of the built-in FilterReaders
  • EscapeUnicodeconvert Unicode to esc'd ASCII
  • ExpandPropertiesconvert "${myPropName}" to prop's value
  • HeadFilterread first n lines of file - combine with TailFilter to do 'middle

filter'

  • LineContains read lines that include spec'd string
  • LineContainsRegExp
  • PrefixLinesadd prefix to all lines
  • ReplaceToken
  • StripJavaComments
  • StripLineBreaks
  • StripLineCommentsremoves lines that begin with strings comments as defined

by user

  • TabsToSpaces
  • TailFilter read last n lines of file
  • DeleteCharacters
  • ConcatFilter
  • TokenFilter
  • Includes 0..1 tokenizer and 1..n string filters as nested elements
  • Tokenizers:
  • Determines how text is broken up into 'tokens'
  • Ant includes:
  • LineTokenizer breaks into lines
  • FileTokenizer doesn't break up
  • StringTokenizer breaks up based on user-defined delimiters
  • String Filters:
  • * indicates that Filter may be used directly in a FilterChain
  • Ant includes:
  • ReplaceString*
  • ReplaceRegex*
  • ContainsString eliminates tokens that don't contain string
  • ContainsRegex* either eliminates tokens without a matching

string, or replaces string

  • Trim* removes whitespace at beginning and/or end
  • IgnoreBlank* eliminates ""
  • DeleteCharacters
  • ScriptFilter similar to Filter task - write your own filter in

another language

Debugging, Logging, Monitoring

  • Manual | Listeners & Loggers
  • Manual | Concepts & Types | Core Types | I/O Redirectors
  • Record, Echo, Echoproperties tasks
  • Ant-Contrib’s Performance Monitor listener & StopWatch task
  • Ant’s -debug & -verbose command line args