Ant指南
1. Ant是什么？
2. 安装Ant
3. q行Ant
4. ~写build.xml
5. 内置task(internet)
6. EAR task(internet)
7. WAR task(internet)
8. JUnit task(internet)
1. Ant是什么？
2. 安装Ant
3. q行Ant
4. ~写build.xml
5. 内置task(internet)
6. EAR task(internet)
7. WAR task(internet)
8. JUnit task(internet)
1. Ant是什么？
Ant是一U基于Java的build工具。理Z来说Q它有些cM于（UnixQC中的make Q但没有make的缺陗?br />2. 安装Ant
既然我们已经有了make, gnumake, nmake, jam以及其他的build工具Z么还要要一U新的build工具呢？因ؓAnt的原作者在多种(g)q_上开发Y件时Q无法忍受这些工L限制和不ѝ类gmake的工h质上是基于shellQ语aQ的Q他们计依赖关p，然后执行命oQ这些命令与你在命o行敲的命令没太大区别Q。这意味着你可以很Ҏ地通过使用OSҎ的或~写新的Q命令）E序扩展该工P然而，q也意味着你将自己限制在了特定的OSQ或特定的OScd上，如Unix?br />
Makefile也很可恶。Q何用过他们的h都碰到过可恶的tab问题。Ant的原作者经常这样问自己Q“是否我的命令不执行只是因ؓ在我的tab前有一个空|Q！”。类gjam的工具很好地处理了这c问题，但是Q用P必须C和用一U新的格式?br />
Ant׃同了。与Zshell命o的扩展模式不同，Ant用Java的类来扩展。（用户Q不必编写shell命oQ配|文件是ZXML的，通过调用target树，可执行各种task。每个task由实C一个实C特定Task接口的对象来q行。（如果你对Ant一Ҏ念都没有的话Q可能看不懂q一节，没有关系Q后面会对target,task做详l的介绍。你如果没有太多的时间甚臛_以略q这一节，然后再回来浏览一下这里的介绍Q那时你׃看懂了。同P如果你对make之类的工具不熟悉也没关系Q下面的介绍Ҏ不会用到make中的概念。）
必须承认Q这样做Q在构造shell命o时会失去一些特有的表达能力。如`find . -name foo -exec rm {}`Q但却给了你跨^台的能力Q你可以在Q何地方工作。如果你真的需要执行一些shell命oQAnt有一?lt;exec> taskQ这个task允许执行特定OS上的命o?br />
q回
׃Ant是一个Open Source的YӞ所以有两种安装Ant的方式，一U是用已~译好的binary 文g安装AntQ另一U是用源代码自己build Ant?br />3. q行Ant
binary 形式的Ant可以?a >http://jakarta.apache.org/builds/ant/release/v1.4.1/bin下蝲。如果你希望你能自己~译AntQ则可从 http://jakarta.apache.org/builds/ant/release/v1.4.1/src。注意所列出的连接都是最新发行版的Ant。如果你d此文Ӟ发现已经有了更新的版本，那么L新版本。如果你是一个疯狂的技术追求者，你也可以?a target="_top">Ant CVS repository下蝲最新版本的Ant?br />
pȝ需?/i>
要想自己build Ant。你需要一个JAXP兼容的XML解析器（parserQ放在你的CLASSPATHpȝ变量中?br />
binary 形式的Ant包括最新版?a >Apache Crimson XML解析器。你可以?a >http://java.sun.com/xml/ 得到更多的关于JAXP的信息。如果你希望使用其他的JAXP兼容的解析器。你要从Ant的lib目录中删掉jaxp.jar以及crimson.jar。然后你可将你心q解析器的jar文g攑ֈAnt的lib目录中或攑֜你的CLASSPATHpȝ变量中?br />
对于当前版本的AntQ需要你的系l中有JDKQ?.1版或更高。未来的Ant版本会要求用JDK 1.2或更高版本?br />
安装Ant
binary 版的Ant包括三个目录:bin, docs 和lib。只有bin和lib目录是运行Ant所需的。要惛_装AntQ选择一个目录ƈ发行版的文件拷贝到该目录下。这个目录被UCANT_HOME?br />
在你q行Ant之前需要做一些配|工作?br />注意Q不要将Ant的ant.jar文g攑ֈJDK/JRE的lib/ext目录下。Ant是个应用E序Q而lib/ext目录是ؓJDK扩展使用的（如JCEQJSSE扩展Q。而且通过扩展装入的类会有安全斚w的限制?br />
- bin目录加入PATH环境变量?/font>
- 讑֮ANT_HOME环境变量Q指向你安装Ant的目录。在一些OS上，Ant的脚本可以猜ANT_HOMEQUnix和Windos NT/2000Q－但最好不要依赖这一Ҏ?/font>
- 可选地Q设定JAVA_HOME环境变量Q参考下面的高节Q，该变量应该指向你安装JDK的目录?br />
可选Task
Ant支持一些可选task。一个可选task一般需要额外的库才能工作。可选task与Ant的内|task分开Q单独打包。这个可选包可以从你下蝲Ant的同一个地方下载。目前包含可选task的jar文g名叫jakarta-ant-1.4.1-optional.jar。这个jar文g应该攑ֈAnt安装目录的lib目录下?br />
每个可选task所需的外部库可参?a >依赖?/font>节。这些外部库可以攑ֈAnt的lib目录下，q样Antp自动装入Q或者将其放入环境变量中?br />
Windows
假定Ant安装在c:\ant\目录下。下面是讑֮环境的命令：set ANT_HOME=c:\antUnix (bash)
set JAVA_HOME=c:\jdk1.2.2
set PATH=%PATH%;%ANT_HOME%\bin
假定Ant安装?usr/local/ant目录下。下面是讑֮环境的命令：export ANT_HOME=/usr/local/ant高
export JAVA_HOME=/usr/local/jdk-1.2.2
export PATH=${PATH}:${ANT_HOME}/bin
要想q行Ant必须使用很多的变量。你臛_参考需要下面的内容Q?br />Building Ant
- Ant的CLASSPATH必须包含ant.jar以及你所选的JAXP兼容的XML解析器的jar文g?/font>
- 当你需要JDK的功能（如javac或rmic taskQ时Q对于JDK 1.1QJDK的classes.zip文g必须攑օCLASSPATH中；对于JDK 1.2或JDK 1.3Q则必须加入tools.jar。如果设定了正确的JAVA_HOME环境变量QAnt所带的脚本Q在bin目录下，会自动加入所需的JDKcR?/font>
- 当你执行特定q_的程序（如exec task或cvs taskQ时Q必设定ant.home属性指向Ant的安装目录。同PAnt所带的脚本利用ANT_HOME环境变量自动讄该属性?/font>
要想从源代码build AntQ你要先安装Ant源代码发行版或从CVS中checkout jakarta-ant模块?br />
安装好源代码后，q入安装目录?br />
讑֮JAVA_HOME环境变量指向JDK的安装目录。要想知道怎么做请参看安装Ant节?br />
保你已下蝲了Q何辅助jar文gQ以便build你所感兴的task。这些jar文g可以攑֜CLASSPATH中，也可以放在lib/optional目录下。参?a >依赖?/font>节可知不同的task需要那些jar文g。注意这些jar文g只是用作build Ant之用。要惌行AntQ你q要?i>安装Ant节中所做的那样讑֮q些jar文g?br />
现在你可以build Ant了：build -Ddist.dir=<directory_to_contain_Ant_distribution> dist (Windows)q样可你指定的目录中创Z个binary版本?br />
build.sh -Ddist.dir=<directory_to_contain_Ant_distribution> dist (Unix)
上面的命令执行下面的动作Q?br />大多数情况下Q你不必直接bootstrap AntQ因为build脚本Z完成q一切。运行bootstrap.bat (Windows) ?bootstrap.sh (UNIX) 可以build一个新的bootstrap版Ant?br />
- 如果有必要可以bootstrap Ant的代码。bootstrap 包括手工~辑一些Ant代码以便q行Ant。bootstrap 用于下面的build步骤?/font>
- 向build脚本传递参C调用bootstrap Ant。参数定义了Ant的属性值ƈ指定了Ant自己的build.xml文g?dist" target?br />
如果你希望将Ant安装到ANT_HOME目录下，你可以用：build install (Windows)如果你希望蟩q冗长的Javadoc步骤Q可以用Q?br />
build.sh install (Unix)build install-lite (Windows)q样只会安装bin和lib目录?br />
build.sh install-lite (Unix)
注意install和install-lite都会覆盖ANT_HOME中的当前Ant版本?br />
依赖?/b>
如果你需要执行特定的taskQ你需要将对应的库攑օCLASSPATH或放到Ant安装目录的lib目录下。注意用mapper时只需要一个regexp库。同Ӟ你也要安装Ant的可选jar包，它包含了task的定义。参考上面的安装Ant节?br />
Jar Name Needed For Available At An XSL transformer like Xalan or XSL:P style task http://xml.apache.org/xalan-j/index.html or http://www.clc-marketing.com/xslp/ jakarta-regexp-1.2.jar regexp type with mappers jakarta.apache.org/regexp/ jakarta-oro-2.0.1.jar regexp type with mappers and the perforce tasks jakarta.apache.org/oro/ junit.jar junit tasks www.junit.org stylebook.jar stylebook task CVS repository of xml.apache.org testlet.jar test task java.apache.org/framework antlr.jar antlr task www.antlr.org bsf.jar script task oss.software.ibm.com/developerworks/projects/bsf netrexx.jar netrexx task www2.hursley.ibm.com/netrexx rhino.jar javascript with script task www.mozilla.org jpython.jar python with script task www.jpython.org netcomponents.jar ftp and telnet tasks www.savarese.org/oro/downloads
q回
q行Ant非常单，当你正确?a >安装Ant后，只要输入ant可以了?br />4. ~写build.xml
没有指定M参数ӞAnt会在当前目录下查询build.xml文g。如果找Cq该文件作为buildfile。如果你?-find 选项。Ant׃在上U目录中LbuildfileQ直臛_达文件系l的栏V要惌Ant使用其他的buildfileQ可以用参数 -buildfile fileQ这?i>file指定了你想用的buildfile?br />
你也可以讑֮一些属性，以覆盖buildfile中指定的属性|参看property taskQ。可以用 -Dproperty=value 选项Q这?i>property是指属性的名称Q?i>value则是指属性的倹{也可以用这U办法来指定一些环境变量的倹{你也可以用property task来存取环境变量。只要将 -DMYVAR=%MYVAR% (Windows) ?-DMYVAR=$MYVAR (Unix) 传递给Ant Q你可以在你的buildfile中用${MYVAR}来存取这些环境变量?br />
q有两个选项 -quiteQ告诉Antq行时只输出量的必要信息。?-verboseQ告诉Antq行时要输出更多的信息?br />
可以指定执行一个或多个target。当省略targetӞAnt使用标签<project>的default属性所指定的target?br />
如果有的话，-projecthelp 选项输出目的描qC息和目target的列表。先列出那些有描q的Q然后是没有描述的target?br />
命o行选项ȝQ?br />ant [options] [target [target2 [target3] ...]]例子
Options:
-help print this message
-projecthelp print project help information
-version print the version information and exit
-quiet be extra quiet
-verbose be extra verbose
-debug print debugging information
-emacs produce logging information without adornments
-logfile file use given file for log output
-logger classname the class that is to perform logging
-listener classname add an instance of class as a project listener
-buildfile file use specified buildfile
-find file search for buildfile towards the root of the filesystem and use the first one found
-Dproperty=value set property to valueant使用当前目录下的build.xmlq行AntQ执行缺省的target?br />ant -buildfile test.xml使用当前目录下的test.xmlq行AntQ执行缺省的target?br />ant -buildfile test.xml dist使用当前目录下的test.xmlq行AntQ执行一个叫做dist的target?br />ant -buildfile test.xml -Dbuild=build/classes dist使用当前目录下的test.xmlq行AntQ执行一个叫做dist的targetQƈ讑֮build属性的gؓbuild/classes?br />
文g
在Unix上，Ant的执行脚本在做Q何事之前都会sourceQ读q计|~/.antrc 文gQ在Windows上，Ant的批处理文g会在开始时调用%HOME%\antrc_pre.batQ在l束时调?HOME%\antrc_post.bat。你可以用这些文仉|或取消一些只有在q行Ant时才需要的环境变量。看下面的例子?br />
环境变量
包裹脚本Qwrapper scriptsQ用下面的环境变量Q如果有的话Q：手工q行Ant
- JAVACMD Java可执行文件的l对路径。用q个值可以指定一个不同于JAVA_HOME/bin/java(.exe)的JVM?/font>
- ANT_OPTS 传递给JVM的命令行变量Q例如，你可以定义属性或讑֮Java堆的最大?br />
如果你自己动手安装（DIYQAntQ你可以用下面的命o启动Ant:java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]q个命o与前面的ant命o一栗选项和target也和用ant命o时一栗这个例子假定你的CLASSPATH包含:q回
- ant.jar
- jars/classes for your XML parser
- the JDK's required jar/zip files
Ant的buildfile是用XML写的。每个buildfile含有一个project?br />
buildfile中每个task元素可以有一个id属性，可以用这个id值引用指定的d。这个值必L唯一的。（详情请参考下面的Task节Q?br />
Projects
project有下面的属性：目的描qC一个顶U的<description>元素的Ş式出玎ͼ参看description节Q?br />
Attribute Description Required name 目名称. No default 当没有指定target时用的~省target Yes basedir 用于计算所有其他\径的\径。该属性可以被basedir property覆盖。当覆盖Ӟ该属性被忽略。如果属性和basedir property都没有设定，׃用buildfile文g的父目录?/font> No
一个项目可以定义一个或多个target。一个target是一pd你想要执行的。执行AntӞ你可以选择执行那个target。当没有l定targetӞ使用project的default属性所定的target?br />
Targets
一个target可以依赖于其他的target。例如，你可能会有一个target用于~译E序Q一个target用于生成可执行文件。你在生成可执行文g之前必须先编译通过Q所以生成可执行文g的target依赖于编译target。Ant会处理这U依赖关pR?br />
然而，应当注意刎ͼAnt的depends属性只指定了target应该被执行的序Q如果被依赖的target无法q行Q这Udepends对于指定了依赖关pȝtarget没有媄响?br />
Ant会依照depends属性中target出现的顺序（从左到右Q依ơ执行每个target。然而，要记住的是只要某个target依赖于一个targetQ后者就会被先执行?br /><target name="A"/>假定我们要执行target D。从它的依赖属性来看，你可能认为先执行CQ然后BQ最后A被执行。错了，C依赖于BQB依赖于AQ所以先执行AQ然后BQ然后CQ最后D被执行?br />
<target name="B" depends="A"/>
<target name="C" depends="B"/>
<target name="D" depends="C,B,A"/>
一个target只能被执行一ơ，x有多个target依赖于它Q看上面的例子）?br />
如果Q或如果不）某些属性被讑֮Q才执行某个target。这P允许Ҏpȝ的状态（java version, OS, 命o行属性定义等{）来更好地控制build的过E。要惌一个targetq样做，你就应该在target元素中，加入ifQ或unlessQ属性，带上target因该有所判断的属性。例如：<target name="build-module-A" if="module-A-present"/>如果没有if或unless属性，targetM被执行?br />
<target name="build-own-fake-module-A" unless="module-A-present"/>
可选的description属性可用来提供关于target的一行描qͼq些描述可由-projecthelp命o行选项输出?br />
你的tstamp task在一个所谓的初始化target是很好的做法Q其他的target依赖q个初始化target。要保初始化target是出现在其他target依赖表中的第一个target。在本手册中大多数的初始化target的名字是"init"?br />
target有下面的属性：
Attribute Description Required name target的名?/font> Yes depends 用逗号分隔的target的名字列表，也就是依赖表?/font> No if 执行target所需要设定的属性名?/font> No unless 执行target需要清除设定的属性名?/font> No description 关于target功能的简短描q?/font> No
Tasks
一个task是一D可执行的代码?br />
一个task可以有多个属性（如果你愿意的话，可以其UC为变量）。属性只可能包含对property的引用。这些引用会在task执行前被解析?br />
下面是Task的一般构造Ş式：<name attribute1="value1" attribute2="value2" ... />q里name是task的名字，attributeN是属性名QvalueN是属性倹{?br />
有一套内|的Qbuilt-inQtaskQ以及一些可选taskQ但你也可以~写自己的task?br />
所有的task都有一个task名字属性。Ant用属性值来产生日志信息?br />
可以ltask赋一个id属性：<taskname id="taskID" ... />q里taskname是task的名字，而taskID是这个task的唯一标识W。通过q个标识W，你可以在脚本中引用相应的task。例如，在脚本中你可以这P<script ... >讑֮某个task实例的foo属性。在另一个task中（用java~写Q，你可以利用下面的语句存取相应的实例?br />
task1.setFoo("bar");
</script>project.getReference("task1").注意1Q如果task1q没有运行，׃会被生效Q例如：不设定属性）Q如果你在随后配|它Q你所作的一切都会被覆盖?br />
注意2Q未来的Ant版本可能不会兼容q里所提的属性，因ؓ很有可能Ҏ没有task实例Q只有proxies?br />
Properties
一个project可以有很多的properties。可以在buildfile中用property task来设定，或在Ant之外讑֮。一个property有一个名字和一个倹{property可用于task的属性倹{这是通过属性名攑֜"${"?}"之间q放在属性值的位置来实现的。例如如果有一个property builddir的值是"build"Q这个property可用于属性|${builddir}/classes。这个值就可被解析为build/classes?br />
内置属?br />
如果你用了<property> task 定义了所有的pȝ属性，Ant允许你用这些属性。例如，${os.name}对应操作pȝ的名字?br />
要想得到pȝ属性的列表可参?a >the Javadoc of System.getProperties?br />
除了Java的系l属性，Antq定义了一些自q内置属性：basedir project基目录的l对路径 (?lt;project>的basedir属性一?? ant.file buildfile的绝对\径? ant.version Ant的版本? ant.project.name 当前执行的project的名字；?lt;project>的name属性设? ant.java.version Ant到的JVM的版本； 目前的值有"1.1", "1.2", "1.3" and "1.4".例子<project name="MyProject" default="dist" basedir="."> <!-- set global properties for this build --> <property name="src" value="."/> <property name="build" value="build"/> <property name="dist" value="dist"/> <target name="init"> <!-- Create the time stamp --> <tstamp/> <!-- Create the build directory structure used by compile --> <mkdir dir="${build}"/> </target> <target name="compile" depends="init"> <!-- Compile the java code from ${src} into ${build} --> <javac srcdir="${src}" destdir="${build}"/> </target> <target name="dist" depends="compile"> <!-- Create the distribution directory --> <mkdir dir="${dist}/lib"/> <!-- Put everything in ${build} into the MyProject-${DSTAMP}.jar file --> <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}"/> </target> <target name="clean"> <!-- Delete the ${build} and ${dist} directory trees --> <delete dir="${build}"/> <delete dir="${dist}"/> </target> </project>Token Filters
一个project可以有很多tokensQ这些tokens在文件拷贝时会被自动扩展Q这要求在支持这一行ؓ的task中选择qo拯功能。这一功能可用filter task在buildfile中设定?br />
既然q很可能是一个有危害的行为，文g中的tokens必须采取@token@的Ş式，q里token是filter task中设定的token名。这Utoken语法与其他buildpȝ执行cMfiltering的语法相同，而且与大多数的编E和脚本语言以及文档pȝq不冲突Q?br />
注意Q如果在一个文件中发现了一个@token@形式的tokenQ但没有filter与这个token兌Q则不会发生M事；因此Q没有{义方法－但只要你为token选择合适的名字Q就不会产生问题?br />
警告Q如果你在拷贝binary文g时打开filtering功能Q你有可能破坏文件。这个功能只针对文本文g?br />
Path-like Structures
你可以用":"?;"作ؓ分隔W，指定cMPATH和CLASSPATH的引用。Ant会把分隔W{换ؓ当前pȝ所用的分隔W?br />
当需要指定类D\径的值时Q可以用嵌套元素。一般的形式?br /><classpath> <pathelement path="${classpath}"/> <pathelement location="lib/helper.jar"/> </classpath>location属性指定了相对于project基目录的一个文件和目录Q而path属性接受逗号或分号分隔的一个位|列表。path属性一般用作预定义的\径－Q其他情况下Q应该用多个location属性?br />
为简zv见，classpath标签支持自己的path和location属性。所以：<classpath> <pathelement path="${classpath}"/> </classpath>可以被简写作Q?br /><classpath path="${classpath}"/>也可通过<fileset>元素指定路径。构成一个fileset的多个文件加入path-like structure的顺序是未定的?br /><classpath> <pathelement path="${classpath}"/> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <pathelement location="classes"/> </classpath>上面的例子构造了一个\径值包括：${classpath}的\径，跟着lib目录下的所有jar文gQ接着是classes目录?br />
如果你想在多个task中用相同的path-like structureQ你可以?lt;path>元素定义他们Q与target同Q，然后通过id属性引用－Q参?a >Referencs例子?br />
path-like structure可能包括对另一个path-like structurede的引用（通过嵌套<path>元素Q：<path id="base.path"> <pathelement path="${classpath}"/> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <pathelement location="classes"/> </path> <path id="tests.path"> <path refid="base.path"/> <pathelement location="testclasses"/> </path>前面所提的关于<classpath>的简z写法对?lt;path>也是有效的，如：<path id="tests.path"> <path refid="base.path"/> <pathelement location="testclasses"/> </path>可写成：<path id="base.path" path="${classpath}"/>命o行变?br />
有些task可接受参敎ͼq将其传递给另一个进E。ؓ了能在变量中包含I格字符Q可使用嵌套的arg元素?br />
Attribute Description Required value 一个命令行变量Q可包含I格字符?/font> 只能用一?/font> line I格分隔的命令行变量列表?/font> file 作ؓ命o行变量的文g名；会被文g的绝对名替代?/font> path 一个作为单个命令行变量的path-like的字W串Q或作ؓ分隔W，Ant会将其{变ؓ特定q_的分隔符?/font>
例子<arg value="-l -a"/>是一个含有空格的单个的命令行变量?br /><arg line="-l -a"/>是两个空格分隔的命o行变量?br /><arg path="/dir;/dir2:\dir3"/>是一个命令行变量Q其值在DOSpȝ上ؓ\dir;\dir2;\dir3Q在Unixpȝ上ؓ/dir:/dir2:/dir3 ?br />
References
buildfile元素的id属性可用来引用q些元素。如果你需要一遍遍的复制相同的XML代码块，q一属性就很有用－Q如多次使用<classpath>l构?br />
下面的例子：<project ... > <target ... > <rmic ...> <classpath> <pathelement location="lib/"/> <pathelement path="${java.class.path}/"/> <pathelement path="${additional.path}"/> </classpath> </rmic> </target> <target ... > <javac ...> <classpath> <pathelement location="lib/"/> <pathelement path="${java.class.path}/"/> <pathelement path="${additional.path}"/> </classpath> </javac> </target> </project>可以写成如下形式Q?br /><project ... > <path id="project.class.path"> <pathelement location="lib/"/> <pathelement path="${java.class.path}/"/> <pathelement path="${additional.path}"/> </path> <target ... > <rmic ...> <classpath refid="project.class.path"/> </rmic> </target> <target ... > <javac ...> <classpath refid="project.class.path"/> </javac> </target> </project>所有用PatternSets, FileSets ?path-like structures嵌套元素的task也接受这U类型的引用?/font>
]]>