Software Development Tools 7

1
Software Development Tools 7

• COMP320
• Dr Vladimir Sazonov
• Ant Datatypes and Properties

These slides are mainly based on Java
Development with Ant - E. Hatcher S.Loughran.
Manning Publications, 2003
2
Ant Datatypes and Properties

• Now, after getting started in previous lectures,
  we will consider Ant concepts in more detail.
• Two most foundational concepts of Ant are
• datatypes
• properties

3
Ant datatypes overview

• To build a typical Java project we mostly deal
  with
• files and paths (such as classpaths).
• This leads to Ant datatypes
• fileset
• path
• and several others

4
Filesets overview
Fileset is a common entity to manipulate for such
tasks as compiling, packaging, copying, deleting,
and documenting. Fileset is a group of files
represented like
ltfileset dir"src" includes"/.java"
id"source.fileset"/gt

• dir is mandatory attribute to denote a base
  directory of the fileset - here src. Files in
  the fileset can be found in a directory tree
  starting from this base directory.
• includes attribute shows which files from this
  directory to include.
• id attribute is a reference which can be used
  later wherever this fileset is expected.

5
Filesets overview

• For example, copying source code to another
  directory
• using the above id"source.fileset" could be
• done by ltcopygt task as follows

ltcopy todir"backup"gt ltfileset
refid"source.fileset"/gt lt/copygt
6
Paths overview

• A path can be defined once for compilation with
• ltjavacgt task,
• and reused for execution with
• ltjavagt task.
• Classpath can be easily and tightly controlled
  by Ant.
• This reduces CLASSPATH configuration problems,
• both for compilation and execution.
• Examples will be presented later.

7
Properties overview

• Ant's property handling mechanism allows for
  parameterizing the build file by any
  string-specified item.
• For example, changing a build to use a different
  version of a third party library (JAR file) can
  be made by one command like this
• In this case struts.jar after D represents an
  Ant property (or parameter) with the
  assigned value /home/ant/newstruts/struts.jar.
• Build file uses special syntax struts.jar to
  refer to this property.
• A key feature of an Ant property is its
  immutability
• - once a property is set, it resists change.

gtant -Dstruts.jar/home/ant/newstruts/struts.jar
8
Datatypes and Properties with ltjavacgt

• The ltjavacgt task is an Ants version of Java
  source compilation command javac with associated
  switches.
• Let us compare Sun's
• JDK 1.3.1 javac command-line compiler switches
  to
• Ant's ltjavacgt task attributes.
• This is shown in the following table.

9
A comparison of javac command-line compiler
switches to Ant's ltjavacgt task attributes
(continued)
10
A comparison of javac command-line compiler
switches to Ant's ltjavacgt task attributes
11
Datatypes and Properties with ltjavacgt (cont.)
Consider Java compilation with Ant utilizing
Ant's datatypes (paths and filesets),
properties and references to datatypes
ltjavac destdir"build.classes.dir"
debug"build.debug"
srcdir"src.dir"gt ltinclude
name"/.java"/gt ltclasspath
refid"compile.classpath"/gt lt/javacgt

• build.classes.dir, build.debug, src.dir are
• property names.
• We refer to property names , as in
  srcdirsrc.dir,
• by using ....
• We can also assigne separately a value of the
  property such as src.dir
• to be the real directory name src.
• Compare this with the direct reference to the
  value like in
• srcdirsrc
• where src is the real directory name.

12
Datatypes and Properties with ltjavacgt (cont.)
It was assumed above that build file also
contains somewhere path element like
ltpath id"compile.classpath"gt ltpathelement
location"lucene.jar"/gt ltpathelement
location"jtidy.jar"/gt lt/pathgt
refid"compile.classpath" in the previous slide
refers to this path element because of
id"compile.classpath". It shows where to find
two JAR files needed for the compilation. More
on ... notation on the next slide.
13
Properties with ltjavacgt
Comments to slides 11,12

• The ... notation refers to an Ant property
  
• a mapping from a name to a string value,
  referring to
• the destination directory build.classes.dir,
• what debug mode to use build.debug,
• the source directory src.dir, and
• JAR locations lucene.jar and jtidy.jar.
• Note that dot notation is used in
• naming properties, like above,
• or IDs, like compile.classpath
• This imitates the natural language.
• In particular, lucene.jar is considered here
• as the property name, not as the file name,
• however, they could coincide incidentally (or
  for the convenience).

14
Datatypes (paths and filesets) with ltjavacgt
Comments to slides 11,12

• The subelement
• ltclasspath refid"compile.classpath"/gt
• specifies a path using a reference
• indicating which previously defined path to use.
• The previously defined path element (see Slide
  12)
• ltpath id"compile.classpath"gt lt/pathgt
• - indicates which JAR files to use.
• These JAR files are specified by the use of
  properties within the location attribute (see
  Slide 12).
• The srcdir attribute of ltjavacgt (see Slide 11)
• - implicitly defines a fileset containing all
  files (to be compiled) in the specified directory
  tree.
• The nested ltincludegt of ltjavacgt task specifies a
  pattern /.java
• - this constrains the files to only Java source
  files.

15
Ant task reference

• For the future, see also descriptions of the
  concepts of Ant in the
• Ant task reference
• (Appendix E to the Ant book) available via
• http//manning.com/hatcher/
• http//www.manning-source.com/books/hatcher/hatche
  r_apxE.pdf
• See also in your computers in University labs
• C\JAVA\ANT\docs\manual\index.html
• or
• http//ant.apache.org/manual/index.html

16
Paths

• A path, or path-like structure, is an ordered
  list of pathelements.
• It is analogous to the Java CLASSPATH where each
  element in the list could be either
• a file
• or directory
• separated by a delimiter.
• Example

ltclasspathgt ltpathelement path"classpath"/gt
ltpathelement location"lib/some.jar"/gt lt/classp
athgt
Or even shorter for the single pathelement
ltclasspath location"lib/some.jar"/gt

• location attribute specifies a single file or
  directory.
• path attribute accepts colon- or
  semicolon-separated list of locations the
  value of the property classpath.

17
Paths (cont.)

• Example of list of locations,
• using path attribute (instead of location)
• Or even shorter for the single path element
• Both semicolon () and colon () above are
  allowed as separator.
• Ant is "bi-slashed" use either forward-slash (/)
  or back-slash (\),
• regardless of operating system.
• - Extremely user friendly!

ltclasspathgt ltpathelement path"build/classeslib
/some.jar"/gt lt/classpathgt
ltclasspath path"build/classeslib/some.jar"/gt
18
Paths (cont.)
Paths can also include a set of files
ltclasspathgt ltfileset dirlibgt ltinclude
name.jar/gt lt/filesetgt lt/classpathgt
Ant assumes no order within a ltfilesetgt
19
Filesets

• Implicitly, all build processes such as compile,
  copy, delete, etc. operate on sets of files.
• Ant provides the fileset as native datatype.
• It is difficult to imagine any useful build that
  does not use a fileset.
• Some tasks assume filesets implicitly,
• while other tasks support filesets explicitly.
• A fileset is a set of files rooted from a single
  directory.
• By default, a fileset specified with only a root
  directory will include all the files in that
  entire directory tree, including files in all
  subdirectories recursively.
• Filesets can appear either
• inside tasks the children of targets, or
• at the same level as targets.

20
Filesets (cont.)

• Let us CREATE a new copy.xml file in
  C\Antbook\ch02\secondbuild
• by extending the build file structured.xml with
  a new target containing new ltcopygt task
• First RUN copy.xml
• ant -f copy.xml (to do init -gt compile -gt
  archive)
• Then RUN
• ant -f copy.xml copy (to execute the above task)

lttarget name"copy"gt ltcopy todir"new_build"gt
ltfileset dir"build"/gt lt/copygt lt/targetgt
21
Fileset examples

• TRY to check by creating appropriate build and
  other files that
• 1. Fileset
• includes all JAR files from the lib directory
  non-recursively, i.e. no subdirectories are
  considered.
• 2. Fileset
• includes all .java files in and below the
  test directory
• that end with the string "Test".

ltfileset dir"lib"gt ltinclude name".jar"/gt lt/fi
lesetgt
ltfileset dir"test"gt ltinclude
name"/Test.java"/gt lt/filesetgt
Hint Use ltcopygt task involving either the first
or the second fileset to see which files are
really copied.
22
Fileset examples (cont.)

• 3.
• includes only non-JSP files in the web directory
  and below.
• By default, include and exclude values are case
  sensitive.
• But this can be disabled by specifying the
  attribute of ltfilesetgt
• casesensitive"false"
• ltincludegt and ltexcludegt subelements in ltfilesetgt
  serve as
• patternsets.
• For example, /.jsp and /Test.java are
  patterns.

ltfileset dir"web"gt ltexclude name"/.jsp"/gt lt
/filesetgt
23
Fileset examples (cont.)
There is also a way to abbreviate
ltfileset dirwebgt ltinclude
name/.jsp/gt lt/filesetgt
as
ltfileset dirweb includes/.jsp/gt
by using attribute includes instead of
subelement ltincludegt
24
Some default exclude patterns
To turn off the automatic exclusion, use the
defaultexcludes attribute
ltfileset dir"..." defaultexcludes"no"gt
25
Patternsets and Selectors

• There is also some additional mechanism of
  patternsets and selectors to form filesets
  which we will not consider.
• See Sections 3.5 and 3.6 in Antbook,
• and also
• C\JAVA\ANT\docs\manual\index.html
• http//ant.apache.org/manual/index.html

26
Filterset

• During the build process, it is common to make
  dynamically simple
• text substitutions.
• The two primary tasks that support this filterset
  functionality are ltcopygt and ltmovegt.
• A filter operation replaces tokenized text in
  source files (e.g. by current date,
  etc.) during either a ltmovegt or ltcopygt
  to a destination file.
• A token is defined as text surrounded by
  beginning and ending
• token delimiters.
• These delimiters default to the character _at_,
• but can be altered using the begintoken and
  endtoken attributes of ltfiltersetgt.

27
Inserting date stamps in files at build-time

• Let us now enhance the copy task to substitute a
  date and time stamp tokens with the actual build
  date and time into the resultant files.
• Consider an example JSP file including the tokens

lthtmlgt ltheadgtlttitlegtAnt Booklt/titlegtlt/headgt
ltbodygt System build time _at_DATE_at_ _at_ _at_TIME_at_
lt/bodygt lt/htmlgt

• Put it, say, in the directory web.

28
Inserting date stamps in files at build-time
Here _at_DATE_at_ and _at_TIME_at_ will be replaced during
the copy
lttstamp/gt ltcopy todir"new_web"
overwrite"true"gt ltfileset dir"web"
includes"/.jsp"/gt ltfiltersetgt ltfilter
token"DATE" value"DSTAMP"/gt ltfilter
token"TIME" value"TSTAMP"/gt
lt/filtersetgt lt/copygt

• The lttstampgt task creates the DSTAMP and TSTAMP
  Ant properties.
• The values of DSTAMP and TSTAMP contain
  the (current) date and time stamps, respectively,
  due to running the task lttstampgt.

29
Inserting date stamps in files at build-time

• Recall that ltcopygt task has default dependency
  checking
• it does not copy up-to-date files
• But filtered copy should always replace the
  destination files.
• Thus, disable the dependency checking with
  overwrite"true" (in the above build file
  fragment).

30
Inserting date stamps in files at build-time

• Applying this filtered copy on the above JSP
  file
• produces something like the following

lthtmlgt ltheadgtlttitlegtAnt Booklt/titlegtlt/headgt
ltbodygt System build time 20050214 _at_ 1501
lt/bodygt lt/htmlgt
There is much more capabilities of filtering in
Ant. See some more examples in Section 3.9 of
Ant Book and in C\JAVA\ANT\docs\manual\index.html

31
Mapper datatype (mapping file names)

• (See C\JAVA\ANT\docs\manual\index.html and Ant
  Book, 3.10)
• Some tasks take source files and create (or
  compare them with) target files.
• Depending on the task, it may be quite obvious
  which name a target file will have
• For example, javac compiles your .java files
  to .class files.
• In other cases you may want to specify the target
  files
• either to help Ant or
• to get an extra bit of functionality.
• Mappers serve to this aim
• they do no real action (such as compiling,
  copying, moving files, etc),
• but can be used by ltuptodategt, ltmovegt, ltcopygt,
  ltapplygt, and several other tasks.
• Depending on the mapper type,
• to and from attributes may be required in
  ltmappergt element.

32
Mappers

• Built-in mapper types are
• identity,
• flatten,
• merge,
• glob,
• regexp (will not be considered),
• package (self-study),
• unpackage (self-study)
• All built-in mappers are case-sensitive.

33
Identity mapper
Here the target file name is identical to
the source file name. Example ltmapper
type"identity"/gt
By default, ltcopygt task uses the identity mapper.
34
Flatten mapper
Here the target file name is identical
to the source file name, but with all
leading directory information stripped off.
Example ltmapper type"flatten"/gt
Example of using
ltcopy todirnew_webgt ltfileset dirweb
includes/.jsp/gt ltmapper
typeflatten/gt lt/copygt
Caution All copied files should have different
names !
35
Merge mapper
The target file name will always be the same, as
defined by to attribute. Example ltmapper
type"merge" to"archive.zip"/gt
ltuptodate propertyzip.notRequiredgt ltsrcfiles
dir src includes/.java/gt ltmapper
typemerge to ../distzip/src.zip/gt lt/uptodat
e gt
Example of using
This only sets the property zip.notRequired to
true if src.zip is uptodate. Note using ../ Here
the mapper "to" attribute is relative to the
"dir" attribute of the nested srcfiles element
(not relative to the base directory!). NOTE Ant
book seemingly has no such important comment!
36
Glob mapper
Example ltmapper type"glob" from".java"
to".java.bak"/gt
ltcopy todirsrcbakgt ltfileset dirsrc
includes/.java/gt ltmapper typeglob
from.java to".java.bak"/gt lt/copygt
Example of using
All Java source files are copied to srcbak
directory with the directory hierarchy preserved
and .java extensions renamed with .java.bak in
the new directory.
37
Glob mapper (cont.)
Another Example ltmapper type"glob"
from"Cies" to"Qy"/gt

• Again, it can be used in ltcopygt task
• copying files with renaming.

38
Glob mapper (cont.)

• Both to and from attributes of glob mapper define
  patterns that may contain at most one
• from".java" to".java.bak"
• For each source file that matches the from
  pattern, a target file name will be constructed
  from the to pattern by replacing the in the to
  pattern with the text that matches the in the
  from pattern.
• Source file names that don't match the from
  pattern will be ignored.

39
Package mapper (self-study)
Example
ltmapper type"package" from"Test.java"
to"TEST-Test.xml"/gt

• package mapper shares the same syntax as the
  glob mapper
• Replaces directory separators / found in the
  matched source pattern with dots in the target
  pattern placeholder.
• package mapper is particularly useful in
  combination with ltuptodategt and ltjunitgt output.

40
Unpackage mapper (self-study)

• Example

ltmapper type"unpackage"
from"TEST-Test.xml" to"test.src.dir/Test.ja
va"gt

• unpackage mapper is the inverse of the package
  mapper.
• Replaces the dots in a package name with
  directory separators /.
• Useful for matching XML formatter results
  against their JUnit test test cases.
• Shares the sample syntax as the glob mapper.

41
Additional Ant Datatypes

• ltzipfilesetgt - to build an archive that contains
  the contents of other archive files.
• ltdirsetgt - like ltfilesetgt, but only for directory
  sets.
• ltfilelistgt - like ltfilesetgt, but only for ordered
  file sets.
• ltclassfilesetgt - for .class files.