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

2 More on Properties  A project can have a set of properties (parameters).  These can be set either  i n the build file by the task, or  outside of Ant build file from the command line.  A property has a name and a value.  Case-sensitive!  For example, if there is  a property name "build.dir"  with the value "build", then this could be used in an attribute like this: destdir="${build.dir}/classes "  This is resolved at run-time as build/classes. [See C:\JAVA\Ant1.8.2\docs\manual\index.html -> Using Ant -> Properties]

3 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 URL: 

4 Some built-in properties of Ant basedir the absolute path of the project's base directory (as set with the optional basedir attribute of ). ant.file the absolute path of the build file. ant.version the version of Ant ant.project.name the name of the project that is currently executing; it is defined by the name attribute of. ant.java.version the JVM version detected by Ant; currently it can hold the values from "1.1" to "1.6". ant.home the path to executing version of Ant's root directory

5 Built-in Properties of Ant (cont.) SOME ANT BUILT-IN PROPERTIES: Examine these built-in properties: TRY it! (Do this by putting the above target into new builtinprop.xml file; see also the next slide.)

6 Built-in Properties of Ant (cont.) This generates output similar to this C:\Antbook\ch02\secondbuild>ant -f builtinprop.xml AntSysProp Buildfile: C:\Antbook\ch02\secondbuild\builtinprop.xml AntSysProp: [echo] [echo] SOME ANT BUILT-IN PROPERTIES: [echo] [echo] ant.home = C:\JAVA\Ant1.8.2 [echo] ant.java.version = 1.6 [echo] ant.version = Apache Ant(TM) version compiled on December [echo] basedir = C:\Antbook\ch02\secondbuild [echo] ant.file = C:\Antbook\ch02\secondbuild\builtinprop.xml [echo] ant.project.name = builtin BUILD SUCCESSFUL Total time: 0 seconds Pay attention to basedir property.

7  basedir, as a property, defaults to the path of the current build file (if basedir ’s attribute is absent)  basedir, as project’s attribute : -fixes the base directory where from all path calculations are done -the value of this attribute can be overridden by setting the basedir property by the command line switch: –Dbasedir=some_other_directory before running the build file basedir property and basedir attribute in element

8 basedir property and basedir attribute in element  TRY to check that any of >ant –Dbasedir=... in command line, and basedir="...", as 's attribute, can change built-in Ant basedir property. (see also Slide 14.) In this case, e.g., our old init target will create directories relative to the new base directory!  If neither the attribute basedir nor the property basedir have been set, the current directory basedir="." of the build file will be used by default.

9 JVM system properties from Ant Some JVM system properties can be shown by using: TRY it! (Do this by extending builtinprop.xml file considered in slides 5,6.) You should get something like this: [echo] user.name = sazonov [echo] user.home = C:\Users\sazonov [echo] java.home = C:\Program Files\Java\jdk1.6.0_24\jre BUILD SUCCESSFUL

10 Setting properties with the task The task allows build files to define their own custom properties. The most common variations of creating properties by task are 1. via name/value attributes 2. via name/location attributes 3. by loading a set of properties from a properties file named like build.properties 4. by loading environment variables as properties (the details for self-study; Slide 23)

11 Setting and using a simple property E.g. we can set a property named build.debug as This can be used for paramatrizing task Thus, compiling will always run with the debugging information (telling to the compiler to include some information from the source code into the compiled class for future use by the debugger jdb as explained in - Optional Self-study). But you can override the above value="on" from command line: >ant -Dbuild.debug=off –f yourBuildFile.xml

12 Loading properties from a properties file CREATE properties file (in another directory) C:\Antbook\ch03\build.properties consisting of name/value pairs for each property: This file can be loaded from Ant build file with the same base directory C:\Antbook\ch03 by the task with the file attribute: If Ant build file has another (our current) base directory C:\Antbook\ch02\secondbuild then we should use Anyway, when this properties file is loaded, output.dir property will have the value … ??? build/output build.debug=off build.dir=build output.dir=${build.dir}/output

13 Fixing properties to absolute path locations IMPORTANT: the values provided by name and value attributes and by name and value pairs of a properties file are considered as literal strings of symbols (except possibly participating ${…} ). Thus, build/output above should be understood as exactly this string of symbols. If we want build/output to be resolved to absolute path C:\Antbook\ch02\secondbuild\build\output, then we should rather use name and location attributes instead of name and value, and should not use properties from properties files (which always assume value rather than location ). (See the next slide for illustration) Addi tion here

14 Fixing properties to absolute path locations TRY in C:\Antbook\ch02\secondbuild : and see the difference between the effects of value and location attributes. (Do this by further extending builtinprop.xml file with properties discussed in Slides 5 and 9) Which two echo messages will we get? What if to change (temporary) basedir= ". " in element to basedir= "../../ch03 "? After checking, recover basedir= ". " in.

15 Overriding a property??? (Immutability of properties) RUN in the directory C:\Antbook\ch03> build file checkproperties.xml containing: Recall that the above properties file C:\Antbook\ch03\build.properties states build.debug=off. GUESS the result! [echo] build.debug = ??? [echo] build.debug = off [echo] build.debug = ??? [echo] build.debug = off [See file build.properties in Slide 12]

16 Immutability of properties Once a property has been set, either in the build file or on the command line, it cannot be changed. WHAT should be the result of the above experiment if either file build.properties or the property build.debug in file build.properties would not exist? TRY it, by running again checkproperties.xml and explain the result! [echo] build.debug = ??? [echo] build.debug = ${build.debug} [echo] build.debug = ??? [echo] build.debug = ${build.debug} [echo] build.debug = on

17 Immutability exceptions Nevertheless, there are ways to break the immutability of properties, for example, by using Ant task (to be considered soon). Most of the reasons for such exceptions are logically legitimate, yet certainly an area of confusion and concern. Hence, Ant can warn you that this exceptions of the immutability of properties is DEPRECATED.

18 Immutability exceptions??? NOTE THAT –D command-line option overriding properties is not considered as an exception! -D is a deliberate tool to set a property in advance, immediately before running build file: Even if the build file contains a task intended to change a property which has been set up from the command line with –D, this task will not actually change it. Thus, immutability is not violated by -D.

19 Loading properties file with prefix attribute If we want to use different properties files containing the same property name with different values, then we can avoid clashing by using prefix attribute.

20 Loading properties file with prefix attribute Consider again our build.properties file and download it as above, but with prefix attribute: build.debug=off build.dir=build output.dir=${build.dir}/output

21 This will add prefix tmp. to all property names from this build.properties file and will result in: The last two properties being now undefined indeed, only prefixed properties have been set up. Loading properties file with prefix attribute [echo] tmp.build.debug = off [echo] tmp.output.dir = build/output [echo] tmp.build.debug = off [echo] tmp.output.dir = build/output [echo] build.debug = ??? [echo] output.dir = ??? [echo] tmp.build.debug = off [echo] tmp.output.dir = build/output [echo] build.debug = ${build.debug} [echo] output.dir = ${output.dir} build.debug=off build.dir=build output.dir=${build.dir}/output

22 Another properties file build1.properties can be downloaded with some other prefix="tmp1". This way shared properties from various properties files, even with different values, may be consistently considered together with different prefixes. For example: tmp.build.debug = off tmp1.build.debug = on Therefore, the information from various properties files may be consistently unified. Loading properties file with prefix attribute

23 Loading environment variables as properties This fragment of Ant build file reads the system environment variables and stores them as properties, prefixed with " env “, i n order to avoid inadvertent collision with existing Ant properties, and especially to stress on the origin of these properties TRY it. [See C:\JAVA\Ant1.8.2\docs\manual\index.html -> Ant Tasks -> List of Tasks -> Property] Create build file EnvVar.xml containing:

24 task outside of targets? task may occur as part of a, but also is allowed to stand alone – directly as a child element of. All tasks that appear outside of targets are evaluated before any target. Therefore, it is best to put all such “non-target property declarations” of a before all targets, to avoid confusion, like in the following (schematic) slide:

25 task outside of targets project hello running <property file="build.properties" prefix= "…" />... Literal value Resolves to abs. path Downloads prop. file Env. var. as proprties All targets at after properties

26 Setting a property value by the task sets a property if a resource is available at runtime. This resource can be  file or directory,  class in classpath,  JVM system resource. General description of the task [See C:\JAVA\Ant1.8.2\docs\manual\index.html ->Ant Tasks ->List of Tasks->Available]

27 Setting a property value by the task If the resource is present, the property value is set to true by default, otherwise, the property is not set at all (is undefined). You can set the value to something other than the default by specifying the value attribute of the task. Normally, this task is used to set properties that can be used to avoid some target execution depending on system parameters. General description of the task [See C:\JAVA\Ant1.8.2\docs\manual\index.html ->Ant Tasks ->List of Tasks->Available]]

28 : Checking for the existence of a class in a classpath <available classname="org.example.antbook.lesson1.Main" classpath="dist/project.jar" property ="MainClass.present.in.jar"/> MainClass.present.in.jar is ${MainClass.present.in.jar} and <available classname="org.example.antbook.lesson1.Main" classpath="build\classes" property ="MainClass.present.in.classes"/> MainClass.present.in.classes is ${MainClass.present.in.classes} Consider two fragments of a target in build file C:\Antbook\ch02\secondbuild\available.xml: They set two properties as follows:

29 The above build file available.xml sets the properties MainClass.present.in.jar and MainClass.present.in.classes to the value " true ", if the class org.example.antbook.lesson1.Main is found in the corresponding classpath mentioned in the above build file. Otherwise no value is set at all! : Checking for the existence of a class in a classpath

30 TRY to check this by running the above file available.xml in the directory C:\Antbook\ch02\secondbuild. You should preliminary run the build file structured.xml discussed formerly to create Main.class and project.jar (if they do not exist yet) in appropriated directories. Check what will be the echo message if the required class or JAR file would not exist (say, if you delete or re-name it)? : Checking for the existence of a class in a classpath

31 TRY to check the exception to immutability of properties by using task: Add the following and task can violate immutability of a property <property name="MainClass.present.in.jar“ value="maybe"/> <echo message="MainClass.present.in.jar is ${MainClass.present.in.jar}"/> <available classname="org.example.antbook.lesson1.Main" classpath="dist/project.jar" property ="MainClass.present.in.jar" /> <echo message="MainClass.present.in.jar is ${MainClass.present.in.jar}"/> before the first fragment considered above (in Slide 28): Running the above shows that the property is changed from maybe to true, but THIS EXCEPTION IS NOT RECOMMENDED TO USE! DEPRECATED!

32 : Checking for the existence of a file or directory <available file="${project.jar}" type="file" property="project.jar.present"/> <echo message= "file ${project.jar} is present=${project.jar.present}"/> This sets the project.jar.present property to the value true if the file./dist/project.jar is found, and undefined, otherwise (instead of false !!!). The type attribute determines whether the file should really be a file or dir specifically. The default behaviour for file attribute without a type attribute is either a file or directory. TRY this example with using task to see the result. What will you see in the console if this file does not exist (deleted or re-named)? it could be type="dir"

33 : Checking for the existence of a JVM system resource <available resource="project.jar" property="project_jar"> resource project.jar is present=${project_jar} This sets the project_jar property to the value " true " if the resource-file project.jar is found in the path dist. JVM system resource is any file on a classpath. TRY the following 7 slides on and postponed

34 Setting properties from the command line Controlling the build process can be accomplished by setting an Ant property from the command line, for, example, if you want to use a new library version for a single build, or if you want to supply a password to a deploy process. There are two command-line switches used to set properties: -D –propertyfile. A property set from the command line is so firm that it cannot be overridden, even using, or similar tasks ( and considered later).

35 Setting properties from the command line Example of building with a different library version The task <property name="lib_jar" location="lib/library.jar"/> sets the property lib_jar to a current library archive. Before incorporating permanently some new library in the official build file in the place of currently used lib/library.jar we can start temporary working with this new library from the command line: ant -Dlib_jar=C:/newversion/library_new.jar compile

36 Properties defined with –D are defined before any processing of the build file occurs. The –propertyfile defines all properties from the specified property file exactly as if each property were individually specified with –D. Properties specified from –D take precedence over those specified from –propertyfile to allow for individual override control. Setting properties from the command line

37 Setting properties from the command line For example, if newlib.properties file contains the line lib_jar=lib/library.jar (*) and the following command is executed (as one line) ant -propertyfile newlib.properties -Dlib_jar=C:/newversion/library_new.jar compile then the value of lib_jar from -D switch (not from the property file!) will be used. In this case lib_jar would have the value C:/newversion/library_new.jar, i.e. not as in (*) above.

38 Controlling Ant with Properties Utilizing Ant’s properties wisely can give a build file highly dynamic nature. Allows to easily adjust the build process to its operating environment and user preferences. There are many ways in which properties can help control builds. NOTE: The concrete value of a property is not always important: In some contexts, simply the existence of a property (whether it is defined at all) is relevant and its actual value not. Of course, there are contexts in which the value of a property is important, e.g. a property whose value is a directory name (or properties produced by task considered later as self-study).

Conditional target execution with if/unless A target can be made able to perform execution of its contents if (or unless ) a property has been set. This allows, for example, to have a better control on the build process depending on the state of the system such as Java version, OS, command-line property defined, etc. To this end, you should add the if (or unless ) attribute with the name of the property that the target should react to. Note: with if / unless Ant will only check whether the property has been set, the particular value doesn't matter. But note that a property set to the empty string is still an existing property. 39 [ See C:\JAVA\Ant1.8.2\docs\manual\index.html->Using Apache Ant->Built-in Properties ]

40 Example of conditional target execution <target name="build-module-A" if="module-A-present"/> <target name="build-module-B" unless="module-A-present"/> The first target’s content will run (when called), if and only if, the property module-A-present is set (to any value). The second target’s content will run, if and only if, the property module-A-present is not set at all. the analogue of if-then-else The property module-A-present can be set either in command line as -Dmodule-A-present=true or by using or one of the many variants of task. If if or unless attribute is absent, the target content will always be executed (of course, if called) – just as usually. Only the existence of a property, regardless of value, is taken into account for if/unless That is why we should not use ${…} around the property name module-A- present ! But you can see yourself what is the undesirable effect of using ${…} here. These two targets are empty for simplicity [ See C:\JAVA\Ant1.8.2\docs\manual\index.html->Using Apache Ant->Built-in Properties ]

41 More detailed version of the above example of conditional target execution <target name="build-module-A" if="module-A-present"> <target name="build-module-B" unless="module-A-present"> <target name="all" depends="build-module-A, build-module-B"/> 1.Run file C:\Antbook\ch03\if-unless.xml : 2. TRY also value="no" or any other value. 3. Comment the line to make module-A-present undefined, and run the build file. Then UNCOMMENT it back. 4. Set this property from the command line using –D switch. 5. RUN this also in verbose mode (using –v switch). 6. RUN this also with unless="${module-A-present}". Using present instead of yes

42 TRY variations of the following and explain the results C:\Antbook\ch03\ cond-target-exec.xml: <javac srcdir="src" destdir="build/classes" includeAntRuntime="no"/> C:\Antbook\ch03>ant -f cond-target-exec.xml C:\Antbook\ch03>ant -f cond-target-exec.xml -Dcopy.source=true What was copied and where? Check the contents of our.jar by using command jar tf dist\our.jar or jar tvf dist\our.jar. Good exercise for the lab. Useful for Class Test. You should be able to predict which will be the result of running this and any build file.

43 Conditional patternset inclusion/exclusion Example of including or excluding files to/from compilation: <javac srcdir="src" destdir="build/classes“ includeAntRuntime="no"/> <exclude name= "org/example/antbook/xdoclet/*.java" if= "omit.xdoclet" /> is acting here on an implicit fileset. TRY it: 1. extend cond-target-exec.xml from the previous slide with the above target compile2, and 2. appropriately extend our directory and file system under C:\Antbook\ch03\src 3. run C:\Antbook\ch03>ant -f cond-target-exec.xml clean compile2 -D omit.xdoclet =true with or without -D omit.xdoclet =true if/unless technique works also for any patternset.

44 References Ant provides rich datatypes to work with, and it also provides the ability to reuse datatype definitions. Each Ant datatype declaration allows an optional unique identifier – the value of id attribute. We can refer to this id elsewhere by using refid attribute. For example, define compile classpath with an id="compile.classpath"

45 References (cont.) Then reuse compile.classpath 's definition: refid="compile.classpath" adds two path elements from the previous slide.

46 The refid and id attributes can be used for all datatypes, including path, fileset, patternset, filterset (and mapper considered later). Anywhere a datatype is declared, it can have a (unique) id associate with it, even when used inside a task. It is recommended, however, that datatypes that will be reused with refid be declared as stand- alone datatypes : just under root tag for readability and clarity. References (cont.)

47 Finally, refid can also be used in a task for setting a property (like location attribute): C:\Antbook\ch03\ref-classpath.xml: References used in setting a property path is ${path} C:\Antbook\ch03>ant -f ref-classpath.xml Buildfile: ref-classpath.xml [echo] path is C:\Antbook\ch03\dist\build\classes;C:\Antbook\ch03\dist\src BUILD SUCCESSFUL Pay attention to the role of basedir ! TRY to vary basedir in this file. SELF-STUDY

48 Summary (Ant datatypes and properties) Our purpose was to introduce the foundational Ant concepts: - paths, filesets, patternsets, filtersets (i.e. datatypes), and - properties, - references.  Ant uses datatypes to provide rich reusable parameters to tasks  is a task utilizing most of Ant’s datatypes

49 Summary (Ant datatypes and properties) (cont.)  A path represents an ordered list of files and directories.  Many tasks can accept a classpath, which is an Ant path.  Paths can be specified in a cross platform manner,  the MS-DOS conventions of semicolon(;) and backslash(\) or the Unix conventions of colon(:) and slash (/) - Ant sorts it all out at run time.  A fileset represents a collection of files rooted from a specified directory.  Tasks that operate on sets of files often use Ant’s fileset datatype.  A patternset represents a collection of file matching patterns.

50  Properties are the heart of Ant’s extensibility and flexibility.  They provide a mechanism to store variables and load them from external resources including the environment.  The rules governing properties, such as immutability, have crucial role in designing build files.  Wisely utilising the fundamental Ant features discussed till now gives the build file  elegance, structure, reusability, extensibility, and control. Summary (Ant datatypes and properties) (cont.)