1. Software Development Tools COMP220 Seb Coope More Ant Features These slides are mainly based on “Java Development with Ant” - E. Hatcher & S.Loughran. Manning Publications, 2003

2. 2 Mapper datatype (mapping file names) (See C:\JAVA\Ant1.8.1\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, compiles *.java files to *.class files.

3. 3 Mapper datatype (mapping file names)  A mapper or elements sets a correspondence between source and target file names.  Mappers do no real action (such as compiling, copying, moving files, etc),  but can be used by tasks,,,, and several others to appropriately modify the actions of these tasks.  Depending on the mapper type,  to and from attributes may be required in element.

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

5. 5 Identity mapper Here the target file name is identical to the source file name. Example: Source file nameTarget file name A.java foo/bar/B.java C.properties Classes/dir/A.properties By default, task uses the identity mapper.

6. 6 Flatten mapper Here the target file name is identical to the source file name, but with all leading directory information stripped off. Example: Source file nameTarget file name A.java foo/bar/B.javaB.java C.properties Classes/dir/A.propertiesA.properties Caution: All copied files should have different names ! Example of using:

7. 7 Merge mapper The target file name will always be the same, as defined by to attribute. Example: Source file nameTarget file name A.Javaarchive.zip foo/bar/B.javaarchive.zip C.propertiesarchive.zip Classes/dir/dir2/A.propertiesarchive.zip This only sets the property zip.notRequired to true if src.zip is uptodate. (See more on task below.) Note using../ Here the mapper " to " attribute is relative to the " dir " attribute of the nested element (not relative to the base directory!). Example of using:

8. 8 Glob mapper Example: Source file nameTarget file name A.javaA.java.bak foo/bar/B.javafoo/bar/B.java.bak C.properties Ignored Classes/dir/A.properties Ignored 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. Example of using:

9. 9 Glob mapper (cont.) Another Example: Source file nameTarget file name A.Java Ignored foo/bar/B.java Ignored C.PropertiesQ.Property Classes/dir/A.propertiesQlasses/dir/A.property Again, it can be used in task: copying files with renaming.

10. 10 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.

11. 11 Package mapper Source file nameTarget file name org/apache/tools/ant/util/ PackageMapperTest.java TEST- org.apache.tools.ant.util. PackageMapperTest.xml org/apache/tools/ant/util/ Helper.java ignored Example: <mapper type="package" from="*Test.java" to="TEST-*Test.xml"/>  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 and output. SELF-STUDY

12. 12 Unpackage mapper Example: Source file nameTarget file name TEST-org.acme.AcmeTest.xml${test.src.dir}/org/acme/AcmeTest.java  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. <mapper type="unpackage" from="TEST-*Test.xml" to="${test.src.dir}/*Test.java"> SELF-STUDY

13. 13 Additional Ant Datatypes - to build an archive that contains the contents of other archive files. - like, but only for sets of directories. - like, but only for ordered file sets. - for.class file sets.

14. 14 Setting a property value by the task Saving time by skipping unnecessary steps Most tasks (such as ) deal with source/target up-to-date checking internally (by default). But there are cases (such as JUnit testing with task) where it is necessary to use a special task in Ant build file. This allows skipping unnecessary steps if some files are up-to-date.

15. 15 Setting a property value by the task (cont.) <uptodate property="compiling.unnecessary" value="OF COURSE!"> <mapper type="glob" from="*.java" to="../build/classes/*.class"/> Try Example (analogous to one considered formerly): In file C:\Antbook\ch02\secondbuild\mappers.xml : Here the mapper "to" attribute is relative to the root directory src of the nested srcfiles element (not relative to the base directory!). NOTE: Ant book seemingly has no such important comment! [See C:\JAVA\Ant1.8.2\docs\manual\index.html ->Ant Tasks->List of Tasks->Uptodate]

16. 16 Setting a property value by the task (cont.) This task sets the property tests.unnecessary to the value "OF COURSE!" if each.java file from the source tree is up to date – not newer than its corresponding.class file. The default value true has been changed by specifying a value attribute as value="OF COURSE!" Other types of mappers can also be used by task.

17. 17 Testing conditions with task sets a property if a certain condition is true. This is a composition of, and other such tasks. If the condition is true, the property value is set to true by default. Otherwise, the property is not set at all (is undefined). Conditions are specified as nested elements of task

18. 18 Conditions allowed to be nested within ElementDefinition Exactly the same semantics and syntax as the task, except property and value attributes are ignored. ( will declare them.) Evaluates to true if the resource is available Exactly the same semantics and syntax as the task, except property and value are ignored. Evaluates to true if file(s) are up-to-date Evaluates to true if the O/S family name ( mac, windows, unix, etc.), architecture, and version match with that declared by family attribute of. Evaluates to true if two properties have the same value Evaluates to true if a given property has been set (to any value) in this project. [C:\JAVA\Ant1.8.2\docs\manual\index.html ->Ant Tasks->List of Tasks->Condition]

19. 19 ElementDefinition Uses the same syntax as the task, evaluating to true if the checksum of the file(s) match. Checks for a valid response from a web server of the specified url Check for a socket listener on a specified port and host Byte-for-byte file comparison Tests whether one string contains another, optionally case-sensitive True if value is on, true, or yes The negation of Conditions available within SELF-STUDY [C:\JAVA\Ant1.8.2\docs\manual\index.html ->Ant Tasks->List of Tasks->Condition]

20. 20 This sets the property isMacOsButNotMacOsX to true if the current operating system is MacOS, but not MacOsX - which Ant considers to be in the Unix family as well. Analogous examples are possible with complicated logical combinations of and other conditions from the above table. (See Ant Book, P. 73.) [C:\JAVA\Ant1.8.2\docs\manual\index.html -> Ant Tasks -> List of Tasks -> Condition] Example with condition :

21. 21 Conditional build failure The next example shows how a build can exit, alerting the user of missing dependencies. We use the task forcing the failure of a build: <available classname="org.example.antbook.xdoclet.Main1" classpath="build\classes" /> <fail message="Missing dependencies!!!" unless="all.dependencies.present" /> Assume we do not have the class org.example.antbook.xdoclet.Main1 under build\classes. Run this target as part of a new file C:\Antbook\ch03\cond-build.failure.xml If BUILD FAILED, omit (or comment) the first task, and TRY it again. Note that Ant knows where to find JUnit! (See second.) SELF-STUDY

22. Software Development Tools COMP220 Dr Vladimir Sazonov Ant: Nested Builds These slides are mainly based on “ Java Tools for Extreme Programming” – R.Hightower & N.Lesiecki. Wiley, 2002

23. 23 Each project (or dependent subproject) should have  its own directory with  its own build file. Ant allows one Ant build file (master build) to call another. This is similar to the command line ant –f buildfile.xml some_target calling a build and some target in it. You can “nest” build files using this method to build many projects and their dependent projects. Nested Builds [See the XP book]

24. 24 The task within a build file is like the ant command and it  runs (calls) another specified build file, and hence  can be used to build subprojects and related projects  can specify - build file name by using the " antfile " attribute - or just a directory by the " dir " attribute assuming that the file build.xml in the directory specified is used by default - a particular target in the called Ant file to execute (otherwise the default target is used) - any properties set in the calling project are available to the “nested” (called) buidlfile - but a property set within task is set only for the called build file. Nested Builds: task [See the XP book]

25. 25 The following are simplest examples of calling another Ant build file from your current Ant build file. We can call a build file from the current (calling) build file and pass a property as follows: Instead of build file name we can specify only the subproject build directory: Then will use the default build file./hello/build.xml (if such exists) instead of./hello/some-build.xml. We can also specify the target to be executed (together with the targets which it depends on in the called build file): task: examples <ant antfile="./hello/some-build.xml" target="run"/>

26. 26 CREATE (or describe, if working without computer)  a system of (sub) directories C:\Antbook\ch02\master-project\hello  two simplest build files - master.xml, in directory master-project, and - build.xml in directory master-project\hello, having one target which contains two tasks.  master.xml should call build.xml by specifying either 1. the file build.xml, or 2. only directory with this file to be called by default, or 3. also a target in this file  master.xml should pass a property to the called file.  messages in build.xml should show on run time - which build file is running ( build.xml ), - the value of the property passed by master.xml by using ${…}. task: examples

27. 27 master.xml: master.xml: I passed PARAMETER passed-info with value ${passed-info} build.xml: task: examples build.xml running PARAMETER passed value is ${passed-info}

28. 28 Run master.xml: C:\Antbook\ch02\master-project>ant -f master.xml Buildfile: C:\Antbook\ch02\master-project\master.xml call: [echo] build.xml running build-target: [echo] PARAMETER passed value is SOME-INFO [echo] master.xml: I passed PARAMETER passed-info with value ${passed-info} BUILD SUCCESSFUL Amend master.xml to try all three versions of calling 1. the file build.xml (as above), or 2. only directory with this file to be called by default, or 3. also a target in this file task: example  Has no value? Why? See the last comment in slide 24 Build.xml is running

29. 29 CREATE (or describe, if working without computer)  additional directory C:\Antbook\ch02\master-project\hello-1  three simplest build files: - master-1.xml, in directory master-project, and - somebuild.xml, and renewed build.xml in directory hello-1, each having two targets that contain only tasks.  master-1.xml should have three targets, each calling either somebuild.xml or build.xml by specifying, respectively, 1. the file somebuild.xml or 2. only directory with these two files or 3. also a target in one of these files task: examples (continued…) For the Lab

30. 30  master-1.xml should pass a specific property value of the same property name passed-info in each of these calls describing the type of the call from master-1.xml (1,2,3 above).  messages in somebuild.xml and build.xml should show on run time - which of these build files is running, - the value of the property passed by master-1.xml, - since the property name is be the same in all three cases, but with different values, this is another demonstration of violating the immutability of properties. The resulting run should look like in the next slide. task: examples For the Lab

31. 31 C:\Antbook\ch02\master-project>ant -f master-1.xml Buildfile: C:\Antbook\ch02\master-project\master-1.xml [echo] master-1.xml is running by-file: [echo] calling FILE somebuild.xml [echo] somebuild.xml running [echo] PARAMETER passed value is BY-FILE somebuild-target-1: [echo] somebuild-target-1 is running somebuild-target-2: [echo] somebuild-target-2 is running by-dir: [echo] calling build.xml as DEFAULT file from DIRECTORY [echo] build.xml running [echo] PARAMETER passed value is BY-DIRECTORY build-target-1: [echo] build-target-1 is running build-target-2: [echo] build-target-2 is running by-target: [echo] calling TARGET build-target-1 in DEFAULT file build.xml [echo] build.xml running [echo] PARAMETER passed value is BY-TARGET build-target-1: [echo] build-target-1 is running BUILD SUCCESSFUL First call Second call Third call Highlighted targets and tasks of masrer-1.xml BY-FILE, BY-DIRECTORY, BY-TARGET are values of the same property passed by master-1.xml from different tasks For the Lab

32. Software Development Tools COMP220 Dr Vladimir Sazonov More on Ant for Self-Study These slides are mainly based on “ Java Tools for Extreme Programming” – R.Hightower & N.Lesiecki. Wiley, 2002

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

34. 34 Ant Book System build time: @DATE@ @ @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: Inserting date stamps in files at build-time  Put it, say, in the directory web. SELF-STUDY

35. 35 Inserting date stamps in files at build-time Here @DATE@ and @TIME@ will be replaced during the copy:  The task, before task, creates the DSTAMP and TSTAMP Ant properties with corresponding values.  The values of ${DSTAMP} and ${TSTAMP} contain the (current) date and time stamps, respectively, due to running the task. SELF-STUDY

36. 36  Recall that 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). Inserting date stamps in files at build-time SELF-STUDY

37. 37 Inserting date stamps in files at build-time Ant Book System build time: 20050214 @ 1501  Applying this filtered copy on the above JSP file produces something like the following: There are much more capabilities of filtering in Ant. Optional Reading: See some more examples in Section 3.9 of Ant Book and in C:\JAVA\Ant1.8.1\docs\manual\index.html SELF-STUDY

38. 38 Creating a build timestamp with The task in its simplest empty form sets three properties automatically based on the current date/time. PropertyValue format (based on current date/time) DSTAMP“YYYYMMDD” TSTAMP“HHMM” TODAY“MONTH DAY YEAR” The task also allows any number of nested elements which define properties, given a format specification (as defined in the Java SimpleDateFormat class) SELF-STUDY

39. 39 Creating a build timestamp with TRY time-date.xml in C:\Antbook\ch03 : <format property="buildtime" pattern="yyyy-MM-dd'T'HH:mm:ss"/> <format property="dayofweek" pattern="EEEE"/> E means “day of week”; EEEE produces Monday, EEE produces Mon. SELF-STUDY

40. 40 H:\Antbook\ch03>ant -f time-date.xml Buildfile: time-date.xml [echo] DSTAMP is 20050225 [echo] TSTAMP is 1626 [echo] TODAY is February 25 2005 [echo] It is Friday [echo] buildtime is 2005-02-25T16:26:23 BUILD SUCCESSFUL Creating a build timestamp with This is the result: Try it yourself. How to copy a fileset with inserting the current date in resulting file names? Hint: use glob mapper. SELF-STUDY