Lukáš Asník Software Development & Monitoring Tools (NSWI126)
Contents tasks <available>, <condition>, <antcall> conditionally processed targets attributes if and unless properties in external files dependencies between targets typical structure of build file real example: Ant build file
Task <available> sets property if resource is available at runtime otherwise property is not set resource: file, directory, class, JVM system resource attributes: property: name of the property to set value: value set to property (default: true) classname, file, resource: class, file or resource to look for classpath, filepath: (class)path to use when looking up classname or resource (classpath) or file (filepath)... usage: both can be set via nested element to set properties useful to avoid target execution depending on system parameters
<available> Example 1/2 <project name="available_example" default="printproperties" basedir="."> <description> Example of using Available task. </description> <available file="file1.txt" property="file1.present" value="file1.txt is present"> <filepath> <dirset dir="../dir1a"/> </filepath> </available> <available file="file2.txt" searchparents="true" property="file2.present"/> <available file="file3.txt" property="file3.present"/> <target name="printproperties"> <echo message="file1.present = ${file1.present}"/> <echo message="file2.present = ${file2.present}"/> <echo message="file3.present = ${file3.present}"/> </project>
<available> Example 2/2
Task <condition> generalization of <available> sets property if certain condition holds true otherwise not set (or value set to else attribute) attributes: property: name of the property to set value: value set to the property (default: true) else: value set to property if condition evaluates to false conditions to test specified as nested elements core and custom conditions
Core Conditions nested elements in <condition> and <waitfor> tasks <not>, <and>, <or>, <xor> no attributes shortcut semantics as Java && and operators conditions evaluated in the order they were specified <available>, <uptodate> identical to the tasks but property and value attributes ignored <os> tests the type of OS, all specified attributes must be true attributes: family, name, arch, version <equals> tests whether two values are equal attributes: arg1, arg2, casesensitive, trim, forcestring
Core Conditions <isset> tests, whether given property is set (attribute property) <filesmatch> byte for byte comparison, two nonexistent files are considered equal attributes: file1, file2, textfile <contains> tests, whether string contains another one attributes: string, substring, casesensitive <istrue> tests, whether string equals any definition of true ("true", "yes", "on") <isfalse> negation of istrue <isref> whether reference was defined in the project, optionally type of the reference <length>, <checksum>, <http>, <socket>, <typefound>,...
Core Conditions Example <project name="condition_example" default="printproperties" basedir="."> <property name="testproperty" value="value1" /> <condition property="condition.result" value="condition is true!" else="condition 1 is false!"> <and> <isset property="testproperty"/> <not> <istrue value="false"/> </not> <or> <equals arg1="a" arg2="b"/> <contains string="string" substring="str" casesensitive="false"/> </or> </and> </condition> <target name="printproperties"> <echo message="${condition.result}"/> </project>
Custom Conditions implement interface org.apache.tools.ant.taskdefs.condition.condition package com.mydomain; import org.apache.tools.ant.buildexception; import org.apache.tools.ant.taskdefs.condition.condition; public class AllUpperCaseCondition implements Condition { private String value; // The setter for the "value" attribute public void setvalue(string value) { this.value = value; } } // This method evaluates the condition public boolean eval() { if (value == null) { throw new BuildException("value attribute is not set"); } return value.touppercase().equals(value); }
Custom Conditions add condition to the system using <typedef> element <typedef name="alluppercase" classname="com.mydomain.alluppercasecondition" classpath="${mydomain.classes}"/> use wherever Core conditions are used
Task <antcall> calls another target within the same buildfile may specify properties (params) must not be used outside of a target! attributes: target: target to execute inheritall: true pass all properties to new project (default: true) inheritrefs: true pass all references to new project (default: false)
<antcall> Properties Passing if inheritall is set to false, only user properties are passed to new project (i. e. command line properties) passed properties override properties set in the new project tag <param>: equivalent to command line properties, does not override them when more <param> elements set the property with the same name, the last declared wins
Properties Passing Example 1/2 <project name="antcall_example_1_param" default="default" basedir="."> <description> Example of passing new properties using param element. </description> <property name="param1" value="this value will be overriden."/> <target name="default"> <antcall target="dosomethingelse"> <param name="param1" value="passedpropertyvalue"/> <param name="cmlparam" value="cannotoverridecommandlineproperty"/> <param name="settwice" value="first"/> <param name="settwice" value="second"/> </antcall> <target name="dosomethingelse"> <echo message="param1=${param1}"/> <echo message="cmlparam=${cmlparam}"/> <echo message="settwice=${settwice}"/> </project>
Properties Passing Example 2/2
<antcall> References <reference> references that should be copied attributes refid: reference in calling project torefid: id of reference in the new project <project name="antcall_example_2_reference" default="default" basedir="."> <path id="path1"> <pathelement path="a"/> <pathelement path="b"/> </path> <path id="path2"> <pathelement path="c"/> <pathelement path="d"/> </path> <target name="default"> <antcall target="printpath"> <reference refid="path2" torefid="path1"/> </antcall> <target name="printpath"> <pathconvert property="pathproperty" refid="path1"/> <echo>path1 is ${pathproperty}</echo> </project>
If and Unless attributes of <target> (and various tasks) target gets executed if/unless a property (name specified as value of if/unless) has been set or the value of if/unless evaluates to true/false only one property for multiple conditions use dependent target <target name="mytarget" depends="mytarget.check" if="mytarget.run"> <echo>files foo.txt and bar.txt are present.</echo> <target name="mytarget.check"> <condition property="mytarget.run"> <and> <available file="foo.txt"/> <available file="bar.txt"/> </and> </condition>
If and Unless Example <project name="ifunless_example" default="default" basedir="."> <property name="true" value="true" /> <property name="false" value="false"/> <target name="t1" if="${true}"> <echo message="target t1"/> <target name="t2" if="${notassigned}"> <echo message="target t2"/> <target name="t3" unless="${false}"> <echo message="target t3"/> <target name="default" depends="t1,t2,t3"/> </project>
Properties in External Files task Property: <property file= pathtofile /> attribute name must not be used file format: <key>:<value> <key>=<value> same as file used in java.util.properties if file is not present, nothing happens
Properties File Example #This is a comment line. Comment line may also start with "!".!Comment line. Every comment line must contain "#" or "!" as its!first non-white space character. #Next line contains only white space and is ignored. #key=value capital=prague #key=value country : \ The \ Czech \ Republic #key with empty string as a value empty #key with empty string as a value empty2 = #Escaping, backslash before z is silently dropped (z is not valid escape character) weird\=key\: = \z
Properties From File Example <project name="propertiesfromfile" default="printproperties" basedir="."> <property file="build.properties"/> <target name="printproperties"> <echo message="capital = ${capital}"/> <echo message="country = ${country}"/> <echo message="empty = ${empty}"/> <echo message="empty2 = ${empty2}"/> <echo message="weird=key: = ${weird=key:}"/> </project>
Target Dependencies target can depend on other targets Ant ensures that those targets have been executed before the current target dependency specified by attribute depends contains list of (comma separated) targets order of execution Ant tries execute targets in order specified by attribute depends target can get executed earlier if earlier target depends on it each target is executed only once! Example (execute target D): <target name="a"/> <target name="b" depends="a"/> <target name="c" depends="b"/> <target name="d" depends="c,b,a"/> Call-Graph: A --> B --> C --> D
Standard Ant Targets init (initialization) sets properties <target name="init"> <tstamp/> creates path-like structures <tstamp/> prepare creates directory structure <target name="prepare" depends="init"> <mkdir dir="${build.dir}"/>
Standard Ant Targets compile <javac> test <target name="compile" depends="prepare"> <javac srcdir="${src.dir}" destdir="${build.dir.classes}" classpath="${classpath}"/> unit testing and reporting <target name="test" depends="compile"> <junit failureproperty="testsfailed"> <classpath> <pathelement path="${classpath}"/> <pathelement path="${build.dir.classes}"/> </classpath> <formatter type="xml"/> <test name="chapter3.test.testall" todir="${reports.dir}"/> </junit> <junitreport todir="${reports.dir}"> <fileset dir="${reports.dir}"> <include name="**/test-*.xml"/> </fileset> <report format="frames" todir="${reports.dir.html}"/> </junitreport>
Standard Ant Targets jar/dist <target name="jar" depends="test" unless="testsfailed"> <jar destfile="${build.dir}/${name}.jar" basedir="${build.dir}" includes="**/*.class"/> docs generate documentation <target name="docs" depends="test" unless="testsfailed"> <javadoc packagenames="com.mycompany.*" sourcepath="${src.dir}" classpath="${classpath}" destdir="${doc.api.dir}" author="true" version="true" use="true" windowtitle="myproject Documentation"> <bottom><![cdata[<em>copyright 2002</em></div>]]></bottom> <link href="http://java.sun.com/products/jdk/1.3/docs/api"/> </javadoc>
Standard Ant Targets clean removes all compiled and intermediate files <target name="clean"> <delete dir="${build.dir}"/> another targets: main, fetch, all default target: set by default attribute of <project> most often used target
Real Example: Ant build file 2030 lines 76 KB
Q & A
Literature Online: http://ant.apache.org/ http://www.informit.com/articles/article.aspx?p=30183&seqnum=2